Skip to content

feat(serve): support reverse-proxy URL prefixes - #656

Merged
NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
SomSamantray:feat/651-fastapi-root-path
Sep 29, 2026
Merged

NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
SomSamantray:feat/651-fastapi-root-path

Conversation

@SomSamantray

Copy link
Copy Markdown
Contributor

What

Configure LAYA_ROOT_PATH to publish the FastAPI server under a reverse-proxy URL prefix. Compose and the NixOS module can now pass the setting through, while the app’s internal routes remain unchanged.

Why

FastAPI’s generated OpenAPI and Swagger UI URLs need the public prefix when the server is behind a proxy. This lets deployments publish the API under paths such as /laya while the proxy strips that prefix before forwarding requests.

How it was verified

  • uv run --python 3.12 --extra serve --with pytest -- python -m pytest tests/test_serve.py -q — 54 passed, 1 skipped.
  • uv run --python 3.12 -- python tests/test_packaging.py — 110 passed.
  • uv run --python 3.12 -- python tests/test_compose_env.py — 49 passed.
  • uv run --python 3.12 --with ruff -- ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120 — passed.
  • uv run --python 3.12 -- python -m compileall -q laya/ tests/ — passed.
  • uv run --python 3.12 --with-requirements requirements-docs.txt -- zensical build --strict --clean — passed.
  • Browser check of /docs with LAYA_ROOT_PATH=/laya showed the /laya server prefix and loaded /laya/openapi.json successfully; no console errors.
  • Docker Compose rendering and Nix evaluation were unavailable locally (Docker and Nix are not installed).

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

Fixes #651

@Bruce-Yii Bruce-Yii left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Flagging an overlap rather than a defect: #670 implements the same thing, for the same issue, with the same environment variable.

Both read LAYA_ROOT_PATH, and this is the line #651 asked for verbatim, so there is nothing to reconcile about the knob itself. The reason it is worth raising is that GitHub will report the two as mergeable, and they are not safe to merge together. Both add a root_path= keyword to the same FastAPI(...) call, so the merged file has it twice:

$ git merge-tree --write-tree upstream/pr-656 upstream/pr-670   # exit 0, no conflict
$ python -m py_compile merged:laya/serve.py
  File "laya/serve.py", line 389
    root_path=_resolve_root_path(root_path),
SyntaxError: keyword argument repeated: root_path

Same shape in compose.http.yaml, which gets LAYA_ROOT_PATH twice in the same service environment mapping, and in nix/laya-serve.nix, which declares rootPath twice in the same attrset.

Things worth knowing about the two, since a maintainer has to pick:

  • This PR is the only one that asserts the contract a user actually sees — that /openapi.json reports servers: [{"url": "/laya"}] through a real request. #670 only asserts app.root_path, so a regression in the generated OpenAPI/Swagger URLs would pass its tests.
  • This PR is also the only one that tests the packaging wiring: that compose forwards the variable and the nix module declares rootPath. #670's nix and compose changes have no test.
  • #670 has two advantages: its _resolve_root_path() normalises input (LAYA_ROOT_PATH=laya → /laya, /laya/ → /laya, where this one passes either through raw), and create_app() takes an explicit root_path argument. Its CI has also actually executed, where this branch's four workflows are still waiting for approval.
  • The documentation here is better: a README paragraph and a worked /laya example, plus the packaging assertion above, against bare table rows.

Your CI here is queued for approval rather than failing, so this is a one-click situation, not a broken branch.

Whichever lands second will not close the other automatically, and its Fixes #651 becomes a no-op — so the two of you may want to agree on which shape wins before a maintainer has to choose. Nothing here needs changing on its own merits; the code in this PR is fine, and the test that pins the OpenAPI output is the piece #670 is missing.

@NandhaKishorM
NandhaKishorM merged commit 580559f into NandhaKishorM:main Sep 29, 2026
NandhaKishorM pushed a commit that referenced this pull request Sep 29, 2026
…ly pin

`docs/docker.md` documents `LAYA_REVISION` in the shared variable table, `laya/revisions.py:51`
reads it, and no Compose file named it. Compose only puts a host variable into a container when
the variable appears in that service's `environment:` block, so:

    $ printf 'LAYA_REVISION=reviewed\n' > .env
    $ docker compose run --rm laya

interpolated the host value, warned about nothing, and started the container without it.
`resolve_revision` then returned `None`, `huggingface_hub` applied its default revision, and
every checkpoint loaded at whatever the mutable default branch or the warm cache held.

This is not one knob among several. `laya/revisions.py:12` gives the reason the variable exists
at all -- "so a container pins" -- and `examples/docker/quickstart.py:27` builds
`Router(device=device)` with no `revision=` argument, so in the container this repo ships the
environment variable is the *only* way to pin. `reviewed` is a supported sentinel resolving to
`PINNED_REVISIONS`. A supply-chain control the shipped deployment silently discards is the
failure mode the control exists to prevent.

`compose.yaml` forwards it, with an empty default so a deployment that never mentions it behaves
exactly as it did before.

## The gate that should have caught this, widened

`tests/test_compose_env.py` exists for precisely this class of drift. Its own docstring says the
method is derived rather than transcribed because "the same three-way drift (package, markdown,
Compose) is what hid them". But `dtype_names()` derives from `laya/agent.py` only, and only within
a few lines of a dtype decision -- which is right for the contract it was written for, and blind to
a name read by any other module. `LAYA_REVISION` is read by `laya/revisions.py`, so it fell
straight through.

The derivation is now widened to every `LAYA_*` the package reads, and the three-way agreement is
checked in both directions:

- every name the runtime reads and the page documents, minus the documented exclusions, is
  forwarded by at least one Compose file, as a `"${NAME:-...}"` host passthrough;
- every name a Compose file forwards has a row in the table, so a knob cannot be set by the
  deployment and missing from the page.

Granularity is "at least one file", not per-service, because per-service would be wrong the other
way: `LAYA_PORT` belongs to `laya-serve` and must not be demanded of the SDK service.

Two findings from writing the widened check, both resolved rather than papered over:

- `LAYA_THREADS` is `"${LAYA_THREADS:-${OMP_NUM_THREADS:-4}}"` -- a nested default, and still a
  host passthrough. The first version of the check rejected it, so the check was wrong, not the
  compose file.
- `LAYA_API_KEY_FILE` looked undocumented because the row is a combined
  `` `LAYA_API_KEY` / `LAYA_API_KEY_FILE` `` cell. It is documented, in a table and in prose at
  `docs/docker.md:259`. The extraction was too narrow; widening it avoids demanding a duplicate row
  for a variable that already has one.

## Deliberately not fixed here

`LAYA_MAX_CONCURRENT` and `LAYA_MAX_TOKEN_BUDGET` are the same defect -- both documented in the
`laya-serve` table, both read by `laya/serve.py`, neither forwarded by any file -- and they are
NOT fixed by this change. `compose.http.yaml` is the only place they could be forwarded, and three
open PRs conflict on it: #528 and #656 insert at the `laya-serve` environment block, and #528 is
itself adding `LAYA_SHA256_DIGESTS` to that block, so the serve-side forwarding belongs with
whoever lands that cluster. A first draft of this change did edit that file and conflicted with
all three, which is what settled the scope.

They are pinned in the test as a `DEFERRED` literal and re-asserted to still be read and still
documented, the same way check 5 pins the MPS exclusion. The day those PRs close, the file fails
and the decision gets made again rather than the two names quietly staying missing.

```
python tests/test_compose_env.py    80 passed, 0 failed   (was 78)
python tests/test_packaging.py     106 passed, 0 failed
python tests/test_doc_tables.py    109 passed, 0 failed
python -m compileall -q laya tests
ruff check tests/test_compose_env.py --select=E9,F63,F7,F82,F401,F811 --line-length=120
git diff --check
```

Reverting only `compose.yaml` turns the new check red, naming the variable:
`compose/at least one file forwards LAYA_REVISION`.

Not run: the `docker compose config` render check, because docker is not installed here. The file
reports that as a `NOTE` and never as a pass, so the rendered-environment half of this is
unverified by execution. `tests/test_env_docs.py` fails 1 of 9 on Windows for an unrelated
pre-existing reason (a hard-coded `/` compared against `os.path.relpath`); it fails identically on
unmodified `9d955671`.
@NandhaKishorM

Copy link
Copy Markdown
Owner

Passed checks and merged. Thank you @SomSamantray! It ships in 0.3.22.

NandhaKishorM pushed a commit that referenced this pull request Oct 1, 2026
…eferral

The gate's unit was "forwarded by at least one file in the tree", which the two
knobs this change forwards defeat exactly: `LAYA_MAX_CONCURRENT` is read during
request admission, so a file that never starts a server satisfies the check while
the server that needs it still cannot be configured. `compose.yaml`'s `laya`
service runs a one-shot quickstart, and this page's own header explains that
overrides for it never reach `laya-serve`.

So the demand moves to the pairing the page tells an operator to boot. The
service is read out of docs/docker.md's "These apply to the `laya-serve` service
only", the pairings out of the `-f` commands on that page, and every name in the
server table that the package actually reads must then appear in the merged
`environment` of each pairing -- files that a command names but the tree lacks
are reported, not crashed on.

Two more derived checks back it: check 3 widens from the two dtype names to every
`"${NAME:-}"` passthrough in every file, and proves the *reader* keeps the empty
string's meaning instead of trusting it (the three idioms in `laya/` that do,
`os.environ.get("N", "")`, the falsy test, and the `raw = …` / `if not raw:
return DEFAULT` resolver, are parsed at each site); and 6c pins each row's
documented default against the module constant behind it, so a page that moves to
32 while `serve.py` stays at 16 is a failure rather than a comment.

`DEFERRED` is now empty: #528 and #656 merged 2026-09-29, unblocking the
environment block the exclusion was written for. The tuple stays and an empty
one is asserted by a named check, so re-deferring a documented knob costs a
failure instead of buying a quiet pass.

On pristine `main` the gate prints 16 named REDs (139 passed); with the
deployment lines added it is 178 passed, 0 failed. A 15-mutant harness over the
deployment, the page and the server module -- dropping a name, hardcoding 16,
requiring the variable, contradicting the row, re-attributing the table, naming
a file the tree lacks, breaking the empty-means-unset resolver -- gives 15 killed,
0 escaped.
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.

[feature]: Add support for configuring root path (base URL) via environment variable

3 participants