API Reference¶

`chumicro_websockets`¶

`chumicro_websockets` ¶

Non-blocking WebSocket client and server for CircuitPython, MicroPython, and CPython.

The public entry points are :class:WebSocketClient and :class:WebSocketServer.

`WebSocketBackpressureError` ¶

Bases: WebSocketError

The TX queue overflowed before the runner could drain it.

`WebSocketError` ¶

Bases: Exception

Base class for every chumicro-websockets failure.

`WebSocketHandshakeError` ¶

Bases: WebSocketError

The opening handshake failed (bad status, headers, or HTTP framing).

`WebSocketProtocolError` ¶

Bases: WebSocketError

Peer sent bytes that RFC 6455 requires closing the connection on.

`WebSocketState` ¶

Lifecycle states for a websocket session.

`WebSocketStateError` ¶

Bases: WebSocketError

Caller invoked an operation that requires a different session state.

`WebSocketTimeoutError` ¶

Bases: WebSocketError

A per-phase timeout elapsed (handshake, close, or pong-after-ping).

`WebSocketURLError` ¶

Bases: WebSocketError

URL doesn't parse as a supported ws:// / wss:// URL.

`InboundMessage` ¶

A complete inbound WebSocket data message returned by next_message.

`WhenOversized` ¶

Policy for inbound messages exceeding max_message_bytes.

`derive_accept_key(client_key)` ¶

Compute Sec-WebSocket-Accept from the client's nonce.

Parameters:

Name	Type	Description	Default
`client_key`	`str`	Verbatim base64 nonce; do not decode it first.	required

`make_websocket_key()` ¶

Generate a fresh Sec-WebSocket-Key (16 random bytes, base64 ASCII) per RFC 6455 §4.1.

`parse_ws_url(url)` ¶

Split a ws:// or wss:// url into (scheme, host, port, path).

Raises:

Type	Description
`WebSocketURLError`	Bad scheme, missing host, or out-of-range port.

`chumicro_websockets.client`¶

`chumicro_websockets.client` ¶

Runner-shaped WebSocket client built on chumicro-sockets and chumicro-timing.

The public entry point is :class:WebSocketClient.

`ConnectingPhase` ¶

Sub-states inside CONNECTING: send the upgrade request, then read the 101.

`WebSocketClient` ¶

Bases: _BaseSession

Non-blocking RFC 6455 WebSocket client.

`io_socket` `property` ¶

The connector's pollable while AWAITING_TRANSPORT, else the live socket.

`from_config(config, *, radio=None, ssl_context=None, transport_factory=None)` `classmethod` ¶

Build a :class:WebSocketClient from runtime config.

`init(transport_factory, *, max_message_bytes=DEFAULT_MAX_MESSAGE_BYTES, recv_budget_per_tick=DEFAULT_RECV_BUDGET_PER_TICK, send_budget_per_tick=DEFAULT_SEND_BUDGET_PER_TICK, max_tx_queue_size=DEFAULT_MAX_TX_QUEUE_SIZE, when_oversized=WhenOversized.DROP_WITH_EVENT, ping_interval_ms=None, pong_timeout_ms=DEFAULT_PONG_TIMEOUT_MS, handshake_timeout_ms=DEFAULT_HANDSHAKE_TIMEOUT_MS, close_timeout_ms=DEFAULT_CLOSE_TIMEOUT_MS, max_inbound_queue_size=DEFAULT_MAX_INBOUND_QUEUE_SIZE, ticks=None)` ¶

Create a client; each keyword defaults to its DEFAULT_* constant.

Parameters:

Name	Type	Description	Default
`transport_factory`	`object`	Callable `(host, port, use_tls) -> connector` for the transport.	required
`max_message_bytes`	`int`	Cap on assembled inbound message size.	`DEFAULT_MAX_MESSAGE_BYTES`
`recv_budget_per_tick`	`int`	Per-tick recv cap that keeps ticks LED-friendly.	`DEFAULT_RECV_BUDGET_PER_TICK`
`send_budget_per_tick`	`int`	Per-tick send cap.	`DEFAULT_SEND_BUDGET_PER_TICK`
`max_tx_queue_size`	`int`	Outbound queue bound; overflow raises :class:`WebSocketBackpressureError`.	`DEFAULT_MAX_TX_QUEUE_SIZE`
`when_oversized`	`str`	:class:`WhenOversized` policy for payloads above `max_message_bytes`.	`DROP_WITH_EVENT`
`ping_interval_ms`	`int \| None`	Auto-ping interval in ms, or `None` to disable.	`None`
`pong_timeout_ms`	`int`	Deadline in ms for a PONG after a PING.	`DEFAULT_PONG_TIMEOUT_MS`
`handshake_timeout_ms`	`int`	Opening-handshake timeout in ms.	`DEFAULT_HANDSHAKE_TIMEOUT_MS`
`close_timeout_ms`	`int`	Close-handshake timeout in ms.	`DEFAULT_CLOSE_TIMEOUT_MS`
`max_inbound_queue_size`	`int`	Bound on the `next_message` queue.	`DEFAULT_MAX_INBOUND_QUEUE_SIZE`
`ticks`	`object \| None`	Tick source; defaults to the :mod:`chumicro_timing` `ticks` submodule.	`None`

`connect(url, *, timeout_ms=None, extra_headers=None)` ¶

Initiate the opening handshake against url.

Parameters:

Name	Type	Description	Default
`url`	`str`	`ws://` or `wss://` URL to connect to.	required
`timeout_ms`	`int \| None`	Handshake timeout override in ms, or `None` for the default.	`None`
`extra_headers`	`object \| None`	Extra request headers (iterable, `dict`, or :class:`CaseInsensitiveDict`).	`None`

Raises:

Type	Description
`WebSocketStateError`	:meth:`connect` was already called.

`check(now_ms)` ¶

Return True if there's work to do on this tick.

`next_deadline(now_ms)` ¶

Earliest tick at which handle() must run on a quiet socket.

`handle(now_ms)` ¶

One tick of progress: drain bounded inbound, then bounded outbound.

`close(code=CLOSE_NORMAL, reason='')` ¶

Initiate a graceful close, or abort an in-flight connect.

`chumicro_websockets.server`¶

`chumicro_websockets.server` ¶

Runner-shaped WebSocket server built on chumicro-sockets and chumicro-timing.

The public entry points are :class:WebSocketServer and :class:Connection.

`ServerHandshakePhase` ¶

Sub-states inside CONNECTING: read the request, then write the 101 response.

`Connection` ¶

Bases: _BaseSession

Server-side per-connection state machine and framing pipeline.

`check(now_ms)` ¶

Return True if there's work to do for this connection.

`handle(now_ms)` ¶

One tick of progress for this connection.

`WebSocketServer` ¶

Runner-shaped WebSocket server owning a TCP/TLS listening socket.

`connections` `property` ¶

Tuple of currently-active :class:Connection objects.

`connection_count` `property` ¶

How many connections are currently active (any non-CLOSED state).

`from_config(config, on_connection, *, radio=None, listener=None, accept_path=None, max_connections=2)` `classmethod` ¶

Build a :class:WebSocketServer from runtime config.

init(listener, on_connection, *, max_connections=2, accept_path=None, max_message_bytes=DEFAULT_MAX_MESSAGE_BYTES, recv_budget_per_tick=DEFAULT_RECV_BUDGET_PER_TICK, send_budget_per_tick=DEFAULT_SEND_BUDGET_PER_TICK, max_tx_queue_size=DEFAULT_MAX_TX_QUEUE_SIZE, when_oversized=WhenOversized.DROP_WITH_EVENT, pong_timeout_ms=DEFAULT_PONG_TIMEOUT_MS, handshake_timeout_ms=DEFAULT_HANDSHAKE_TIMEOUT_MS, close_timeout_ms=DEFAULT_CLOSE_TIMEOUT_MS, max_inbound_queue_size=DEFAULT_MAX_INBOUND_QUEUE_SIZE, ticks=None) ¶

Create a server; each per-connection knob defaults to its DEFAULT_* constant.

Parameters:

Name	Type	Description	Default
`listener`	`object`	Listening socket, typically from :func:`chumicro_sockets.listener`.	required
`on_connection`	`object`	`callable(connection)` fired once per connection at handshake completion.	required
`max_connections`	`int`	Concurrent-connection cap; at the cap the server stops calling `accept()`.	`2`
`accept_path`	`str \| None`	URI path to require, or `None` to accept any; a mismatch gets a 404.	`None`
`max_message_bytes`	`int`	Per-connection cap on assembled inbound message size.	`DEFAULT_MAX_MESSAGE_BYTES`
`recv_budget_per_tick`	`int`	Per-tick recv cap.	`DEFAULT_RECV_BUDGET_PER_TICK`
`send_budget_per_tick`	`int`	Per-tick send cap.	`DEFAULT_SEND_BUDGET_PER_TICK`
`max_tx_queue_size`	`int`	Per-connection outbound queue bound.	`DEFAULT_MAX_TX_QUEUE_SIZE`
`when_oversized`	`str`	:class:`WhenOversized` policy for oversized inbound payloads.	`DROP_WITH_EVENT`
`pong_timeout_ms`	`int`	Deadline in ms for a PONG after a PING.	`DEFAULT_PONG_TIMEOUT_MS`
`handshake_timeout_ms`	`int`	Opening-handshake timeout in ms.	`DEFAULT_HANDSHAKE_TIMEOUT_MS`
`close_timeout_ms`	`int`	Close-handshake timeout in ms.	`DEFAULT_CLOSE_TIMEOUT_MS`
`max_inbound_queue_size`	`int`	Bound on each connection's `next_message` queue.	`DEFAULT_MAX_INBOUND_QUEUE_SIZE`
`ticks`	`object \| None`	Tick source; defaults to the :mod:`chumicro_timing` `ticks` submodule.	`None`

`close()` ¶

Stop accepting new connections and close every active session.

`check(now_ms)` ¶

Return True if there's work to do this tick.

`handle(now_ms)` ¶

Accept new connections and advance every active connection one tick.

API Reference¶

chumicro_websockets¶

chumicro_websockets ¶

WebSocketBackpressureError ¶

WebSocketError ¶

WebSocketHandshakeError ¶

WebSocketProtocolError ¶

WebSocketState ¶

WebSocketStateError ¶

WebSocketTimeoutError ¶

WebSocketURLError ¶

InboundMessage ¶

WhenOversized ¶

derive_accept_key(client_key) ¶

make_websocket_key() ¶

parse_ws_url(url) ¶

chumicro_websockets.client¶

chumicro_websockets.client ¶

ConnectingPhase ¶

WebSocketClient ¶

io_socket property ¶

from_config(config, *, radio=None, ssl_context=None, transport_factory=None) classmethod ¶

connect(url, *, timeout_ms=None, extra_headers=None) ¶

check(now_ms) ¶

next_deadline(now_ms) ¶

handle(now_ms) ¶

close(code=CLOSE_NORMAL, reason='') ¶

chumicro_websockets.server¶

chumicro_websockets.server ¶

ServerHandshakePhase ¶

Connection ¶

check(now_ms) ¶

handle(now_ms) ¶

WebSocketServer ¶

connections property ¶

connection_count property ¶

from_config(config, on_connection, *, radio=None, listener=None, accept_path=None, max_connections=2) classmethod ¶

close() ¶

check(now_ms) ¶

handle(now_ms) ¶

`chumicro_websockets`¶

`chumicro_websockets` ¶

`WebSocketBackpressureError` ¶

`WebSocketError` ¶

`WebSocketHandshakeError` ¶

`WebSocketProtocolError` ¶

`WebSocketState` ¶

`WebSocketStateError` ¶

`WebSocketTimeoutError` ¶

`WebSocketURLError` ¶

`InboundMessage` ¶

`WhenOversized` ¶

`derive_accept_key(client_key)` ¶

`make_websocket_key()` ¶

`parse_ws_url(url)` ¶

`chumicro_websockets.client`¶

`chumicro_websockets.client` ¶

`ConnectingPhase` ¶

`WebSocketClient` ¶

`io_socket` `property` ¶

`from_config(config, *, radio=None, ssl_context=None, transport_factory=None)` `classmethod` ¶

`connect(url, *, timeout_ms=None, extra_headers=None)` ¶

`check(now_ms)` ¶

`next_deadline(now_ms)` ¶

`handle(now_ms)` ¶

`close(code=CLOSE_NORMAL, reason='')` ¶

`chumicro_websockets.server`¶

`chumicro_websockets.server` ¶

`ServerHandshakePhase` ¶

`Connection` ¶

`check(now_ms)` ¶

`handle(now_ms)` ¶

`WebSocketServer` ¶

`connections` `property` ¶

`connection_count` `property` ¶

`from_config(config, on_connection, *, radio=None, listener=None, accept_path=None, max_connections=2)` `classmethod` ¶

`close()` ¶

`check(now_ms)` ¶

`handle(now_ms)` ¶