diff options
| author | DanConwayDev <DanConwayDev@protonmail.com> | 2026-01-14 13:40:20 +0000 |
|---|---|---|
| committer | DanConwayDev <DanConwayDev@protonmail.com> | 2026-01-14 13:40:20 +0000 |
| commit | 2821578202d1313c23c30a5dbae39548822e3c55 (patch) | |
| tree | cbe4d2447312b7bc7653bef874b6fb23d60a0ede /docs/explanation/README.md | |
| parent | 50000cd9d47681390c3c45feef98fe51c7b79a0f (diff) | |
docs: add defensive measures explanation
Add comprehensive documentation explaining the defensive features
implemented in ngit-grasp. The detailed analysis of other relay
implementations is now preserved in commit history (e3792b9).
Diffstat (limited to 'docs/explanation/README.md')
| -rw-r--r-- | docs/explanation/README.md | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/docs/explanation/README.md b/docs/explanation/README.md index f477b73..58cc46f 100644 --- a/docs/explanation/README.md +++ b/docs/explanation/README.md | |||
| @@ -151,6 +151,48 @@ Explanation documentation helps you **understand concepts** and design decisions | |||
| 151 | 151 | ||
| 152 | --- | 152 | --- |
| 153 | 153 | ||
| 154 | ### [Defensive Measures & Rate Limiting](defensive-measures.md) | ||
| 155 | **Protection against abuse, spam, and denial-of-service attacks** | ||
| 156 | |||
| 157 | **Topics:** | ||
| 158 | - Connection and subscription management | ||
| 159 | - Event publishing rate limits | ||
| 160 | - Content filtering (blacklists/whitelists) | ||
| 161 | - Event validation plugin system (WritePolicy/QueryPolicy) | ||
| 162 | - Relay health management (naughty list, exponential backoff) | ||
| 163 | - Privacy-preserving IP tracking | ||
| 164 | - Future enhancements (per-IP rate limiting) | ||
| 165 | |||
| 166 | **Read when:** You want to understand how ngit-grasp protects against abuse and what defensive features are available | ||
| 167 | |||
| 168 | --- | ||
| 169 | |||
| 170 | ### [GRASP-05 Archive Mode](grasp-05-archive.md) | ||
| 171 | **Read-only mirroring of repositories** | ||
| 172 | |||
| 173 | **Topics:** | ||
| 174 | - Archive whitelist configuration | ||
| 175 | - Archive-all mode | ||
| 176 | - Read-only mode defaults | ||
| 177 | - Use cases for backup/mirror relays | ||
| 178 | |||
| 179 | **Read when:** You want to understand how to run an archive/backup relay | ||
| 180 | |||
| 181 | --- | ||
| 182 | |||
| 183 | ### [Deletion Requests](deletion-requests.md) | ||
| 184 | **Handling repository and event deletion** | ||
| 185 | |||
| 186 | **Topics:** | ||
| 187 | - Deletion request architecture | ||
| 188 | - Delete disrespector concept | ||
| 189 | - Preventing left-pad scenarios | ||
| 190 | - Archival policies | ||
| 191 | |||
| 192 | **Read when:** You want to understand how ngit-grasp handles deletion events (planned feature) | ||
| 193 | |||
| 194 | --- | ||
| 195 | |||
| 154 | ## Planned Explanation Documentation | 196 | ## Planned Explanation Documentation |
| 155 | 197 | ||
| 156 | ### GRASP Protocol Design | 198 | ### GRASP Protocol Design |