DanConwayDev
4665a00ea9
Replaces the periodic /prs/ cleanup sweep (reverted in the previous
commit) with inline zero-ref cleanups at the three sites that can
leave a /prs/<submitter>/<identifier>.git bare repo empty:
1. The /prs/ receive handler at the end of a push, already in place
prior to the revert.
2. The PR-event policy when it discards a scoped placeholder whose
incoming event fails the (signer, identifier, commit) check —
deletes refs/nostr/<event-id> and, if that empties the repo,
removes the bare directory in the same step.
3. The standard 30-minute purgatory expiry sweep when a scoped
placeholder times out without a matching PR event arriving —
same shape as (2), but reached from the synchronous cleanup
loop, so the per-path lock is taken with try_lock and the
filesystem cleanup is skipped (leaving a harmless dangling ref)
if a push is currently in flight to the same path.
All three sites share a single Arc<DashMap<PathBuf, Arc<Mutex<()>>>>
of per-`(submitter, identifier)` locks. The receive handler now holds
its entry for the entire pipeline — `git init --bare` →
`git-receive-pack` → per-ref validation → zero-ref cleanup — instead
of only for the init step, so a concurrent push or off-push cleanup
cannot remove the bare repo while it is still being written. The
same lock map is plumbed into PolicyContext (used by pr_event.rs)
and Purgatory (via a one-shot `set_prs_cleanup_ctx` setter wired in
main, so tests can leave it unset and get the previous behaviour for
in-memory entries).
This delivers what the reverted commit was reaching for without the
370-line periodic walker, the mtime heuristic, or the
`has_prs_scope`/`DEFAULT_EXPIRY` API surface area on Purgatory: the
last ref always implies an immediate (or, under lock contention, a
next-cycle) repo removal, and the only code path that ever deletes
a /prs/ repo dir is one that already holds the per-path lock.
Docs:
- CHANGELOG.md, docs/how-to/enable-grasp-06.md: describe the three
inline cleanup sites; drop the "periodic 10-minute sweep" line.
- docs/explanation/architecture.md: drop the src/grasp06/cleanup.rs
bullet; document the lock as held for the whole pipeline and
shared with off-push cleanup paths.
- docs/explanation/grasp-06-contributor-pr-submission.md: replace
the "Periodic /prs/ cleanup" subsection with a "Zero-ref /prs/
cleanup" subsection enumerating the three sites and the shared
lock map; update "On-demand bare repo creation" to reflect the
wider lock scope.
Explanation
Understanding-oriented documentation - Concepts, design decisions, and the "why" behind ngit-grasp.
What Is Explanation?
Explanation documentation helps you understand concepts and design decisions, providing context and discussing alternatives.
Characteristics:
- ✅ Understanding-oriented (clarify concepts)
- ✅ Theoretical (ideas and design)
- ✅ Discuss alternatives
- ✅ Provide context and background
- ✅ Answer "why" questions
Not explanation:
- ❌ Step-by-step lessons (those are Tutorials)
- ❌ Problem-solving recipes (those are How-To)
- ❌ Technical specifications (those are Reference)
Available Explanation Documentation
Architecture Overview
Understand the system design and component interaction
Topics:
- Overall architecture
- Component responsibilities
- Data flows
- Technology choices
- Design patterns
Read when: You want to understand how ngit-grasp works as a system
Inline Authorization
Why we validate pushes inline instead of using Git hooks
Topics:
- The authorization problem
- Git hooks approach
- Inline approach
- Comparison and trade-offs
- Implementation details
Read when: You want to understand the core architectural decision
Design Decisions
Key architectural choices and their rationale
Topics:
- Inline authorization vs hooks
- Technology stack choices
- Storage design
- API design
- Performance considerations
Read when: You want to know why things are the way they are
Comparison with ngit-relay
How ngit-grasp differs from the reference implementation
Topics:
- Architecture comparison
- Component differences
- Trade-offs
- Migration path
- Compatibility
Read when: You're familiar with ngit-relay and want to understand differences
Purgatory Design
In-memory holding area for events awaiting git data
Topics:
- The "which arrives first?" problem
- Separate storage for state vs PR events
- Late binding for state events
- Bidirectional waiting for PR events
- Authorization during push
Read when: You want to understand how ngit-grasp handles out-of-order event/git data arrival
GRASP-02 Proactive Sync
Relay-to-relay synchronization for repository discovery
Topics:
- Negentropy-based event sync
- Repository announcement discovery
- Relay management and reconnection
- Layer 2 filtering
- Bootstrap and dynamic relay discovery
Read when: You want to understand how ngit-grasp discovers and syncs repositories across relays
GRASP-02 Purgatory Git Data Fetching
Proactive git data fetching from remote servers
Topics:
- Identifier-based batching
- Exponential backoff with fresh start
- Domain throttling (5 concurrent, 30/min)
- Debounced delays (3min user, 500ms sync)
- 30-minute expiry
- Mock-based testability
Read when: You want to understand how purgatory automatically fetches missing git data
Unified Git Data Sync
Shared processing for git push and purgatory sync paths
Topics:
- Why unify push and sync processing
- OID syncing to owner repos
- Ref alignment logic
- Event release from purgatory
- WebSocket notification
Read when: You want to understand how git data is processed consistently regardless of arrival method
Monitoring Overview
Prometheus metrics and observability
Topics:
- Metrics philosophy
- Connection tracking
- Git operation metrics
- Nostr event metrics
- Privacy considerations
Read when: You want to understand how to monitor ngit-grasp in production
Defensive Measures & Rate Limiting
Protection against abuse, spam, and denial-of-service attacks
Topics:
- Connection and subscription management
- Event publishing rate limits
- Content filtering (blacklists/whitelists)
- Event validation plugin system (WritePolicy/QueryPolicy)
- Relay health management (naughty list, exponential backoff)
- Privacy-preserving IP tracking
- Future enhancements (per-IP rate limiting)
Read when: You want to understand how ngit-grasp protects against abuse and what defensive features are available
GRASP-05 Archive Mode
Read-only mirroring of repositories
Topics:
- Archive whitelist configuration
- Archive-all mode
- Read-only mode defaults
- Use cases for backup/mirror relays
Read when: You want to understand how to run an archive/backup relay
Deletion Requests
Handling repository and event deletion
Topics:
- Deletion request architecture
- Delete disrespector concept
- Preventing left-pad scenarios
- Archival policies
Read when: You want to understand how ngit-grasp handles deletion events (planned feature)
Planned Explanation Documentation
GRASP Protocol Design
Status: 🔜 Planned
Topics:
- Why Nostr for Git?
- Authorization model
- Trust and verification
- Decentralization benefits
Storage Architecture
Status: 🔜 Planned
Topics:
- Why separate Git and Nostr storage?
- Indexing strategy
- Performance considerations
- Scaling approach
Testing Philosophy
Status: 🔜 Planned
Topics:
- Why test isolation?
- Integration vs unit tests
- Compliance testing approach
- Test-driven development
Performance Considerations
Status: 🔜 Planned
Topics:
- Async architecture
- Caching strategy
- Database choices
- Bottlenecks and solutions
How to Use Explanation Documentation
- Read to understand - Not to accomplish a task
- Follow your curiosity - Read what interests you
- Connect concepts - Link ideas together
- Question and explore - Think critically
Not sure if this is what you need?
- Want to learn by doing? → Tutorials
- Need to solve a problem? → How-To Guides
- Looking for technical details? → Reference
Contributing Explanation Documentation
When writing explanation:
DO:
- ✅ Discuss concepts and ideas
- ✅ Provide context and background
- ✅ Explain alternatives
- ✅ Use analogies and examples
- ✅ Connect to broader context
- ✅ Answer "why" questions
DON'T:
- ❌ Provide step-by-step instructions (link to Tutorials/How-To)
- ❌ List technical details (link to Reference)
- ❌ Assume you must be comprehensive
- ❌ Avoid opinions (explanation can be opinionated)
Template:
# Explanation: [Topic]
**Purpose:** [What concept/decision this explains]
**Audience:** [Who wants to understand this]
---
## The Problem/Question
[What are we trying to understand?]
---
## Background
[Context and history]
---
## Our Approach
[How we address it]
### Why This Works
[Explanation of benefits]
### Trade-offs
[What we gain and lose]
---
## Alternatives Considered
### [Alternative 1]
**Pros:**
- [Benefits]
**Cons:**
- [Drawbacks]
**Why we didn't choose it:**
[Reasoning]
---
## Conclusion
[Summary of understanding]
---
## Related Documentation
- [Links to relevant docs]
See Diátaxis: Explanation for detailed guidance.
Part of the ngit-grasp documentation using the Diátaxis framework.