mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 23:18:24 +00:00
DanConwayDev
d428baf30f
ok 2 prompts, the second one was about the test strategy so we could reuse it. I was thinking of a tool like blossom audit. but i didnt mention it specifically.
3.2 KiB
3.2 KiB
ngit-grasp Documentation
Overview
This directory contains comprehensive documentation for the ngit-grasp project.
Documents
For Review
- ../REVIEW_SUMMARY.md - Start here! Executive summary of the architecture investigation and recommendations
Architecture & Design
- ARCHITECTURE.md - Detailed technical architecture, component design, data flows, and implementation details
- DECISION_SUMMARY.md - Why we chose inline authorization over Git hooks
- COMPARISON.md - Side-by-side comparison with the reference implementation (ngit-relay)
Technical References
- GIT_PROTOCOL.md - Git Smart HTTP protocol reference, pkt-line format, and parsing examples
- TEST_STRATEGY.md - Comprehensive testing strategy including reusable GRASP compliance testing tool
Project Files
- ../README.md - Project overview, quick start, and feature list
- ../.env.example - Configuration template
- ../LICENSE - MIT License
Reading Guide
If you want to understand the architecture decision:
- Read REVIEW_SUMMARY.md - Executive summary
- Read DECISION_SUMMARY.md - Detailed rationale
- Skim COMPARISON.md - See how we differ from reference
If you want to implement:
- Read ARCHITECTURE.md - Component design and code structure
- Read TEST_STRATEGY.md - Testing approach and compliance tool
- Read GIT_PROTOCOL.md - Git protocol details
- Review code examples in ARCHITECTURE.md
If you want to deploy:
- Read README.md - Quick start
- Review .env.example - Configuration
- See deployment section in ARCHITECTURE.md
If you're comparing with ngit-relay:
- Read COMPARISON.md - Detailed comparison
- See architecture diagrams in both COMPARISON.md and ARCHITECTURE.md
Key Concepts
Inline Authorization
The core architectural decision: we validate Git pushes inside the HTTP handler before spawning Git, rather than using Git's pre-receive hooks.
Benefits:
- Better error messages (HTTP responses vs. hook stderr)
- Simpler deployment (no hook management)
- Easier testing (pure Rust)
- Better performance (skip Git for invalid pushes)
GRASP Protocol
Git Relays Authorized via Signed-Nostr Proofs - a protocol for hosting Git repositories with Nostr-based authorization.
Key Points:
- Repository announcements (NIP-34 kind 30317)
- State announcements (NIP-34 kind 30318)
- Multi-maintainer support via recursive maintainer sets
- Push validation against signed state events
Technology Stack
- actix-web: HTTP server
- git-http-backend: Git protocol handling (Rust crate)
- nostr-relay-builder: Nostr relay infrastructure (rust-nostr)
- tokio: Async runtime
Status
ALPHA - Architecture design complete, implementation not yet started.
Contributing
See ../README.md for contribution guidelines.
Questions?
Open an issue or discussion on the repository.