fix: async-task client crash, hidden-path resolution, and two unusable doc examples

[xianml]

What

Four correctness fixes, each found by exercising the SDK while writing an agent skill for authoring Bentos (#5705, which is now skill-only and does not depend on this PR). Two code fixes, each with a test that fails when the fix is reverted; two doc pages whose examples cannot work as written.

1. SyncHTTPClient.<api>.submit() crashed on every call

with bentoml.SyncHTTPClient("http://localhost:3000") as client:
    task = client.my_task.submit(text="hello")
# AttributeError: 'SyncHTTPClient' object has no attribute '_opened_files'

The finally block in SyncHTTPClient._submit still cleaned up the pre-ClientFileManager attribute. _opened_files moved to ClientFileManager and is referenced nowhere else in the file, so every submit() raised — the request was sent and the task queued, but the caller only ever saw the AttributeError. AsyncHTTPClient._submit and SyncHTTPClient._call were already converted; this brings the last one over.

The async-task endpoints had no test coverage anywhere in the suite, which is how this shipped. Adds tests/e2e/fixtures/tasks/ (a trivial @bentoml.task service, no model) and three tests covering submit/status/get/retry, submit with a file argument, and the async client — ~2.6 s for the file. Two of the three fail before the fix.

2. A hidden ancestor of the working directory made every relative path illegal

$ BENTOML_HOME=~/.bentoml bentoml serve my_bento:latest
ValueError: Accessing hidden files is not allowed:
  /home/me/.bentoml/bentos/my_bento/<ver>/src/requirements.txt

resolve_user_filepath walked every part of the resolved absolute path, so any hidden directory above the working directory poisoned it. Serving a built bento whose service.py calls Image().requirements_file("requirements.txt") therefore failed for any dotted BENTOML_HOME — and the loader swallows it as "not a valid bento tag", so the reported error is the unrelated module-import failure.

The path above cwd is not user input, and cwd containment is already enforced one check earlier, so the hidden-file rule now applies to the relative part only. Dotfiles inside the project, escaping cwd, absolute paths and /etc+/proc all stay rejected — pinned by 7 new tests, two of which fail before the change.

3. Task status values and the cancel/retry methods were wrong in the docs and in the OpenAPI schema

ResultStatus is pending | in_progress | completed | failed | canceled, but the docs told readers to write if status.value == 'success' / 'failure' — branches that can never be taken — and TaskStatusResponse advertised ["in_progress", "success", "failure", "cancelled"], so a client generated from the spec disagrees with the server. Verified against a running server: GET /<api>/status returns "completed".

The two mutating routes were also swapped in the docs: retry is POST, cancel is PUT. Cancel is additionally unsupported by the local development server ("task cancellation is not supported in local development server"), which the page now says.

4. Every "custom service start command" example fails at startup

@bentoml.service(cmd=["uvicorn", "myapp:app", "--host", "$BENTOML_HOST", "--port", "$PORT"])
class ExternalServer: ...
# KeyError: 'PORT'  ->  Application startup failed. Exiting.

cmd entries go through expand_envs, i.e. string.Template.substitute(os.environ), which raises on a missing key — and BentoML defines neither PORT nor BENTOML_HOST. All four snippets on the page used them. Reproduced on 1.4.39, then verified that a hard-coded port matching http.proxy_port proxies correctly (GET / → 200 through the proxy).

The snippets now hard-code a port matching proxy_port and set workers=1, with a note covering both rules — the command must listen on http.proxy_port, and a custom-command Service defaults to min(16, cpu_count/2) workers of which only the first starts the process.

Testing

• tests/unit/_internal/utils/test_filesystem.py — 7 tests, 2 fail without fix 2.
• tests/e2e/bento_new_sdk/test_tasks.py — 3 tests, 2 fail without fix 1.
• tests/unit shows the same 23 pre-existing environment failures (missing protobuf/grpc extras locally) before and after these commits, with 9 added passes.

🤖 Generated with Claude Code