Crate brokapi_sansio 

Sans-io core trait and test harness: protocol logic with no sockets, timers or async runtime.

A broker connector is split in two. The protocol layer decides what a frame means and what to send next. The runtime owns the sockets and the clock. This crate is the seam between them:

• BrokerCore is the trait a protocol core implements. Frames and the current time go in. Events (EventSink), outbound messages (Outbound) and the next wake-up time come out.
• Harness drives a core with recorded frames and virtual time, so a protocol can be tested without a network and without waiting.
• Helpers every core needs: JsonFrameBuffer (reassemble JSON split over frames), SubscriptionSet (the wanted subscriptions), OrderFsm and OrderRegistry (the life of an order, including the Unknown outcome).

The crate does no I/O at all, and the examples in it run with no mock. The connectors that use it run against the broker mocks, see brokapi-mocks.

The book is at https://brokapi.ru/docs/.

Examples

Reassemble a JSON message that arrived in two pieces, then track an order through its life:

use std::time::Instant;
use brokapi_core::{BrokerOrderId, ClientOrderId, OrderState};
use brokapi_sansio::{BufferPush, JsonFrameBuffer, OrderFsm, OrderSignal};

let mut buf = JsonFrameBuffer::new();
assert_eq!(buf.push(r#"{"type":"order","#), BufferPush::Incomplete);
let BufferPush::Complete(frames) = buf.push(r#""id":"42"}"#) else { panic!("expected a frame") };
assert_eq!(frames, vec![r#"{"type":"order","id":"42"}"#.to_string()]);

let mut order = OrderFsm::new(ClientOrderId::new_v4(), Instant::now());
order.apply(OrderSignal::Ack { broker_id: BrokerOrderId::new("42") }, Instant::now())?;
assert!(matches!(order.state(), OrderState::Acked { .. }));

Structs

CoreEvent

An event produced by a sans-io core, before it is wrapped in an Envelope.

DesiredSubscription

One wanted subscription: what to follow, under which id.

EventSink

A list the core pushes events into while it handles a frame or a timeout.

FrameRecord

One inbound frame of a recorded session, with the instant it arrived.

Harness

Drives a BrokerCore with virtual time and records what comes out.

JsonFrameBuffer

Puts the pieces of a JSON stream back together and cuts it into whole top-level values.

OrderFsm

The life of one order as a finite state machine over [OrderState].

OrderRegistry

Many OrderFsms keyed by client order id.

SubscriptionSet

The full set of subscriptions the consumer wants: the input of BrokerCore::apply.

Enums

BufferPush

Result of feeding a chunk into JsonFrameBuffer.

FsmError

Why a signal could not be applied.

OrderSignal

Something that happened to an order, fed to OrderFsm::apply.

Outbound

A wire message a core wants sent, returned by BrokerCore::poll_transmit.

SubscriptionKind

Kind of streaming subscription the connector should maintain.

Traits

BrokerCore

Protocol logic of one broker stream, written without sockets, timers or an async runtime.