Use Hypercorn for dual-stack GeoIP binds on Railway

Author: Rieranthony

apps/geoip/README.md

@@ -59,7 +59,7 @@ GEOIP_SERVICE_URL=http://localhost:8083
 
 Deploy this app as its own Railway service named `geoip`.
 
-The service binds to `::` by default so Railway private networking can reach it in both new dual-stack environments and older IPv6-only ones.
+The service uses Hypercorn and binds both `0.0.0.0` and `::` by default so Railway's public deployment healthchecks and private networking can both reach it.
 
 Use `/live` as the Railway deployment healthcheck path. `/health` remains a readiness endpoint and can return `503` until the MaxMind databases have been downloaded and loaded.
 

apps/geoip/requirements.txt

@@ -1,4 +1,3 @@
 fastapi==0.115.12
 geoip2==5.1.0
-uvicorn[standard]==0.34.2
-
+hypercorn==0.18.0

apps/geoip/src/main.py

@@ -6,7 +6,6 @@
 from typing import AsyncIterator
 
 from fastapi import FastAPI, HTTPException, Response
-import uvicorn
 
 from .config import Settings
 from .database import GeoIPDatabaseManager
@@ -26,6 +25,17 @@ async def refresh_databases_forever(manager: GeoIPDatabaseManager) -> None:
 			logger.exception("Periodic GeoIP database refresh failed")
 
 
+def build_bind_addresses(host: str, port: int) -> list[str]:
+	normalized_host = host.strip()
+	if not normalized_host or normalized_host == "::":
+		return [f"0.0.0.0:{port}", f"[::]:{port}"]
+
+	if ":" in normalized_host and not normalized_host.startswith("["):
+		return [f"[{normalized_host}]:{port}"]
+
+	return [f"{normalized_host}:{port}"]
+
+
 def create_app(manager: GeoIPDatabaseManager | None = None) -> FastAPI:
 	if manager is None:
 		manager = GeoIPDatabaseManager(Settings.from_env())
@@ -73,5 +83,12 @@ async def lookup(payload: LookupRequest) -> LookupResponse:
 
 
 if __name__ == "__main__":
+	from hypercorn.asyncio import serve
+	from hypercorn.config import Config
+
 	settings = Settings.from_env()
-	uvicorn.run("src.main:app", host=settings.host, port=settings.port)
+	config = Config()
+	config.bind = build_bind_addresses(settings.host, settings.port)
+	config.accesslog = "-"
+	config.errorlog = "-"
+	asyncio.run(serve(app, config))

apps/geoip/tests/test_main.py

@@ -4,7 +4,7 @@
 
 from fastapi.testclient import TestClient
 
-from src.main import create_app
+from src.main import build_bind_addresses, create_app
 from src.models import HealthResponse, LookupResponse
 
 
@@ -73,6 +73,10 @@ def test_live_returns_200_even_when_not_ready() -> None:
 	assert response.json() == {"status": "ok"}
 
 
+def test_build_bind_addresses_defaults_to_dual_stack_for_railway() -> None:
+	assert build_bind_addresses("::", 8080) == ["0.0.0.0:8080", "[::]:8080"]
+
+
 def test_lookup_returns_payload() -> None:
 	with TestClient(create_app(FakeManager(ready=True))) as client:
 		response = client.post("/v1/lookup", json={"ip": "8.8.8.8"})