diff options
| author | DanConwayDev <DanConwayDev@protonmail.com> | 2026-02-25 15:07:40 +0000 |
|---|---|---|
| committer | DanConwayDev <DanConwayDev@protonmail.com> | 2026-02-25 15:07:40 +0000 |
| commit | 5ad9d9093fcbe7037e5474a9d8fa20a0b64fb79a (patch) | |
| tree | 3c22fb4b42a62badedc29963d1ce39a2fbc83bb1 /docs | |
| parent | 4fc3b279d3eb86993f7748959a3986be5a6c49a7 (diff) | |
drop nostr-db backend support, keep only lmdb and memory
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/explanation/architecture.md | 2 | ||||
| -rw-r--r-- | docs/explanation/comparison.md | 10 | ||||
| -rw-r--r-- | docs/explanation/deletion-requests.md | 2 | ||||
| -rw-r--r-- | docs/how-to/deploy.md | 4 | ||||
| -rw-r--r-- | docs/learnings/grasp-01-implementation.md | 4 | ||||
| -rw-r--r-- | docs/reference/configuration.md | 28 |
6 files changed, 22 insertions, 28 deletions
diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md index e101425..e0a57e5 100644 --- a/docs/explanation/architecture.md +++ b/docs/explanation/architecture.md | |||
| @@ -101,7 +101,7 @@ After examining both the reference implementation and HTTP server options, we ha | |||
| 101 | - Initialize configuration from environment (clap + dotenvy) | 101 | - Initialize configuration from environment (clap + dotenvy) |
| 102 | - Set up Hyper HTTP server with request routing | 102 | - Set up Hyper HTTP server with request routing |
| 103 | - Initialize Nostr relay builder with custom [`Nip34WritePolicy`](src/nostr/builder.rs:51) | 103 | - Initialize Nostr relay builder with custom [`Nip34WritePolicy`](src/nostr/builder.rs:51) |
| 104 | - Set up shared storage (LMDB, NostrDB, or Memory) | 104 | - Set up shared storage (LMDB or Memory) |
| 105 | - Handle WebSocket upgrades for Nostr relay | 105 | - Handle WebSocket upgrades for Nostr relay |
| 106 | - Handle graceful shutdown | 106 | - Handle graceful shutdown |
| 107 | 107 | ||
diff --git a/docs/explanation/comparison.md b/docs/explanation/comparison.md index 090e0eb..315f091 100644 --- a/docs/explanation/comparison.md +++ b/docs/explanation/comparison.md | |||
| @@ -11,7 +11,7 @@ This document compares ngit-grasp (this project) with ngit-relay (the reference | |||
| 11 | | **Git Protocol** | git-http-backend (C via fcgiwrap) | HTTP layer in Rust + git subprocess | | 11 | | **Git Protocol** | git-http-backend (C via fcgiwrap) | HTTP layer in Rust + git subprocess | |
| 12 | | **Authorization** | Pre-receive Git hook | Inline HTTP handler validation | | 12 | | **Authorization** | Pre-receive Git hook | Inline HTTP handler validation | |
| 13 | | **Nostr Relay** | Khatru (Go library) | nostr-relay-builder (Rust library) | | 13 | | **Nostr Relay** | Khatru (Go library) | nostr-relay-builder (Rust library) | |
| 14 | | **Event Store** | Badger (Go KV database) | LMDB or NostrDB (Rust) | | 14 | | **Event Store** | Badger (Go KV database) | LMDB (Rust) | |
| 15 | | **Proactive Sync** | Git-only (polls DB + fetches from git servers) | Nostr event sync + git sync (event-driven) | | 15 | | **Proactive Sync** | Git-only (polls DB + fetches from git servers) | Nostr event sync + git sync (event-driven) | |
| 16 | | **Process Management** | supervisord (4 processes) | Single tokio runtime | | 16 | | **Process Management** | supervisord (4 processes) | Single tokio runtime | |
| 17 | | **Packaging** | Docker with supervisord | Single static binary or Docker | | 17 | | **Packaging** | Docker with supervisord | Single static binary or Docker | |
| @@ -78,7 +78,7 @@ This document compares ngit-grasp (this project) with ngit-relay (the reference | |||
| 78 | │ │ │ │ builder library) │ │ | 78 | │ │ │ │ builder library) │ │ |
| 79 | │ │ - info/refs │ │ - NIP-34 Policy │ │ | 79 | │ │ - info/refs │ │ - NIP-34 Policy │ │ |
| 80 | │ │ - upload-pk │◀─────┤ (inline query) │ │ | 80 | │ │ - upload-pk │◀─────┤ (inline query) │ │ |
| 81 | │ │ - receive-pk │ auth │ - LMDB/NostrDB │ │ | 81 | │ │ - receive-pk │ auth │ - LMDB/Memory │ │ |
| 82 | │ │ + inline │ check│ - WebSocket │ │ | 82 | │ │ + inline │ check│ - WebSocket │ │ |
| 83 | │ │ validation │ │ - NIP-11 endpoint │ │ | 83 | │ │ validation │ │ - NIP-11 endpoint │ │ |
| 84 | │ └──────┬───────┘ └──────────┬─────────┘ │ | 84 | │ └──────┬───────┘ └──────────┬─────────┘ │ |
| @@ -100,7 +100,7 @@ This document compares ngit-grasp (this project) with ngit-relay (the reference | |||
| 100 | │ │ | 100 | │ │ |
| 101 | │ ┌──────────────────────────────────────────────────┐ │ | 101 | │ ┌──────────────────────────────────────────────────┐ │ |
| 102 | │ │ Shared State (Arc<T>) │ │ | 102 | │ │ Shared State (Arc<T>) │ │ |
| 103 | │ │ - Database (LMDB/NostrDB/Memory) │ │ | 103 | │ │ - Database (LMDB/Memory) │ │ |
| 104 | │ │ - Purgatory (DashMap - concurrent queue) │ │ | 104 | │ │ - Purgatory (DashMap - concurrent queue) │ │ |
| 105 | │ │ - Metrics (Prometheus) │ │ | 105 | │ │ - Metrics (Prometheus) │ │ |
| 106 | │ └──────────────────────────────────────────────────┘ │ | 106 | │ └──────────────────────────────────────────────────┘ │ |
| @@ -161,7 +161,7 @@ This is why ngit-grasp has ~13x more code - the majority is implementing GRASP-0 | |||
| 161 | | Feature | ngit-relay | ngit-grasp | | 161 | | Feature | ngit-relay | ngit-grasp | |
| 162 | |---------|-----------|-----------| | 162 | |---------|-----------|-----------| |
| 163 | | **Implementation** | Khatru (Go library) | nostr-relay-builder (Rust library) | | 163 | | **Implementation** | Khatru (Go library) | nostr-relay-builder (Rust library) | |
| 164 | | **Database** | Badger (Go KV store) | LMDB or NostrDB (Rust) | | 164 | | **Database** | Badger (Go KV store) | LMDB (Rust) | |
| 165 | | **Process** | Separate process on :3334 | Integrated (same binary) | | 165 | | **Process** | Separate process on :3334 | Integrated (same binary) | |
| 166 | | **Policies** | Go functions in `policies.go` | Rust traits (modular sub-policies) | | 166 | | **Policies** | Go functions in `policies.go` | Rust traits (modular sub-policies) | |
| 167 | | **Event Validation** | Single function with branches | 4 separate policy modules | | 167 | | **Event Validation** | Single function with branches | 4 separate policy modules | |
| @@ -287,7 +287,7 @@ For users of ngit-relay, migration to ngit-grasp involves: | |||
| 287 | 287 | ||
| 288 | ### Data Migration | 288 | ### Data Migration |
| 289 | 289 | ||
| 290 | 1. **Events**: Export from Badger → Import to LMDB/NostrDB | 290 | 1. **Events**: Export from Badger → Import to LMDB |
| 291 | - No direct migration tool yet (would need to be built) | 291 | - No direct migration tool yet (would need to be built) |
| 292 | - Alternative: Use proactive sync to re-fetch from other relays | 292 | - Alternative: Use proactive sync to re-fetch from other relays |
| 293 | 2. **Git Repositories**: Direct copy (same structure) | 293 | 2. **Git Repositories**: Direct copy (same structure) |
diff --git a/docs/explanation/deletion-requests.md b/docs/explanation/deletion-requests.md index 7660774..4b4cd88 100644 --- a/docs/explanation/deletion-requests.md +++ b/docs/explanation/deletion-requests.md | |||
| @@ -28,7 +28,7 @@ The deletion system uses three separate data stores: | |||
| 28 | ┌─────────────────────────────────────────────────────────┐ | 28 | ┌─────────────────────────────────────────────────────────┐ |
| 29 | │ Main Database │ | 29 | │ Main Database │ |
| 30 | │ (Live events - actively served) │ | 30 | │ (Live events - actively served) │ |
| 31 | │ LMDB/NostrDB/Memory backend │ | 31 | │ LMDB/Memory backend │ |
| 32 | └─────────────────────────────────────────────────────────┘ | 32 | └─────────────────────────────────────────────────────────┘ |
| 33 | ↓ deletion request | 33 | ↓ deletion request |
| 34 | ┌─────────────────────────────────────────────────────────┐ | 34 | ┌─────────────────────────────────────────────────────────┐ |
diff --git a/docs/how-to/deploy.md b/docs/how-to/deploy.md index 157e5f8..9117fe2 100644 --- a/docs/how-to/deploy.md +++ b/docs/how-to/deploy.md | |||
| @@ -233,7 +233,7 @@ git ls-remote https://ngit.example.com/<npub>/<repo>.git | |||
| 233 | 233 | ||
| 234 | ### Storage | 234 | ### Storage |
| 235 | - `dataDir` - Base directory for data (default: /var/lib/ngit-grasp-{name}) | 235 | - `dataDir` - Base directory for data (default: /var/lib/ngit-grasp-{name}) |
| 236 | - `databaseBackend` - "lmdb" | "nostr-db" | "memory" (default: "lmdb") | 236 | - `databaseBackend` - "lmdb" | "memory" (default: "lmdb") |
| 237 | 237 | ||
| 238 | ### Identity | 238 | ### Identity |
| 239 | - `relayName` - Relay name for NIP-11 (default: "{domain} grasp relay") | 239 | - `relayName` - Relay name for NIP-11 (default: "{domain} grasp relay") |
| @@ -363,7 +363,7 @@ curl http://localhost:8082/metrics | |||
| 363 | **Tune configuration:** | 363 | **Tune configuration:** |
| 364 | - Reduce `metricsTopNRepos` | 364 | - Reduce `metricsTopNRepos` |
| 365 | - Increase `syncMaxBackoffSecs` | 365 | - Increase `syncMaxBackoffSecs` |
| 366 | - Switch to `databaseBackend = "nostr-db"` for better performance | 366 | - Tune `syncMaxBackoffSecs` for your network conditions |
| 367 | 367 | ||
| 368 | --- | 368 | --- |
| 369 | 369 | ||
diff --git a/docs/learnings/grasp-01-implementation.md b/docs/learnings/grasp-01-implementation.md index 27124af..f893d78 100644 --- a/docs/learnings/grasp-01-implementation.md +++ b/docs/learnings/grasp-01-implementation.md | |||
| @@ -20,7 +20,7 @@ | |||
| 20 | |-----------|--------|-----------| | 20 | |-----------|--------|-----------| |
| 21 | | HTTP Server | Hyper (not actix-web) | Better control over WebSocket upgrade handling | | 21 | | HTTP Server | Hyper (not actix-web) | Better control over WebSocket upgrade handling | |
| 22 | | Nostr Relay | nostr-relay-builder | Mature, well-tested, supports custom policies | | 22 | | Nostr Relay | nostr-relay-builder | Mature, well-tested, supports custom policies | |
| 23 | | Database | LMDB (default), NostrDB, Memory | LMDB for production, Memory for testing | | 23 | | Database | LMDB (default), Memory | LMDB for production, Memory for testing | |
| 24 | | Configuration | clap + dotenvy | CLI flags > env vars > .env > defaults | | 24 | | Configuration | clap + dotenvy | CLI flags > env vars > .env > defaults | |
| 25 | 25 | ||
| 26 | --- | 26 | --- |
| @@ -125,7 +125,7 @@ The decision to validate pushes **before** spawning git-receive-pack worked extr | |||
| 125 | Using rust-nostr's relay builder was the right call: | 125 | Using rust-nostr's relay builder was the right call: |
| 126 | - Handles NIP-01 protocol correctly | 126 | - Handles NIP-01 protocol correctly |
| 127 | - Custom `WritePolicy` trait for our validation | 127 | - Custom `WritePolicy` trait for our validation |
| 128 | - Database abstraction (LMDB, NostrDB, Memory) | 128 | - Database abstraction (LMDB, Memory) |
| 129 | - Active maintenance and updates | 129 | - Active maintenance and updates |
| 130 | 130 | ||
| 131 | ### 3. Separate Audit Tool | 131 | ### 3. Separate Audit Tool |
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index b09b20f..a05aeee 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md | |||
| @@ -245,44 +245,38 @@ NGIT_RELAY_DATA_PATH=/mnt/ssd/relay-data | |||
| 245 | #### `NGIT_DATABASE_BACKEND` | 245 | #### `NGIT_DATABASE_BACKEND` |
| 246 | 246 | ||
| 247 | **Description:** Database backend type for storing Nostr events | 247 | **Description:** Database backend type for storing Nostr events |
| 248 | **Type:** String (enum: memory, nostrdb, lmdb) | 248 | **Type:** String (enum: memory, lmdb) |
| 249 | **Default:** `memory` | 249 | **Default:** `lmdb` |
| 250 | **Required:** No | 250 | **Required:** No |
| 251 | 251 | ||
| 252 | **Valid Values:** | 252 | **Valid Values:** |
| 253 | 253 | ||
| 254 | - `memory` - In-memory database (default, fastest, no persistence) | 254 | - `lmdb` - LMDB backend (persistent, general purpose) |
| 255 | - `nostrdb` - NostrDB backend (persistent, optimized for Nostr) [Not yet implemented] | 255 | - `memory` - In-memory database (fastest, no persistence) |
| 256 | - `lmdb` - LMDB backend (persistent, general purpose) [Not yet implemented] | ||
| 257 | 256 | ||
| 258 | **Examples:** | 257 | **Examples:** |
| 259 | 258 | ||
| 260 | ```bash | 259 | ```bash |
| 261 | # Development (default, no persistence) | 260 | # Production (default, persistent) |
| 262 | NGIT_DATABASE_BACKEND=memory | ||
| 263 | |||
| 264 | # Production with NostrDB (when implemented) | ||
| 265 | NGIT_DATABASE_BACKEND=nostrdb | ||
| 266 | |||
| 267 | # Production with LMDB (when implemented) | ||
| 268 | NGIT_DATABASE_BACKEND=lmdb | 261 | NGIT_DATABASE_BACKEND=lmdb |
| 262 | |||
| 263 | # Development/testing (no persistence) | ||
| 264 | NGIT_DATABASE_BACKEND=memory | ||
| 269 | ``` | 265 | ``` |
| 270 | 266 | ||
| 271 | **Comparison:** | 267 | **Comparison:** |
| 272 | 268 | ||
| 273 | | Backend | Persistence | Performance | Use Case | | 269 | | Backend | Persistence | Performance | Use Case | |
| 274 | | ------- | ----------- | ----------- | ---------------------------- | | 270 | | ------- | ----------- | ----------- | ---------------------------- | |
| 275 | | memory | No | Fastest | Development, testing | | ||
| 276 | | nostrdb | Yes | High | Production (Nostr-optimized) | | ||
| 277 | | lmdb | Yes | High | Production (general purpose) | | 271 | | lmdb | Yes | High | Production (general purpose) | |
| 272 | | memory | No | Fastest | Development, testing | | ||
| 278 | 273 | ||
| 279 | **Notes:** | 274 | **Notes:** |
| 280 | 275 | ||
| 281 | - `memory` backend loses all data on restart | 276 | - `memory` backend loses all data on restart |
| 282 | - NostrDB and LMDB backends will use `NGIT_RELAY_DATA_PATH` for storage | 277 | - `lmdb` backend uses `NGIT_RELAY_DATA_PATH` for storage |
| 283 | - NostrDB and LMDB are planned features, not yet available | ||
| 284 | - Default `memory` backend suitable for development and testing only | 278 | - Default `memory` backend suitable for development and testing only |
| 285 | - Production deployments should use persistent backends when available | 279 | - Production deployments should use `lmdb` |
| 286 | 280 | ||
| 287 | --- | 281 | --- |
| 288 | 282 | ||