mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 15:08:24 +00:00
DanConwayDev
aa543d8051
Motivation: rust-nostr 0.45 introduced a broad local-relay hardening series whose effective defaults were mostly absent from its changelog and entirely absent from ngit-grasp's custom NIP-11 response. One new 64 KiB event bound is incompatible with production history containing a valid roughly 149 KiB NIP-34 patch event. Leaving other defaults implicit risks another dependency upgrade silently changing serving policy, while exposing every internal knob would create configuration that peers cannot usefully negotiate. Approach: explicitly select every retained rust-nostr hardening value in the builder. Expose only the subscription and per-filter result limits that peers can discover and ngit-grasp sync already consumes, plus the Git-specific event size policy. Apply one filter-limit option consistently to explicit, query, and omitted-limit caps. Raise the event default from 64 KiB to 192 KiB and validate it remains beneath the fixed 5 MiB WebSocket message ceiling. Publish the standard NIP-11 limitation fields and correct the architecture/reference documentation, including removal of the obsolete max_filters claim. Correctness: the NIP-11 max_subscriptions value feeds the existing per-session subscription ledger; default_limit feeds adaptive pagination with its existing verification-page safeguard. max_limit is advertised truthfully but is not misused as an omitted-filter promise. The 192 KiB bound clears the observed patch by about 29% while preserving a finite allocation boundary. All three new options are synchronized across source, reference docs, NixOS, and the environment example. Excluded scope: message-size negotiation, filter-payload limits, per-IP fairness, and non-standard NIP-11 extensions remain separate work. Rate, handshake, subscription-memory, filter-count, and negentropy bounds are pinned but deliberately not operator-configurable because our sync cannot negotiate them through standard NIP-11 fields. Validation: focused unit tests passed for explicit configuration defaults, event/WebSocket size validation, configured NIP-11 advertisement, and the full http::nip11::tests module (10 tests before adding the focused override case). The previously validated full library suite and deployment build were not repeated at the user's request.
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
- Getting Started - Your first ngit-grasp setup
- Running Your First Audit - Using grasp-audit tool
🔧 How-To Guides - Solving Problems
Purpose: Accomplish specific tasks
For: Users with basic knowledge solving real problems
Style: Practical recipes and solutions
- Deploy ngit-grasp - Production deployment guide
- Configure Nix Flakes - Nix development environment
- Run Compliance Tests - GRASP compliance testing
- Upgrade nostr-sdk - Handling SDK upgrades
📖 Reference - Technical Information
Purpose: Look up technical details
For: Users who know what they're looking for
Style: Dry, factual, comprehensive
- Git Protocol - Git Smart HTTP protocol details
- GRASP Protocol - GRASP specification details
- Configuration - All config options
- API Reference - Internal API documentation
💡 Explanation - Understanding Concepts
Purpose: Understand the "why" and design decisions
For: Users wanting deeper understanding
Style: Discussion, context, alternatives
- Architecture Overview - System design and components
- Inline Authorization - Why we chose this approach
- Comparison with ngit-relay - How we differ from reference
- Design Decisions - Key architectural choices
🚀 Quick Start Paths
I'm brand new to ngit-grasp
- Read README.md for project overview
- Follow Getting Started Tutorial
- Understand Architecture Overview
I want to deploy ngit-grasp
- Review Configuration Reference
- Follow Deployment How-To
- Set up monitoring and backups
I want to develop on ngit-grasp
- Follow Getting Started Tutorial
- Read Architecture Overview
- Check Nix Flakes How-To
- Review Test Strategy
I want to understand the design
- Read Inline Authorization Explanation
- Review Design Decisions
- Compare with ngit-relay Comparison
I'm looking for specific information
- Protocol details? → Reference
- Configuration options? → Configuration Reference
- Git protocol? → Git Protocol Reference
📂 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