live_data/lib.rs
1//! # live-data
2//!
3//! Shared descriptor, manifest, and subscription types for the
4//! [`live-feed`] publisher SDK and the [`live-stream`] consumer SDK.
5//! The crate is transport-agnostic and I/O-free: it defines only the
6//! wire-shaped types that both sides of a live data ecosystem agree on.
7//!
8//! ## Stability
9//!
10//! Early development, API in flux. The 0.1.0 line locks the *shape* of
11//! the wire protocol so the publisher and consumer SDKs can be built
12//! against a stable types crate; behavioural and ergonomic improvements
13//! land in the runtime crates rather than churning these types.
14//!
15//! ## Umbrella concepts
16//!
17//! - [`FeedDescriptor`] - a single named live feed with its schema,
18//! available transports, formats, and server-side capabilities.
19//! - [`FeedManifest`] - what a publisher returns when a consumer asks
20//! "what feeds are available here?".
21//! - [`SubscriptionDescriptor`] - what a consumer sends when opening a
22//! feed: columns, filter, sampling, preferred transport, and
23//! preferred format.
24//! - [`SubscribeResponse`] - the publisher's reply, either an
25//! [`SubscribeAck`] with the endpoint to consume from, or a
26//! [`SubscribeError`] explaining why the request was refused.
27//!
28//! [`live-feed`]: https://crates.io/crates/live-feed
29//! [`live-stream`]: https://crates.io/crates/live-stream
30
31pub mod descriptor;
32pub mod endpoint;
33pub mod error;
34pub mod manifest;
35pub mod schema;
36pub mod subscription;
37pub mod transport;
38
39pub use descriptor::{Capabilities, FeedDescriptor};
40pub use endpoint::Endpoint;
41pub use error::{Error, Result};
42pub use manifest::FeedManifest;
43pub use schema::{FieldSpec, WireSchema};
44pub use subscription::{
45 FilterExpr, Sampling, SubscribeAck, SubscribeError, SubscribeErrorCode, SubscribeResponse,
46 SubscriptionDescriptor,
47};
48pub use transport::{FormatPreference, TransportPreference, TransportTag};
49
50/// Wire protocol version negotiated between publishers and consumers.
51///
52/// Bumped only when the on-wire shape of any type in this crate changes
53/// in a way that older peers cannot tolerate.
54pub const PROTOCOL_VERSION: u32 = 1;
55
56/// Control-channel tag used by a consumer to request the manifest.
57pub const CONTROL_TAG_FEEDS: &str = "live.feeds";
58
59/// Control-channel tag used by a consumer to open a subscription.
60pub const CONTROL_TAG_SUBSCRIBE: &str = "live.subscribe";