Queues and slow clients

Backpressure determines how new data is admitted when resources are limited. Lily applies separate limits to inbound waiting, outbound queue admission, and socket writes.

Inbound waiting#

One normal action runs per connection. Complete application messages wait behind it, with defaults of 16 messages and 1 MiB of total payload. The active action is not part of that waiting total. Exceeding a limit selects a policy Close and attempts to stop active execution.

The reader handles Ping/Pong/Close independently. Normal shutdown discards waiting inbound application messages while allowing the already selected action an opportunity to drain. Message lifecycle explains this admission milestone.

Outbound admission#

use lilyrs::websocket::ServerConfig;
let policy = ServerConfig {
    inbound_queue_capacity: 16,
    inbound_queue_max_bytes: 1_048_576,
    outbound_queue_capacity: 256,
    outbound_queue_max_bytes: 1_048_576,
    outbound_admission_timeout_millis: 5_000,
    write_timeout_millis: 5_000,
    ..ServerConfig::default()
};

Build the policy together with Origin and your other application settings. .config(policy) selects a whole object. These are defaults for the reviewed version, not capacity recommendations for your workload.

An outbound byte reservation is retained while waiting for a count slot, in the queue, and during write/flush; dequeuing does not immediately release it. The default cap for one encoded application message is 1 MiB. Protocol control frames use a separate priority/authority path.

Slow recipients#

When admission times out, a Close with 1013, lily.v2.slow_consumer is attempted. If the transport is blocked, delivery of that Close to the peer is not guaranteed. The send is still reported as failed/backpressured. Waiting for admission and waiting for write/flush use different budgets.

Broadcast recipient admissions can progress concurrently; a healthy recipient need not wait behind a slow one. This does not mean the call completes every recipient instantly. Handle partial receipts and retry policy accordingly.

Distinguish byte limits#

The default inbound-frame limit is 256 KiB and the reassembled-message limit is 1 MiB. The write-buffer threshold is 128 KiB and ceiling is 2 MiB; the ceiling must exceed the threshold and fit the outbound message plus the server-frame header.

send_binary puts a JSON envelope in a Binary frame. BinaryPayload is typed byte content, carried as base64 by the default codec. Binary support is not a ready-made file-upload/chunk/resume/storage API. Choose HTTP uploads and streaming, or an explicit application protocol, for files.

These limits do not guarantee total RSS bounds; application callback memory, TLS buffers, and retained objects also consume resources. Other fixed limits are listed in the reference.