mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 23:18:24 +00:00
DanConwayDev
c8ab2c9c29
Adds NGIT_EVENT_BLACKLIST option for blocking all events from specific npubs, taking precedence over all other validation to enable comprehensive moderation without affecting curation policy. Key features: - Simple npub-only format: <npub>,<npub>,... - Checked FIRST before any other validation (including repository blacklist) - Blocks ALL event types (announcements, state events, PRs, comments, etc.) - Events never reach relay storage or purgatory - Specific rejection reason for operator debugging Implementation: - Add EventBlacklistConfig struct with check() method - Add NGIT_EVENT_BLACKLIST config option and event_blacklist_config() method - Add config field to PolicyContext for policy access - Add check_event_blacklist() to Nip34WritePolicy - Check event blacklist first in admit_event() method (before any other validation) - 4 new unit tests covering all blacklist behavior Configuration synced across all four sources: - src/config.rs: Core implementation with EventBlacklistConfig - .env.example: Comprehensive documentation with examples - docs/reference/configuration.md: Complete reference documentation - nix/module.nix: NixOS module option with environment mapping README updates: - Add comprehensive "Curation & Moderation" section - Document repository whitelists (GRASP-01 and GRASP-05 modes) - Document repository and event blacklists with precedence order - Add configuration table for all curation/moderation settings - Provide real-world examples for different relay configurations Testing: - 4 new tests for event blacklist functionality - All 336 library tests passing - All 64 integration tests passing - All 38 filter support tests passing Verification: - Repository blacklist confirmed to apply to sync (uses same admit_event flow) - Sync events validated through process_event_static -> write_policy.admit_event Use cases: - Block spam/abusive users completely - Prevent malicious actors from submitting any events - Temporary blocks for investigation - Moderation without affecting whitelist curation policy
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.