From 1a16cabe00719b718a7558e2db151a34463d6440 Mon Sep 17 00:00:00 2001 From: Aashish <145881415+aashish254@users.noreply.github.com> Date: Mon, 12 Oct 2026 03:26:26 +0545 Subject: [PATCH] docs(sdk): /health answers nine keys with idle unloading on, and the 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. --- docs/typescript-sdk.md | 8 ++++-- tests/test_serve.py | 61 +++++++++++++++++++++++++++++++++--------- 2 files changed, 55 insertions(+), 14 deletions(-) diff --git a/docs/typescript-sdk.md b/docs/typescript-sdk.md index 2cbbbeb85..bc389977d 100644 --- a/docs/typescript-sdk.md +++ b/docs/typescript-sdk.md @@ -66,8 +66,12 @@ An option that cannot mean anything is refused locally, before the request goes budget that is not a positive integer, a threshold outside `[0, 1]`, or a threshold map that is empty or holds a value outside `[0, 1]`. Nothing is silently ignored. Laya's public `/health` returns `status`, `loaded`, `revisions`, `device`, `device_is_preference`, -`checkpoint_devices`, and `cpu_fallbacks` -- the same seven keys the laya-serve deployment -page documents; see [HTTP API](http-api.md). Prediction never probes health first. +`checkpoint_devices`, and `cpu_fallbacks` to a caller it can authenticate, plus +`idle_unload_seconds` and `idle_seconds` on a deployment that sets `LAYA_IDLE_UNLOAD_SECONDS` -- +seven keys, or nine there, exactly as [HTTP API](http-api.md) documents them. An anonymous probe +on a deployment with `LAYA_API_KEY` set gets `{"status": "ok"}` alone, because the withheld fields +name resident checkpoints, their revisions and the host's device state; that body is a healthy +response, and `health()` returns it rather than raising. Prediction never probes health first. FastAPI detail strings and validation arrays are preserved as `LayaAPIError` messages/details. Structured error envelopes from compatible backends are also diff --git a/tests/test_serve.py b/tests/test_serve.py index e76d1f0f2..a0d953598 100644 --- a/tests/test_serve.py +++ b/tests/test_serve.py @@ -3632,6 +3632,12 @@ def predict(self, *args, **kwargs): # reporting) describe the full shape, so the SDK page contradicted them. The gate AST-parses the # handler's returns so the doc's key set has to match the code's -- any new /health field added # to the return dict must be named on this page too, or the test fails with the exact mismatch. +# Reading only the return dict's own keys left one kind of field out: `**idle` spreads a local +# conditional dict, so `idle_unload_seconds` and `idle_seconds` were invisible to the gate and the +# page under-reported the shape by two fields on a deployment that sets +# `LAYA_IDLE_UNLOAD_SECONDS`. `test_idle_details_stay_authenticated` and +# `test_idle_unload_reloads_on_the_next_request` read both of them off a live handler, so the gate +# now resolves a starred spread to the local dict it unpacks. TS_SDK_PAGE = os.path.join(ROOT, "docs", "typescript-sdk.md") TS_SDK_OLD_CLAIM = ( "Laya's public `/health` returns `status`, `loaded`, and `device`. " @@ -3639,11 +3645,22 @@ def predict(self, *args, **kwargs): ) +def _literal_dict_keys(value): + """Keys of a dict literal, looking through `({...} if condition else {})`.""" + if isinstance(value, ast.Dict): + return {key.value for key in value.keys if isinstance(key, ast.Constant)} + if isinstance(value, ast.IfExp): + return _literal_dict_keys(value.body) | _literal_dict_keys(value.orelse) + return set() + + def _serve_health_return_keys(): - """Every literal dict key the `health` handler returns across all branches. + """Every dict key the `health` handler returns across all branches. `LIVENESS_ONLY` is a module-level dict, so the `return LIVENESS_ONLY` branch resolves via - the module scope; the authorized `return {...}` branch contributes its own keys directly. + the module scope; the authorized `return {...}` branch contributes its own keys directly, and + a `**name` spread contributes the keys of the dict `name` was assigned -- that is how the two + conditional idle fields reach the response, and reading the return dict's own keys missed them. """ with open(os.path.join(ROOT, "laya", "serve.py"), encoding="utf-8") as handle: tree = ast.parse(handle.read(), filename="laya/serve.py") @@ -3652,20 +3669,30 @@ def _serve_health_return_keys(): if isinstance(node, ast.Assign) and isinstance(node.value, ast.Dict): for target in node.targets: if isinstance(target, ast.Name): - module_dicts[target.id] = { - k.value for k in node.value.keys if isinstance(k, ast.Constant) - } + module_dicts[target.id] = _literal_dict_keys(node.value) for node in ast.walk(tree): if isinstance(node, ast.FunctionDef) and node.name == "health": + local_dicts = {} + for assign in ast.walk(node): + if isinstance(assign, ast.Assign): + for target in assign.targets: + if isinstance(target, ast.Name): + local_dicts[target.id] = _literal_dict_keys(assign.value) keys = set() for ret in ast.walk(node): if not isinstance(ret, ast.Return) or ret.value is None: continue value = ret.value if isinstance(value, ast.Dict): - keys.update(k.value for k in value.keys if isinstance(k, ast.Constant)) - elif isinstance(value, ast.Name) and value.id in module_dicts: - keys.update(module_dicts[value.id]) + for key, spread in zip(value.keys, value.values): + if isinstance(key, ast.Constant): + keys.add(key.value) + elif key is None and isinstance(spread, ast.Name): + keys.update(local_dicts.get(spread.id, ())) + keys.update(module_dicts.get(spread.id, ())) + elif isinstance(value, ast.Name): + keys.update(local_dicts.get(value.id, ())) + keys.update(module_dicts.get(value.id, ())) return keys raise AssertionError("no `health` handler found in laya/serve.py -- gate is checking a moved symbol") @@ -3673,7 +3700,7 @@ def _serve_health_return_keys(): def _ts_sdk_health_claim_keys(): r"""The backticked key names in the sentence that opens 'public `/health` returns'. - The claim spans two lines on this page, so read from "public \`/health\` returns" up to the + The claim spans several lines on this page, so read from "public \`/health\` returns" up to the sentence-ending "Prediction never probes health first" before collecting backticked names; that stops the scan from picking up later backticked references. """ @@ -3685,21 +3712,31 @@ def _ts_sdk_health_claim_keys(): end = tail.find("Prediction never probes health first") assert end != -1, "the /health claim's tail sentence is gone -- the gate cannot bound its scan" sentence = tail[:end] - return set(re.findall(r"`([A-Za-z_][A-Za-z_0-9]*)`", sentence)) - {"health"} + names = set(re.findall(r"`([A-Za-z_][A-Za-z_0-9]*)`", sentence)) - {"health"} + # The sentence names the two settings that decide which fields appear. A response key of this + # payload is never spelled in upper case, so an ALL-CAPS backtick is an environment variable and + # not a field the caller reads off the body. + return {name for name in names if not name.isupper()} def test_ts_sdk_health_claim_matches_the_handler(): """The SDK page must name exactly the keys `laya/serve.py`'s `health` handler returns.""" assert "returns `status`, `loaded`, and `device`" in TS_SDK_OLD_CLAIM, ( "the pre-fix literal must itself carry the wrong key set, otherwise this ban is vacuous") - # Sanity-check the AST extraction: the shipped code returns seven keys on the authorized - # branch, so a future PR that reshapes /health without updating this page fails below. + # Sanity-check the AST extraction: the shipped code returns seven keys on the authorized branch + # and spreads two more when idle unloading is on, so a future PR that reshapes /health without + # updating this page fails below. handler_keys = _serve_health_return_keys() assert "status" in handler_keys, "the LIVENESS_ONLY short-circuit disappeared; the AST reader missed it" for key in ("loaded", "revisions", "device", "device_is_preference", "checkpoint_devices", "cpu_fallbacks"): assert key in handler_keys, "%s is not in the /health handler's return set -- did the " \ "shape change without this test being updated?" % key + assert {"idle_unload_seconds", "idle_seconds"} <= handler_keys, ( + "`health` no longer spreads a conditional dict into its return, or the spread is now a shape " + "this reader cannot resolve. The handler answers nine keys on a deployment with " + "LAYA_IDLE_UNLOAD_SECONDS set and docs/typescript-sdk.md names all nine; re-read the " + "handler before re-pinning either side.") documented = _ts_sdk_health_claim_keys() assert documented == handler_keys, ( "docs/typescript-sdk.md's /health sentence names %s, but `laya/serve.py`'s `health` "