arcly_stream/lib.rs
1//! **arcly-stream** — a high-performance live-media streaming kernel.
2//!
3//! The pub/sub core of a streaming server: lock-free, zero-copy frame fan-out to
4//! an arbitrary number of late-joining subscribers, with instant-start GOP
5//! replay, publish/play authorization, live QoS, and a pluggable media plane —
6//! all free of any config schema, metrics singleton, or HTTP runtime. You bring
7//! the wire protocols and telemetry by implementing small traits; the kernel
8//! owns the hard, hot-path part.
9//!
10//! ```
11//! use arcly_stream::prelude::*;
12//!
13//! let engine = Engine::builder()
14//! .max_publishers(1000)
15//! .application(AppSpec::new("live").gop_cache(120)) // instant-start
16//! .build();
17//! assert_eq!(engine.list_apps().len(), 1);
18//! ```
19//!
20//! # Architecture
21//!
22//! The crate is layered as a small always-on **kernel**, a feature-gated
23//! **media plane**, and **deferred wire protocols** that exist only as traits:
24//!
25//! ```text
26//! ┌─────────────────────── Core kernel (always on) ───────────────────────┐
27//! │ Engine · StreamHandle (broadcast fan-out, GOP cache, live QoS) │
28//! │ PublishRegistry / PlaybackRegistry / EventBus · Observer · auth · │
29//! │ audit · health · MediaFrame / CodecId · StreamError │
30//! └───────────────────────────────────────────────────────────────────────┘
31//! ▲ implements ▲ feature-gated, pure Rust
32//! │ │
33//! ┌─────┴── Wire protocols & muxers ──┐ ┌───────┴── Media plane ──────────┐
34//! │ rtmp RTMP publish/play (ready) │ │ codec H.264/H.265/AV1/VP9/VVC │
35//! │ mpegts MPEG-TS muxer (ready) │ │ hls Packager + segmenter │
36//! │ ProtocolHandler (SRT/WHIP/RTSP) │ │ record RecordingSink │
37//! │ Transcoder/ClusterRelay (traits) │ │ ingest TCP accept loop │
38//! └───────────────────────────────────┘ └─────────────────────────────────┘
39//! ```
40//!
41//! Two wire-plane components ship operational: the [`rtmp`](crate::protocol::rtmp)
42//! handler (publish + play over real RTMP) and the
43//! [`MpegTsMuxer`](crate::packager::MpegTsMuxer) (player-compatible `.ts` output).
44//! Remaining protocols (SRT/WHIP/RTSP) and ABR/cluster backends are still trait
45//! contracts a host implements.
46//!
47//! ## Design invariants
48//!
49//! - **Zero-copy fan-out** — frames are `bytes::Bytes`; one publish clones an
50//! `Arc<MediaFrame>` pointer to every subscriber, never the payload.
51//! - **No locks on the hot path** — the frame bus is a `tokio::broadcast`
52//! channel; cached CONFIG frames and the GOP head use `ArcSwap` / atomics.
53//! - **No global state** — telemetry ([`Observer`]), authorization
54//! ([`StreamAuthenticator`]), and audit ([`AuditSink`]) are *injected* traits
55//! with no-op/permit-all defaults, never singletons. The engine is
56//! `Send + Sync` and can be instantiated many times per process.
57//! - **Contracts are traits** — protocols depend on [`PublishRegistry`] /
58//! [`PlaybackRegistry`], not on the concrete [`Engine`], so a host can swap in
59//! its own bus.
60//! - **`#![forbid(unsafe_code)]`** — the kernel contains no `unsafe`, enforced
61//! by the compiler.
62//!
63//! ## Module layout
64//!
65//! | Module | Responsibility |
66//! |---------------|---------------------------------------------------------------|
67//! | [`frame`] | `MediaFrame`, `CodecId`, `FrameType`, `FrameFlags` |
68//! | [`identity`] | `AppName`, `StreamId`, `StreamKey` (cheap `Arc<str>` ids) |
69//! | [`error`] | `StreamError` and the crate [`Result`] alias |
70//! | [`traits`] | `MediaSource`, `MediaSink`, `ProtocolHandler`, `StorageBackend`, `HwAccelBackend` |
71//! | [`bus`] | `StreamHandle` fan-out (GOP cache, live QoS) + registry contracts |
72//! | [`engine`] | `Engine`, `EngineBuilder`, `AppSpec` — composition, run loop, source pump, idle reaper |
73//! | [`auth`] | `StreamAuthenticator` publish/play authorization (permit-all default) |
74//! | [`observe`] | `Observer` telemetry hook + `NoopObserver` |
75//! | [`audit`] | `AuditSink` + `AuditPipeline` lifecycle audit trail |
76//! | [`health`] | `HealthCheck` / `HealthRegistry` readiness aggregation |
77//! | [`transcode`] | `Transcoder` / `RenditionSpec` ABR contracts |
78//! | [`cluster`] | `ClusterRelay` origin/edge federation contracts |
79//! | [`testing`] | In-memory helpers for downstream tests |
80//!
81//! ## Cargo features
82//!
83//! | Feature | Effect |
84//! |---|---|
85//! | *(none)* | Pure engine: frame model, bus, traits, auth/audit/health/cluster contracts |
86//! | `codec` | Baseline H.264 NAL/SPS + AAC ADTS parsers ([`codec`]) |
87//! | `codec-h265` / `codec-av1` / `codec-vp9` / `codec-vvc` | Next-gen codec parsers (opt-in, pure Rust) |
88//! | `codecs-all` | Every codec parser at once |
89//! | `storage-fs` | Filesystem [`StorageBackend`] adapter |
90//! | `ingest` | Shared TCP accept loop, keyframe gate, rate limiter, NAL scan |
91//! | `hls` | HLS/LL-HLS packager: `Muxer`/`Packager`, segmenter, playlists ([`packager`]) |
92//! | `mpegts` | Native MPEG-TS `Muxer` (`MpegTsMuxer`) — playable `.ts` segments |
93//! | `rtmp` | Working RTMP publish/play [`ProtocolHandler`](protocol::rtmp::RtmpHandler) |
94//! | `record` | Segment/recording sink over a [`StorageBackend`] ([`record`]) |
95//! | `hls` / `record` | Shared keyframe-boundary [`segment`] timing |
96//! | `metrics` | Prometheus [`Observer`] implementation |
97//! | `macros` | `#[derive(MediaSink)]`, `#[protocol]` ergonomics |
98//! | `full` | everything |
99
100#![cfg_attr(docsrs, feature(doc_cfg))]
101// The engine contains no `unsafe` — make that a compiler-enforced guarantee so
102// a future change can't quietly introduce it.
103#![forbid(unsafe_code)]
104
105pub mod audit;
106pub mod auth;
107pub mod bus;
108pub mod cluster;
109pub mod engine;
110pub mod error;
111pub mod frame;
112pub mod health;
113pub mod identity;
114pub mod observe;
115pub mod testing;
116pub mod traits;
117pub mod transcode;
118
119#[cfg(feature = "_codec")]
120#[cfg_attr(docsrs, doc(cfg(feature = "codec")))]
121pub mod codec;
122
123#[cfg(feature = "storage-fs")]
124#[cfg_attr(docsrs, doc(cfg(feature = "storage-fs")))]
125pub mod storage;
126
127#[cfg(feature = "ingest")]
128#[cfg_attr(docsrs, doc(cfg(feature = "ingest")))]
129pub mod protocol;
130
131#[cfg(feature = "hls")]
132#[cfg_attr(docsrs, doc(cfg(feature = "hls")))]
133pub mod packager;
134
135#[cfg(feature = "record")]
136#[cfg_attr(docsrs, doc(cfg(feature = "record")))]
137pub mod record;
138
139#[cfg(any(feature = "hls", feature = "record"))]
140#[cfg_attr(docsrs, doc(cfg(any(feature = "hls", feature = "record"))))]
141pub mod segment;
142
143#[cfg(feature = "metrics")]
144#[cfg_attr(docsrs, doc(cfg(feature = "metrics")))]
145pub mod observability;
146
147// ── Flat re-exports (match sc-core's surface so migration is mechanical) ────
148pub use audit::{AuditAction, AuditPipeline, AuditRecord, AuditSink};
149pub use auth::{AllowAll, Credentials, StreamAuthenticator};
150pub use bus::{
151 EventBus, PlaybackRegistry, PublishRegistry, Qos, StreamEvent, StreamEventKind, StreamHandle,
152 StreamMetadata, StreamState, Subscription,
153};
154pub use cluster::{ClusterRelay, NodeAddr};
155pub use engine::{AppSpec, Engine, EngineBuilder, EngineConfig};
156pub use error::{ProtocolErrorKind, StreamError};
157pub use frame::{AudioFrame, CodecId, FrameFlags, FrameType, MediaFrame, VideoFrame};
158pub use health::{HealthCheck, HealthRegistry, HealthReport, HealthStatus};
159pub use identity::{AppName, StreamId, StreamKey};
160pub use observe::{NoopObserver, Observer};
161pub use traits::{HwAccelBackend, MediaSink, MediaSource, ProtocolHandler, StorageBackend};
162pub use transcode::{RenditionSpec, Transcoder};
163
164/// The crate-wide fallible result. Mirrors `sc-core::Result`.
165pub type Result<T> = std::result::Result<T, StreamError>;
166
167/// Re-exports the derive macros expand against. Stable surface for codegen so
168/// internal files can move without touching the macro crate.
169#[cfg(feature = "macros")]
170#[doc(hidden)]
171pub mod __macro_support {
172 pub use crate::bus::PublishRegistry;
173 pub use crate::traits::{MediaSink, ProtocolHandler};
174 pub use crate::{MediaFrame, Result, StreamError, StreamKey};
175 pub use async_trait::async_trait;
176 pub use std::sync::Arc;
177 pub use tokio_util::sync::CancellationToken;
178}
179
180/// `use arcly_stream::prelude::*;` — everything a downstream user needs.
181pub mod prelude {
182 pub use crate::audit::{AuditPipeline, AuditRecord, AuditSink};
183 pub use crate::auth::{AllowAll, Credentials, StreamAuthenticator};
184 pub use crate::bus::{
185 EventBus, PlaybackRegistry, PublishRegistry, Qos, StreamEvent, StreamEventKind,
186 StreamHandle, StreamState, Subscription,
187 };
188 pub use crate::cluster::{ClusterRelay, NodeAddr};
189 pub use crate::engine::{AppSpec, Engine, EngineBuilder, EngineConfig};
190 pub use crate::error::{ProtocolErrorKind, StreamError};
191 pub use crate::frame::{CodecId, FrameFlags, FrameType, MediaFrame};
192 pub use crate::health::{HealthCheck, HealthRegistry, HealthStatus};
193 pub use crate::identity::{AppName, StreamId, StreamKey};
194 pub use crate::observe::{NoopObserver, Observer};
195 pub use crate::traits::{
196 HwAccelBackend, MediaSink, MediaSource, ProtocolHandler, StorageBackend,
197 };
198 pub use crate::transcode::{RenditionSpec, Transcoder};
199 pub use crate::Result;
200 pub use async_trait::async_trait;
201 pub use tokio_util::sync::CancellationToken;
202
203 #[cfg(feature = "macros")]
204 pub use arcly_stream_macros::{protocol, MediaSink as MediaSinkDerive};
205}