mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 15:08:24 +00:00
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.
How-To Guides
Task-oriented documentation - Practical solutions to common problems.
What Are How-To Guides?
How-to guides are recipes that show you how to solve specific problems or accomplish particular tasks.
Characteristics:
- ✅ Task-oriented (solve a problem)
- ✅ Practical (actionable steps)
- ✅ Assume basic knowledge
- ✅ Focus on results
- ✅ Can be followed in any order
Not how-to guides:
- ❌ Complete lessons for beginners (those are Tutorials)
- ❌ Technical specifications (those are Reference)
- ❌ Conceptual discussions (those are Explanation)
Available How-To Guides
Configure Nix Flakes
Problem: Set up reproducible development environment
Difficulty: Intermediate
You'll learn:
- Enable Nix flakes
- Enter development environment
- Work with subprojects
- Troubleshoot common issues
Test Sync Against Production Data
Problem: Debug and improve sync using real-world data
Difficulty: Intermediate
You'll learn:
- Run sync against production relays
- Sanitize logs for LLM analysis
- Identify common issues and patterns
- Iteratively improve sync behavior
Planned How-To Guides
Deploy ngit-grasp
Status: 🔜 Planned (waiting for main server)
Problem: Deploy to production
You'll learn:
- Server requirements
- Reverse proxy setup (nginx/Caddy)
- SSL/TLS configuration
- Monitoring and logging
Run Compliance Tests
Status: 🔜 Planned
Problem: Test GRASP compliance
You'll learn:
- Set up test relay
- Run integration tests
- Interpret results
- Add custom tests
Upgrade nostr-sdk
Status: 🔜 Planned
Problem: Handle breaking changes in nostr-sdk
You'll learn:
- Check for breaking changes
- Update dependencies
- Fix compilation errors
- Test after upgrade
Configure Authentication
Status: 🔜 Planned (feature not yet implemented)
Problem: Secure your relay
You'll learn:
- Enable authentication
- Configure allowed users
- Set up rate limiting
- Monitor access
Backup and Restore
Status: 🔜 Planned
Problem: Protect your data
You'll learn:
- Backup Git repositories
- Backup Nostr events
- Restore from backup
- Automate backups
How to Use How-To Guides
- Find your problem - Browse or search for what you need
- Check prerequisites - Make sure you have required knowledge
- Follow the steps - Adapt to your specific situation
- Solve and move on - No need to read everything
Not sure if this is what you need?
- New to ngit-grasp? → Tutorials
- Looking for technical details? → Reference
- Want to understand why? → Explanation
Contributing How-To Guides
When writing a how-to guide:
DO:
- ✅ Start with the problem/goal
- ✅ List prerequisites clearly
- ✅ Provide concrete steps
- ✅ Include troubleshooting
- ✅ Show examples
- ✅ Link to related docs
DON'T:
- ❌ Teach basics (link to Tutorials)
- ❌ Explain every concept (link to Explanation)
- ❌ List all options (link to Reference)
- ❌ Make it a tutorial (stay focused on the task)
Template:
# How-To: [Task/Problem]
**Problem:** [What you're trying to accomplish]
**Difficulty:** [Beginner/Intermediate/Advanced]
**Time:** [Estimated time]
## Prerequisites
- [Required knowledge/tools]
## Solution
### Step 1: [Action]
[Instructions]
### Step 2: [Action]
[Instructions]
## Troubleshooting
### [Common problem]
**Solution:** [How to fix]
## Related Documentation
- [Links to relevant docs]
See Diátaxis: How-To Guides for detailed guidance.
Part of the ngit-grasp documentation using the Diátaxis framework.