mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 23:18:24 +00:00
DanConwayDev
d3d905010c
The previous design held the per-(submitter, identifier) mutex for the
entire receive-pack pipeline — `git init --bare`, the pack upload from
the client, `git-receive-pack`, per-ref validation, and the zero-ref
cleanup. Two concurrent pushes to the same `/prs/<submitter>/<id>.git`
path were therefore fully serialised end-to-end, with the second push's
HTTP connection blocked on the mutex for the entire duration of the
first push (including its pack upload over the wire). With multiple
agents or CI jobs sharing a contributor identity this could produce
HTTP/proxy timeouts and apparently-stuck pushes for no good reason —
git's own ref locking would normally handle intra-push concurrency on
the same path just fine.
Switch to a `PrsPathState { mu: Mutex<()>, in_flight: AtomicUsize }`
per path. The receive handler now takes the mutex only briefly:
* at the start of the request to run `git init --bare` and bump
`in_flight` from 0 to 1, then release the mutex,
* at the end of the request to drop `in_flight` and, if it lands on
zero with the repo at zero refs, `rm -rf` the bare directory.
`git-receive-pack` and per-ref validation run with no per-path lock
held, so concurrent pushes by different agents to the same path proceed
in parallel.
Off-push cleanup paths (the PR-event policy when it discards a scoped
placeholder whose incoming event mismatches, and the purgatory expiry
sweep when a scoped placeholder times out) take the same mutex briefly,
delete the dangling ref, then remove the bare directory only when
`in_flight.load() == 0` and `list_refs` is empty. With both reads
performed under the mutex that gates `in_flight` mutations, a repo
deletion can never race a push that is mid-receive: either the push is
still in init/register and we wait on the mutex, or the push has
already incremented `in_flight` (so we read non-zero and skip), or the
push has finished and decremented (so the directory is genuinely idle).
The end-of-push cleanup now also runs when receive-pack returns a
protocol-error response (200 with ERR pkt-line), which the previous
code's early-return skipped — a probe push that failed git-level
validation after `ensure_repo_initialised` had created the directory
used to leak an empty `.git` dir, which now gets removed in the same
critical section.
A small `path_state(&locks, path)` helper centralises the
get-or-insert-Arc dance the three sites used to duplicate.
Docs updated:
* docs/explanation/grasp-06-contributor-pr-submission.md — replace
the "lock held for the entire push pipeline" paragraph with the
new mutex + `in_flight` discipline; update the three-sites
enumeration to describe the `in_flight == 0` guard.
* docs/explanation/architecture.md — same shape, one-paragraph.
* docs/how-to/enable-grasp-06.md — call out that the mutex is held
only briefly so concurrent pushes don't serialise.
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.