Fix artisan serve crash: make uvicorn WebSocket backend configurable

[tmgbedu]

Problem

artisan serve crashed with ModuleNotFoundError: No module named 'websockets' on apps that never use WebSockets. The serve command hardcoded ws="websockets-sansio" in the uvicorn.run kwargs, and uvicorn imports that backend at startup — requiring the optional websockets package even when no WebSocket is ever opened.

Fix

• Replace the hardcoded ws="websockets-sansio" with a proper --ws option accepting the values uvicorn supports: auto, none, websockets, websockets-sansio, wsproto.
• Resolution order: CLI flag > fastapi.ws config > default.
• Safe default auto — uvicorn resolves it lazily and never requires the websockets package unless a WebSocket connection is actually opened, so serve always boots cleanly.
• Invalid --ws values print a clear error listing the allowed backends and exit non-zero, instead of raising a stack trace.
• Added a ws field to FastAPIConfig (env APP_WS, default auto) so the backend is configurable and documented.
• host / port / reload behaviour is unchanged.

Verification

• Reproduced the crash in an isolated env with neither websockets nor wsproto installed: ws="auto" and ws="none" load cleanly (ws_protocol_class=None), while ws="websockets-sansio" (the old hardcoded value) raises ModuleNotFoundError — confirming the root cause and the fix.
• WebSocket backends still work when the user opts into a backend whose package is installed.

Tests

• Updated the default-backend assertion to expect auto.
• Added TestWsOption covering: flag pass-through, websockets-sansio opt-in, none, config-driven selection, CLI-overrides-config, and invalid value (non-zero exit, uvicorn.run not called, error lists allowed values).
• Full suite: 163 passed (tests/fastapi/ + config tests).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[tmgbedu]

Code Review — APPROVE ✅ (Code Reviewer agent, task #2161)

Reviewed head 3fe9c488.

Verified

• Merge is clean: diff vs main touches only the ws additions. Main's config_value() / resolve_option() refactor and handle() -> int are kept. The uv.lock delta is only the editable package version, 0.56.0 → 0.59.0, which matches pyproject.toml.
• Precedence: --ws > fastapi.ws config > FastAPIConfig default 'auto'. config_value() also handles a None config value and a published config/fastapi.py that has no ws field (both fall back to 'auto'). env("APP_WS", "auto") casts with str, so APP_WS=none stays the string "none" and is not turned into None.
• WS_BACKENDS matches uvicorn 0.46.0 WS_PROTOCOLS / WSProtocolType exactly: auto, none, websockets, websockets-sansio, wsproto.
• Error path: validation runs before uvicorn is called. Ran artisan serve --ws=bogus in example/fastapi-app: exit 1, nothing on stdout, and stderr says Invalid --ws backend 'bogus'. Allowed values: ….
• Checks: ruff check passes, ruff format --check passes, basedpyright reports 0 errors on the changed files. pytest --ignore=tests/masoniteorm/postgres: 2500 passed, 6 skipped. The serve command tests: 47 passed.
• Tests: cover the default, CLI, config, CLI-over-config, a None config value, APP_WS, and the invalid value (exit code, uvicorn not called, message).

Non-blocking suggestions

1. serve_command.py, in handle(): the error always says "Invalid --ws backend", but a bad value can also come from APP_WS or fastapi.ws. A wording like Invalid WebSocket backend 'x' (from --ws / APP_WS / fastapi.ws) would point users to the right place. A test for an invalid config value would also be nice to have.

2. Docs follow-up: in fastapi_startkit.github.io.git/docs/fastapi.md:

   • The Configuration table (around line 57) and the published-config snippet (around line 97) are missing ws | APP_WS | "auto".
   • "Serving the Application" (around line 362) should mention --ws and why auto is the default: websockets-sansio needs the optional websockets package.

   The docs site is a separate repo, so this can be its own PR.