Crate flowersec 

Flowersec for Rust

The flowersec crate is the Tokio-native SDK for end-to-end encrypted sessions, RPC, notifications, and reliable byte streams. It supports Rust 1.88 or newer on Linux, macOS, and Windows and contains no Flowersec-authored unsafe.

Install

cargo add flowersec

Public API

Parse an invitation with Artifact::parse, bind its durable single-use spend callback with ArtifactLease, and establish a Session through connect(...). The public application surface includes Session, RpcPeer, ByteStream, IncomingStream, StreamMetadata, StreamHandlers, negotiated UnreliableMessageChannel, and typed RPC through RpcPeerExt::call_typed(...).

let options = flowersec::ConnectorOptions::new()
    .with_trust_roots_der(roots)?;
let session = flowersec::connect(lease, options).await?;
session.probe_liveness().await?;
session.close().await?;

ConnectionController owns long-lived reconnection. Each attempt acquires a fresh lease and creates a new Session; it never migrates or replays work from a terminated Session.

StreamHandlers serves bounded application stream handlers on any established Session. RpcHandlers configures client RPC and notification callbacks. SessionHandlers configures accepted server Sessions and composes the same stream dispatcher.

Server APIs

Rust exposes the direct Acceptor, opaque TunnelRuntime, and carrier-neutral ProxyServer. The proxy implements the bounded HTTP and WebSocket application wire shared with the TypeScript browser runtime.

Reliable stream shutdown is explicit: close_write() sends a graceful FIN and keeps reads available, while reset() and close() abort both directions. Handler failures reset only their stream.

Supported Connections

Rust supports direct and relayed WebSocket and raw QUIC client connections, direct server acceptance, and opaque relay listeners. It does not provide an artifact issuer or WebTransport adapter. Deployments issue artifacts through an application control plane such as the Go control-plane package.

CA candidates use platform or explicit DER trust roots. Pin candidates use only the active artifact-bound leaf-certificate SHA-256 pins and never fall back to CA verification. No system trust store is selected implicitly outside the explicit CA policy. Public errors are closed and redacted; credentials, candidate selection, and protocol state remain private.

See the Rust cookbook, API contract, Transport v3 architecture, wire contract, and error model. Native Rust support for Flowersec secure direct and tunneled sessions over Transport v3.

Maintained callers use the opaque Artifact, one-shot connect, optional long-lived ConnectionController, and carrier-neutral Session, direct Acceptor, and opaque TunnelRuntime contracts. Carrier configuration, candidates, wire formats, and cryptographic state are crate-private.

use flowersec::framing;

use flowersec::client;

use flowersec::endpoint;

use flowersec::proxy;

use flowersec::origin;

use flowersec::rpc;

use flowersec::stream;

use flowersec::protocolio;

use flowersec::gen::flowersec::v1;

Carrier and wire implementation modules are intentionally inaccessible.

Structs

AcceptError

A redacted direct-acceptance failure without artifact or peer diagnostics.

AcceptedSession

One accepted public session paired with its frozen handlers.

Acceptor

Accepts strict v3 direct sessions without exposing carrier or wire state.

AcceptorOptions

Runtime-owned raw QUIC bind, TLS identity, and resource policy.

Artifact

ArtifactLease

ArtifactSourceError

ConnectError

A redacted v3 connection failure with a closed five-code public surface.

ConnectionController

ConnectionControllerConfigurationError

Invalid public connection-controller configuration.

ConnectionControllerError

ConnectionControllerOptions

ConnectionDiagnostic

ConnectionDiagnosticFailure

ConnectionSnapshot

ConnectorOptions

Native v3 connector trust, handler, and lifecycle configuration.

IncomingStream

One accepted logical stream and its authenticated setup metadata.

NotificationSubscription

A cancelable subscription for peer-originated RPC notifications.

ProxyServer

Application-session proxy protocol owner. It has no carrier or tunnel API.

ProxyServerOptions

Bounded server-side browser proxy configuration.

RpcError

A bounded application failure returned by a remote RPC handler.

RpcHandlers

Reusable inbound RPC and notification definitions for client sessions.

RuntimeAuthorizationRequest

Opaque deployment authorization request for one observed FSB3 tunnel leg.

SessionHandlerOptions

Bounded dispatch options for one accepted session.

SessionHandlers

Immutable handler set consumed by crate::Acceptor::accept_with_handlers.

SessionTermination

Stable, redacted reason for authoritative session termination.

StreamHandlerOptions

Bounded dispatch options for application streams on any established session.

StreamHandlers

Carrier-neutral application-stream registry and dispatcher.

StreamMetadata

A validated immutable value accepted as application stream metadata.

TunnelAdmissionOptions

Bounds work performed before an authorized leg enters pairing.

TunnelAuthorizationError

Redacted failure returned by an application-owned authorization callback.

TunnelAuthorizationResponse

Opaque, secret-free deployment response for one tunnel leg.

TunnelRuntime

Production strict-v3 opaque tunnel relay.

TunnelRuntimeOptions

Resource, bind, TLS identity, and origin policy for one opaque relay.

WebSocketAcceptorOptions

Runtime-owned WSS bind, TLS identity, origin, and resource policy.

Enums

AcceptErrorCode

Stable, redacted direct-acceptance failure category.

ArtifactError

ArtifactSpendError

ConnectErrorCode

Stable, redacted Flowersec v3 connection failure code.

ConnectionControllerErrorCode

ConnectionFailure

ConnectionFailurePhase

ConnectionState

HandlerRegistrationError

Stable registration failure for invalid or duplicate handlers.

ProxyServerError

Stable server-side proxy failure without upstream or peer details.

RetryDisposition

RpcCallError

Separates a remote application outcome from a session operation failure.

SessionError

Closed, redacted failure set shared by public session, stream, and RPC operations.

StreamMetadataError

TunnelRuntimeError

Stable relay lifecycle failure categories.

UnreliableMessageError

Stable, redacted failure set for carrier-neutral unreliable messages.

UnreliableMessageErrorCode

Portable code set for unreliable-message failures. Dropped sends remain observable outcomes rather than failures.

UnreliableSendOutcome

Observable result of submitting one message to the native unreliable carrier. It does not imply delivery or ordering.

Traits

ArtifactSource

ByteStream

A reliable encrypted logical byte stream independent of the active carrier.

NotificationHandler

Handles one inbound RPC notification without producing a response.

RpcHandler

Handles one bounded JSON RPC request or notification.

RpcPeer

Carrier-neutral RPC access owned by a session.

RpcPeerExt

Type-safe JSON convenience methods layered over the object-safe RPC core.

Session

Public Flowersec session contract shared by WSS and raw QUIC.

StreamHandler

Handles one authenticated application stream without carrier access.

StreamHandlerRegistrar

Sealed application-stream registration boundary for SDK-owned servers.

TunnelAuthorizer

Application-owned authorization boundary for strict v3 tunnel legs.

UnreliableMessageChannel

Opaque, carrier-neutral unreliable message access owned by a session.

Functions

connect

Establishes one strict v3 session from a single-use artifact lease.

connect_with_cancellation

Establishes one strict v3 session with caller-owned cancellation.

Type Aliases

JsonObject

Canonical JSON metadata attached to a logical stream.

ProxyErrorReporter