Skip to content

docs(security): /health sample must filter to revisions, not claim four keys - #994

Merged
NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
aashish254:fix-security-health-sample
Oct 7, 2026
Merged

NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
aashish254:fix-security-health-sample

Conversation

@aashish254

Copy link
Copy Markdown
Contributor

What

docs/security.md's "Confirm what actually loaded" section shows curl -s localhost:8000/health
followed by a four-key JSON comment ending in "device":"auto". The handler at
laya/serve.py:667-674 returns seven keys (status, loaded, revisions, device, device_is_preference, checkpoint_devices, cpu_fallbacks), and "auto" is what the LAYA_DEVICE environment variable
defaults to -- not a value the handler emits. #811 already fixed the sibling page, docs/http-api.md,
and pinned its sample to the handler's return dict. This PR applies the same discipline to
docs/security.md and adds a matching gate.

The doc now filters to .revisions with jq, which is what that section is actually about:

```bash
curl -s localhost:8000/health | jq '.revisions'
# {"english": "55cf4c4e…"}
```

`/health` returns seven top-level fields, documented in [the HTTP API page](http-api.md);
this section filters to the one it is about.

Why

A reader following the old snippet to write their own healthcheck would find three fields silently
missing from their parser -- device_is_preference, checkpoint_devices, and cpu_fallbacks all
carry the "where the work is really running" signal that #574 and the device-fact reporting added.
"device":"auto" is worse than merely stale: the handler never returns "auto", so a probe that
asserted body["device"] != "auto" as a "config vs measurement" check would go red on every real
server. docs/http-api.md:70-73 already documents this contract and the gate at
tests/test_serve.py::test_http_api_page_documents_exactly_the_health_fields enforces it there.
docs/security.md was the one page that still quoted the pre-#574 shape.

The filter, not a longer literal, is the fix because the section is about revisions. Showing a
seven-key blob to introduce one field buries the point; showing what jq extracts keeps the
snippet useful. The gate accepts either shape: a curl line that pipes through a filter, or a raw
sample whose JSON keys exactly match health()'s return dict -- read out of the source with the
same _health_return_keys() helper #811's gate uses.

How it was verified

PYTHONDONTWRITEBYTECODE=1 python -B -m pytest tests/test_serve.py -q
# 249 passed in 8.64s   (baseline 248; +1 new test)

/opt/homebrew/bin/ruff check tests/test_serve.py laya/ \
  --select=E9,F63,F7,F82,F401,F811 --line-length=120
# All checks passed!

PYTHONDONTWRITEBYTECODE=1 python -B -m compileall -q laya/ tests/
# 0

PYTHONDONTWRITEBYTECODE=1 python -B ../laya-bench/mutate_security_health_sample.py
# baseline: 1 passed
# m1 pre-fix 4-key raw /health sample restored:          CAUGHT
# m2 jq filter removed, doc leaves a partial raw sample: CAUGHT
# m3 filter kept, but no example of the filtered shape:  CAUGHT
# m4 second /health curl snippet added:                  CAUGHT
# 4/4 mutants caught

Secret scan on the full diff (regex api[_-]?key|secret|password|credential|bearer|sk-…|ghp_…|AKIA…|BEGIN (RSA|PRIVATE|OPENSSH)): no matches. No credentials in this diff.

Deconfliction (gh pr list --state open --limit 500 --json number,title,files):
docs/security.md has zero open PRs. tests/test_serve.py has one open PR (#963, "fix
docker-compose healthcheck") but no overlapping hunks: my changes are one import line at line 12
and one test function appended after line 2842; the pre-existing tail of the file is untouched.

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

…ur keys

The "Confirm what actually loaded" section printed a 4-key /health payload
ending in `"device":"auto"`; laya/serve.py's health() returns seven keys,
and `"auto"` is what LAYA_DEVICE defaults to, not a value the handler
emits. NandhaKishorM#811 pinned docs/http-api.md to the handler's own return dict;
this covers the sibling page the same way. The doc now filters to
`.revisions` with jq and cross-references http-api.md for the full shape;
tests/test_serve.py accepts either a filtered curl or a raw sample that
names every health() key.
@NandhaKishorM
NandhaKishorM merged commit c141936 into NandhaKishorM:main Oct 7, 2026
32 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Merged in 0.3.29.

The security page's /health sample claimed four keys where it should filter to revisions. On the security page specifically, a sample that over-states what an endpoint returns is the kind of thing a reader uses to decide what is safe to expose.

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