palyra-transport-quic crate provides a high-performance, multiplexed, and secure communication layer for node-to-node RPC and streaming events within the Palyra ecosystem. It leverages the QUIC protocol via the quinn library, with mandatory TLS 1.3 encryption and optional mutual TLS (mTLS) authentication provided by rustls.
Architecture Overview
The QUIC transport layer is designed to handle unreliable network conditions while maintaining strict security guarantees. It supports bidirectional streams for request-response patterns and unidirectional streams for fire-and-forget events.Key Components
| Component | Role | File |
|---|---|---|
Endpoint | The local QUIC socket (server or client). | crates/palyra-transport-quic/src/lib.rs#3-3 |
QuicServerTlsConfig | Encapsulates CA certs, server identity, and mTLS requirements. | crates/palyra-transport-quic/src/lib.rs#38-44 |
QuicTransportLimits | Configures timeouts (handshake/idle) and stream concurrency. | crates/palyra-transport-quic/src/lib.rs#16-23 |
QuicRuntime | The daemon-side implementation that accepts and routes QUIC streams. | crates/palyra-daemon/src/quic_runtime.rs#18-18 |
Connection Lifecycle Diagram
This diagram illustrates the flow from endpoint binding to stream handling within theQuicRuntime.
Title: QUIC Connection and Stream Lifecycle
Sources: crates/palyra-daemon/src/quic_runtime.rs#82-142, crates/palyra-transport-quic/src/lib.rs#120-176
Security and mTLS
Palyra enforcesPROTOCOL_VERSION = 1 and uses a dedicated ALPN token palyra-quic-v1 to prevent protocol cross-talk crates/palyra-transport-quic/src/lib.rs#12-14.
mTLS Authentication
Authentication is handled via X.509 certificates generated by thepalyra-identity crate.
- Server Side: The server can be configured to require client certificates via
require_client_authcrates/palyra-transport-quic/src/lib.rs#42-42. - Revocation: The
RevocationAwareClientVerifierchecks client certificates against aRevocationIndexduring the TLS handshake crates/palyra-identity/src/mtls.rs#63-105.
Certificate Verification Logic
Title: mTLS Verification Space Sources: crates/palyra-transport-quic/src/lib.rs#120-145, crates/palyra-identity/src/mtls.rs#93-105Data Framing
Since QUIC is stream-oriented,palyra-transport-quic implements a framing layer to send discrete messages. The write_frame and read_frame functions handle length-prefixing and size validation crates/palyra-transport-quic/src/lib.rs#112-117.
- Max Frame Size: Defaults to 512 KB (
DEFAULT_MAX_FRAME_BYTES) crates/palyra-transport-quic/src/lib.rs#13-13. - Validation: If a frame exceeds the limit,
QuicTransportError::FrameTooLargeis returned crates/palyra-transport-quic/src/lib.rs#112-113.
Daemon Implementation: quic_runtime
The palyra-daemon uses the QUIC transport for internal node synchronization and health monitoring.
Supported Methods
The daemon’s QUIC handler recognizes specific method strings in theQuicRuntimeRequest crates/palyra-daemon/src/quic_runtime.rs#42-47:
node.health: Returns the health status and whether mTLS is required crates/palyra-daemon/src/quic_runtime.rs#13-13.node.stream_events: A streaming method that supports resumption viaresume_fromsequence numbers crates/palyra-daemon/src/quic_runtime.rs#14-14.
Concurrency Control
The daemon limits concurrent QUIC connections using anArc<Semaphore> to prevent resource exhaustion crates/palyra-daemon/src/quic_runtime.rs#91-93. The default limit is 256 connections crates/palyra-daemon/src/quic_runtime.rs#16-16.
Runtime Request/Response Mapping
Title: QuicRuntime Data Flow Sources: crates/palyra-daemon/src/quic_runtime.rs#144-200Configuration and Limits
TheQuicTransportLimits struct defines the operational boundaries of a connection:
| Parameter | Default Value | Description |
|---|---|---|
handshake_timeout | 10s | Max time for TLS/QUIC handshake. |
idle_timeout | 30s | Max time without activity before closing. |
keep_alive_interval | 5s | Frequency of QUIC PING frames. |
max_concurrent_bidi_streams | 32 | Limit on simultaneous request-response streams. |