diff options
| author | DanConwayDev <DanConwayDev@protonmail.com> | 2025-12-03 11:19:40 +0000 |
|---|---|---|
| committer | DanConwayDev <DanConwayDev@protonmail.com> | 2025-12-03 11:19:40 +0000 |
| commit | 2eaff5b79fed364d5eba5eb38e4b7bf76326884d (patch) | |
| tree | deacd6294f8860096ee82ee76930204efd65e33c /docs/archive/2025-11-04-evening/current_status.md | |
| parent | 57bc8cd9c021feaf08e139e8fb62800bc476068e (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.md | 443 |
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 | |||
| 10 | Implement 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 | |||
| 71 | From `../ngit-relay/docker-compose.yml`: | ||
| 72 | ```yaml | ||
| 73 | ports: | ||
| 74 | - "8081:8081" # Single port for EVERYTHING | ||
| 75 | ``` | ||
| 76 | |||
| 77 | From `../ngit-relay/src/nginx.conf`: | ||
| 78 | ```nginx | ||
| 79 | server { | ||
| 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:** | ||
| 95 | 1. **nginx listens on ONE port (8081)** | ||
| 96 | 2. **nginx routes by URL path:** | ||
| 97 | - `/<npub>/<identifier>.git/*` โ git-http-backend (fcgiwrap) | ||
| 98 | - Everything else โ Khatru relay (localhost:3334) | ||
| 99 | 3. **Khatru relay runs on INTERNAL port 3334** | ||
| 100 | 4. **git-http-backend runs via fcgiwrap socket** | ||
| 101 | |||
| 102 | ### Our Rust Implementation Strategy | ||
| 103 | |||
| 104 | We need to replicate nginx's routing in Rust: | ||
| 105 | |||
| 106 | ``` | ||
| 107 | HTTP/WebSocket Request on port 8080 | ||
| 108 | โ | ||
| 109 | actix-web router | ||
| 110 | โ | ||
| 111 | โโโโโโดโโโโโ | ||
| 112 | โ โ | ||
| 113 | Git Path Other Path | ||
| 114 | /<npub>/ / | ||
| 115 | <id>.git | ||
| 116 | โ โ | ||
| 117 | git-http Nostr Relay | ||
| 118 | backend (WebSocket upgrade) | ||
| 119 | handler | ||
| 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 | ``` | ||
| 148 | tests/ | ||
| 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] | ||
| 167 | async 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:** | ||
| 241 | 1. **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 | |||
| 247 | 2. **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 | |||
| 253 | 3. **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 | |||
| 259 | 4. **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:** | ||
| 277 | 1. **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 | |||
| 285 | 2. **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 | |||
| 292 | 3. **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 | |||
| 333 | From `../ngit-relay/.env.example`, we need: | ||
| 334 | |||
| 335 | ```bash | ||
| 336 | # Service Configuration | ||
| 337 | NGIT_DOMAIN=example.com # Used for announcement validation | ||
| 338 | NGIT_BIND_ADDRESS=127.0.0.1:8080 # Single port for HTTP/WS/Git | ||
| 339 | |||
| 340 | # Relay Information (NIP-11) | ||
| 341 | NGIT_RELAY_NAME="ngit-grasp instance" | ||
| 342 | NGIT_RELAY_DESCRIPTION="Rust GRASP implementation" | ||
| 343 | NGIT_OWNER_NPUB="npub1..." # Relay owner | ||
| 344 | |||
| 345 | # Storage Paths | ||
| 346 | NGIT_GIT_DATA_PATH=/srv/ngit-grasp/repos # Git repositories | ||
| 347 | NGIT_RELAY_DATA_PATH=/srv/ngit-grasp/relay-db # Nostr events | ||
| 348 | |||
| 349 | # Features (Future) | ||
| 350 | NGIT_PROACTIVE_SYNC_GIT=false # GRASP-02 | ||
| 351 | NGIT_PROACTIVE_SYNC_NOSTR=false # GRASP-02 | ||
| 352 | |||
| 353 | # Logging | ||
| 354 | NGIT_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 | |||
| 394 | 1. **Fix Architecture** (CRITICAL) | ||
| 395 | - Integrate actix-web for HTTP/WebSocket routing | ||
| 396 | - Single port for all services | ||
| 397 | - Preserve existing relay functionality | ||
| 398 | |||
| 399 | 2. **Add Git HTTP** (HIGH) | ||
| 400 | - Integrate `git-http-backend` crate | ||
| 401 | - Basic clone/fetch support | ||
| 402 | - Repository provisioning from announcements | ||
| 403 | |||
| 404 | 3. **Update Tests** (HIGH) | ||
| 405 | - Add GRASP-01 Git HTTP tests | ||
| 406 | - Reference protocol line numbers | ||
| 407 | - Verify single-port architecture | ||
| 408 | |||
| 409 | 4. **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 | ||