Metadata-Version: 2.5
Name: muxws
Version: 0.4.1
Summary: Multiplexed, cancellable, bidirectional streams over one WebSocket - protocol and reference implementation.
Project-URL: Homepage, https://github.com/velis74/muxws
Project-URL: Repository, https://github.com/velis74/muxws
Project-URL: Issues, https://github.com/velis74/muxws/issues
Project-URL: Documentation, https://docs.velis.si/muxws/
Author-email: Jure Erznožnik <jure.erznoznik@gmail.com>
License: MIT
License-File: LICENSE
Keywords: asyncio,multiplexing,streams,websocket
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: demo
Requires-Dist: fastapi; extra == 'demo'
Requires-Dist: uvicorn; extra == 'demo'
Requires-Dist: websockets; extra == 'demo'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: fastapi; extra == 'dev'
Requires-Dist: httpx2; extra == 'dev'
Requires-Dist: msgpack; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: starlette; extra == 'dev'
Requires-Dist: uvicorn; extra == 'dev'
Requires-Dist: websockets; extra == 'dev'
Provides-Extra: msgpack
Requires-Dist: msgpack>=1.0; extra == 'msgpack'
Provides-Extra: starlette
Requires-Dist: starlette>=0.37; extra == 'starlette'
Provides-Extra: websockets
Requires-Dist: websockets>=14; extra == 'websockets'
Description-Content-Type: text/markdown

# <img src="muxws-icon.svg" alt="" style="width:2.5em; height: 2.5em; vertical-align: middle"> 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`](https://github.com/velis74/muxws/blob/main/SPEC.md) and
[`conformance/`](https://github.com/velis74/muxws/blob/main/conformance/README.md) 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](https://docs.velis.si/muxws/guide/rationale) lists which parts of the
HTTP model muxws copies and which it does not;
[Comparison](https://docs.velis.si/muxws/guide/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

```bash
pip install muxws                       # extras: [starlette], [websockets], [msgpack]
npm install muxws                       # optional peers: ws, @msgpack/msgpack
```

## Documentation

The manual is at **[docs.velis.si/muxws](https://docs.velis.si/muxws/)**. `npm run docs:dev` builds and
serves it locally.

| | |
|---|---|
| A server and a client in three files | [Getting started](https://docs.velis.si/muxws/guide/getting-started) |
| A browser demo, a Unix-socket demo and a throughput benchmark | [Demos](https://docs.velis.si/muxws/guide/demos) |
| Every public symbol in both languages | [API reference](https://docs.velis.si/muxws/api/) |
| The normative rules and the conformance fixtures for new implementations | [`SPEC.md`](https://github.com/velis74/muxws/blob/main/SPEC.md), [`conformance/`](https://github.com/velis74/muxws/blob/main/conformance/README.md) |
| Changes per release, and the changes required when upgrading | [Changelog](https://docs.velis.si/muxws/guide/changelog), [Migration guide](https://docs.velis.si/muxws/guide/migration) |

## Status

Alpha. The wire protocol and the packages are versioned independently:

- **Wire protocol:** generation 1, frozen. The WebSocket subprotocol is `muxws.v1.<codec>`. The `v1`
  changes 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.
