Skip to content

meta: metaserve deployment and API doc updates for the scale work - #16

Merged
KodeStar merged 1 commit into
mainfrom
docs/metaserve-at-scale
Aug 1, 2026
Merged

meta: metaserve deployment and API doc updates for the scale work#16
KodeStar merged 1 commit into
mainfrom
docs/metaserve-at-scale

Conversation

@KodeStar

@KodeStar KodeStar commented Aug 1, 2026

Copy link
Copy Markdown
Owner

Updates the meta developer docs to match metaserve's post-scale-work behaviour. The pages described the pre-#1261 shape, and one part was operationally dangerous.

Important

Merge after KodeStar/audiosilo-meta#1261 (feat/serve-at-scale), which is what makes all of this true. Landing it earlier documents behaviour that is not shipped yet.

docs-developers/meta/api.md

  • /healthz is a readiness check, not liveness. It answers 503 {"status":"starting"} with a Retry-After header until an artifact loads, and 200 {"status":"ok","built_at":...,"works":...} after. Adds a warning admonition: use it as the readiness/startup probe and never as a liveness probe - that would restart-loop a server patiently waiting out a GitHub outage, when the degraded boot is deliberate.
  • New "Boot and degraded start" section, replacing the now-false claim that the server "fetches the newest data release on boot so it never starts empty". Covers all three states: a reachable GitHub (with cache-hit adoption verified against the release's meta.sqlite.sha256, no download), an unreachable GitHub with something cached (newest cached artifact served, flagged stale - documented explicitly as a log-only signal, since no endpoint exposes it), and an unreachable GitHub with nothing cached (503s on /healthz, /api/v1/* and /abs/search with an honest Retry-After, backing off from 30s doubling to --interval).
  • Paging on people/{id} and series/{id}: documents the additive ?limit= / ?offset= params and the new authored_total, narrated_total, works_total, limit, offset fields. People pages at 100 by default (max 500) with the window applied to authored and narrated independently; series returns the whole member list unless ?limit is given (max 500), because the player's series rail depends on the complete list.
  • coverage/works ?q= is now a word-prefix FTS match over title/subtitle, authors, narrators and series names - no longer a title/author substring. (coverage/series-gaps ?q= is unchanged and was already described correctly.)
  • --db described as optional, with the "at least one of --db/--poll" rule; dropped the trailing note about a container "serving build-time data", which no longer exists; noted that superseded cache files are pruned on adopt.

docs-developers/meta/overview.md

  • The image ships no data: it is the site build plus the metaserve binary. New "The published image" section covering the cache volume (--poll --cache /data/cache, /data declared as the volume, budget two artifacts at peak), why a restart is cheap, that a dataless boot is a valid state rather than a crash, and readiness-only probing.
  • release.yml also triggers on internal/build/** / cmd/metabuild/**, so a builder change reaches a published artifact.
  • Dropped metabuild --added from the CLI table - that flag is retired (added_at now lives in the data).

Verification

Every claim was checked against the code on origin/feat/serve-at-scale rather than the PR description - including the exact /healthz bodies, the clampLimit/clampOffset defaults and maxima, the field names, the ftsQuery behaviour, and the Dockerfile/compose deployment shape. One correction that came out of that: the PR summary reads as though staleness is surfaced to clients, but it only appears in the log, so the docs say so explicitly.

npm run build passes (Docusaurus throws on broken links and anchors; two ## headings gained query strings, and nothing links to those anchors).

Deliberately not in this PR

The meta pages still document the pre-pack file-per-record layout (data/works/<shard>/<slug>/work.json and friends) throughout data-model.md, plus overview.md's "one file per entity" / "sharded JSON" / "id/shard agreement" lines and one line in contributing-data.md. That is stale after the pack migration (KodeStar/audiosilo-meta#1259), but it is a coherent rewrite of data-model.md rather than a few lines, and half-fixing it here would leave overview.md contradicting data-model.md. Worth its own PR. Same reasoning for the missing libex importer source and metamigrate in the CLI table.

metaserve's deployment behaviour changed with the serve-at-scale work
(KodeStar/audiosilo-meta#1261) and the pages described the old shape - one
part dangerously so.

api.md:
- /healthz is a READINESS check, not liveness: 503 {"status":"starting"}
  with Retry-After until an artifact loads, 200 with built_at after. Adds a
  warning against wiring it as a liveness probe, which would restart-loop a
  server deliberately waiting out a GitHub outage.
- New "Boot and degraded start" section replacing the "fetches the newest
  data release on boot so it never starts empty" claim: cached-artifact
  adoption by verified digest, the stale-cache fallback (log-only signal),
  and the nothing-cached 503 + honest Retry-After with 30s-to-interval
  backoff.
- people/{id} and series/{id} document ?limit=/?offset= and the new
  authored_total / narrated_total / works_total / limit / offset fields.
  People page at 100 (max 500); series returns the whole list unless ?limit
  is given, because the player's series rail depends on it.
- coverage/works ?q= is a word-prefix FTS match over title, subtitle,
  authors, narrators and series names, no longer a title/author substring.
- --db described as optional; drops the now-false "build-time data" note.

overview.md:
- The image is the site build plus the metaserve binary with no data; adds
  "The published image" covering the cache volume, the valid dataless boot,
  and readiness probing.
- release.yml also triggers on internal/build/** and cmd/metabuild/**.
- Drops metabuild's retired --added flag.
@KodeStar
KodeStar merged commit 3ed4145 into main Aug 1, 2026
1 check passed
@KodeStar
KodeStar deleted the docs/metaserve-at-scale branch August 1, 2026 18:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant