muxws
v0.4.6
Published
Multiplexed, cancellable, bidirectional streams over one WebSocket
Readme
muxws
Multiplexed streams over one WebSocket, with HTTP/2 and HTTP/3 stream semantics. muxws carries many
independent, cancellable, bidirectional streams on one socket; either end can open a stream. It needs no
QUIC or HTTP/3 stack. muxws is defined by its wire format. Python and TypeScript implementations are in
this repository; SPEC.md and
conformance/ specify the protocol
for further implementations.
muxws copies the stream semantics of HTTP/2 and HTTP/3, not their transport. A connection runs over one TCP socket or one Unix domain socket, so all streams share one global message order and there is no per-stream loss recovery. Rationale lists which parts of the HTTP model muxws copies and which it does not; Comparison compares the two protocols frame by frame. muxws does not route requests, serialize domain objects, authenticate peers, store messages durably or define RPC services.
Install
pip install muxws # extras: [starlette], [websockets], [msgpack]
npm install muxws # optional peers: ws, @msgpack/msgpackExample
A FastAPI acceptor (pip install "muxws[starlette]" fastapi uvicorn) that answers one payload with one
reply and another with a stream of chunks:
from fastapi import FastAPI, WebSocket
from muxws import accept, Stream
app = FastAPI()
async def on_stream(payload: object, stream: Stream) -> None:
if payload == {"say": "hello"}:
await stream.reply({"greeting": "hello, muxws"})
elif isinstance(payload, dict) and isinstance(payload.get("count"), int):
for n in range(1, payload["count"] + 1):
await stream.send({"chunk": n})
await stream.end()
@app.websocket("/ws")
async def muxws_endpoint(websocket: WebSocket) -> None:
peer = await accept(websocket)
peer.on_stream(on_stream)
await peer.serve()A Node dialer (npm install muxws ws); a browser imports connect from muxws instead:
import 'muxws';
import { connect } from 'muxws/node';
const peer = await connect('ws://127.0.0.1:8000/ws');
const answer = await peer.request<{ greeting: string }>({ say: 'hello' }, { timeoutMs: 5000 });
for await (const chunk of peer.open<{ chunk: number }>({ count: 3 }, { end: true })) {
console.log(chunk.chunk);
}
await peer.close();The Getting started guide runs both and adds a Python dialer.
Documentation
The manual is at docs.velis.si/muxws. npm run docs:dev builds and
serves it locally.
| | |
|---|---|
| A server and a client in three files | Getting started |
| A browser demo, a Unix-socket demo and a throughput benchmark | Demos |
| Every public symbol in both languages | API reference |
| The normative rules and the conformance fixtures for new implementations | SPEC.md, conformance/ |
| Changes per release, and the changes required when upgrading | Changelog, Migration guide |
Demo
Run locally
Requirements: uv, Node 22+.
git clone https://github.com/velis74/muxws.git && cd muxws
uv sync
npm ci
uv run python demo.py --browser # then open http://127.0.0.1:5173Status
Alpha. The wire protocol and the packages are versioned independently:
- Wire protocol: generation 1, frozen. The WebSocket subprotocol is
muxws.v1.<codec>. Thev1changes only with a breaking wire change. - Packages: version 0.x. Version 1.0 follows the first confirmed production deployment.
Packages: muxws on PyPI; muxws on npm, with the browser entry point and the muxws/node and
muxws/msgpack subpaths.
Licence
MIT. Copyright © 2025 Jure Erznožnik.
