Expand description
Bounded rustls transports and socket-free TLS sessions for Bornera owners.
The adapter keeps TCP establishment, socket policy, TLS handshake work, encrypted I/O, and graceful close progression inside Bornera’s existing per-slot budgets. Application writes become irreversible when rustls accepts their plaintext; ciphertext may remain locally buffered afterward.
RustlsTransportLimits mechanically bounds application-write buffering and
observable TLS egress/plaintext. Its bornera::TransportPressure is a stable,
caller-audited conservative charge because rustls does not expose allocation
capacities for all private protocol and cryptographic-provider state. Shared
rustls::ClientConfig ownership and operating-system socket buffers remain
outside the per-connection charge.
RustlsClientSession and RustlsServerSession apply the same limits to
caller-driven rustls state. They own no socket, readiness source, clock, task,
or runtime: an external connection owner supplies bounded ciphertext slices,
drains bounded TLS output, and decides when those bytes reach its transport.
§Sizing a Kafka-oriented connection
There is deliberately no universal TLS profile. The protocol owner chooses frame and decoder limits; the transport profile separately bounds per-turn work and accounts for rustls-owned memory. Revalidate the profile when the exact rustls version, crypto provider, certificate chain, client-auth configuration, or frame limits change.
The limits relate as follows:
IoLimits::chunk_bytesbounds application and raw TLS bytes progressed by one slot operation. It is a fairness and latency bound, not a frame-size limit.application_write_buffer_bytesis rustls’s application-write buffer limit. A positive application write is Bornera’s irreversible transport-ownership edge.max_tls_egress_bytesbounds observable ciphertext waiting inside rustls.max_plaintext_bytesbounds decrypted plaintext waiting to be read by Bornera.TransportPressure::outboundmust covermax_tls_egress_bytes.TransportPressure::plaintextmust cover both the application-write and readable- plaintext bounds. The inbound and protocol categories are caller-audited charges for opaque rustls and provider state; they are accounting reservations, not allocator controls.RustlsClientSession::ingest_tlsandRustlsServerSession::ingest_tlsconsume at most the caller’s slice and the configured inbound charge in one call. A session never retains that caller slice; rustls’s private encoded-input storage remains covered by the audited inbound charge.
For example, a Kafka driver might start qualification with 16 KiB I/O chunks, 64 KiB of application-write buffering, 128 KiB each of observable TLS egress and readable plaintext, and audited 128 KiB charges for opaque inbound and protocol state. This charges 576 KiB per connection:
use std::{io, num::NonZeroUsize};
use bornera::{IoLimits, TransportPressure};
use bornera_core::RetainedBytes;
use bornera_rustls::RustlsTransportLimits;
fn nonzero(value: usize) -> Result<NonZeroUsize, io::Error> {
NonZeroUsize::new(value).ok_or_else(|| io::Error::other("limit must be nonzero"))
}
let kib = |value: u64| RetainedBytes::new(value * 1_024);
let _io = IoLimits::new(nonzero(8)?, nonzero(16 * 1_024)?);
let pressure = TransportPressure::new(kib(128), kib(128), kib(192), kib(128))?;
let tls = RustlsTransportLimits::new(
nonzero(64 * 1_024)?,
nonzero(128 * 1_024)?,
nonzero(128 * 1_024)?,
pressure,
)?;
assert_eq!(tls.transport_limits().retained_bytes(), kib(576));This is a worked starting point, not a production recommendation. The Kafka driver should own the selected values, exercise maximum request and response frames, handshake and reauthentication, certificate chains, and client certificates where enabled, then record the measured/audited profile.
§Rustls feature contract
This release pins rustls 0.23.45 with ring, std, and tls12. TLS 1.2 support
is intentional for Kafka broker compatibility rather than an accidental result
of feature unification. The supplied rustls::ClientConfig determines client
versions, while rustls::ServerConfig determines server-session versions,
identity, client authentication, and ALPN policy. Downstream consumers should
record any decision to narrow or change either protocol-version set.
Structs§
- Rustls
Client Session - One bounded rustls client connection without a socket, clock, task, or runtime.
- Rustls
Client Status - Exact bounded state needed by an external client transport and lifecycle owner.
- Rustls
Connector - Cloneable per-attempt connector retaining TLS identity and bounded configuration.
- Rustls
Server Config - Shared rustls identity and exact per-session retained-memory policy.
- Rustls
Server Session - One bounded rustls server connection without a socket, clock, task, or runtime.
- Rustls
Server Status - Exact bounded state needed by an external socket and lifecycle owner.
- Rustls
Transport - One registered TCP source with a bounded rustls client connection.
- Rustls
Transport Config - Immutable configuration for one logical TLS server identity.
- Rustls
Transport Limits - Stable per-connection charges for rustls-owned variable memory.
Enums§
- Rustls
Client Session Error - Failure before one socket-free rustls client session becomes observable.
- Rustls
Config Error - Invalid logical TLS configuration established before socket acquisition.
- Rustls
Connect Error - Failure before one rustls transport becomes registered or observable.
- Rustls
Diagnostic - Stable rustls-specific code retained in a Bornera transport diagnostic.
- Rustls
Peer Closure - Authenticated peer-input termination observed by a TLS server session.
- Rustls
Server Session Error - Failure before one socket-free rustls server session becomes observable.
- Rustls
Transport Limits Error - Invalid rustls transport-memory accounting configuration.