ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
Network

🌐 Network I/O, packet protocol, and audio/video streaming More...

Topics

 Network Module
 πŸŒ Core network I/O operations with timeout support
 Shared Packet Parsing Utilities
 πŸ“‘ Shared protocol parsing utilities for server and client packet handlers
 WebRTC P2P Connections
 Event hooks and caller context for one WebRTC DataChannel.
 Compression Module
 πŸ“¦ Network compression utilities for ascii-chat
 ACIP
 ascii-chat's binary packet protocol and transport-facing message layer.

Detailed Description

🌐 Network I/O, packet protocol, and audio/video streaming

Network operations, packet types, and audio/video networking.

ACIP packet preparation

ACIP packet preparation

Sending a packet sounds simple until the same payload has to work over a synchronous socket, an asynchronous queue, WebSockets, and WebRTC. The preparation layer is the small piece that makes those paths agree on what is being sent. It inspects the ACIP header, applies the negotiated security policy, and hands the transport the buffers it should actually transmit.

The important rule is ownership. A plaintext packet can keep borrowing the caller's iovec storage. An encrypted packet cannot: its ciphertext belongs to the transport's queued send operation and must stay alive until that operation releases it. WebRTC uses the same encrypted ACIP envelope after peer negotiation; DTLS remains transport security, not a replacement for the ACIP policy.

What preparation does

Preparation reads enough of the header to decide whether the packet is eligible for the current connection. It then chooses one of three outcomes:

  1. borrow plaintext vectors without copying their payload;
  2. seal an encrypted packet into transport-owned storage; or
  3. reject the packet before it reaches a queue or socket.

The caller does not need to know whether the transport is TCP, WebSocket, or WebRTC. The caller supplies packet fragments and the negotiated policy; the prepared result carries the lifetime and output contract.

acip_packet_plan_t plan = {0};
asciichat_error_t err = acip_packet_plan(crypto, buffers, buffer_count, &plan);
if (err != ASCIICHAT_OK) {
// Nothing was encrypted or queued.
return err;
}
if (plan.encrypt) {
size_t wire_length = 0;
err = acip_packet_encrypt(crypto, &plan, control_domain,
ciphertext, ciphertext_capacity,
&wire_header, &wire_length);
if (err != ASCIICHAT_OK) {
return err;
}
// Submit ciphertext and keep it alive until the async send consumes it.
} else {
// Submit the borrowed buffers while they remain immutable and alive.
}
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
@ ASCIICHAT_OK
Definition error_codes.h:50
asciichat_error_t acip_packet_plan(crypto_context_t *crypto, const socket_buffer_t *buffers, size_t count, acip_packet_plan_t *plan)
Definition prepare.c:9
asciichat_error_t acip_packet_encrypt(crypto_context_t *crypto, const acip_packet_plan_t *plan, buffer_domain_t *domain, void *ciphertext, size_t capacity, packet_header_t *header, size_t *length)
The useful part of acip packet plan is in buffers, count, plaintext_size, ciphertext_capacity: togeth...
Definition prepare.c:53

The plan is intentionally a borrowing description, not an owning packet. Synchronous callers may use the original buffers directly. Asynchronous callers must arrange for the queue to retain or copy them before returning; encrypted callers must also keep their ciphertext storage alive until the transport has consumed it.

Why the header is inspected first

The preparation path must not encrypt or allocate blindly. Header validation catches impossible lengths, unsupported packet families, and packets that violate the connection's state before expensive work begins. That is also why a plaintext path still reads the header: policy and bounds are shared by every transport.

In the encrypted path, the existing ACIP nonce and authenticated ciphertext are wrapped in the negotiated record format. The transport sees one prepared envelope; application code never assembles a second, transport-specific crypto format.

Testing the contract

The focused unit test covers borrowed vectors, handshake exceptions, contiguous and fragmented ciphertext, decryption, bounds, allocation and crypto failures, synchronous and asynchronous TCP, and queue rejection. Run it from the build directory:

cmake --build build --target test-acip-prepare
ctest --test-dir build -R test-acip-prepare --output-on-failure

The integration tests then exercise the same contract through real binary WebSocket frames, WebRTC peers, TCP/WS/WSS policy combinations, and browser DataChannels. A successful test means more than β€œthe bytes arrived”: it means the packet was admitted under the same security and ownership rules on both sides.

uv run --frozen \
python -m pytest tests/python/tests/integration/acip \
--acip-websocket-probe build/bin/test-acip-prepare
uv run --frozen \
python tests/integration/crypto_policy.py build/bin/ascii-chat

Reading the benchmark numbers

The benchmark measures preparation, not network throughput. It counts allocations and explicit payload copies around 64 KiB packets, using real encryption where the path requires it. A lower copy count is useful, but it is not permission to trade away ownership correctness or validation.

The most meaningful result from the October 2026 Windows/Clang run was that contiguous encrypted asynchronous TCP and WebSocket preparation avoided the old full-payload copy while plaintext vectors stayed borrowed. Results vary by compiler, CPU, queue pressure, and packet shape, so rerun the benchmark when changing the preparation contract.

See also
ACIP
Network I/O

Audio/Video Networking

Video and audio share the ACIP transport but use different admission and processing paths. Control packets are reliable and ordered; disposable media is bounded and may be dropped under pressure.

Video

Clients capture or decode frames, encode when the selected format requires it, and send image or encoded-frame messages through the client ACIP API. Servers collect participant frames, create per-client layouts, render to terminal capabilities, and send ASCII or encoded output. The renderer consumes decoded frame buffers; it does not know about sockets.

Audio

Audio capture produces PCM or Opus batches. The server keeps per-client input buffers, mixes other participants, and sends PCM/Opus batches to each peer. The client playback callback reads a bounded jitter buffer and outputs silence on underrun. The old single-sample packet remains only for compatibility.

Admission

Media producers send through the shared outbound scheduler. It prioritizes control, then audio, then visual traffic and applies transport-specific datagram preferences without creating parallel media queues in each mode. Failed admission is an explicit error; producers must stop or drop according to the media policy rather than blocking a realtime loop.

See also
topic_network
topic_packet_types
topic_client_capture
topic_client_audio

Discovery session authentication keys

Migrated from docs/discovery-key-sets.md into the rendered Doxygen topic set.

Discovery session authentication keys

ACDS stores session identity as a set of (key_type, public_key) identities. The current ACIP create/join packets carry only 32-byte Ed25519 identities; key_type is therefore explicitly ed25519. X25519 encryption keys, GPG key identifiers, fingerprints and textual SSH key encodings are not interchangeable with these identities. Other key types require a future protocol change.

Admission policy

  • Existing database sessions and creates with total_keys equal to zero (legacy) or one retain the existing admission policy: the session name and any required password permit a join, subject to the service's identity requirements. Their stored host identity is not a guest allowlist.
  • A create with total_keys > 1 explicitly creates a restricted session. Each supplied identity must provide its own valid Ed25519 create signature and a timestamp within the existing five-minute window. Anonymous and duplicate keys are rejected. The creator must possess every registered private key; this protocol does not delegate registration of arbitrary third-party keys.
  • Any active member of that restricted set may join, including multiple devices using different listed keys. Every join must provide a current signature for that key over the existing join message, even when service-wide identity verification is optional. An unlisted, revoked, forged or stale identity is rejected before participant insertion or connection details are returned.
  • Password checks remain additional requirements. Revoking every member leaves a restricted session closed; re-adding a revoked key does not reactivate it. The existing key-management C APIs are trusted database administration APIs; this change adds no network key-management command.

This policy does not change media authentication, key algorithms, host election, or notification behavior. Lookup continues to advertise the original primary host key for wire compatibility; it does not publish the full authorization set.

Create sequence

On one connection, send exactly total_keys SESSION_CREATE packets, with indexes 0..total_keys-1. The first packet supplies the session configuration. Each later packet supplies its own key, timestamp and signature, with the same total, capabilities and participant limit as the first packet. Later session settings are not applied. Each signature uses the existing ACIP create signing format; the set is assembled on one connection under the existing transport crypto policy. No new signing algorithm or signature format is introduced. The final packet commits the set and returns one SESSION_CREATED. A legacy total_keys=0 request completes immediately. Zero-key terminators were unreachable legacy server code and are not part of the counted protocol.

Missing, reordered, repeated, oversized or changed-count sequences fail and clear the pending state. Partial sets are connection-local and never persisted. Disconnecting discards them. Requests with truncated reserved names or unterminated fixed string fields are rejected before callbacks read them.

Storage migration

Startup runs an idempotent SQLite transaction creating session_key_policy and session_identity_keys. It copies the existing rotation keys (including their versions, timestamps and revocations), then backfills each non-anonymous host key without overriding a pre-existing revocation. Existing sessions get an unrestricted policy row. Session IDs, names, passwords, participants, timestamps and host state remain in their original tables. The old untyped session_keys table, when present, remains available for inspection; new key APIs use the typed table. Fresh databases no longer create the superseded table or its indexes.

Policy rows mark migrated sessions. Reopening the database does not recopy stale legacy keys or resurrect a revoked key. Foreign keys cascade key sets and policy rows when a session is deleted. New session creation, policy and all member keys commit in one savepoint; storage failure rolls back the whole session. SQLite's connection mutex protects these multi-statement operations on the shared handle. Password verification runs outside that mutex so Argon2 work cannot block other clients' database operations. Restricted admission is checked before password verification and checked again with fresh capacity, session identity and password state inside the insertion transaction. Changes during password verification therefore reject the join or require a retry without rehashing under the lock.

Native event-driven I/O

Migrated from docs/event-driven-io.md into the rendered Doxygen topic set.

Native event-driven I/O

Native server and discovery-service TCP connections use one libuv event loop per listener group. The native client adopts its connected socket into a dedicated event loop before the crypto handshake. Libuv uses epoll on Linux, kqueue on macOS/BSD, and IOCP on Windows. IOCP reports completed operations; epoll and kqueue report readiness. platform/event.h exposes asynchronous reads and writes so networking code does not depend on either model.

libplatform owns handles, wakeups, deadlines, and worker lifetimes. lib/network/packet/decoder.c incrementally assembles ACIP headers and payloads, validates lengths before allocation, checks CRCs, and emits complete packets. lib/network/tcp/async.c implements the ACIP transport with owned output buffers and encryption. The server mode owns handshake state and media scheduling.

Ownership and shutdown

Adoption invalidates the caller's socket. Only the event loop closes it. Reads borrow a 64 KiB stream buffer; a stream worker pauses reads until its completion callback. At most one worker runs per stream. Handshakes, packet handlers, SQLite work, and client cleanup execute outside the event loop in libuv's worker pool. Render threads remain per client, but the server TCP path no longer creates per-client socket receive, dispatch, and send threads.

Writes copy caller buffers before returning and preserve enqueue order. Accepted writes invoke their completion callback exactly once, including cancellation, before the stream's close callback. Completion reports a local write, not peer acknowledgement. A successful ACIP send and the frame-send counter mean admission to the output queue. An error after encryption closes the stream because its sequence counter may already have advanced.

Shutdown stops acceptance, closes streams, cancels pending output, and drains worker and close callbacks before destroying the loop. External producers must stop before destroying their transport. The client retains a blocking receive adapter for application consumers, backed by a condition variable and complete packet queue; that consumer does not perform socket I/O.

Bounds and deadlines

  • Each stream permits at most 16 MiB or 4096 pending writes, including submitted writes. The client receive queue permits 16 MiB or 4096 packets.
  • Packet assembly, encryption workspace, and queued payloads also use the shared process buffer budget. Exhaustion rejects the operation instead of bypassing that budget with an untracked payload allocation.
  • New ASCII frames are skipped while output exceeds 256 KiB. New audio batches are skipped above 512 KiB. Already queued encrypted packets are never removed or reordered. Control traffic can use the remaining queue capacity; exhaustion terminates the connection.
  • Each loop admits at most 512 simultaneous streams and 1024 posted commands.
  • Media handshakes have a 30-second absolute deadline. Partial application packets have a 30-second deadline; receiving another fragment does not extend the current packet's deadline.
  • Discovery handshakes have a 30-second deadline, partial packets five seconds, and idle connections 60 seconds. Discovery payloads are limited to 64 KiB.

Compatibility boundaries

WebSocket and WebRTC continue to use libwebsockets and libdatachannel's event loops and their existing ACIP adapters. Browser/WASM builds do not link libuv. DNS resolution and outbound connection establishment retain the existing connection code. Outbound discovery requests retain their synchronous adapter. Native client, server, and discovery-service TCP stream I/O always uses the event backend; there is no alternate threaded TCP path or backend selection option. Linux copy avoidance is attempted automatically inside that event loop. Large writes use owned mappings and nonblocking MSG_ZEROCOPY submissions, with one outstanding submission per stream. A timer drains the error queue without blocking other connections; completion releases the mapping. Unsupported or copied submissions fall back to ordinary libuv writes on the same stream. All writes have a 30-second progress deadline; cancellation discards mappings without recycling kernel-pinned pages. This implementation does not claim a measured throughput improvement.

Build and verification

Install libuv development files (libuv1-dev on Debian/Ubuntu, libuv with Homebrew or vcpkg). The musl build fetches libuv as a static dependency.

cmake --preset default -B build
cmake --build build --target ascii-chat test-network-events
./build/bin/test-network-events
uv run --frozen python -m pytest tests/python/tests/integration/event_io --ascii-chat-binary build/bin/ascii-chat
uv run --frozen python -m pytest tests/python/tests/integration/network --ascii-chat-binary build/bin/ascii-chat
uv run --frozen python -m pytest tests/python/tests/integration/network/test_server_client_lifecycle.py --ascii-chat-binary build/bin/ascii-chat

Use .exe executable names on Windows. The standalone test covers fragmented and coalesced packets, corrupt and oversized input, worker-driven echo, deadlines, queue saturation, and exactly-once cancellation. Integration tests exercise encrypted snapshots with stalled peers, reconnects, password, pinned identity and plaintext modes, WebSocket coexistence, automatic copy avoidance, discovery sessions, and graceful shutdown. With BUILD_TESTS=ON, the new tests register as network-events and event-io-integration in CTest.

Discovery host designation

Migrated from docs/host-designation.md into the rendered Doxygen topic set.

Discovery host designation

ACDS is authoritative about the current host. Host election and quality policy remain in the existing handoff implementation.

A joined connection may announce only its own participant ID in its own session. ACDS accepts the announcement only when its host ID and generation match the current handoff authority, including its committed round. Before a handoff exists, authority is initialized from the persisted host, or the session initiator. The endpoint must be terminated, have a nonzero port and a known connection type. An empty address uses the connection source address, as session creation already does. Once accepted, an endpoint is immutable within a committed decision; a conflicting replacement is rejected. An exact duplicate can repeat delivery.

Authority validation, database updates and fanout are serialized with handoff commits using the existing handoff mutex. HOST_DESIGNATED goes to every joined connection in the session, including the announcing host, through the existing pinned registry visitor. Other sessions and connections that have not joined are excluded. Individual failed sends are logged without stopping delivery to others. A subsequent announcement can repair delivery; a joining/reconnecting participant receives the persisted designation immediately after SESSION_JOINED.

Addresses follow the same disclosure rule as SESSION_JOINED: only password protected sessions or sessions with explicit public IP exposure disclose them. WebRTC participants can reconcile by participant ID without an address.

HOST_ANNOUNCEMENT and HOST_DESIGNATED include a 32-bit handoff generation in network byte order, initially one, plus the committed handoff round (initially zero). The pair orders decisions: multiple hosts may be committed within one membership generation. Preparing a successor does not advance the current host decision. The extended payload requires matching client/server versions; old announcement sizes fail closed. The generation is scoped to the active ACDS handoff lifetime, not a durable epoch across ACDS restarts.

Clients consume designations on the ACDS signaling transport, validate exact size, session, endpoint and generation, and ignore stale or duplicate authority. An endpoint-less designation may be completed by an endpoint for the same host and generation. Repeated handoff commits also cannot queue another teardown. An unchanged host updates metadata without restarting healthy media. A changed host uses the existing deferred role dispatcher, which joins media workers before releasing transports. TCP participants wait for a disclosed replacement endpoint; WebRTC participants can switch by host ID.

An actual host change uses the shared NOTICE_ANNOUNCE component with β€œThe session has a new host.” It does not capture input, require acknowledgment, or introduce a modal popup over live video. Initial joins and duplicate events stay quiet. This is related to #280 (popup windows) and #297 (OS notifications). It does not implement a generic popup/help refactor or platform OS notifications.

Telemetry uses the existing OpenTelemetry adapter. Host-selection spans distinguish initial negotiation from successor decisions, with selected/committed/failed outcomes, generation/round, eligible candidate count and the selected candidate's upload/NAT quality. Selection, commit and failure counters and a recovery-duration histogram record decisions rather than periodic ticks. Recovery duration measures observed host loss to commit/failure, rather than media resumption. Designation/reconciliation spans describe announcement/replay/commit sources, accepted/ignored/failed outcomes and local role. Ignored designation and applied role-change counters distinguish duplicates from actual transitions. Broadcast-attempted means the registry visit completed, not that every recipient acknowledged delivery. Attributes omit session strings, participant identifiers and network addresses.

Measured host selection and handoff

Migrated from docs/measured-host-handoff.md into the rendered Doxygen topic set.

Measured host selection and handoff

Discovery participants share one C selector (network/consensus/election.c). The handoff coordinator (network/consensus/handoff.c) runs on ACDS, whose authenticated connection registry supplies membership and fences host changes. Native discovery and the browser use the same control codec. Browser hosting uses session/host.c; TypeScript schedules browser APIs and manages peer connections, without a second election algorithm.

PARTICIPANT_LIMIT, defined in common.h, is 128. Discovery admission, membership storage, ring topology, native hosting, browser hosting, and audio source bounds use this shared limit. This is a capacity bound, not a claim that every machine can mix 128 simultaneous video streams at the maximum frame rate.

Measurements

Every five seconds each participant sends a start marker followed by a bounded 64 KiB probe on its existing authenticated ACDS connection. ACDS measures the interval between the complete packets with its own monotonic clock. It derives delivered kilobits per second from bytes actually received. A probe taking over five seconds is invalid; a completed observation expires after fifteen seconds. Sequence numbers prevent reuse of a completed probe. The coordinator never compares clocks from different machines.

This is an ACDS-path throughput observation, including transport and scheduling effects. It is not an estimate of the maximum Internet uplink, the capacity of every candidate-to-participant route, or wire bandwidth. The traffic meter remains an application-byte meter and is not used as capacity evidence.

Native adapters reuse positively observed LAN/public-interface/router-mapping information when available. A STUN reflexive address alone is not proof of a public interface or a particular NAT type. Browser NAT classification, RTT, and STUN success percentage remain unknown unless the adapter can actually measure them. Unknown fields earn no favorable score contribution. A missing observation never becomes the old 50 Mbps/25 ms/90 percent default.

Selection and readiness

The active host is excluded from successor selection. Candidates need fresh, valid observations and a supported hosting capability. The existing weighted integer score is authoritative; ties compare NAT tier, upload throughput, then participant UUID bytes. Array/arrival order does not resolve ties. The legacy ring state machine stores results from this same selector rather than calculating a different score.

ACDS sends PREPARE to the selected candidate. Native discovery creates and starts its host context; a browser creates its C host engine. Only a matching READY acknowledgment publishes a PLAN. Membership generations and round numbers fence late acknowledgments. A rejected or timed-out preparation is excluded, allowing the next eligible candidate to be tried. Preparation does not change the active media host.

On host departure, ACDS commits the prepared successor and updates the session record. An expired host observation also triggers recovery when a stalled host retains its signaling socket. Native discovery stops its old media workers before applying the new role. Participants negotiate fresh WebRTC connections to the committed participant ID; the successor starts its host media loop. Browser capture and page settings remain owned by the existing page while its session adapter changes role.

The control stream uses versioned packet 6090, a fixed 64-byte header, explicit big-endian integers, and exact-length validation. ACDS checks session and sender IDs against the joined transport identity. Clients cannot submit election decisions. Legacy host announcements cannot overwrite an already fenced host. No eligible successor produces an explicit failure after a bounded recovery window.

The current discovery creation path creates WebRTC sessions. Native-only testing therefore uses native executables over WebRTC, including real ACDS TCP signaling. The TCP-listener capability is reserved in the codec; adapters do not claim it without a supported, verified migration route. Discovery recovery requires ACDS; the earlier draft's claim of ACDS-independent failover does not describe this implementation.

Validation

The consensus unit suite covers wire validation, missing/stale observations, ties, preparation rejection, membership changes, failure deadlines, and the 128/129 participant boundary. Coordinator fixtures inject observations explicitly.

web/web/tests/e2e/run-handoff.mjs starts actual ACDS and native processes and launches Chromium through Playwright. Its socket proxy throttles one participant's probe path so the expected successor is known before killing the host. Scenarios:

  • Native host and two native participants: kill the host with SIGKILL, assert that the expected successor enters its host media loop, and require freshly rendered frames after the other participant reconnects.
  • Browser host and two browser participants: kill the host's separate browser process and require new, distinct decoded ASCII images on both survivors.
  • Native host, browser successor, and the React /discovery page: kill the native host, require a new connected peer connection on the page, then require new changing ASCII images after that reconnection.

Set ASCII_CHAT_TEST_BINARY, PLAYWRIGHT_CORE_PATH, CHROMIUM_PATH, HANDOFF_WEB_URL, and HANDOFF_ARTIFACTS for the test environment. Serve web/web with Vite+, with the test origin allowed and cross-origin isolation enabled. The browser and native processes must be able to reach each other's ICE addresses. Set HANDOFF_SCENARIOS=native,browser,mixed to run the complete matrix. Result JSON, process logs, and screenshots are written to the artifact directory. The test uses changing synthetic video, disables native audio devices, and does not claim audio continuity or TURN-route coverage.

Audio and forced relay experiment

Run web/web/tests/e2e/run-handoff-audio.mjs with the same binary, Chromium, website, Playwright and artifact settings as the video runner. HANDOFF_AUDIO_SCENARIOS=browser,mixed selects a browser host or native host followed by browser successors. Native-only audio uses the companion runner below. The probe uses the production AudioPipeline, deterministic test2 capture, Opus packets, the C host mixer and decoded remote PCM playback callback. The native host uses --test-audio; hardware microphones are unnecessary. The visible page reports decoded non-silent blocks and sample counts. These observations establish decode and playback submission, not physical speaker output, perceptual audio quality or exact sample preservation.

The default is three abrupt host process kills, with 30 seconds of media activity before each loss. Each round creates a replacement participant, waits for an acknowledged successor, then kills the current host. Both survivors must observe a new commit and receive five changing images plus 25 new non-silent decoded audio blocks after that commit. Set HANDOFF_LOSSES (2–20) and HANDOFF_DWELL_MS (at least 1000) to extend sessions; record overrides with the result. HANDOFF_PORT selects the base signaling port (default 31000; mixed uses base + 20).

HANDOFF_ROUTE=relay additionally requires HANDOFF_TURN_URL, HANDOFF_TURN_USERNAME and HANDOFF_TURN_PASSWORD. Use a reachable credentialed TURN server; the runner does not silently fall back to direct routing. Both browser ICE policies and the native host use relay-only mode. In relay mode, before and after every loss, getStats must identify selected successful candidate pairs with nonzero sent/received bytes; every selected pair must have relay candidates at both ends. Direct mode records available selected-pair diagnostics but relies on decoded media for continuity: native interop may omit selected-pair traffic counters. Credentials are not written into result JSON. A configured TURN URL or a gathered relay candidate alone is insufficient.

Each result records pre-loss and post-commit counters, selected pairs, wall-clock recovery-observation time, and decoded-audio callback gaps using the receiver's monotonic clock. The interruption includes the last pre-kill observation through the first new block after commit; it is an upper bound on the audible gap, not a synchronized one-way latency. Screenshots and browser/native logs accompany the JSON, and failed runs retain an explicit passed: false result. A failed or unexecuted scenario is not covered by the original video-only validation claims.

The experiment exposed browser worker admission dropping the synchronous SERVER_STATE emitted before the C participant ID is registered. The worker now retains the logical admission recipient during that call; the focused worker regression checks delivery and rejection of unknown recipients.

Validation on Windows x64, Clang/Ninja and Chrome 155 executed all six rows below with three real host process losses per session and 30-second dwell periods. Four invocations ran concurrently on one Windows host, sharing CPU, Chromium and local coturn resources; this shared load can lengthen measured interruptions. HANDOFF_PORT bases were 38200 (browser/mixed direct), 38400 (browser/mixed relay), 38600 (slow mixed relay) and 38800 (native direct). Each browser/mixed invocation ran its two scenarios sequentially, with mixed using base + 20. Browser runs used the rebuilt source-matched Release WASM bundle. Both browser observers recovered new changing video and non-silent decoded audio after every commit. Mixed runs first proved native host audio while only one browser receiver was connected. Every forced-relay measurement verified selected relay-to-relay pairs carrying bytes before and after loss.

Scenario Host losses Callback interruption upper bound Recovery observation
browser-audio-direct 3 2.81–4.19 s 3.50–4.85 s
browser-audio-relay 3 1.44–2.55 s 2.28–3.17 s
mixed-audio-direct 3 0.41–1.83 s 1.31–2.42 s
mixed-audio-relay 3 0.16–1.33 s 0.86–1.92 s
native-audio-direct 3 1.56–2.12 s 2.42–2.83 s
mixed-audio-relay-slow-video-and-promotion 3 7.14–9.11 s 7.91–9.70 s

Raw result JSON records counters, selected pairs, timestamps, binary hashes and the WASM manifest. Logs, screenshots and process exit evidence remain local test artifacts under .tmp/handoff-integrated-{direct,relay,slow,native}. Set HANDOFF_ARTIFACTS to retain equivalent evidence when reproducing the runs. These results demonstrate recovery with interruptions, not seamless audio or general Internet reliability.

Run web/web/tests/e2e/run-handoff-native-audio.mjs for native-only audio. It keeps three live participants by adding a replacement between losses, uses --test-audio with muted local speakers, and requires fresh decoded remote PCM plus 25 decoded video frames after reconnect. Test-source decode observations are emitted after successful playback submission. Saved log offsets use the chronological log file; stderr is retained separately. Strictly newer receiver monotonic timestamps prevent buffered pre-loss observations from satisfying recovery. HANDOFF_NATIVE_LOSSES accepts 2–3; HANDOFF_DWELL_MS and HANDOFF_PORT work as above. Native-only TURN routing was not exercised. Physical speaker output, sample-perfect recovery and large participant counts are not covered.

Both WASM targets were rebuilt using Emscripten 5.0.0 with its default dlmalloc allocator. An experimental emmalloc override aborted actual C client initialization despite loading assets successfully. The added Playwright runtime-init regression exercises initClientWasm before cleanup so asset-only checks cannot miss that failure. Publication verifies the source fingerprint and each generated file hash.

Additional production repairs transfer the live probe protocol and its five-second clock into the promoted host, preserving sequence, generation and freshness during slow runtime initialization (ACDS replay/rate limits remain unchanged), preserve healthy ACDS signaling while a failed media queue enters its bounded successor wait (queue congestion limits remain unchanged), send native SERVER_STATE only after peer negotiation is ready, and inject native host audio into its local memory participant on an independent capture worker, joined before the host role destroys its capture context. Audio draining is independent of video frame rate. Adopted browser startup has a 30-second deadline; readiness cancels it.

The final relay stress row sets HANDOFF_NATIVE_FPS=1 and HANDOFF_PROMOTION_DELAY_MS=7000. An eight-second exclusive native-source observation decoded 401 blocks, including 268 non-silent blocks (66.8 percent), before introducing another browser sender. Every injected loss produced exactly one host commit while the promoted worker start was delayed seven seconds. The longer measured interruptions in that row include the intentional delay. A fake-clock regression also holds runtime initialization for twelve seconds and verifies uninterrupted five-second probing; lifecycle tests cover ready and hung startup cleanup. All 388 web unit tests in 56 files passed.

These runtime results use integrated implementation commit 38e9f02b0454be22eeb9d614d4682111ac688d9e, including master b1090964d6898fa2525289936a6c535a696efa1b. Both WASM targets and the native executable were rebuilt after integration. Source/artifact verification, all six Chromium asset/runtime-init tests, all 388 web unit tests, and the Linux host-render contract (CTest 1/1) passed on that source. The Linux native executable also rebuilt successfully. Earlier synthetic-merge stale-bundle validation is addressed by that actual rebuild. macOS amd64 CI configuration separately failed while resolving ffmpeg.org, before compiling the changed source.

Network copy reduction

Migrated from docs/network-copy-reduction.md into the rendered Doxygen topic set.

Network copy reduction

Issue #36 is implemented through a portable scatter/gather path and an automatic Linux kernel-copy-avoidance path. The ACIP wire format, encryption coverage, nonce generation, compression format, and CRC32-C polynomial are unchanged.

Implementation

Work item Implementation
Baseline and measurement Native correctness/benchmark executable, reconstructed assembly baseline, process CPU measurements, send/completion counters, repeatable JSON output
Portable scatter/gather socket_buffer_t, socket_sendv, socket_sendv_all; Linux/macOS sendmsg, Windows synchronous WSASend
Transport and media integration ACIP payload vectors; PCM, Opus, ASCII-frame and raw-image slices; one gather for encryption; encrypt directly into final owned wire storage
Reception Transfer the existing decrypted allocation, removing the normalization copy; validate framing before allocating payloads; tolerate zero-copy completion readiness on the receive side
Validation Native Windows, Docker/Linux, and macOS tests; encrypted exchanges between each OS pair; existing Linux transport, CRC, compression and crypto suites
Linux kernel copy avoidance SO_ZEROCOPY/MSG_ZEROCOPY, completion consumption, bounded mapping lifetime, cancellation, copied-completion detection, unsupported/resource-pressure fallback

The original basic packet sender already avoided concatenating the packet header and payload, but used two separate send operations. It now submits both slices together. ACIP previously concatenated them, and its audio/video helpers also assembled media headers and payloads. Those intermediate media copies are removed. Incremental CRC32-C permits checksumming slices without assembling them.

Unencrypted TCP borrows the slices until the synchronous send completes. Encrypted TCP gathers the inner packet once because the existing authenticated encryption API requires contiguous input. It writes ciphertext directly after space reserved for the outer header, eliminating the separate ciphertext-to-wire-buffer copy. Existing mixer, encoder, compressor and buffer-pool outputs remain usable; network I/O is not moved into an audio callback. WebSocket and WebRTC use a contiguous fallback and retain their existing queue ownership and message boundaries.

Vectored I/O removes application assembly copies; it does not itself eliminate the ordinary kernel copy. Ordinary anonymous mappings do not eliminate receive copies either. TCP is a byte stream, so receiving vectors or recvmmsg entries cannot be interpreted as individual ACIP packets. The receive path therefore keeps explicit header/payload framing rather than introducing packet batching. File-transfer APIs (sendfile, splice, TransmitFile) do not apply to this transformed, encrypted in-memory media path.

Deadlines and ownership

  • One deadline covers every partial write and retry of a vectored packet.
  • The TCP transport's send mutex covers encryption/nonce allocation and the complete send, including partial writes and Linux completion processing.
  • A failure after transmission may have started terminates the stream. Retrying a whole partially written packet would corrupt framing.
  • macOS and Windows also bound the underlying send syscall using the remaining SO_SNDTIMEO, then restore the original timeout. The Mac blocked-peer test exposed a large sendmsg(MSG_DONTWAIT) stalling against a tiny socket buffer; polling alone was insufficient. Socket blocking mode is preserved.
  • Library callers using raw packet/socket APIs must serialize complete packets; a TCP send syscall is not an application-packet atomicity guarantee.

Linux kernel zero-copy

Copy avoidance is automatic; there is no CLI or environment switch. Native TCP streams submit large owned buffers through the event loop. Linux completion checks are nonblocking, and unsupported or copied submissions fall back within the same event backend. See event-driven I/O for ownership, deadlines, and shutdown behavior. Portable copy reductions are always active.

TCP wire buffers at least 64 KiB are eligible. Linux allocates private mappings for those owned buffers. The synchronous utility adapter encrypts directly into them; the native event adapter copies each queued wire packet into owned storage. One submission is outstanding at a time, with an allocation ceiling of 32 MiB; the protocol/crypto limits impose smaller practical packet sizes. The sender consumes the socket's IPv4/IPv6 zero-copy error-queue completion before submitting again. This avoids an unbounded pinned-memory queue and cookie ordering or wraparound assumptions. The sender must exclusively own zero-copy submissions and error-queue consumption on that socket.

Unsupported kernels and resource pressure fall back to ordinary sends. After a copied completion, the unsent remainder is sent normally and future zero-copy attempts on that transport are disabled. Already-sent bytes are never resubmitted. On timeout/disconnect the stream is shut down and the mapping discarded with munmap, never overwritten or recycled by a userspace allocator. Kernel references keep any still-pinned physical pages alive independently of the mapping.

The Linux kernel documentation describes completion ownership and copied notifications. Docker loopback and the tested Docker Desktop/SSH routes returned copied completions. These tests validate submission, completion and fallback; they do not establish a real-NIC zero-copy speedup. Small audio packets never request kernel zero-copy.

Reproduce

cmake --preset default -B build -DBUILD_TESTS=ON
cmake --build build --target test-network-vectors
ctest --test-dir build -R '^network-vectors$' --output-on-failure
uv run --frozen python tests/benchmarks/network_copy_benchmark.py \
build/bin/test-network-vectors --runs 3 --output network-results.json

On Windows use python and the .exe binary. CTest configures vcpkg DLL paths; direct benchmark invocation also needs the dependency DLL directories on PATH. The test does not require Catch2 and links the production library.

The suite verifies CRC continuity, empty slices, length rejection, short writes, blocked-peer deadlines, malformed headers/CRCs, partial-header disconnects, concurrent senders, full-duplex encrypted traffic, maximum sizes, ownership transfer, media payload compatibility, message-transport fallback, and Linux zero-copy cancellation. Round trips exercise kernel zero-copy explicitly; the application automatically attempts copy avoidance for eligible writes and falls back within the same event backend when unsupported or when the kernel reports copied completions.

For cross-host checks, run test-network-vectors --serve PORT and test-network-vectors --peer PORT IPV4. This test-only listener accepts one connection with a 60-second accept deadline, exchanges ephemeral keys, then verifies encrypted payloads in both directions. The Mac exchanges were run through an SSH tunnel; Windows/Linux used Docker Desktop's host route.

The benchmark alternates assembled/vectored processes, three runs per mode. Each process sends 100 packets per size (0, 256, 4096, 65536, and 1048554 bytes), both plaintext and encrypted. A 4 KiB send buffer forces partial writes. Every received payload is checked. The assembled baseline reconstructs the prior ACIP/TCP assembly copies, using the same current socket helper and receive path; it is not a benchmark of the entire historical application. Results include process CPU seconds, throughput, send latency percentiles, syscall attempts, and zero-copy completions. CPU includes sender/receiver threads, crypto setup and logging. These are synthetic packet measurements, not end-to-end audio latency or memory-bus measurements.

Validation results (2026-10-10)

All three native test runs passed before opening the PR:

  • Windows x64 on the development machine, Clang 23 Debug build.
  • Linux x86_64 in Docker (ascii-chat-tests-local:latest), Clang 23.1.1 Debug build. Existing TCP transport, CRC32, compression and crypto-network suites also passed.
  • Intel MacBook (loomen@zachbook-pro), Clang 23.1.2 Debug build with sanitizers.

Encrypted bidirectional exchanges passed Windows/macOS, Linux/macOS and Linux/Windows. The Linux peers recorded matching submissions/completions and the copied-completion fallback. Unrelated remote/local checkouts were preserved.

Representative medians from three runs per mode:

Environment CPU seconds, assembled β†’ vectored Encrypted 4 KiB p95 Β΅s, assembled β†’ vectored Encrypted ~1 MiB MiB/s, assembled β†’ vectored
Windows 3.297 β†’ 3.078 180.2 β†’ 142.8 74.22 β†’ 74.85
Docker/Linux 4.166 β†’ 4.002 273.0 β†’ 258.5 64.33 β†’ 67.35
macOS 4.450 β†’ 4.287 318.3 β†’ 229.3 54.56 β†’ 56.50

The measurements support lower overall CPU cost in this workload, but throughput and tail latency vary; earlier Windows samples also showed lower large-packet throughput. They do not substantiate the issue's projected universal percentage improvements. Kernel zero-copy is attempted automatically for eligible writes. These routes required copied completions, which disable further copy-avoidance attempts on that connection while ordinary writes continue through the same event backend.

Network and Transport Architecture

HTTP image API

ascii-chat api-server exposes the shared HTTP listener for image-to-ASCII conversion. GET /health returns a minimal JSON readiness response. POST /convert accepts an image body with image/* or application/octet-stream, or one image multipart field. Width, height, palette, and output format are query parameters; output can be text, JSON, or escaped HTML. URL fetching, local paths, and batch conversion are not part of this public surface.

Overview

ascii-chat separates network work into three layers. Connections own lifecycle, callbacks, deadlines, security state, and packet delivery. Transports own the details of delivery: framing, readiness, backpressure, optional datagrams, and backend resources. ACIP owns packet types, negotiation, authentication, encryption, compression, and dispatch above both. The same protocol handlers therefore work across native and browser-facing transports.

The main boundaries are:

Shared HTTP services

HTTP-only services use http_server_t and the request/response types in network/http/server/server.h. The native listener is a bounded libuv service accepting HTTP/1.0, HTTP/1.1, and prior-knowledge HTTP/2 over TCP. It owns sockets and event-loop callbacks, while handlers own routing and application behavior. The public contract intentionally does not expose libuv, libwebsockets, TLS, nghttp2, nghttp3, or ngtcp2 types, so MCP, API, and discovery can share the same handler code. Generic HTTP/3 request streams attach to a pre-opened QUIC endpoint through the same handler contract; WebTransport CONNECT streams remain a separate ACIP transport use of that endpoint. A supervisor-owned listening socket can be passed to http_server_adopt_socket() before start, avoiding a duplicate bind. An explicitly enabled HTTP version is never silently downgraded.

The protocol mapping is deliberate:

HTTP version Entry point Notes
HTTP/1.0 libuv TCP listener Request/response completion is connection-oriented; keep-alive is not assumed.
HTTP/1.1 libuv TCP listener Persistent connections, Content-Length, chunked bodies, and trailers are supported.
HTTP/2 libuv TCP listener or negotiated TLS endpoint nghttp2 streams use the shared request/response handler and output backpressure.
HTTP/3 QUIC endpoint nghttp3 streams use the same handler contract; WebTransport CONNECT remains the ACIP path.

HTTP/2 and HTTP/3 are required protocol implementations. A listener configured for a specific protocol reports setup or negotiation failure instead of silently changing endpoint semantics. HTTP/3 attaches to the existing QUIC endpoint: it does not create a second UDP listener or authentication path.

Request bodies, headers, connections, in-flight requests, and responses are bounded by the shared server policy. Handlers may retain a response for asynchronous work, but must release it after completion; cancellation invalidates retained responses and prevents late writes after a stream or connection closes. Wakeups and graceful shutdown remain server-owned.

Connections

network_connection_t moves through NETWORK_NEGOTIATING, NETWORK_READY, NETWORK_CLOSING, and NETWORK_CLOSED. Its callbacks run serially outside backend event loops:

  • open allocates application state and may reject startup.
  • packet receives a borrowed payload valid until the callback returns.
  • closing stops and joins application producers.
  • closed releases application state after transport callbacks drain.

Use network_connection_transport() to reach the transport. Do not keep a socket descriptor, invent a second receive loop, or destroy the transport behind the connection's back.

Transports

acip_transport_t is the stable delivery boundary. Its method table covers send/receive, close, interruption, readiness, capabilities, and backend cleanup. The transport owns its implementation state; application user_data is an association owned by the connection or protocol owner.

  • acip_transport_send() and acip_transport_sendv() borrow buffers until the method returns. Queued backends copy data when they retain it.
  • acip_transport_sendv_ex() carries deadlines and datagram preferences. Unsupported semantics return an error; they are not silently downgraded.
  • acip_transport_interrupt() stops pending I/O without freeing the object.
  • acip_transport_destroy() is an ownership operation, not cancellation. Stop producers, drain callbacks, and join users before destroying it.

Backends

Backend Endpoint or use Delivery
TCP Native address/port or tcp:// Ordered byte stream with ACIP framing
WebSocket ws:// or wss:// ACIP packets in WebSocket messages
WebRTC Discovery-negotiated peer DataChannel transport; signaling is separate
QUIC quic:// Reliable streams and negotiated datagrams
WebTransport Advertised https:// endpoint HTTP/3 transport backed by QUIC

A backend may expose an underlying socket for event integration, but callers must not bypass the transport contract. WebRTC and WebTransport may not have a useful application socket at all.

Packet flow

Application code normally sends through a type-specific ACIP helper:

transport, frame, frame_length, frame_metadata);
struct acip_transport acip_transport_t
Forward declaration of ACIP transport.
Definition host.h:508
asciichat_error_t acip_send_ascii_frame(acip_transport_t *transport, acip_frame_workspace_t *workspace, const char *text, size_t length, uint32_t width, uint32_t height, const char *client_id)
acip_transport_t * network_connection_transport(network_connection_t *c)

Lower-level code can use packet_send_via_transport() when it already owns a packet type and payload. The receive side validates ACIP framing, applies negotiated security and compression, and dispatches the borrowed payload to the registered handler.

Media admission and backpressure

The shared ACIP outbound scheduler sits between media producers and every transport. It provides bounded admission, ordered control traffic, media dropping under pressure, and encryption sequencing. A mode must not add a second audio queue, video send buffer, or transport send thread.

Reliable control packets stay ahead of disposable media. Visual and audio datagrams are used only when the peer negotiated the capability and the caller explicitly requests that delivery mode.

See Transport backpressure and media admission and Network copy reduction.

Establishment and adoption

network_connection_open() resolves an endpoint, chooses its backend, and returns one owned connection. network_connect_config_t carries timeout, cancellation, QUIC trust-anchor, and datagram preferences through establishment. network_connection_run() drives packet callbacks on the controlling worker.

Servers create a network_server_t with listeners and callbacks. An already connected or authenticated transport can be adopted with network_server_adopt() or network_server_adopt_negotiating(); ownership transfers only on success.

Security

Transport selection does not replace application authentication. The shared crypto handshake and identity policy still decide whether a peer is trusted. A WebRTC DataChannel or TLS/WebSocket connection supplies delivery security, but password, key, and ACDS identity requirements remain explicit policy.

Shutdown

Shutdown is staged: stop producers, join them without holding a needed lock, let transport callbacks drain, then close and destroy the owner. A failed join retains live dependencies so a later shutdown attempt can finish safely.

Connection, handshake, partial-packet, idle, and cancellation deadlines belong to the connection/backend layers. New network code should not add a blocking recv() loop with hard-coded timeout constants in a mode.

Low-level socket helpers

Platform socket helpers remain useful inside TCP, WebSocket, and listener implementations. They are not the public protocol boundary. Add new behavior to the connection or transport abstraction first, then use platform helpers only inside the backend that needs them.

Discovery and peer connections

ACDS is a signaling and session-discovery service, not a second media protocol. The client uses the shared connection and ACIP runtime to authenticate with ACDS, exchange session metadata, and relay WebRTC SDP/ICE. After peer establishment, media and control packets use the negotiated peer transport; the ACDS connection is not in the media path.

See also
topic_av
topic_packet_types
topic_acds
md_docs_2networking-runtime.html
md_docs_2event-driven-io.html

Connection ownership and execution

Migrated from docs/networking-runtime.md into the rendered Doxygen topic set.

Connection ownership and execution

network_connection_t owns a transport, framing state, deadlines, and connection security storage. network_server_t owns listeners, accepted connections, and their execution workers. Media servers, ACDS, and native session hosts supply application callbacks through the same interface.

stateDiagram-v2
[*] --> Negotiating: accept or dial
Negotiating --> Ready: protocol negotiation succeeds
Negotiating --> Closing: rejection, deadline, or startup failure
Ready --> Closing: disconnect, protocol error, or requested stop
Closing --> Closing: producer join fails; retain dependencies
Closing --> Closed: producers and transport callbacks have drained
Closed --> [*]

TCP uses the platform event loop. WebSocket and WebRTC keep their respective library event engines. Backend adapters deliver input to the common connection executor; modes do not accept sockets, run transport receive loops, or maintain synthetic TCP registry entries for other transports.

network_connection_open() resolves and establishes an outbound endpoint. Its optional configuration carries the caller's timeout and cancellation callback/data through TCP and WebSocket establishment; application shutdown is checked as well. network_connection_run() drives packet callbacks on its controlling worker. An established authenticated peer can be adopted by a server or an outbound owner without repeating the peer's cryptographic negotiation.

Application callbacks

Callback Ownership contract
open Allocate application state and attach it to the connection. A failure still enters teardown.
packet Borrow the decoded payload until return. Return a terminal protocol/application error to close.
closing Stop and join application producers before transport destruction. Must permit retry after a failed join.
closed Release application state after transport callbacks have drained. Called once.

Hooks for one connection execute serially, outside backend event loops. A failed join retains the connection, transport, application state, and owning server so shutdown can retry safely. Owners must join their execution worker before destroying an outbound connection.

Registry visits snapshot and pin connections under the registry mutex, then invoke callbacks after releasing it. Connection teardown removes the registry entry and waits for existing visitors before releasing application state. A visitor may request a stop; it must not synchronously destroy its pinned owner.

Protocol and media behavior

The media and discovery negotiation profiles preserve their existing wire protocols. They share execution, admission, deadlines, and teardown. Transport security and authenticated peer adoption remain explicit inputs to negotiation; neither replaces required password or identity authentication.

Discovery participants use the same media path after either TCP establishment or authenticated WebRTC adoption. Initial capabilities precede stream startup for both; there is no separate client-join announcement or TCP-only wait loop.

Native clients, discovery participants, and servers accept --webrtc-bind-address IP (ASCII_CHAT_WEBRTC_BIND_ADDRESS) to select the local IPv4 or unbracketed IPv6 address for ICE UDP sockets. Discovery gathers all interfaces when this option is empty. Servers otherwise use their selected TCP interface. The signaling service's address does not select the ICE interface. For a call between two processes on the same machine, set this option to 127.0.0.1 on both peers to keep connectivity checks on loopback. This also avoids host firewall or local-network permissions affecting loopback tests. tests/python/tests/integration/discovery/test_discovery_webrtc.py verifies both selected ICE candidates and received media; --Audio additionally verifies stereo packet sizes, and --ipv6 selects IPv6 loopback for ICE while signaling stays on IPv4.

Server render workers submit media directly to the ACIP outbound scheduler. That scheduler owns congestion admission, ordered control traffic, media dropping, and encryption sequencing for every transport. There is no second mode-owned audio queue, video send buffer, or transport send thread.

Windows validation

test-network-connections exercises TCP, WebSocket, and local WebRTC callbacks, pinned registry visits, rejected startup, handshake and partial-packet deadlines, malformed input, and retained cleanup after a failed producer join. The other standalone suites cover participant ownership, peer readiness, security policy, backend events, and congestion.

The media server allocates slots and buffers only after security negotiation and initial capabilities succeed. Unauthenticated stalled peers consume a bounded connection entry rather than a media slot.

The media server sends SERVER_STATE when security becomes ready, before waiting for capabilities. Browser discovery uses that announcement to begin application setup; it must not depend on allocating a media slot first.

tests/integration/network_fps_windows.py uses real native servers and ConPTY clients. It measures the CLI presentation counter over a sustained interval for TCP, WebSocket, and WebRTC, retaining commands, logs, terminal output, and JSON samples. A connected socket or render-loop log is insufficient to pass.

web/web/playwright.networking.config.ts starts an isolated web server and runs unified-networking.spec.ts against native processes built from this checkout. The browser checks advancing rendered frames and disconnect/reconnect behavior, with screenshots and traces retained as evidence.

ACIP Packet Types

Packet types live in include/ascii-chat/network/packet/packet.h. The packet header carries type, length, client identity, and CRC. Transport adapters frame bytes; ACIP handlers validate and dispatch the packet above them.

Families

  • Handshake and rekey: protocol version, crypto capabilities/parameters, key exchange, authentication, encrypted records, and epoch transitions.
  • Control: capabilities, ping/pong, join/leave, stream start/stop, server state, size updates, errors, and remote logs.
  • Media: ASCII frames, image frames, H.264/H.265 frames, audio batches, and Opus audio batches.
  • ACDS: session creation/join/leave, signaling, participant state, host designation, ring consensus, quality, and discovery errors.

PACKET_TYPE_AUDIO is retained as a legacy compatibility type. New media code should use PACKET_TYPE_AUDIO_BATCH or PACKET_TYPE_AUDIO_OPUS_BATCH. PACKET_TYPE_ENCRYPTED is an envelope, not an application media type.

Classification

The ACIP message helpers classify control, media, signaling, and precompressed packets. Handshake packets are handled before the session reaches READY; encrypted records and rekey packets have explicit epoch rules. Do not add a packet type just to move bytes between a producer and transport: use an existing ACIP message or extend the protocol handler and validation together.

APIs

Use packet_send_via_transport() or the type-specific helpers in network/acip/client.h, server.h, and send.h. Direct socket helpers are backend-level compatibility APIs and must not be used by application modes. Receive paths validate the header, length, magic, CRC, security state, and packet family before invoking the handler.

See also
topic_network
topic_av
include/ascii-chat/network/packet/packet.h

QUIC and WebTransport

QUIC is an optional UDP transport for ACIP. It is selected explicitly with a quic:// endpoint on native clients; it does not replace TCP, WebSocket, or WebRTC. Browser clients reach the same listener through HTTP/3 WebTransport. Both paths still run the normal ACIP handshake and application authentication.

Endpoints and configuration

A native server enables QUIC with a concrete bind address, UDP port, TLS certificate, and private key:

ascii-chat server --quic-bind-address 0.0.0.0 --quic-port 27224 \
--tls-cert server.crt --tls-key server.key

A native client connects explicitly and may provide a private CA:

ascii-chat client quic://chat.example:27224 --tls-ca-file CA.pem

--quic-port 0 uses the TCP server port for the listener. TCP remains available. A certificate must match the hostname or IP used by the client; clients use the system trust store unless --tls-ca-file is supplied.

Transport and security

include/ascii-chat/network/quic/quic.h owns the endpoint and transport lifecycle. The resulting acip_transport_t is consumed by the same connection, negotiation, ACIP dispatch, and outbound scheduler used by other backends. Callers must not create a second QUIC receive loop or bypass the transport abstraction.

QUIC TLS requires TLS 1.3 and authenticates the transport endpoint. It does not replace ACIP authentication, identity pinning, or the encrypted-record policy. The transport is not ready for media until TLS and the ACIP security handshake have both completed; quic_transport_allow_media() enforces that barrier.

Streams and datagrams

Reliable ACIP traffic is split into independent control, audio, and visual streams. Each stream begins with an ACQS class preamble, followed by the existing ACIP packet headers and payloads. Packet length and CRC remain ACIP responsibilities. Ordering is guaranteed within a stream, not across all streams, so control transitions are acknowledged before dependent media is admitted.

QUIC DATAGRAM is optional and negotiated. Audio and visual datagrams are preferences, not guarantees: if the peer or path does not support them, the scheduler uses reliable streams. A datagram that expires or is rejected for congestion is not silently retried as reliable media. Fragmented media uses bounded reassembly and can request a keyframe after loss.

Backpressure and ownership

Reliable sends are retained until ngtcp2 acknowledges their bytes and count against a bounded per-connection queue. The shared scheduler prioritizes control, then audio, then visual traffic, and returns an explicit error when admission is impossible. Receive callbacks borrow packet data only until the callback returns; consumers that retain it must copy it.

Stop producers, join transport users, interrupt pending I/O, and then release the transport and endpoint. A failed join leaves live dependencies intact so shutdown can be retried safely.

WebTransport

The HTTP/3 listener shares the QUIC UDP endpoint. ALPN selects raw acip/1 or h3; WebTransport validates the configured HTTPS origin and /acip path before mapping streams and HTTP datagrams into ACIP flows. ACDS may advertise a native QUIC port and a public WebTransport URL independently. ACDS signaling remains on its existing authenticated connection; peer media uses the independently established QUIC/WebTransport ACIP session.

Migration and fallback

The native endpoint can migrate a confirmed connection to another local address in the same address family. Producers must be paused during the operation; TLS, ACIP keys, stream positions, and replay state remain attached to the connection. A failed bind preserves the old socket.

Native fallback to TCP is opt-in with --quic-fallback-port and requires ACIP encryption plus the pinned --server-key. Certificate, authentication, protocol, and cancellation failures do not trigger fallback, and an explicit QUIC URL does not silently switch transports.

Testing and limitations

This topic covers the QUIC implementation. QUIC tests cover native streams, negotiated datagrams, TLS/identity failures, discovery advertisements, WebTransport, and path migration. The private UDP driver is experimental and must not be exposed directly to untrusted networks; production admission and the shared connection lifecycle remain the supported integration path.

See also
topic_network
md_docs_2transport-backpressure.html

Transport backpressure and media admission

Migrated from docs/transport-backpressure.md into the rendered Doxygen topic set.

Transport backpressure and media admission

Every native connection owns a plaintext outbound scheduler. Browser WebSocket, WebRTC and hosted peer sessions use the same contract through OutboundQueue. Backend event loops remain independent; none decides whether video is disposable.

Capacity and ownership

The hard per-connection accounted budget is 8 MiB. Video cannot use the final 1 MiB: 512 KiB is reserved for audio and another 512 KiB for control. Packet-count limits reserve descriptors too (448 video, 480 audio, 512 total). Accounting reserves plaintext, two wire/encryption owners, protocol overhead and descriptors. Native TCP/WebSocket request a 64 KiB socket send buffer and reserve 128 KiB within the budget, covering Linux socket accounting. Receive buffers retain their normal tuning. Native SCTP send space is capped and reserves 64 KiB within this budget, because libdatachannel does not expose that retained amount in buffered bytes. Both rtcSctpSettings.sendBufferSize and each peer's rtcConfiguration.maxMessageSize are set to that same 64 KiB limit: libdatachannel raises its SCTP socket buffer to at least the local maximum message size. Larger ACIP packets are split into negotiated-size DataChannel messages by the existing transport and reassembled before ACIP decoding. Snapshots report the fixed reservation separately from measured backend bytes. Backend pending bytes are additional; Receive buffers and bytes already in the network are outside this outbound budget.

Media submissions copy the borrowed plaintext before returning accepted. Expected congestion is a separate admission disposition, not a network failure. The public acip_outbound_submitv returns asciichat_error_t plus an acip_admission_t. Existing convenience send functions translate non-admission to ERROR_BUFFER_FULL; callers retain a usable connection and distinguish that from fatal write failure. Audio/control rejection is explicit. Already admitted reliable packets are never silently removed. A persistently blocked reliable queue closes the connection: five seconds for waiting audio, ten seconds for waiting control. A transport that has already accepted bytes remains responsible for its own failure/deadline handling.

One native worker serializes each connection's final write order. Handshake and setup/control calls (except ping/pong) wait until backend submission, preserving negotiation barriers. Enqueueing is serialized with admission and budget reservation. The caller must quiesce producers before destroying a transport, as with the existing transport lifetime contract. Destruction stops admission, interrupts writes, joins the worker, and releases every queued owner before backend resources are freed.

Scheduling and codec recovery

Independent raw image and ASCII snapshots replace older wholly unsent snapshots of the same stream. Video expires after 100 ms waiting in the application queue. Audio and ping/pong may precede unsent video, retaining FIFO order within their traffic classes and never crossing a setup/teardown/negotiation barrier. Other controls remain FIFO barriers. Encryption happens after these decisions. Neither ciphertext nor a partly submitted packet can be reordered, discarded, or retried.

Backends receive one complete ACIP packet at a time. Scheduling waits for reported pending bytes to drain before committing the next packet of any class. This keeps tiny control packets from building a long opaque FIFO behind video. Liveness pings/pongs enqueue asynchronously; setup and negotiation calls retain their synchronous submission barriers.

Bytes already in a socket, SCTP, or the network cannot be removed. A frame straddling a receiver throttle can therefore be older than 100 ms; that age is measured rather than hidden.

H.264 and H.265 share conservative dependency handling. After any queued encoded frame is discarded, all unsent pictures for that codec/stream are removed and subsequent dependent pictures are rejected until a keyframe is admitted. Native and browser capture request a fresh keyframe from their encoder. Native encoders request closed recovery pictures with repeated parameter sets. Browser WebCodecs continues its Annex B parameter-set handling. Discarding that recovery frame invalidates the stream again. Stream state is bounded to 64 codec/stream pairs.

acip_outbound_snapshot and browser snapshot() distinguish local admission, backend submission, drops, congestion, recovery frames, application/backend bytes, and oldest queued video age. Submission is not receiver delivery. Server logging now calls its counter admission FPS; the live harness measures receiver FPS.

Verification

Build ascii-chat, test-backpressure, test-backpressure-live, test-network-events, and test-webrtc-security. Run the deterministic test before the live matrix:

build/bin/test-backpressure
uv run --frozen python -m pytest tests/python/tests/integration/backpressure \
--backpressure-probe build/bin/test-backpressure-live --backpressure-output build/backpressure

The live test opens real TCP, libwebsockets and libdatachannel connections. TCP and WebSocket throttle the receive path to 4 KiB every 64 ms for three seconds. WebSocket uses a bounded transparent TCP relay and an independent receiver service thread, preserving the production libwebsockets flow-control behavior after a two-second baseline. WebRTC advertises a UDP relay as its ICE candidate, verifies the selected remote port, and paces its datagrams during the same interval. A healthy connection runs alongside the saturated one. Each case restores capacity for ten seconds, verifies fresh frame and control delivery, then disconnects with queued data. Audio sequence checks verify ordering. For both encoded codecs, every keyframe starts a brand-new FFmpeg decoder; every delivered frame must decode successfully with no decoder corruption flags. Legal codec filler NAL units pad encoded packets to at least 16 KiB so encoder bitrate defaults cannot accidentally bypass saturation. Raw packets contain an 80x45 RGB image. Control pings are interleaved with every generated frame.

CSV records application/backend bytes, oldest queued video age, delivered count, drops, and the latest receiver-observed frame age. Logs and summary.json record peak queues, mean/max receiver frame age, delivered FPS by phase, healthy-peer FPS, control delivery, and codec recovery. Decoder delivery is measured here; terminal presentation is separately covered by network_fps_windows.py.

The Windows LGPL FFmpeg bundle may lack a working HEVC encoder. Use --backpressure-codecs raw,h264 there and run the full raw/H.264/H.265 matrix with a software HEVC-enabled FFmpeg build on Linux/macOS. An unavailable codec is a failed scenario in the runner, never silently counted as a pass.