All jobs

Add WebSockets to a Litestar App

Yes. An agent adds a typed websocket_listener and a channels broadcast to your Litestar app, tests both with TestClient, keeps mypy strict happy, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the app and the rules it is held to first. In a project laid out like litestar-org/litestar-hello-world, app.py is the whole service: async_hello_world on GET /async, sync_hello_world on GET /sync with sync_to_thread=False, both annotated Dict[str, Any] with a # noqa: UP006 because requires-python starts at 3.8, and an __all__ tuple the ensure-dunder-all pre-commit hook checks. pyproject.toml depends on litestar[standard]>=2.4.1, which pdm.lock resolves to 2.4.1 together with websockets 12.0 through uvicorn's extras, so no new dependency is needed for a socket endpoint. Ruff runs with select = ["ALL"] at line length 120, mypy in strict mode with litestar[standard] and pytest as additional dependencies, plus pyright, slotscheck and codespell, all through .pre-commit-config.yaml; tests/test_app.py has two tests using litestar.testing.TestClient against the imported app, and .github/workflows/ci.yaml runs pre-commit on 3.11 and the tests on 3.8 through 3.11 with PDM.

Two endpoints cover what people mean by websockets. The first is an echo with typed data: @websocket_listener("/ws") on a handler that takes data: Dict[str, Any] and returns a dict with the message and a server timestamp; Litestar parses the incoming frame as JSON because of the annotation, serialises the return value, and handles accept, receive loop and disconnect itself. A connection_lifespan async context manager logs the connection and its close, which is where a real app would authenticate or register the client. The second is a broadcast on /chat built on litestar.channels: a ChannelsPlugin with MemoryChannelsBackend and channels=["chat"] goes into the app's plugins, a POST /chat handler takes a message and calls channels.publish(data, "chat"), and a @websocket("/chat") handler accepts the socket, subscribes with async with channels.start_subscription(["chat"]) as subscriber and runs subscriber.run_in_background(socket.send_text) until the client leaves. The plugin reaches both handlers as the channels dependency without an import in the handler signature's module.

The code is written to pass the repository's own gates. Every handler keeps the Dict, Any and Optional spellings from typing for 3.8, the new names go into __all__, the listener's return type is explicit so mypy strict accepts it, and the broadcast handler catches WebSocketDisconnect so a closed tab does not log a traceback. app = Litestar(route_handlers=[...], plugins=[channels_plugin]) is the one line of the existing file that changes shape; the two HTTP handlers stay as they are.

tests/test_app.py gains four tests in the existing TestClient style. client.websocket_connect("/ws") sends a JSON frame with send_json and asserts the echoed message and a timestamp key with receive_json; a second test sends a text frame that is not JSON and asserts the socket closes. For the broadcast, two sockets connect to /chat, a POST /chat is sent, and both receive the text; a fourth test checks a subscriber that disconnects stops receiving. The agent runs pdm install, pre-commit run --all-files and pdm run pytest on Python 3.11 and 3.8 in its sandbox, fixes what ruff's full rule set and mypy strict raise, and opens the pull request with that output.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add WebSocket support to this Litestar app and open a pull request. Read app.py, pyproject.toml, pdm.lock, tests/test_app.py, .pre-commit-config.yaml and .github/workflows/ci.yaml first. Add no dependency unless pdm.lock lacks what the endpoints need. Add a websocket_listener on /ws that takes data typed as a dict, returns the message with a server timestamp, and has a connection_lifespan that logs connect and disconnect. Add a ChannelsPlugin with MemoryChannelsBackend and a chat channel to the app's plugins; add POST /chat that publishes the body to the channel and a websocket handler on /chat that subscribes and forwards every message with run_in_background until the client disconnects. Keep Python 3.8 compatible typing with the noqa the file already uses, update __all__, and keep ruff select ALL, mypy strict, pyright and slotscheck passing. Extend tests/test_app.py with TestClient websocket_connect tests for the echo, a non-JSON frame, a broadcast to two clients and a disconnected subscriber. Run pdm install, pre-commit run --all-files and pdm run pytest on Python 3.11 and 3.8 until all pass, then open a pull request listing the routes and what each test proves.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request changes app.py and tests/test_app.py and nothing else: pyproject.toml and pdm.lock are untouched because websockets was already resolved. Its description lists the routes, GET /async, GET /sync, WS /ws, POST /chat and WS /chat, says what each new test asserts, and quotes the pre-commit and pytest output from both Python versions in the sandbox.

It names the two decisions a reviewer will ask about: the in-memory channels backend holds subscribers in one process, so the description points at RedisChannelsPubSubBackend for more than one worker, and the echo listener parses JSON without validating it, which is what Litestar's listener does, so a schema is a follow-up with a msgspec.Struct annotation.

Before merging, a reviewer decides whether /chat needs the same guard as any future authenticated route, whether the memory backend is right for the deployment, and whether ws_handler_send_history on the plugin should replay recent messages to a client that joins late.

Run it on every Linear issue labelled realtime

An automation on the Project with a linear trigger on linear.issue.labeled, realtime in config.labels, and the prompt "this issue names a page or event that should push updates to connected clients; add a channel and a publish call where the event happens, extend the tests, and open a pull request" starts one run per labelled issue once the plugin exists. The trigger adds the issue after the prompt and fills in nothing else, so an issue about order status gets an orders channel and a publish in the handler that changes an order.

A team with several Litestar services sends this body once per repository from its own server, each POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own app: a service already running several uvicorn workers gets the Redis backend from the start, and one with JWTAuth configured gets the socket routes placed behind it.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Litestar's socket support is typed and small, and the mistakes hide in the typing: a listener whose return annotation mypy strict rejects, a typing import that breaks 3.8, a handler that forgets __all__ and fails a hook, a subscription that is never closed when the client goes away. The agent fits the change to the repository's own hooks and runs them, with the tests, on both ends of the supported Python range in its sandbox, where it can hold two sockets open against the app at once.

The hook output, the test runs and the diff stay with the run, so a reviewer sees that ruff with every rule, mypy strict, pyright and slotscheck pass and that each socket route's behaviour is asserted, including the disconnect path. A team with several Python services sends the same request to all of them at once.

Frequently asked questions

Does this add a dependency?

Not in this app. litestar[standard] brings uvicorn's standard extras, and pdm.lock already resolves websockets 12.0, which uvicorn uses for the socket protocol. The channels plugin lives in litestar.channels inside the framework. An app on a leaner extra would get the dependency added and the lock updated.

What is the difference between the listener and the raw handler?

websocket_listener runs the accept and receive loop for you and calls your function once per frame with the data converted to its annotation; it suits request-reply. websocket hands you the WebSocket and you write the loop, which the broadcast needs because it sends whenever the channel does, not when the client speaks.

Will the broadcast work with several server processes?

Not with MemoryChannelsBackend, which keeps subscribers in one process. The pull request names RedisChannelsPubSubBackend as the swap, one import and one constructor argument, so every worker sees every publish. The handlers and tests do not change.

How are the socket tests run without a server?

litestar.testing.TestClient opens a socket to the app in-process with websocket_connect, and the returned session has send_json, receive_json, send_text and receive_text. The agent keeps the same with TestClient(app=app) as client shape the two existing tests use.

More Litestar jobs

The same job on other stacks

Keep reading