Crate melin_app 

Application abstraction for the Melin durable transport.

The transport (journal, replication, pipeline, snapshot framing) is generic over an Application: a state machine that defines the semantics of the events the transport persists, replicates, and dispatches. This crate holds only the trait definitions and small transport-shared types — no matching logic, no wire codec, no I/O.

Split rationale: the transport is the reusable, commercial core; apps (trading engines, bespoke matchers, no-op benchmarks) plug in. Keeping trait definitions in their own crate means an app can depend on the abstraction without pulling transport internals.

Modules

affinity

Linux sched_setaffinity + SCHED_FIFO helpers used by every pipeline thread in the transport (journal, matching, response, shadow, replication sender/receiver). Generic OS plumbing — the matching engine never references it directly. CPU core pinning and real-time scheduling for pipeline threads.

amortized_timer

Clock-read amortization for busy-spin loops. The shadow stage, replication sender, and replica receiver all hit this on the hot path. Pure timing utility — no transport coupling. Periodic-event timer safe to call from a busy-spin hot loop.

app_factory

Application-construction + bulk-seed seam consumed by the server runtime to produce fresh Application instances for replication recovery and to publish the initial-state events a fresh primary journals at startup. Application construction, pre-allocation, and operator policy.

auth

Connection-level permission model — application-shaped access control (operator / trader / custodian / read-only / replication). Consumed by the wire-side auth handshake in melin-protocol::auth. Connection-level permission model for application access control, plus the authorized_keys file loader that maps Ed25519 public keys to permissions.

decoder

Request-decoder seam: RequestDecoder + Decoded<E>. Lets the server runtime turn wire frames into application events without naming the concrete wire enum. See decoder for the trait shape and the four outcomes the runtime branches on. Wire-side request decoder seam.

encoder

Response-encoder seam: ResponseEncoder. Mirror of decoder on the outbound path — application reports / query responses get encoded to wire bytes through this trait, while transport-shaped envelope variants (BatchEnd, EngineError) stay in runtime. Wire-side response encoder seam.

Structs

ApplyCtx

Transport state observable by the application during event application.

WireSeq

Wire-sequence space: the monotonic sequence the journal allocates per durable event. Comparable across nodes and stable across recovery (a fresh vs recovered primary), unlike disruptor ring positions which reset every process start — the newtype exists so the two spaces cannot be mixed (see melin-transport-core’s cursors module, which re-exports this and defines the sibling spaces). Defined here, in the trait crate, so ApplyCtx can carry it across the application boundary.

Enums

CodecError

Codec failures surfaced by AppEvent::decode. Kept deliberately small: the transport only needs to distinguish “malformed tag”, “truncated buffer”, and “invalid field value” to decide whether to abort replay.

RejectReason

Transport-originated rejection reasons. These are the rejections the transport itself synthesises before an event reaches the application (duplicate request on the dedup path, halted pipeline). App-originated rejections (insufficient balance, risk limits, unknown symbol) are modelled inside the app’s own Application::Report type and do not appear here.

Traits

AppEvent

An application event that can be round-tripped through the journal.

Application

An application driven by the Melin durable transport.

EncodeReport

Wire encoder for application reports.

Functions

unix_epoch_nanos

Wall-clock nanoseconds since the Unix epoch. Used for the informational timestamp_ns field stamped into journal records and replication frames, and for any context that needs a real-world timestamp.