Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

docs(sdk): /health answers nine keys with idle unloading on, and the page says so

Aashish1a16cabe0071
diff --git a/docs/typescript-sdk.md b/docs/typescript-sdk.md
index 2cbbbeb8..bc389977 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 e76d1f0f..a0d95359 100644
--- a/tests/test_serve.py
+++ b/tests/test_serve.py
@@ -3632,6 +3632,12 @@ def test_a_restarted_app_still_queues_concurrent_requests(monkeypatch):
# 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 @@ TS_SDK_OLD_CLAIM = (
)
+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` "