diff --git a/README.md b/README.md index 78dbf35..5f003b7 100644 --- a/README.md +++ b/README.md @@ -9,19 +9,38 @@ table in real time. It works like this: ## Rationale -RIPE RIS Live streams the BGP updates that RIPE's route collectors receive, as -they happen, from the moment a client connects. It reports changes, not the -routing table they add up to, so it cannot say which AS an IP address is routed -to now or which routes a prefix has. RouteWatch applies the feed's updates to a -routing table that it keeps in memory, with a copy in its own SQLite database. -It answers IP-to-AS lookups and prefix pages from that table. +RouteWatch exists to serve our other services as an internal API for information +about IP addresses. -The feed sends no table when a client connects. So the routing table holds only -the routes announced since RouteWatch first started. An IP-to-AS lookup finds -nothing for an address whose routes have not been announced since then. The -routing table also misses updates RouteWatch drops when it falls behind, and -updates sent while it is stopped. So a lookup or a prefix page can show a route -the feed has withdrawn. +RouteWatch follows BGP routing table updates from RIPE RIS Live. RIS Live +streams the updates that RIPE's route collectors receive, as they happen, from +the moment a client connects. It reports changes, not the routing table they add +up to. RouteWatch applies those changes to a routing table that it keeps in +memory, with a copy in its own SQLite database. From that table, RouteWatch sees +directly: + +- which AS each IP address is routed to +- which announced prefix holds each IP address, and how big that prefix is + +RouteWatch adds details of each AS from WHOIS, the public directory of the +internet registries. The details include the organisation that holds the AS. +RouteWatch keeps them in its database and looks them up again once they are 30 +days old. An IP lookup answers from those stored details and never waits for +WHOIS. + +So our own services can ask RouteWatch about an IP address, instead of each +working it out for itself. + +RIS Live sends no routing table when a client connects. So the routing table +holds only the routes announced since RouteWatch first started. An IP lookup +finds no route for an address until a prefix that holds it is announced. The +routing table also misses these updates: + +- those sent while RouteWatch is stopped +- those that RouteWatch drops when it falls behind + +A lookup or a prefix page can therefore show a route that has since been +withdrawn. ## Features diff --git a/TODO.md b/TODO.md index 31d485c..3f59e85 100644 --- a/TODO.md +++ b/TODO.md @@ -35,6 +35,10 @@ tested. # Completed Steps +- 2026-10-27: README "Rationale" says why RouteWatch exists: to answer our other + services' questions about IP addresses, from its own routing table and the + WHOIS details it keeps. It still says what RIS Live does not give (closes + #204) - 2026-10-27: every JSON answer carries `@meta`. A panic on a JSON route answers 500 with the JSON error body. `/status.json` and the health check answer 405 with the JSON error body to any method they do not take. The 500 and the 405