Skip to content

docs(sdk): /health answers nine keys with idle unloading on, and the gate could not see them - #1143

Merged
NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
aashish254:docs-health-nine-keys
Oct 12, 2026
Merged

NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
aashish254:docs-health-nine-keys

Conversation

@aashish254

Copy link
Copy Markdown
Contributor

What

Two halves of the same claim, both wrong, both about the fields /health answers:

  • docs/typescript-sdk.md told a reader that laya-serve answers seven keys and cross-referenced
    docs/http-api.md as documenting "the same seven keys". That page documents nine (:84-85), and
    the handler really does answer nine on a deployment that sets LAYA_IDLE_UNLOAD_SECONDS.
  • tests/test_serve.py's gate over that sentence could not see the difference. It read
    k.value for k in value.keys if isinstance(k, ast.Constant) off the handler's return dict, and
    **idle is a None key in that AST, so the two conditional fields were invisible and the page
    matched the code exactly while both were wrong.

The gate now resolves a starred spread to the dict the handler assigned to that name, the sentence
names all nine keys plus the liveness-only arm, and a new assertion pins the pair so the reader
cannot silently lose it again. 6 insertions and 2 deletions in the page, 49 and 12 in the test.

Why

LAYA_IDLE_UNLOAD_SECONDS is a shipped, documented, forwarded setting:
compose.http.yaml:59 passes it through, docs/docker.md:343 and docs/http-api.md:36 document it
in their environment tables, and laya/serve.py:1189-1190 turns it into two response fields. So the
SDK design page's "seven keys" is a shape a caller can build against and be wrong about.

The same page never mentioned the other arm either. On a deployment with LAYA_API_KEY set,
laya/serve.py:1168 short-circuits to LIVENESS_ONLY = {"status": "ok"}, and the SDK already
handles that deliberately: sdk/typescript/src/response.ts:35-44 requires only status and checks
device/loaded "when the server does send it", sdk/typescript/src/types.ts:179-185 documents
the withholding in the Health type, and sdk/typescript/test/client.test.mjs:39 is a test named
"health accepts the liveness-only answer a locked-down server gives an anonymous probe". The design
page is the last copy still describing one unconditional shape, which is the copy a reader trusts
before they read the source.

How it was verified

The gate was green while the page was wrong, so the first witness is the live handler next to the
gate's own helpers, run against this tree:

$ PYTHONDONTWRITEBYTECODE=1 PYTHONPATH="$PWD" .venv/bin/python -B /tmp/probe_health_gate.py
gate _serve_health_return_keys(): ['checkpoint_devices', 'cpu_fallbacks', 'device', 'device_is_preference', 'loaded', 'revisions', 'status']
gate _ts_sdk_health_claim_keys() : ['checkpoint_devices', 'cpu_fallbacks', 'device', 'device_is_preference', 'loaded', 'revisions', 'status']
gate passes today (documented == handler_keys): True
idle pair visible to the gate: False
runtime keys, anonymous probe on a keyed deployment: ['status']
runtime keys, authenticated probe, idle unload on : ['checkpoint_devices', 'cpu_fallbacks', 'device', 'device_is_preference', 'idle_seconds', 'idle_unload_seconds', 'loaded', 'revisions', 'status']
count: 1 vs 9
missing from the page's list: ['idle_seconds', 'idle_unload_seconds']

That is the pre-fix tree: the gate and the page agree on seven, and the handler answers nine (or
one, unauthenticated). Re-run against the patched helper and the same page sentence:

gate _serve_health_return_keys(): ['checkpoint_devices', 'cpu_fallbacks', 'device', 'device_is_preference', 'idle_seconds', 'idle_unload_seconds', 'loaded', 'revisions', 'status']
gate _ts_sdk_health_claim_keys() : ['checkpoint_devices', 'cpu_fallbacks', 'device', 'device_is_preference', 'idle_seconds', 'idle_unload_seconds', 'loaded', 'revisions', 'status']
gate passes today (documented == handler_keys): True
idle pair visible to the gate: True
runtime keys, anonymous probe on a keyed deployment: ['status']
runtime keys, authenticated probe, idle unload on : ['checkpoint_devices', 'cpu_fallbacks', 'device', 'device_is_preference', 'idle_seconds', 'idle_unload_seconds', 'loaded', 'revisions', 'status']
count: 1 vs 9
missing from the page's list: []

The runtime lines are unchanged between the two runs, which is the point: only the gate and the
page moved.

Then four mutants, each applied to the committed tree, each reverted with git checkout -- after
one run:

mutant expected result
page reverted to the seven-key sentence, new gate kept fail 1 failed, 1 passed rc=1 KILLED
gate stops resolving the starred spread, new page kept fail 1 failed, 1 passed rc=1 KILLED
gate stops filtering LAYA_* names fail 1 failed, 1 passed rc=1 KILLED
handler's idle becomes an unresolvable call, so the pair vanishes fail 1 failed, 1 passed rc=1 KILLED

The fourth mutant is what makes the new assertion worth having: a future reshaping of the spread
fails with a message pointing at the handler and the page, instead of quietly dropping two fields
from the pinned set.

The page's sentence is scanned between two anchors, so it keeps the phrases the gate looks for
(public \/health` returns, Prediction never probes health first) and stays clear of the banned three-key literal. Naming both settings inside that span is why the scanner now drops ALL-CAPS backticks: a response key of this payload is never upper case, so LAYA_IDLE_UNLOAD_SECONDSandLAYA_API_KEY` are settings, not fields.

Gates:

$ PYTHONDONTWRITEBYTECODE=1 python -B scripts/test_suites.py
FAIL: 0
497 passed, 1 skipped, 5 warnings in 16.45s
all 87 suites passed
$ python -B -m pytest tests/test_serve.py -k ts_sdk_health -q
2 passed, 287 deselected in 0.19s
$ ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120
All checks passed!
$ python -B -m compileall -q laya/ tests/
(no output, exit 0)

The suite count is 497 before and after: this change extends two existing tests rather than adding
a third.

ruff check tests/test_serve.py --select=…F811 reports one error, the import re at :3765 that
shadows :12; it is there at upstream/main too (git show upstream/main:tests/test_serve.py
gives the same single error), the CI lint path is ruff check laya/, and removing it is unrelated
work, so it is left alone.

Diff scan for secrets. Literal result of grepping
api[_-]?key|secret|token|password|bearer|sk-[A-Za-z0-9]|ghp_|AKIA|private[_-]?key over git diff HEAD~1:

14:+on a deployment with `LAYA_API_KEY` set gets `{"status": "ok"}` alone, because the withheld fields

One hit, and it is the name of an environment variable in a sentence explaining what an
anonymous probe gets. No value, no key material, nothing credential-shaped anywhere in the diff.

Checklist

  • Focused on one change (split unrelated work into another PR)
  • Rebased on the latest main
  • Tests pass locally
  • Docs or examples updated when the public API changed

…page says so

The AST gate read only the return dict's own literal keys, so the two conditional fields
spread by `**idle` were invisible and docs/typescript-sdk.md under-reported the shape while
cross-referencing the page that documents them. Resolve a starred spread to the dict it
unpacks, keep the sentence pinned, and name the liveness-only arm the client accepts.
@NandhaKishorM
NandhaKishorM merged commit 005d667 into NandhaKishorM:main Oct 12, 2026
40 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Merged. The gate was the bug, not the page.

_serve_health_return_keys read the return dict's own literal keys, and **idle spreads a local conditional dict, so idle_unload_seconds and idle_seconds were invisible to it. The page under-reported the response by two fields on any deployment that sets LAYA_IDLE_UNLOAD_SECONDS, and the test whose whole job is to catch that could not see them. Resolving a starred spread to the local dict it unpacks, and looking through ({...} if cond else {}), is the right generalisation, and test_idle_details_stay_authenticated already read both fields off a live handler, so the two halves now agree.

The anonymous-probe half is worth having on the SDK page too: on a deployment with LAYA_API_KEY set, an unauthenticated /health is {"status": "ok"} alone, that body is a healthy response, and health() returns it rather than raising. A caller who treats a missing loaded key as an error would otherwise read a correct 200 as a failure.

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.

2 participants