overview: one endpoint, live projections and a response cache (m36)

docs/how-to/set-up-admin-authentication.md

@@ -62,7 +62,7 @@ Which of steps 4 and 5 applies to your server depends on its authority. Under `n
 Login is `POST /api/auth/login` with a JSON body. Without a session, the API answers 401:
 
 ```sh
-curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8451/api/stats
+curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8451/api/overview
 ```
 
 ```
@@ -92,7 +92,7 @@ The cookie is named `nxdns_session` and carries `HttpOnly; SameSite=Lax; Path=/`
 
 ```sh
 curl -sS -b /tmp/nxdns-lab/cookies.txt -o /dev/null -w '%{http_code}\n' \
-  http://127.0.0.1:8451/api/stats
+  http://127.0.0.1:8451/api/overview
 ```
 
 ```
@@ -125,13 +125,13 @@ Sessions live in memory only. A restart logs everyone out. Thirty-two concurrent
 ```sh
 curl -sS -b /tmp/nxdns-lab/cookies.txt -c /tmp/nxdns-lab/cookies.txt \
   -X POST http://127.0.0.1:8451/api/auth/logout
-curl -sS -b /tmp/nxdns-lab/cookies.txt -o /dev/null -w 'stats: %{http_code}\n' \
-  http://127.0.0.1:8451/api/stats
+curl -sS -b /tmp/nxdns-lab/cookies.txt -o /dev/null -w 'overview: %{http_code}\n' \
+  http://127.0.0.1:8451/api/overview
 ```
 
 ```
 {"authenticated":false}
-stats: 401
+overview: 401
 ```
 
 Logging out with a stale cookie, or with none, answers the same way. The point of logging out is to end up logged out, and that is where such a request already is.
@@ -154,7 +154,7 @@ Changing the password ends every session, including the one that made the change
 
 ```sh
 curl -sS -b /tmp/nxdns-lab/c2.txt -o /dev/null -w 'old session: %{http_code}\n' \
-  http://127.0.0.1:8451/api/stats
+  http://127.0.0.1:8451/api/overview
 curl -sS -X POST http://127.0.0.1:8451/api/auth/login \
   -H 'content-type: application/json' -d '{"password":"lab-password"}' \
   -w ' (old password)\n'
@@ -217,14 +217,14 @@ curl -sS -X POST http://127.0.0.1:8451/api/auth/login \
 curl -sS -c /tmp/nxdns-lab/c5.txt -X POST http://127.0.0.1:8451/api/auth/login \
   -H 'content-type: application/json' -d '{"password":"offline-password"}' \
   -w ' (new password, http %{http_code})\n'
-curl -sS -b /tmp/nxdns-lab/c5.txt -o /dev/null -w 'stats: %{http_code}\n' \
-  http://127.0.0.1:8451/api/stats
+curl -sS -b /tmp/nxdns-lab/c5.txt -o /dev/null -w 'overview: %{http_code}\n' \
+  http://127.0.0.1:8451/api/overview
 ```
 
 ```
 {"error":"invalid password"} (old password, http 401)
 {"authenticated":true,"auth_required":true} (new password, http 200)
-stats: 200
+overview: 200
 ```
 
 The next export shows the new hash and a null `password` again:
@@ -245,7 +245,7 @@ See [back up and restore](back-up-and-restore.md) for when `import` does need `-
 Authentication is off. Every route is open, and a login attempt succeeds without minting anything — there is nothing to log in to, and a session that authorises nothing would be a lie for the browser to store:
 
 ```sh
-curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8453/api/stats
+curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8453/api/overview
 curl -sS -X POST http://127.0.0.1:8453/api/auth/login \
   -H 'content-type: application/json' -d '{"password":"anything"}'
 ```

docs/reference/api.md

@@ -109,11 +109,7 @@ Auth `open` means no session is required; `session` means a valid session cookie
 | GET | `/api/queries` | session | counted | read | Query log rows for the Activity page |
 | GET | `/api/queries/{id}` | session | counted | read | One query, fully explained |
 | GET | `/api/queries/live` | session | exempt | read | Live query stream (server-sent events) |
-| GET | `/api/stats` | session | counted | read | Totals for a period |
-| GET | `/api/stats/timeseries` | session | counted | read | Bucketed counts for a period |
-| GET | `/api/stats/types` | session | counted | read | Query-type breakdown for a period |
-| GET | `/api/stats/routes` | session | counted | read | How the period's queries were answered |
-| GET | `/api/stats/clients` | session | counted | read | Per-client bucketed counts for a period |
+| GET | `/api/overview` | session | counted | read | Everything the Overview page draws, for one period |
 | GET | `/api/lookup` | session | counted | read | Explain a domain |
 | GET | `/api/diagnostics` | session | counted | read | Operational event log |
 | DELETE | `/api/diagnostics` | session | counted | runtime action | Purge every resolved event |
@@ -221,6 +217,6 @@ A non-empty `rewrites.cname_target` on a query detail means the decision landed
 
 ### Coverage
 
-Every window-bounded read — `GET /api/queries` and the five `GET /api/stats*` endpoints — answers with a `coverage` object: `available_since` is the oldest instant the query log is still complete for, and `complete` is true only when the window the request asked about starts at or after it. Retention deletes rows and advances the watermark in one transaction, so a client can tell an empty window from a pruned one instead of charting the gap as zero. A request with no lower bound at all asks about the whole of history, and is never complete.
+Every window-bounded read — `GET /api/queries` and `GET /api/overview` — answers with a `coverage` object: `available_since` is the oldest instant the query log is still complete for, and `complete` is true only when the window the request asked about starts at or after it. Retention deletes rows and advances the watermark in one transaction, so a client can tell an empty window from a pruned one instead of charting the gap as zero. A request with no lower bound at all asks about the whole of history, and is never complete.
 
-Each of these responses reads its rows and its watermark inside one SQLite read transaction, so retention cannot prune between the two and hand back pre-prune rows tagged with a post-prune `available_since`. Coherence stops there: two separate requests are two separate reads, and queries logged between them can move the counts.
+Each of these responses reads its rows and its watermark inside one SQLite read transaction, so retention cannot prune between the two and hand back pre-prune rows tagged with a post-prune `available_since`. `GET /api/overview` puts every Overview panel inside that one transaction, so its totals and its four breakdowns describe one database state. Coherence stops there: two separate requests are two separate reads, and queries logged between them can move the counts.