mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 23:18:24 +00:00
DanConwayDev
aa543d8051
Motivation: rust-nostr 0.45 introduced a broad local-relay hardening series whose effective defaults were mostly absent from its changelog and entirely absent from ngit-grasp's custom NIP-11 response. One new 64 KiB event bound is incompatible with production history containing a valid roughly 149 KiB NIP-34 patch event. Leaving other defaults implicit risks another dependency upgrade silently changing serving policy, while exposing every internal knob would create configuration that peers cannot usefully negotiate. Approach: explicitly select every retained rust-nostr hardening value in the builder. Expose only the subscription and per-filter result limits that peers can discover and ngit-grasp sync already consumes, plus the Git-specific event size policy. Apply one filter-limit option consistently to explicit, query, and omitted-limit caps. Raise the event default from 64 KiB to 192 KiB and validate it remains beneath the fixed 5 MiB WebSocket message ceiling. Publish the standard NIP-11 limitation fields and correct the architecture/reference documentation, including removal of the obsolete max_filters claim. Correctness: the NIP-11 max_subscriptions value feeds the existing per-session subscription ledger; default_limit feeds adaptive pagination with its existing verification-page safeguard. max_limit is advertised truthfully but is not misused as an omitted-filter promise. The 192 KiB bound clears the observed patch by about 29% while preserving a finite allocation boundary. All three new options are synchronized across source, reference docs, NixOS, and the environment example. Excluded scope: message-size negotiation, filter-payload limits, per-IP fairness, and non-standard NIP-11 extensions remain separate work. Rate, handshake, subscription-memory, filter-count, and negentropy bounds are pinned but deliberately not operator-configurable because our sync cannot negotiate them through standard NIP-11 fields. Validation: focused unit tests passed for explicit configuration defaults, event/WebSocket size validation, configured NIP-11 advertisement, and the full http::nip11::tests module (10 tests before adding the focused override case). The previously validated full library suite and deployment build were not repeated at the user's request.
Reference
Information-oriented documentation - Technical details and specifications.
What Is Reference Documentation?
Reference documentation provides factual, technical information that you look up when needed.
Characteristics:
- ✅ Information-oriented (facts and data)
- ✅ Comprehensive and accurate
- ✅ Structured for lookup
- ✅ Dry and to-the-point
- ✅ Maintained as code changes
Not reference:
- ❌ Learning materials (those are Tutorials)
- ❌ Problem-solving guides (those are How-To)
- ❌ Conceptual explanations (those are Explanation)
Available Reference Documentation
Configuration
Complete reference for all configuration options
Contents:
- Environment variables
- Configuration file format
- Validation rules
- Examples for development/production/testing
Use when: You need to know what a config option does or what values are valid
Git Protocol
Git Smart HTTP protocol specification
Contents:
- Protocol overview
- Pkt-line format
- Request/response structure
- Reference updates format
- Parsing examples
Use when: You need to understand Git HTTP internals
Test Strategy
Testing approach and compliance framework
Contents:
- Test categories (unit, integration, compliance)
- GRASP compliance requirements
- Test isolation strategy
- Running tests
- Coverage requirements
Use when: You're writing tests or need to understand test structure
Planned Reference Documentation
GRASP Protocol
Status: 🔜 Planned
Contents:
- GRASP-01 requirements
- GRASP-02 (Proactive Sync)
- GRASP-05 (Archive)
- Event formats
- Validation rules
API Reference
Status: 🔜 Planned (waiting for main server)
Contents:
- HTTP endpoints
- Request/response formats
- Error codes
- Authentication
- Rate limiting
nostr-sdk Upgrade Guide
Status: 🔜 Planned
Contents:
- Version compatibility matrix
- Breaking changes by version
- Migration examples
- Common patterns
Event Formats
Status: 🔜 Planned
Contents:
- NIP-34 repository announcements (kind 30317)
- NIP-34 state events (kind 30318)
- Custom tags
- Validation rules
CLI Reference
Status: 🔜 Planned
Contents:
- Command-line arguments
- Subcommands
- Environment variables
- Exit codes
How to Use Reference Documentation
- Know what you're looking for - Reference is for lookup, not learning
- Use search or table of contents - Find the specific detail you need
- Check version - Ensure docs match your version
- Verify with code - Reference should match implementation
Not sure if this is what you need?
- New to the topic? → Tutorials
- Trying to solve a problem? → How-To Guides
- Want to understand concepts? → Explanation
Contributing Reference Documentation
When writing reference documentation:
DO:
- ✅ Be accurate and complete
- ✅ Use consistent structure
- ✅ Include all options/parameters
- ✅ Provide examples
- ✅ Update when code changes
- ✅ Use tables for structured data
DON'T:
- ❌ Explain concepts (link to Explanation)
- ❌ Provide tutorials (link to Tutorials)
- ❌ Solve problems (link to How-To)
- ❌ Include opinions or recommendations
Template:
# Reference: [Topic]
**Purpose:** [What this reference covers]
**Audience:** [Who needs this information]
---
## Overview
[Brief description of what's being documented]
---
## [Section 1]
### [Item]
**Description:** [What it is/does]
**Type:** [Data type]
**Default:** [Default value]
**Required:** [Yes/No]
**Examples:**
\`\`\`
[Example usage]
\`\`\`
**Notes:**
- [Important details]
---
## Related Documentation
- [Links to relevant docs]
See Diátaxis: Reference for detailed guidance.
Part of the ngit-grasp documentation using the Diátaxis framework.