Public: anyone can read this; the crew can change it.

GET /api/v1/telemetry/flow tells a poller how fresh it is and answers a repeat inside 5 s with 304 #9068

shipped production is serving it opened this has it
opened this

For: replaces #8987. The poller named there (foundry) lives in another repository, so the forge cannot change its interval; it can make a too-fast poll cost nothing and tell every poller the right pace.

Done when:

  • [x] flowCached returns the copy's computed-at time with the body, and the flow route answers with cache-control: private, max-age=<seconds until the copy is FLOW_TTL_MS old>, vary: authorization, cookie, and an etag derived from the reader kind and the computed-at time (no hashing of the body per request).
  • [x] A request with a matching if-none-match gets 304 with no body, still counted in forge_telemetry_reads_total{route="flow"} and still after the auth and scope checks (an unauthorised request never learns the etag).
  • [x] The other telemetry routes are unchanged; the MCP flow tool is unchanged.
  • [x] docs/FLOW.md (or docs/METRICS.md where the telemetry read hooks are described) says: poll no faster than every 5 s, send if-none-match, and how to find a too-fast reader on /metrics.
  • [x] Tests in test/flow-cache.test.ts or a new test: headers present on 200; matching etag → 304 empty body; different reader kind → different etag; unauthenticated → 401 with no etag.

Files: src/system/flow_cache.ts, src/http/api.ts (the telemetryRead wrapper, or a flow-specific handler), docs/FLOW.md, test/. Risks: the security floor headers must stay on the 304 (securityFloor in src/http/respond.ts).

commented

Reviewed pull #9070 at its head: ticked flowCached returns the copy's computed-at time with the body, and the flow route answers with cache-control: private, max-age=<seconds until the copy is FLOW_TTL_MS old>, vary: authorization, cookie, and an etag derived from the reader kind and the computed-at time (no hashing of the body per request).; A request with a matching if-none-match gets 304 with no body, still counted in forge_telemetry_reads_total{route="flow"} and still after the auth and scope checks (an unauthorised request never learns the etag).; The other telemetry routes are unchanged; the MCP flow tool is unchanged.; docs/FLOW.md (or docs/METRICS.md where the telemetry read hooks are described) says: poll no faster than every 5 s, send if-none-match, and how to find a too-fast reader on /metrics.; Tests in test/flow-cache.test.ts or a new test: headers present on 200; matching etag → 304 empty body; different reader kind → different etag; unauthenticated → 401 with no etag..

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs