corpus_ipc/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! # corpus-ipc
4//!
5//! Spike and neuromodulator wire protocol and IPC transports for Limen-Neural SNN runtimes.
6//!
7//! Repository: <https://github.com/Limen-Neural/corpus-ipc>
8//!
9//! Provides a unified interface for various backends:
10//!
11//! - [`IpcBackend`] — required backend contract (deprecated alias: `RuntimeBackend`)
12//! - [`RustBackend`] — pure-Rust native backend (no external deps, always available)
13//! - `ZmqIpcBackend` — binary readout subscriber (feature `zmq`;
14//!   deprecated alias: `ZmqRuntimeBackend`). `Send` + `Sync` via mutex-serialized
15//!   socket ownership; the raw `zmq::Socket` is never `Sync`.
16//!
17//! ## Protocol surfaces
18//!
19//! Three integrations stay separate. None of them is a guaranteed-delivery bus:
20//!
21//! 1. **Structured ZeroMQ** (feature `zmq`) — `ZmqMessagePublisher` /
22//!    `ZmqMessageSubscriber` carry one compact canonical JSON
23//!    `WireEnvelope<IpcMessage>` frame per message. `ZmqHybridFlowBackend`
24//!    adapts that pair to [`HybridFlowBackend`]. PUB/SUB is best-effort and
25//!    at-most-once.
26//! 2. **Binary readout** — `ZmqIpcBackend` subscribes to `[i64 tick][N × f32 LE]`
27//!    packets. It does not implement [`HybridFlowBackend`].
28//! 3. **REST** — `corpus_ipc_server` (feature `server`) wraps [`IpcBackend`]
29//!    only. It does not speak `IpcMessage` JSON or the binary readout framing.
30//!
31//! ## Feature flags
32//!
33//! The default crate is schema and transport only: wire models, [`IpcBackend`],
34//! and [`RustBackend`]. Optional stacks are opt-in so library consumers do not
35//! compile or link ZeroMQ or the HTTP service:
36//!
37//! | Feature | Enables |
38//! | --- | --- |
39//! | *(none / default)* | Wire models and `RustBackend` |
40//! | `zmq` | `ZmqIpcBackend` binary readout, plus `ZmqMessagePublisher`, `ZmqMessageSubscriber`, `ZmqTransportConfig`, and `ZmqHybridFlowBackend` (vendored libzmq; needs a C++ compiler) |
41//! | `server` | `corpus_ipc_server` Axum 0.8 REST binary (`axum` + `tokio`) |
42//!
43//! Combine `server` and `zmq` when the REST service should select the ZMQ
44//! backend via `CORPUS_IPC_BACKEND_TYPE=zmq`.
45//!
46//! ## Wire compatibility
47//!
48//! [`WireCompatibility`] is the source of truth for on-wire schema versions
49//! (independent of crate semver). Decode hybrid-flow JSON through
50//! [`decode_ipc_message_json`] so too-old and too-new envelopes fail closed
51//! before the payload is used. See [`compatibility`] for the encoding rules
52//! (unknown fields ignored; unknown [`IpcMessage`] variants never default).
53
54mod canonical_ser;
55pub mod compatibility;
56pub mod error;
57pub mod models;
58pub mod rust_backend;
59#[cfg(feature = "server")]
60pub mod server;
61pub mod trait_def;
62pub mod validation;
63
64#[cfg(feature = "zmq")]
65pub mod zmq_backend;
66#[cfg(feature = "zmq")]
67mod zmq_context;
68#[cfg(feature = "zmq")]
69pub mod zmq_message;
70#[cfg(feature = "zmq")]
71pub mod zmq_readout;
72
73/// Re-export the wire-schema compatibility envelope.
74pub use compatibility::{
75    CanonicalEncodeError, Compatibility, CompatibilityError, EnvelopeError, SupportedWireVersion,
76    WireCompatibility, WireEnvelope, accept_wire_version, classify_wire_version,
77    decode_ipc_message_json, decode_ipc_message_value, encode_canonical_ipc_message,
78    encode_ipc_message_json,
79};
80/// Re-export the main error type.
81pub use error::{BackendError, ProtocolError};
82/// Re-export all public data models used on the wire.
83pub use models::{
84    BatchMetadata, ConfigPayload, ConfigValue, EmbeddingBatch, GradientBatch, GradientUpdate,
85    IpcMessage, IpcSpikeBatch, IpcTraceBatch, NeuromodulatorSnapshot, SpikeBatch, SpikeEvent,
86    StimulusBatch, TraceBatch, TraceData,
87};
88/// Re-export the core trait, factory, and backend.
89pub use rust_backend::RustBackend;
90#[allow(deprecated)]
91pub use trait_def::{BackendFactory, BackendType, HybridFlowBackend, IpcBackend, RuntimeBackend};
92/// Re-export typed wire validation.
93pub use validation::{
94    ProtocolLimits, Validate, ValidationError, ValidationKind, ValidationMeasure,
95};
96
97#[cfg(feature = "zmq")]
98pub use zmq_backend::ZmqIpcBackend;
99#[cfg(feature = "zmq")]
100#[allow(deprecated)]
101pub use zmq_backend::ZmqRuntimeBackend;
102#[cfg(feature = "zmq")]
103pub use zmq_message::{
104    FramingFault, STRUCTURED_MAX_FRAME_BYTES, ZmqHybridFlowBackend, ZmqMessageError,
105    ZmqMessagePublisher, ZmqMessageSubscriber, ZmqTransportConfig,
106};
corpus_ipc/lib.rs

corpus_ipc/
lib.rs
