laantungir/ngit-grasp
1
0
Fork 0
mirror of https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git synced 2026-10-05 15:08:24 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
2a13fa7d7a790e1f726c6589a4d678c87fe2888d
ngit-grasp/docs
T
History
DanConwayDev 09bb4e1d7a Merge #1a76cd3d: Fix relay retry churn and avoidable response stalls 
nostr:nevent1qgsx2lyl2e4zvfadwcvkd9fkrcwczj7mf858hy85mwqclwgut8wpg2spz3mhxue69uhhyetvv9ujumn8d96zuer9wcq3yamnwvaz7tm8d96xummnw3ezucm0d5q3kamnwvaz7tmwva5hgtnyv9hxxmmwwashjer9wchxxmmdqqsp5akd8h6qc7k40glf0a8d9wuw7qrw5uljn2wa7k8s5w2v04ykewg6jm5uw

PR-Author: DanConwayDev's Agent
nostr:npub1v47f74n2ycn66asev62nv8sas99akj0g0wg0fkup37u3ckwuzs4q7cwtp0

CoverNote:

Small HTTP/WebSocket responses could wait for delayed acknowledgements, while checkpoint writes and metrics rendering performed blocking work on async workers. Background discovery also lost retry history during cleanup and could accept incomplete fetches as successful history.

Review the five commits independently:

| Commit | Scope | Change |
| --- | --- | --- |
| `ddcfa3c` | User responses | Enable TCP_NODELAY on accepted sockets; include delayed-ACK and concurrent LMDB read benchmarks. |
| `fe36d6f` | Shared runtime | Move periodic checkpoints to a blocking worker, release snapshot locks before I/O, and join active writes before the final shutdown snapshot. |
| `f55ce48` | Shared runtime | Render metrics on a blocking worker; retain a shared permit through completion so canceled scrapes cannot start overlapping scans. |
| `5d62037` | Background sync | Preserve discovery ownership and failure history through cleanup and reconnection without adding persistent subscriptions. |
| `df9280e` | Background sync | Require the exact subscription’s EOSE and a drained event stream before accepting discovered history. |

Each commit includes its tests, architecture documentation and changelog entry. Dependency versions and inbound relay query behavior match the base; the transport change applies to accepted connections. The two sync fixes affect outbound discovery.

Validation on the rewritten tree:

- Full workspace tests: 3,034 passed, 0 failed, 16 ignored.
- Formatting and Clippy with warnings denied: passed.
- Nix package build and its library checks: passed.
- Both opt-in response benchmarks passed. Twenty-five two-event reads with delayed ACK took 8.65 ms total. Concurrent LMDB reads reached EOSE at 1, 4, 16 and 32 readers; the maximum per-reader time for three 32-event batches at 32 readers was 220.87 ms.

The five retained fixes match the previously reviewed implementation. The withdrawn SDK workaround and pin are excluded. Investigation reports are absent from the final tree; the original history is preserved locally on `archive/relay-timeout-performance-2026-09-14`.

Local latency and load measurements are diagnostic samples, not production guarantees. These changes do not establish that every historical seven-second timeout had the same cause.
2026-09-14 11:37:20 +01:00
..
archive/2026-01-relay-ngit-dev-migration
fix migration scripts for non-interactive SSH and bash 5.3
2026-02-24 08:58:23 +00:00
explanation
fix(sync): require EOSE before accepting discovery history
2026-09-14 10:06:15 +00:00
grafana
feat(sync): Phase 6 - observability and production readiness
2025-12-04 18:43:49 +00:00
how-to
docs(test): record fixture ownership and timing contracts
2026-09-12 14:49:09 +00:00
learnings
refactor(auth): make current maintainer authority explicit
2026-08-29 21:20:49 +00:00
reference
docs: point GRASP references at Nostr Git
2026-09-04 13:59:46 +00:00
tutorials
docs: use Diátaxis structure
2025-11-04 10:25:53 +00:00
README.md
docs(deploy): add host-specific production paths
2026-08-20 19:38:04 +00:00

README.md

ngit-grasp Documentation

Welcome to the ngit-grasp documentation! We use the Diátaxis framework to organize our documentation into four types, each serving a different purpose.

                    PRACTICAL          THEORETICAL
                    ─────────          ───────────
                    
LEARNING      │   Tutorials    │    Explanation   │
              │                │                  │
              │  Getting       │   Architecture   │
              │  Started       │   Decisions      │
              │                │                  │
              ├────────────────┼──────────────────┤
              │                │                  │
WORKING       │  How-To        │    Reference     │
              │  Guides        │                  │
              │                │   API Docs       │
              │  Deployment    │   Protocols      │
              │  Testing       │                  │
              │                │                  │

📚 Documentation Types

🎓 Tutorials - Learning by Doing

Purpose: Learn the basics through practical steps
For: Newcomers getting started
Style: Step-by-step lessons with guaranteed outcomes

🔧 How-To Guides - Solving Problems

Purpose: Accomplish specific tasks
For: Users with basic knowledge solving real problems
Style: Practical recipes and solutions

📖 Reference - Technical Information

Purpose: Look up technical details
For: Users who know what they're looking for
Style: Dry, factual, comprehensive

💡 Explanation - Understanding Concepts

Purpose: Understand the "why" and design decisions
For: Users wanting deeper understanding
Style: Discussion, context, alternatives

🚀 Quick Start Paths

I'm brand new to ngit-grasp

  1. Read README.md for project overview
  2. Follow Getting Started Tutorial
  3. Understand Architecture Overview

I want to deploy ngit-grasp

  1. Review Configuration Reference
  2. Choose an environment in Deploy ngit-grasp
  3. Verify the deployment and test its backup

I want to develop on ngit-grasp

  1. Follow Getting Started Tutorial
  2. Read Architecture Overview
  3. Check Nix Flakes How-To
  4. Review Test Strategy

I want to understand the design

  1. Read Inline Authorization Explanation
  2. Review Design Decisions
  3. Compare with ngit-relay Comparison

I'm looking for specific information

📂 Additional Resources

Archive

Historical session notes and completed work. Useful for understanding project evolution but not required reading.

Learnings

DEPRECATED - Being migrated to Diátaxis structure:

  • Gotchas → How-To Guides
  • Patterns → Reference or Explanation
  • Notes → Appropriate category

🤝 Contributing to Documentation

When adding documentation, ask yourself:

Is it a tutorial?

  • Does it teach a beginner?
  • Is it a complete lesson with guaranteed outcome?
  • → Add to tutorials/

Is it a how-to guide?

  • Does it solve a specific problem?
  • Is it a recipe for accomplishing a task?
  • → Add to how-to/

Is it reference material?

  • Is it technical information?
  • Will people look it up when needed?
  • → Add to reference/

Is it explanation?

  • Does it explain "why"?
  • Does it discuss alternatives or design?
  • → Add to explanation/

See Diátaxis documentation for more guidance.

📊 Project Status

ALPHA - Under active development. Core functionality working, API may change.

Completed

  • ✅ grasp-audit compliance testing tool
  • ✅ Nix flake development environment
  • ✅ nostr-sdk 0.43 upgrade
  • ✅ Documentation restructure (Diátaxis)

In Progress

  • 🔄 Core ngit-grasp server implementation
  • 🔄 GRASP-01 compliance

Planned

  • 🔜 GRASP-02 (Proactive Sync)
  • 🔜 GRASP-05 (Archive)

🔗 External Links

Documentation structure based on Diátaxis
Last updated: November 4, 2025

Reference in New Issue View Git Blame Copy Permalink