Skip to main content

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}