upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
path: root/docs/archive/2025-11-04-evening/current_status.md
diff options
context:
space:
mode:
authorDanConwayDev <DanConwayDev@protonmail.com>2025-12-03 11:19:40 +0000
committerDanConwayDev <DanConwayDev@protonmail.com>2025-12-03 11:19:40 +0000
commit2eaff5b79fed364d5eba5eb38e4b7bf76326884d (patch)
treedeacd6294f8860096ee82ee76930204efd65e33c /docs/archive/2025-11-04-evening/current_status.md
parent57bc8cd9c021feaf08e139e8fb62800bc476068e (diff)
remove docs archive
Diffstat (limited to 'docs/archive/2025-11-04-evening/current_status.md')
-rw-r--r--docs/archive/2025-11-04-evening/current_status.md443
1 files changed, 0 insertions, 443 deletions
diff --git a/docs/archive/2025-11-04-evening/current_status.md b/docs/archive/2025-11-04-evening/current_status.md
deleted file mode 100644
index f14c391..0000000
--- a/docs/archive/2025-11-04-evening/current_status.md
+++ /dev/null
@@ -1,443 +0,0 @@
1# Current Status - ngit-grasp Implementation
2
3**Date:** November 4, 2025
4**Status:** In Development - GRASP-01 Core Requirements
5
6---
7
8## ๐ŸŽฏ Project Goal
9
10Implement a **GRASP-01 compliant** Git relay service in Rust that:
11- Serves a NIP-01 Nostr relay at `/` (WebSocket)
12- Serves Git repositories via Git Smart HTTP at `/<npub>/<identifier>.git`
13- **Both on the SAME PORT** (critical requirement!)
14- Validates pushes against Nostr state events
15- Passes all compliance tests from grasp-audit
16
17---
18
19## ๐Ÿ“‹ GRASP-01 Requirements (from ../grasp/01.md)
20
21### 1. Nostr Relay Requirements
22
23**MUST:**
24- โœ… Serve NIP-01 compliant relay at `/` (WebSocket)
25- โœ… Accept NIP-34 repository announcements (kind 30617)
26- โœ… Accept NIP-34 state announcements (kind 30618)
27- โณ Reject announcements that don't list this service in `clone` and `relays` tags
28- โณ Accept events that tag accepted announcements
29- โœ… Serve NIP-11 relay information document
30- โณ Include `supported_grasps`, `repo_acceptance_criteria`, `curation` in NIP-11
31
32**Current Implementation:**
33- Basic WebSocket relay working
34- Event storage and querying functional
35- NIP-11 basic implementation exists
36- **Missing:** Announcement validation against service URL
37- **Missing:** Event acceptance policy based on announcements
38
39### 2. Git Smart HTTP Service Requirements
40
41**MUST:**
42- โŒ Serve Git repos at `/<npub>/<identifier>.git` via unauthenticated Git Smart HTTP
43- โŒ Accept pushes matching latest state announcement (respecting maintainer set)
44- โŒ Set repository HEAD per state announcement
45- โŒ Accept pushes to `refs/nostr/<event-id>` for PRs
46- โŒ Include `allow-reachable-sha1-in-want` and `allow-tip-sha1-in-want`
47- โŒ Serve webpage at repo endpoint for browsers
48
49**Current Implementation:**
50- **NOT STARTED** - Git HTTP backend not integrated
51- No Git repository management
52- No push validation
53
54### 3. CORS Support Requirements
55
56**MUST:**
57- โŒ Set `Access-Control-Allow-Origin: *` on ALL responses
58- โŒ Set `Access-Control-Allow-Methods: GET, POST` on ALL responses
59- โŒ Set `Access-Control-Allow-Headers: Content-Type` on ALL responses
60- โŒ Respond to OPTIONS requests with 204 No Content
61
62**Current Implementation:**
63- **NOT STARTED** - No CORS headers
64
65---
66
67## ๐Ÿ—๏ธ Architecture Understanding (from ngit-relay)
68
69### Critical Architecture Insight: SINGLE PORT
70
71From `../ngit-relay/docker-compose.yml`:
72```yaml
73ports:
74 - "8081:8081" # Single port for EVERYTHING
75```
76
77From `../ngit-relay/src/nginx.conf`:
78```nginx
79server {
80 listen 8081; # Single listener
81
82 # Git repos at /<npub>/<identifier>.git
83 location ~ ^/npub1([a-z0-9]+)/([^/]+\.git)(/.*)?$ {
84 # ... git-http-backend via fcgiwrap
85 }
86
87 # Nostr relay at /
88 location / {
89 # ... proxy to khatru on localhost:3334
90 }
91}
92```
93
94**Key Points:**
951. **nginx listens on ONE port (8081)**
962. **nginx routes by URL path:**
97 - `/<npub>/<identifier>.git/*` โ†’ git-http-backend (fcgiwrap)
98 - Everything else โ†’ Khatru relay (localhost:3334)
993. **Khatru relay runs on INTERNAL port 3334**
1004. **git-http-backend runs via fcgiwrap socket**
101
102### Our Rust Implementation Strategy
103
104We need to replicate nginx's routing in Rust:
105
106```
107HTTP/WebSocket Request on port 8080
108 โ†“
109 actix-web router
110 โ†“
111 โ”Œโ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”
112 โ†“ โ†“
113Git Path Other Path
114/<npub>/ /
115<id>.git
116 โ†“ โ†“
117git-http Nostr Relay
118backend (WebSocket upgrade)
119handler
120```
121
122**Implementation Options:**
123
124**Option A: actix-web (HTTP framework)**
125- Handle HTTP/WebSocket on same port
126- Route by path pattern
127- Use `git-http-backend` crate for Git protocol
128- Native WebSocket support for Nostr relay
129
130**Option B: Direct TCP + Manual Routing**
131- Accept TCP connections
132- Parse HTTP headers to determine route
133- More complex but more control
134
135**Recommendation: Option A (actix-web)**
136- Well-tested HTTP/WebSocket handling
137- Easy routing by path
138- Good async performance
139- Already in our dependencies
140
141---
142
143## ๐Ÿงช Test Strategy
144
145### Current Test Structure
146
147```
148tests/
149โ”œโ”€โ”€ common/
150โ”‚ โ”œโ”€โ”€ mod.rs # Test utilities
151โ”‚ โ””โ”€โ”€ relay.rs # TestRelay fixture
152โ”œโ”€โ”€ nip01_compliance.rs # NIP-01 smoke tests
153โ””โ”€โ”€ nip34_announcements.rs # NIP-34 tests (TODO)
154```
155
156### Test Approach
157
158**Integration Tests (tests/*):**
159- Use `TestRelay` fixture to start/stop relay
160- Use `grasp-audit` library to run compliance tests
161- Tests reference GRASP protocol line numbers
162- Automatic relay lifecycle management
163
164**Example Test Structure:**
165```rust
166#[tokio::test]
167async fn test_grasp01_git_http_basic() {
168 // Reference: ../grasp/01.md lines 15-17
169 // Requirement: MUST serve git repository via unauthenticated git smart http
170
171 let relay = TestRelay::start().await;
172 let config = AuditConfig::ci();
173 let client = AuditClient::new(relay.url(), config).await.unwrap();
174
175 // Run GRASP-01 git HTTP tests
176 let results = specs::Grasp01GitHttp::run_all(&client).await;
177
178 relay.stop().await;
179 assert!(results.all_passed());
180}
181```
182
183### Test Coverage Needed
184
185**NIP-01 (Nostr Relay):**
186- โœ… WebSocket connection
187- โœ… Send/receive events
188- โœ… Subscriptions (REQ/CLOSE)
189- โœ… Event validation (signatures, IDs)
190- โณ NIP-11 relay info document
191
192**NIP-34 (Git Announcements):**
193- โณ Accept valid repository announcements (kind 30617)
194- โณ Accept valid state announcements (kind 30618)
195- โณ Reject announcements without service in clone/relays
196- โณ Validate maintainer sets
197- โณ Handle related events (issues, patches)
198
199**GRASP-01 (Git HTTP):**
200- โŒ Serve Git repo at `/<npub>/<id>.git`
201- โŒ Clone repository via HTTP
202- โŒ Push matching state announcement
203- โŒ Reject push not matching state
204- โŒ Handle `refs/nostr/<event-id>` for PRs
205- โŒ CORS headers on all responses
206- โŒ OPTIONS request handling
207
208---
209
210## ๐Ÿ“ Implementation Plan
211
212### Phase 1: Fix Current Relay (In Progress)
213
214**Goal:** Make NIP-01 relay fully compliant
215
216**Tasks:**
217- [x] Basic WebSocket relay working
218- [x] Event storage and querying
219- [ ] NIP-11 relay info with GRASP fields
220 - [ ] Add `supported_grasps: ["GRASP-01"]`
221 - [ ] Add `repo_acceptance_criteria`
222 - [ ] Add `curation` policy
223- [ ] Announcement validation
224 - [ ] Check `clone` tag includes our domain
225 - [ ] Check `relays` tag includes our domain
226 - [ ] Reject if not listed (unless GRASP-05)
227- [ ] Event acceptance policy
228 - [ ] Accept events tagging accepted announcements
229 - [ ] Accept events tagged by accepted announcements
230
231**Test Coverage:**
232- [x] NIP-01 smoke tests passing
233- [ ] NIP-11 compliance tests
234- [ ] NIP-34 announcement tests
235
236### Phase 2: Add Git HTTP Backend (Next)
237
238**Goal:** Serve Git repositories via HTTP on same port as relay
239
240**Tasks:**
2411. **Integrate actix-web**
242 - [ ] Replace raw WebSocket with actix-web
243 - [ ] Add HTTP routing
244 - [ ] Preserve WebSocket upgrade for `/`
245 - [ ] Add Git HTTP route for `/<npub>/<id>.git`
246
2472. **Integrate git-http-backend crate**
248 - [ ] Add dependency on `git-http-backend`
249 - [ ] Create Git handler for `/<npub>/<id>.git`
250 - [ ] Serve `git-upload-pack` (clone/fetch)
251 - [ ] Serve `git-receive-pack` (push)
252
2533. **Repository Management**
254 - [ ] Auto-provision repos from announcements
255 - [ ] Store repos at `{GIT_DATA_PATH}/<npub>/<id>.git`
256 - [ ] Initialize bare repositories
257 - [ ] Set HEAD from state announcements
258
2594. **CORS Support**
260 - [ ] Add CORS middleware to actix-web
261 - [ ] Set required headers on all responses
262 - [ ] Handle OPTIONS requests
263
264**Test Coverage:**
265- [ ] Can clone repository via HTTP
266- [ ] Can fetch from repository
267- [ ] Repository provisioned from announcement
268- [ ] HEAD set correctly from state
269- [ ] CORS headers present
270- [ ] OPTIONS requests handled
271
272### Phase 3: Push Authorization (Final)
273
274**Goal:** Validate pushes against Nostr state announcements
275
276**Tasks:**
2771. **Inline Authorization**
278 - [ ] Intercept `git-receive-pack` before Git process
279 - [ ] Parse ref updates from request
280 - [ ] Query latest state announcement from relay
281 - [ ] Validate push matches state
282 - [ ] Handle maintainer sets (recursive)
283 - [ ] Return HTTP error if validation fails
284
2852. **PR Support**
286 - [ ] Accept pushes to `refs/nostr/<event-id>`
287 - [ ] Validate PR event exists on relay
288 - [ ] Validate ref tip matches PR event `c` tag
289 - [ ] Implement 20-minute timeout for PR refs
290 - [ ] Garbage collect orphaned PR refs
291
2923. **State Synchronization**
293 - [ ] Update HEAD when state announcement received
294 - [ ] Handle state updates for existing repos
295 - [ ] Handle multi-maintainer scenarios
296
297**Test Coverage:**
298- [ ] Push matching state succeeds
299- [ ] Push not matching state fails
300- [ ] Multi-maintainer push validation
301- [ ] PR ref push/validation
302- [ ] PR ref garbage collection
303- [ ] State update triggers HEAD change
304
305---
306
307## ๐Ÿ› Known Issues
308
309### 1. Architecture Mismatch
310**Issue:** Tests assume relay on one port, Git on another
311**Fix:** Both must be on same port (like ngit-relay)
312**Impact:** Need to refactor server architecture
313
314### 2. Missing Git Implementation
315**Issue:** No Git HTTP backend integrated
316**Fix:** Add actix-web + git-http-backend
317**Impact:** Core GRASP-01 requirement not met
318
319### 3. No Announcement Validation
320**Issue:** Relay accepts all announcements
321**Fix:** Validate `clone` and `relays` tags
322**Impact:** Not GRASP-01 compliant
323
324### 4. No CORS Support
325**Issue:** No CORS headers on responses
326**Fix:** Add CORS middleware
327**Impact:** Web clients can't access relay
328
329---
330
331## ๐Ÿ”ง Environment Configuration
332
333From `../ngit-relay/.env.example`, we need:
334
335```bash
336# Service Configuration
337NGIT_DOMAIN=example.com # Used for announcement validation
338NGIT_BIND_ADDRESS=127.0.0.1:8080 # Single port for HTTP/WS/Git
339
340# Relay Information (NIP-11)
341NGIT_RELAY_NAME="ngit-grasp instance"
342NGIT_RELAY_DESCRIPTION="Rust GRASP implementation"
343NGIT_OWNER_NPUB="npub1..." # Relay owner
344
345# Storage Paths
346NGIT_GIT_DATA_PATH=/srv/ngit-grasp/repos # Git repositories
347NGIT_RELAY_DATA_PATH=/srv/ngit-grasp/relay-db # Nostr events
348
349# Features (Future)
350NGIT_PROACTIVE_SYNC_GIT=false # GRASP-02
351NGIT_PROACTIVE_SYNC_NOSTR=false # GRASP-02
352
353# Logging
354NGIT_LOG_LEVEL=INFO
355```
356
357**Current .env.example status:**
358- โณ Needs update with all required fields
359- โณ Add GRASP-specific configuration
360- โณ Document which fields are used where
361
362---
363
364## ๐Ÿ“Š Progress Summary
365
366### Completed โœ…
367- Basic Nostr relay (WebSocket)
368- Event storage and querying
369- NIP-01 smoke tests
370- Test infrastructure (TestRelay fixture)
371- Integration with grasp-audit library
372
373### In Progress โณ
374- NIP-11 relay information
375- NIP-34 announcement handling
376- Event acceptance policies
377
378### Not Started โŒ
379- Git HTTP backend
380- Repository provisioning
381- Push authorization
382- CORS support
383- actix-web integration
384
385### Compliance Status
386- **NIP-01:** ~60% (basic relay works, missing some features)
387- **NIP-34:** ~20% (can store events, no validation)
388- **GRASP-01:** ~30% (relay works, Git HTTP not started)
389
390---
391
392## ๐ŸŽฏ Next Session Priorities
393
3941. **Fix Architecture** (CRITICAL)
395 - Integrate actix-web for HTTP/WebSocket routing
396 - Single port for all services
397 - Preserve existing relay functionality
398
3992. **Add Git HTTP** (HIGH)
400 - Integrate `git-http-backend` crate
401 - Basic clone/fetch support
402 - Repository provisioning from announcements
403
4043. **Update Tests** (HIGH)
405 - Add GRASP-01 Git HTTP tests
406 - Reference protocol line numbers
407 - Verify single-port architecture
408
4094. **Fix NIP-11** (MEDIUM)
410 - Add GRASP-specific fields
411 - Document compliance level
412 - Include in tests
413
414---
415
416## ๐Ÿ“š Key References
417
418**GRASP Protocol:**
419- `../grasp/README.md` - Overview
420- `../grasp/01.md` - GRASP-01 Core Requirements (THE SPEC)
421- `../grasp/02.md` - GRASP-02 Proactive Sync
422- `../grasp/05.md` - GRASP-05 Archive
423
424**Reference Implementation:**
425- `../ngit-relay/README.md` - Architecture overview
426- `../ngit-relay/src/nginx.conf` - **CRITICAL: Shows single-port routing**
427- `../ngit-relay/docker-compose.yml` - **CRITICAL: Shows port config**
428- `../ngit-relay/.env.example` - Configuration template
429
430**Nostr Specs:**
431- [NIP-01](https://nips.nostr.com/1) - Basic protocol
432- [NIP-11](https://nips.nostr.com/11) - Relay information
433- [NIP-34](https://nips.nostr.com/34) - Git stuff
434
435**Our Code:**
436- `tests/nip01_compliance.rs` - Current test approach
437- `tests/common/relay.rs` - TestRelay fixture
438- `grasp-audit/src/specs/nip01_smoke.rs` - Test specs
439
440---
441
442**Last Updated:** November 4, 2025
443**Next Review:** After actix-web integration