palyrad) and various nodes or CLI clients. This layer is primarily implemented in the palyra-transport-quic crate, leveraging the quinn implementation of the QUIC protocol and rustls for TLS 1.3 security.
Architecture and Stack
The transport stack is designed to provide mTLS (mutual TLS) by default, ensuring that both the server and the client are cryptographically identified using certificates issued by the Palyra internal Certificate Authority (CA).Core Components
palyra-transport-quic: A utility crate that abstractsquinnsetup, TLS configuration, and frame-based I/O crates/palyra-transport-quic/src/lib.rs#4-10.QuicRuntime: The daemon-side implementation that manages the lifecycle of QUIC connections and dispatches requests to internal methods like health checks and event streaming crates/palyra-daemon/src/quic_runtime.rs#18-25.- TLS 1.3 & mTLS: Powered by
rustls, providing encrypted handshakes and mandatory client certificate verification for sensitive operations crates/palyra-transport-quic/src/lib.rs#135-145.
Transport Configuration
The system uses a set of default limits to ensure stability and prevent resource exhaustion:| Parameter | Default Value | Description |
|---|---|---|
PROTOCOL_VERSION | 1 | Internal versioning for the QUIC framing protocol crates/palyra-transport-quic/src/lib.rs#12. |
DEFAULT_MAX_FRAME_BYTES | 512 KB | Maximum size for a single application-level frame crates/palyra-transport-quic/src/lib.rs#13. |
handshake_timeout | 10s | Maximum time allowed for TLS/QUIC handshake crates/palyra-transport-quic/src/lib.rs#28. |
idle_timeout | 30s | Connection timeout if no data is exchanged crates/palyra-transport-quic/src/lib.rs#29. |
max_concurrent_bidi_streams | 32 | Limit on simultaneous bidirectional streams per connection crates/palyra-transport-quic/src/lib.rs#31. |
Connection Lifecycle and Data Flow
The following diagram illustrates the flow from endpoint binding to stream handling within thepalyra-daemon.
QUIC Server Initialization and Request Flow
Sources: crates/palyra-daemon/src/quic_runtime.rs#62-80, crates/palyra-daemon/src/quic_runtime.rs#92-120, crates/palyra-daemon/src/quic_runtime.rs#124-142.Security and mTLS Integration
The transport layer consumes identities generated by thepalyra-identity crate. It supports revocation-aware verification to ensure that compromised or decommissioned devices cannot reconnect.
Revocation-Aware Verification
TheRevocationAwareClientVerifier wraps the standard rustls verifier. During the verify_client_cert call, it checks the certificate’s SHA-256 fingerprint against a RevocationIndex crates/palyra-identity/src/mtls.rs#63-72.
Sources: crates/palyra-identity/src/mtls.rs#93-105, crates/palyra-transport-quic/src/lib.rs#38-44, crates/palyra-transport-quic/src/lib.rs#120-134.
mTLS Enforcement Modes
The daemon can be configured with varying levels of strictness regarding client certificates:- Mandatory mTLS: Clients must provide a valid certificate signed by the Gateway CA. This is the default for node RPC services crates/palyra-identity/src/lib.rs#28.
- Insecure Opt-out: Used primarily for initial pairing or local development where mTLS is explicitly disabled via configuration crates/palyra-daemon/tests/node_rpc_mtls.rs#121-125.
Framing and Multiplexing
QUIC provides native multiplexing, but Palyra adds a lightweight framing layer on top of bidirectional streams. This allows for structured request/response patterns and event streaming within a single QUIC connection.Request/Response Protocol
Requests are serialized as JSON and wrapped in a frame. TheQuicRuntimeRequest includes:
protocol_version: Must matchPROTOCOL_VERSION(currently 1) crates/palyra-daemon/src/quic_runtime.rs#43.method: The RPC method to invoke (e.g.,node.health,node.stream_events) crates/palyra-daemon/src/quic_runtime.rs#44.resume_from: An optional sequence number for event stream resumption crates/palyra-daemon/src/quic_runtime.rs#46.
Event Streaming and Resumption
For methods likenode.stream_events, the server sends a sequence of QuicRuntimeResponse frames. If a connection drops, the client can reconnect and provide a resume_from sequence number. The server then skips acknowledged events and resumes from resume_from + 1 crates/palyra-daemon/src/quic_runtime.rs#180-195.
Frame I/O Functions
Thepalyra-transport-quic crate provides helper functions for reading and writing frames with size limits:
read_frame: Reads a length-prefixed payload from aquinn::RecvStreamcrates/palyra-transport-quic/src/lib.rs#239-260.write_frame: Writes a length-prefixed payload to aquinn::SendStreamcrates/palyra-transport-quic/src/lib.rs#262-275.
Error Handling and Fallback
The transport layer defines a comprehensive error set inQuicTransportError crates/palyra-transport-quic/src/lib.rs#81-118.
Key error scenarios handled include:
- Handshake Timeout: Handshake fails to complete within the configured
handshake_timeoutcrates/palyra-transport-quic/src/lib.rs#100-101. - Pinned Certificate Mismatch: If a client has a pinned server fingerprint, the connection is aborted if the server’s certificate does not match crates/palyra-transport-quic/src/lib.rs#104-105.
- TCP Fallback: The
connect_with_explicit_fallbackfunction allows the system to attempt a QUIC connection and fall back to TCP/gRPC if QUIC is blocked by network middleboxes, provided theTcpFallbackPolicyallows it crates/palyra-transport-quic/src/lib.rs#69-72.