diff --git a/docs/explanation/metrics-and-administration.md b/docs/explanation/metrics-and-administration.md index 94a7d15..52817e8 100644 --- a/docs/explanation/metrics-and-administration.md +++ b/docs/explanation/metrics-and-administration.md @@ -464,6 +464,18 @@ ngit_quota_repo_bytes{repo=""} **Authentication:** NIP-86 (Nostr signature-based) +#### ConnectionTracker + +**Purpose:** Existing infrastructure that tracks connection patterns and abuse indicators. + +**Implementation:** Already implemented in the current codebase. Tracks: +- Connection patterns by source +- Invalid signature attempts +- Filter violations +- Potential abuse indicators + +**Usage in this architecture:** ConnectionTracker data will be exposed via the management dashboard (Phase 5) to help administrators identify problematic users and patterns. No new development required - this is existing functionality being surfaced in the UI. + #### Audit Logging **Purpose:** Record all administrative actions for accountability. @@ -764,6 +776,10 @@ This section breaks down the implementation into phases with clear dependencies - `ngit_storage_bytes_by_user{pubkey=""}` (top N) - `ngit_storage_bytes_by_repo{repo=""}` (top N) - Implement background storage scanner (periodic updates, configurable interval) +- Verify Issue 76fe (Repository Count Metric): + - Test that `ngit_repositories_total` metric exists and increments correctly + - Verify count matches actual repository count in git directory + - Add regression test to prevent future breakage - Testing: Verify accuracy against `du` command, test top-N selection **Effort:** 4-5 days (2-3 days per track, parallel) @@ -834,6 +850,11 @@ This section breaks down the implementation into phases with clear dependencies - Add rate limiting on `/metrics` endpoint (prevent brute-force) - Log failed authentication attempts - Testing: Test with valid/invalid keys, verify rate limiting, test timing attack resistance +- **Configuration sync:** Update all four config locations per AGENTS.md: + - `src/config.rs` - Add NGIT_METRICS_API_KEYS config field + - `docs/reference/configuration.md` - Document the new option + - `nix/module.nix` - Add NixOS module option + - `.env.example` - Add example with comments **Effort:** 2-3 days @@ -869,6 +890,11 @@ This section breaks down the implementation into phases with clear dependencies - Support both declarative (env/config) and dynamic (database) modes - Implement `NGIT_DECLARATIVE_ONLY` flag behavior - Testing: Test each operation, verify auth, test declarative vs dynamic modes +- **Configuration sync:** Update all four config locations per AGENTS.md: + - `src/config.rs` - Add NGIT_ADMIN_PUBKEYS and NGIT_DECLARATIVE_ONLY config fields + - `docs/reference/configuration.md` - Document the new options + - `nix/module.nix` - Add NixOS module options + - `.env.example` - Add examples with comments **Effort:** 4-5 days (IF rust-nostr supports NIP-86), 6-8 days (if manual implementation) @@ -960,16 +986,18 @@ This section breaks down the implementation into phases with clear dependencies - Implement quota checking in event handler (for repository creation) - Return clear error messages when quota exceeded - Include current usage, limit, and suggested actions - - Add quota warning events (notify users approaching limits) + - Add metrics for quota violations - Testing: Test each quota type, test error messages, test edge cases -3. **Graceful Degradation** - - Implement read-only mode when approaching relay-wide limit - - Add configuration for warning thresholds (80%, 90%, 95%) - - Add metrics for quota violations - - Testing: Test mode transitions, verify read operations still work +3. **Configuration** + - Add `NGIT_MAX_STORAGE_BYTES`, `NGIT_DEFAULT_USER_QUOTA_BYTES`, `NGIT_DEFAULT_REPO_QUOTA_BYTES` environment variables + - **Configuration sync:** Update all four config locations per AGENTS.md: + - `src/config.rs` - Add quota-related config fields + - `docs/reference/configuration.md` - Document the new options + - `nix/module.nix` - Add NixOS module options + - `.env.example` - Add examples with comments -**Effort:** 5-6 days +**Effort:** 3-4 days **Dependencies:** - Phase 4 (requires quota storage from NIP-86 API) @@ -1026,18 +1054,18 @@ Phase 5: Management Dashboard (6-8 days) ⚠️ MANUAL REVIEW REQUIRED Deliverable: Working code + tests Manual Review: Detailed plan before implementation -Phase 6: Quota Enforcement (5-6 days) +Phase 6: Quota Enforcement (3-4 days) └─ Sequential tasks within phase (can run unattended once Phase 5 approved) Dependencies: Phase 4, Phase 5 (approved), Phase 1 Track B, Issue b905 Deliverable: Working code + tests ``` -**Total Sequential Time:** ~26-34 days (5-7 weeks) +**Total Sequential Time:** ~24-32 days (5-6 weeks) **Parallelization Opportunities:** - **Within-phase:** Phases 0, 1, and 2 have independent tracks that can run simultaneously - **Cross-phase:** Limited. Most phases have strict dependencies on prior phases -- **Realistic speedup:** With 2 developers working parallel tracks: ~22-28 days (4-6 weeks) +- **Realistic speedup:** With 2 developers working parallel tracks: ~20-26 days (4-5 weeks) **Recommended Approach:** - Single developer: Follow phases sequentially (0→1→2→3→4→5→6), executing parallel tracks within each phase @@ -1080,15 +1108,15 @@ None. Most existing issues remain relevant and are incorporated into this plan. - Phase 3: 2-3 days (Prometheus auth) - Phase 4: 4-8 days (NIP-86 API - depends on rust-nostr support) - Phase 5: 6-8 days (dashboard, requires manual review of plan) -- Phase 6: 5-6 days (quota enforcement, can run unattended once Phase 5 approved) +- Phase 6: 3-4 days (quota enforcement, can run unattended once Phase 5 approved) -**Total:** 26-37 days (5-7 weeks) sequential, 22-30 days (4-6 weeks) with within-phase parallelization +**Total:** 24-35 days (5-7 weeks) sequential, 20-28 days (4-6 weeks) with within-phase parallelization **By Issue:** - 76fe: 0 days (verification only) - 7d0b: 9-12 days (Phase 2 Track A + Phase 5) - 2cdc: 8-13 days (Phase 0 Track A + Phase 4 + Phase 5 API key mgmt) -- 8430: 9-14 days (Phase 4 quota storage + Phase 6) +- 8430: 7-12 days (Phase 4 quota storage + Phase 6) - 1f4f: Included in Phase 5 (dashboard displays existing ConnectionTracker data) - b905: Dependency (must be complete before Phase 6) - d6ee: NOT ADDRESSED (removed from this plan) @@ -1162,8 +1190,9 @@ None. Most existing issues remain relevant and are incorporated into this plan. - [ ] Repositories can be deleted via management API/UI - [ ] Repository deletion integrates with NIP-09 event deletion - [ ] Storage quotas enforced on git push and repository creation -- [ ] Clear error messages guide users when quotas exceeded -- [ ] Graceful degradation when approaching relay-wide limits +- [ ] Clear error messages guide users when quotas exceeded (include current usage, limit, and suggested actions) +- [ ] Metrics track quota violations +- [ ] All four config locations updated for new quota-related environment variables - [ ] All tests pass, changes committed **Overall Success:**