Skip to main content

Crate bornera_rustls

Crate bornera_rustls 

Source
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_bytes bounds 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_bytes is rustls’s application-write buffer limit. A positive application write is Bornera’s irreversible transport-ownership edge.
  • max_tls_egress_bytes bounds observable ciphertext waiting inside rustls.
  • max_plaintext_bytes bounds decrypted plaintext waiting to be read by Bornera.
  • TransportPressure::outbound must cover max_tls_egress_bytes.
  • TransportPressure::plaintext must 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_tls and RustlsServerSession::ingest_tls consume 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§

RustlsClientSession
One bounded rustls client connection without a socket, clock, task, or runtime.
RustlsClientStatus
Exact bounded state needed by an external client transport and lifecycle owner.
RustlsConnector
Cloneable per-attempt connector retaining TLS identity and bounded configuration.
RustlsServerConfig
Shared rustls identity and exact per-session retained-memory policy.
RustlsServerSession
One bounded rustls server connection without a socket, clock, task, or runtime.
RustlsServerStatus
Exact bounded state needed by an external socket and lifecycle owner.
RustlsTransport
One registered TCP source with a bounded rustls client connection.
RustlsTransportConfig
Immutable configuration for one logical TLS server identity.
RustlsTransportLimits
Stable per-connection charges for rustls-owned variable memory.

Enums§

RustlsClientSessionError
Failure before one socket-free rustls client session becomes observable.
RustlsConfigError
Invalid logical TLS configuration established before socket acquisition.
RustlsConnectError
Failure before one rustls transport becomes registered or observable.
RustlsDiagnostic
Stable rustls-specific code retained in a Bornera transport diagnostic.
RustlsPeerClosure
Authenticated peer-input termination observed by a TLS server session.
RustlsServerSessionError
Failure before one socket-free rustls server session becomes observable.
RustlsTransportLimitsError
Invalid rustls transport-memory accounting configuration.