hyprstream_rpc/stream_info.rs
1//! Target-independent StreamInfo + StreamOpt types.
2//!
3//! Extracted from `streaming` (native-only) so that generated client code
4//! on wasm32 can reference `StreamInfo` without pulling in ZMQ/tokio deps.
5//!
6//! Service codegen modules emit `pub type StreamInfo = hyprstream_rpc::stream_info::StreamInfo;`
7//! (and similar aliases for the StreamOpt axis types) rather than generating duplicates.
8//!
9//! #273: `StreamInfo`, `StreamOpt`, and the five QoS axis unions are now fully
10//! code-generated from `streaming.capnp` into [`crate::streaming_types`] (the
11//! Cap'n Proto derive macro supports tagged-unions + data-carrying `group` arms).
12//! This module re-exports them as the canonical hub and keeps the hand-authored
13//! `Job`/`Log`/`Pipe` presets, which encode specific `StreamOpt` combinations.
14
15// ─── StreamOpt axis types ──────────────────────────────────────────────────────
16//
17// Code-generated (#273). The generated enums/struct match the historic
18// hand-written shapes exactly, so the presets and all call sites compile unchanged:
19// Ordering::{Ordered, Unordered{anti_replay_window}}
20// Delivery::{AtMostOnce, AtLeastOnce{dedup_window, resumable}}
21// Completion::{EndOfStream, None}
22// Retention::{Live, Blocks(u32), Seconds(u32)}
23// OverflowPolicy::{Block, DropOldest{high_water_mark}}
24// StreamOpt { ordering, delivery, completion, retention, overflow_policy }
25// StreamInfo { stream_id, dh_public: [u8; 32], qos, broadcast_path, reach }
26//
27// #274: the moq reach model — `StreamInfo.reach: Vec<Destination>` plus the
28// `Role` / `TransportConfig` / `QuicReach` types — is also code-generated here
29// from `streaming.capnp` (native capnp, no JSON-in-Text on the wire).
30pub use crate::streaming_types::{
31 Completion, Delivery, Destination, IrohReach, MoqlServerIdentity, Ordering, OverflowPolicy,
32 QuicReach, Retention, Role, StreamInfo, StreamOpt, TransportConfig,
33};
34
35/// Marker trait for typed stream QoS presets.
36///
37/// Each preset is a zero-sized type that encodes a specific `StreamOpt`
38/// configuration, enabling type-safe API contracts without runtime dispatch.
39/// Implement this trait to define a new named preset.
40pub trait StreamOptPreset: Clone + Send + Sync + 'static {
41 fn stream_opt() -> StreamOpt;
42}
43
44/// Inference / job streams.
45///
46/// Ordered, at-least-once with 4096-entry dedup window, resumable from
47/// last-acked Group, EndOfStream terminator, 256-Group relay retention,
48/// lossless backpressure. Use for InferenceService token streams and model
49/// lifecycle events (#169).
50#[derive(Debug, Clone, Copy, Default)]
51pub struct Job;
52
53/// Log / notification streams.
54///
55/// Ordered, at-least-once, no terminator sentinel, 300-second relay
56/// retention. Use for Metrics, Notification, and mobile clients with
57/// intermittent connectivity (#169).
58#[derive(Debug, Clone, Copy, Default)]
59pub struct Log;
60
61/// Pipe / console streams.
62///
63/// Ordered, at-least-once with 256-entry dedup, live retention, no
64/// terminator. Use for container I/O attach and the model↔worker callback
65/// DEALER replacement (#170).
66#[derive(Debug, Clone, Copy, Default)]
67pub struct Pipe;
68
69impl StreamOptPreset for Job {
70 fn stream_opt() -> StreamOpt {
71 StreamOpt {
72 ordering: Ordering::Ordered,
73 delivery: Delivery::AtLeastOnce {
74 dedup_window: 4096,
75 resumable: true,
76 },
77 completion: Completion::EndOfStream,
78 retention: Retention::Blocks(256),
79 overflow_policy: OverflowPolicy::Block,
80 }
81 }
82}
83
84impl StreamOptPreset for Log {
85 fn stream_opt() -> StreamOpt {
86 StreamOpt {
87 ordering: Ordering::Ordered,
88 delivery: Delivery::AtLeastOnce {
89 dedup_window: 4096,
90 resumable: true,
91 },
92 completion: Completion::None,
93 retention: Retention::Seconds(300),
94 overflow_policy: OverflowPolicy::Block,
95 }
96 }
97}
98
99impl StreamOptPreset for Pipe {
100 fn stream_opt() -> StreamOpt {
101 StreamOpt {
102 ordering: Ordering::Ordered,
103 delivery: Delivery::AtLeastOnce {
104 dedup_window: 256,
105 resumable: false,
106 },
107 completion: Completion::None,
108 retention: Retention::Live,
109 overflow_policy: OverflowPolicy::Block,
110 }
111 }
112}
113
114/// Default event-bus delivery (#606).
115///
116/// At-most-once, drop-oldest-on-backpressure, live retention, no terminator.
117/// Matches the historic `moq_event` "fan-out, at-most-once, best-effort"
118/// behaviour, but BOUNDED: a slow subscriber's local queue evicts its oldest
119/// entry instead of blocking the publisher-side read tasks indefinitely. Use
120/// for lifecycle/telemetry events where the latest state matters more than
121/// every historical transition (e.g. `worker.*.heartbeat`).
122#[derive(Debug, Clone, Copy, Default)]
123pub struct EventLive;
124
125/// Reliable event-bus delivery (#606).
126///
127/// At-least-once with a 1024-entry dedup window, resumable from last-acked
128/// sequence, retains the last 64 delivery blocks, lossless (block) backpressure.
129/// Use for events that must not be silently dropped, e.g. `model.loaded` /
130/// `model.loadFailed` and other completion/lifecycle-latch signals (see the
131/// EventService consolidation epic, EV7).
132#[derive(Debug, Clone, Copy, Default)]
133pub struct EventReliable;
134
135impl StreamOptPreset for EventLive {
136 fn stream_opt() -> StreamOpt {
137 StreamOpt {
138 ordering: Ordering::Ordered,
139 delivery: Delivery::AtMostOnce,
140 completion: Completion::None,
141 retention: Retention::Live,
142 overflow_policy: OverflowPolicy::DropOldest {
143 high_water_mark: 256,
144 },
145 }
146 }
147}
148
149impl StreamOptPreset for EventReliable {
150 fn stream_opt() -> StreamOpt {
151 StreamOpt {
152 ordering: Ordering::Ordered,
153 delivery: Delivery::AtLeastOnce {
154 dedup_window: 1024,
155 resumable: true,
156 },
157 completion: Completion::None,
158 retention: Retention::Blocks(64),
159 overflow_policy: OverflowPolicy::Block,
160 }
161 }
162}