0171 — GeoIP swaps complete reader generations
Decision
stitchkit/geo is a server-only managed resource with three observable states:
uninitialized, unavailable and ready. It accepts a peer-neutral loader;
the optional MaxMind adapter opens City and optional ASN files as one verified
revision, then swaps the complete generation atomically. A failed refresh is
reported while the last known good generation continues serving lookups.
Retired readers close only after their in-flight lookups finish. Private or
invalid IP addresses resolve to null before reaching the database.
Why
Closing a reader while a lookup is using it creates intermittent failures. Replacing City and ASN independently creates attributions assembled from two different database revisions. Treating initial absence and refresh failure as the same state either lies about readiness or throws away valid data.
Consequences
maxmindis an optional peer loaded lazily bycreateMaxMindGeoIpLoader.- Applications provide database paths and decide how unavailable/reload errors affect their own readiness.
- The framework returns generic attribution fields and owns no download, licensing, analytics or storage policy.