blob: 745211d79c3a2bd3774e6c9a5295aaa737901b5c (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
# ngit-grasp Documentation
## Overview
This directory contains comprehensive documentation for the ngit-grasp project.
## Documents
### For Review
- **[../REVIEW_SUMMARY.md](../REVIEW_SUMMARY.md)** - Start here! Executive summary of the architecture investigation and recommendations
### Architecture & Design
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Detailed technical architecture, component design, data flows, and implementation details
- **[DECISION_SUMMARY.md](DECISION_SUMMARY.md)** - Why we chose inline authorization over Git hooks
- **[COMPARISON.md](COMPARISON.md)** - Side-by-side comparison with the reference implementation (ngit-relay)
### Technical References
- **[GIT_PROTOCOL.md](GIT_PROTOCOL.md)** - Git Smart HTTP protocol reference, pkt-line format, and parsing examples
- **[TEST_STRATEGY.md](TEST_STRATEGY.md)** - Comprehensive testing strategy including reusable GRASP compliance testing tool
### Project Files
- **[../README.md](../README.md)** - Project overview, quick start, and feature list
- **[../.env.example](../.env.example)** - Configuration template
- **[../LICENSE](../LICENSE)** - MIT License
## Reading Guide
### If you want to understand the architecture decision:
1. Read [REVIEW_SUMMARY.md](../REVIEW_SUMMARY.md) - Executive summary
2. Read [DECISION_SUMMARY.md](DECISION_SUMMARY.md) - Detailed rationale
3. Skim [COMPARISON.md](COMPARISON.md) - See how we differ from reference
### If you want to implement:
1. Read [ARCHITECTURE.md](ARCHITECTURE.md) - Component design and code structure
2. Read [TEST_STRATEGY.md](TEST_STRATEGY.md) - Testing approach and compliance tool
3. Read [GIT_PROTOCOL.md](GIT_PROTOCOL.md) - Git protocol details
4. Review code examples in ARCHITECTURE.md
### If you want to deploy:
1. Read [README.md](../README.md) - Quick start
2. Review [.env.example](../.env.example) - Configuration
3. See deployment section in [ARCHITECTURE.md](ARCHITECTURE.md)
### If you're comparing with ngit-relay:
1. Read [COMPARISON.md](COMPARISON.md) - Detailed comparison
2. 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](../README.md) for contribution guidelines.
## Questions?
Open an issue or discussion on the repository.
|