|
| 1 | +# ADR-002: IP-based Request Filtering |
| 2 | + |
| 3 | +**Date:** 2026-02-25 |
| 4 | +**Status:** Accepted |
| 5 | +**Deciders:** Team juv25d |
| 6 | +**Technical:** - PR #59 - Add IP filter to request pipeline |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +## Context |
| 11 | + |
| 12 | +We want to restrict access to the HTTP server based on the client IP address. |
| 13 | +This should happen early in the request, before any route/handler/static file logic. |
| 14 | + |
| 15 | +The initial implementation should be simple, easy to configure and safe to use during group development. |
| 16 | + |
| 17 | +--- |
| 18 | + |
| 19 | +## Decision |
| 20 | + |
| 21 | +We implement an IP filter as a global filter in the server pipeline. |
| 22 | + |
| 23 | +The filter supports three modes: |
| 24 | + |
| 25 | +- **Whitelist mode:** only IPs explicitly listed are allowed. |
| 26 | +- **Blacklist mode:** all IPs are allowed except those explicitly listed. |
| 27 | +- **Open mode:** if both whitelist and blacklist are empty, all requests are allowed (useful during development) |
| 28 | + |
| 29 | +The initial implementation uses **exact IP address matching**. |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## Rationale |
| 34 | + |
| 35 | +The design prioritizes: |
| 36 | +- clear and predictable behavior |
| 37 | +- simple configuration |
| 38 | +- low friction for development environments |
| 39 | + |
| 40 | +Whitelist and blacklist are intentionally treated as separate configuration approaches. |
| 41 | +Using both simultaneously can be ambiguous, so the project can either document precedence rules or enforce a single-mode configuration in future iterations. |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## Consequences |
| 46 | + |
| 47 | +### Positive |
| 48 | +- Centralized access control early in the pipeline |
| 49 | +- Easy to enable/disable restrictions via configuration |
| 50 | +- Works well for group development (open mode) |
| 51 | + |
| 52 | +### Trade-offs |
| 53 | +- Exact IP matching only. |
| 54 | +- Potential ambiguity if both lists are configured |
| 55 | + |
| 56 | +--- |
| 57 | + |
| 58 | +## Alternatives Considered |
| 59 | + |
| 60 | +### Enforce single mode (whitelist or blacklist) |
| 61 | +**Pros:** clear API contract |
| 62 | +**Cons:** less flexible during experimentation |
| 63 | +**Status:** considered for future refinement if the team wants stricter validation |
| 64 | + |
| 65 | +--- |
0 commit comments