Rewrite the README sentences that fail the prose rules or disagree with the code

A fresh read of README.md whole against the rules of issue 157, with every
statement except measured figures checked against the code on next. Four
sentences fail the prose rules, all in sections added since 742e759: the
origin change definition, the first uses of TTL and SOA record, and the
geojs request. Five disagree with the code: the geojs request carries only
the addresses the cache does not hold; after a write fails on SQLite's hard
heap limit, the prefix handler also writes its origin changes again, and
the PTR and geolocation caches write their answers again; the test rerun on
failure drops -cover; and latitude and longitude are in degrees, which
their names do not say.

Model: fable-5-1
This commit is contained in:
sneak committed 2026-11-10 16:07:33 +00:00
1 parent 6de44ac054
commit ed7a565e91
1 file changed
+21 -15
+21 -15
View File
@@ -143,9 +143,9 @@ and origin AS can have two kept routes, one or none.
AS path, a next hop and a time. The next hop is the router the peer sends the
prefix's traffic to. RouteWatch records the peer itself as the next hop. The
page also lists the prefix's origin changes, newest first. An origin change is
an AS starting to announce the prefix, when its first peer carries it, or
stopping, when its last peer no longer does. The page shows at most the newest
5,000. Each row shows:
recorded when the first peer starts to carry the prefix with an origin AS, or
when the last peer stops. The page shows at most the newest 5,000. Each row
shows:
- the time
- announced or withdrawn
- the origin AS
@@ -197,8 +197,9 @@ also carries an `@meta` object:
- `api_version`: `1`
- `execution_time_ms`: the number of milliseconds the request took
Every value with a unit is a number, and the unit ends the field name. Examples
are `_ms`, `_seconds`, `_bytes`, `_per_sec` and `_per_min`.
Every value with a unit is a number. The unit ends the field name, as in `_ms`,
`_seconds`, `_bytes`, `_per_sec` and `_per_min`. `latitude` and `longitude` are
in degrees, and their names do not say so.
The paths:
@@ -502,11 +503,13 @@ How RouteWatch keeps the answers:
there.
- It writes new answers every 5 seconds to `cache.db` in the state directory
(see Configuration), and loads them from there at startup.
- An answer expires after the TTL of its records, the shortest one when there
are several. RouteWatch keeps it for at least 60 seconds and at most 24 hours.
- When an address has no PTR names, that answer expires after the SOA record's
minimum field, or the record's own TTL when that is shorter. RouteWatch keeps
it for at most 1 hour.
- Each DNS record carries a TTL, the time for which it may be kept. An answer
expires after the shortest TTL of its records. RouteWatch keeps it for at
least 60 seconds and at most 24 hours.
- When an address has no PTR names, the answer's SOA record says how long that
answer may be kept. The answer expires after the SOA record's minimum field,
or the record's own TTL when that is shorter. RouteWatch keeps it for at most
1 hour.
- An answer with no PTR names and no SOA record is not kept. Neither is one
whose SOA record has a TTL or minimum field of 0.
- A failed lookup is not kept, so the next lookup of the address asks again.
@@ -520,7 +523,8 @@ An IP lookup finds where each address is, on a best-effort basis. It uses two
sources:
- [geojs](https://www.geojs.io/) is asked first. One request carries every
address of the lookup, and it has 1 second to answer.
address of the lookup that the cache does not hold. geojs has 1 second to
answer.
- [DB-IP City Lite](https://db-ip.com/db/download/ip-to-city-lite) answers when
geojs has no answer for the address. It is a database file that RouteWatch
reads itself.
@@ -702,8 +706,10 @@ What happens at each limit:
allocating more.
- The SQLite hard heap limit: a database statement fails with an out-of-memory
error, which the handler logs. The prefix handler writes the routing table's
changes again in a later write. Everything else in the failed write is
dropped. The process keeps running.
changes and its origin changes again in a later write. Everything else in a
handler's failed write is dropped. The PTR cache and the geolocation part
write their answers to `cache.db` again in a later write. The process keeps
running.
- The handler queues: the handlers are the four parts that take the feed's
messages (see Design). The prefix handler's queue holds at most 100,000
messages, about 100 MiB. Each of the other three holds at most 20,000. When a
@@ -1070,8 +1076,8 @@ calls one of them. The scripts:
- `script/projectname`: print the project name, `routewatch`, which
`script/docker` uses as the image tag.
- `script/test`: build the `test` phase of the `Dockerfile` alone. It runs
`go test -short -count=1 -timeout 90s -race -cover ./...`, and reruns it with
`-v` on failure.
`go test -short -count=1 -timeout 90s -race -cover ./...`. On failure it runs
the tests again with `-v` and without `-cover`.
- `script/lint`: build the `lint` phase of the `Dockerfile` alone. It runs
`golangci-lint` v2.14.0 with `.golangci.yml`.
- `script/fmt`: format the Go code with `go fmt` and the markdown with