Crate corpus_ipc 

corpus-ipc

Spike and neuromodulator wire protocol and IPC transports for Limen-Neural SNN runtimes.

Repository: https://github.com/Limen-Neural/corpus-ipc

Provides a unified interface for various backends:

• IpcBackend — required backend contract (deprecated alias: RuntimeBackend)
• RustBackend — pure-Rust native backend (no external deps, always available)
• ZmqIpcBackend — binary readout subscriber (feature zmq; deprecated alias: ZmqRuntimeBackend). Send + Sync via mutex-serialized socket ownership; the raw zmq::Socket is never Sync.

Protocol surfaces

Three integrations stay separate. None of them is a guaranteed-delivery bus:

1. Structured ZeroMQ (feature zmq) — ZmqMessagePublisher / ZmqMessageSubscriber carry one compact canonical JSON WireEnvelope<IpcMessage> frame per message. ZmqHybridFlowBackend adapts that pair to HybridFlowBackend. PUB/SUB is best-effort and at-most-once.
2. Binary readout — ZmqIpcBackend subscribes to [i64 tick][N × f32 LE] packets. It does not implement HybridFlowBackend.
3. REST — corpus_ipc_server (feature server) wraps IpcBackend only. It does not speak IpcMessage JSON or the binary readout framing.

Feature flags

The default crate is schema and transport only: wire models, IpcBackend, and RustBackend. Optional stacks are opt-in so library consumers do not compile or link ZeroMQ or the HTTP service:

Feature	Enables
(none / default)	Wire models and RustBackend
zmq	ZmqIpcBackend binary readout, plus ZmqMessagePublisher, ZmqMessageSubscriber, ZmqTransportConfig, and ZmqHybridFlowBackend (vendored libzmq; needs a C++ compiler)
server	corpus_ipc_server Axum 0.8 REST binary (axum + tokio)

Combine server and zmq when the REST service should select the ZMQ backend via CORPUS_IPC_BACKEND_TYPE=zmq.

Wire compatibility

WireCompatibility is the source of truth for on-wire schema versions (independent of crate semver). Decode hybrid-flow JSON through decode_ipc_message_json so too-old and too-new envelopes fail closed before the payload is used. See compatibility for the encoding rules (unknown fields ignored; unknown IpcMessage variants never default).

Re-exports

pub use compatibility::CanonicalEncodeError;

pub use compatibility::Compatibility;

pub use compatibility::CompatibilityError;

pub use compatibility::EnvelopeError;

pub use compatibility::SupportedWireVersion;

pub use compatibility::WireCompatibility;

pub use compatibility::WireEnvelope;

pub use compatibility::accept_wire_version;

pub use compatibility::classify_wire_version;

pub use compatibility::decode_ipc_message_json;

pub use compatibility::decode_ipc_message_value;

pub use compatibility::encode_canonical_ipc_message;

pub use compatibility::encode_ipc_message_json;

pub use error::BackendError;

pub use error::ProtocolError;

pub use models::BatchMetadata;

pub use models::ConfigPayload;

pub use models::ConfigValue;

pub use models::EmbeddingBatch;

pub use models::GradientBatch;

pub use models::GradientUpdate;

pub use models::IpcMessage;

pub use models::IpcSpikeBatch;

pub use models::IpcTraceBatch;

pub use models::NeuromodulatorSnapshot;

pub use models::SpikeBatch;

pub use models::SpikeEvent;

pub use models::StimulusBatch;

pub use models::TraceBatch;

pub use models::TraceData;

pub use rust_backend::RustBackend;

pub use trait_def::BackendFactory;

pub use trait_def::BackendType;

pub use trait_def::HybridFlowBackend;

pub use trait_def::IpcBackend;

pub use trait_def::RuntimeBackend;

pub use validation::ProtocolLimits;

pub use validation::Validate;

pub use validation::ValidationError;

pub use validation::ValidationKind;

pub use validation::ValidationMeasure;

pub use zmq_backend::ZmqIpcBackend;

pub use zmq_backend::ZmqRuntimeBackend;Deprecated

pub use zmq_message::FramingFault;

pub use zmq_message::STRUCTURED_MAX_FRAME_BYTES;

pub use zmq_message::ZmqHybridFlowBackend;

pub use zmq_message::ZmqMessageError;

pub use zmq_message::ZmqMessagePublisher;

pub use zmq_message::ZmqMessageSubscriber;

pub use zmq_message::ZmqTransportConfig;

Modules

compatibility

Fail-closed wire-schema compatibility for IpcMessage.

error

Backend error type.

models

Data types that flow over the compute backend IPC wire.

rust_backend

Pure-Rust native backend — no external dependencies.

server

Axum-based REST microservice exposing an IpcBackend over HTTP.

trait_def

Canonical IPC backend traits and the BackendType factory selector.

validation

Typed wire-payload validation and resource limits.

zmq_backend

ZMQ SUB backend — reads binary compute data packets from the remote IPC socket.

zmq_message

Structured IpcMessage transport over ZeroMQ PUB/SUB.

zmq_readout

Pure parser for ZMQ SUB readout packets (i64 tick + N × f32 LE payload).