meta: metaserve deployment and API doc updates for the scale work - #16
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/healthzis a readiness check, not liveness. It answers503 {"status":"starting"}with aRetry-Afterheader until an artifact loads, and200 {"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.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/searchwith an honestRetry-After, backing off from 30s doubling to--interval).people/{id}andseries/{id}: documents the additive?limit=/?offset=params and the newauthored_total,narrated_total,works_total,limit,offsetfields. People pages at 100 by default (max 500) with the window applied toauthoredandnarratedindependently; series returns the whole member list unless?limitis 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.)--dbdescribed 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.mdmetaservebinary. New "The published image" section covering the cache volume (--poll --cache /data/cache,/datadeclared 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.ymlalso triggers oninternal/build/**/cmd/metabuild/**, so a builder change reaches a published artifact.metabuild --addedfrom the CLI table - that flag is retired (added_atnow lives in the data).Verification
Every claim was checked against the code on
origin/feat/serve-at-scalerather than the PR description - including the exact/healthzbodies, theclampLimit/clampOffsetdefaults and maxima, the field names, theftsQuerybehaviour, 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 buildpasses (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.jsonand friends) throughoutdata-model.md, plusoverview.md's "one file per entity" / "sharded JSON" / "id/shard agreement" lines and one line incontributing-data.md. That is stale after the pack migration (KodeStar/audiosilo-meta#1259), but it is a coherent rewrite ofdata-model.mdrather than a few lines, and half-fixing it here would leaveoverview.mdcontradictingdata-model.md. Worth its own PR. Same reasoning for the missinglibeximporter source andmetamigratein the CLI table.