hyprstream_rpc_std/stream_mount.rs
1//! VFS Mount for streaming data — streams as 9P files (epic #809 W3, #819).
2//!
3//! `/stream/{topic}/data` — read stream data (sequential, blocks until data/EOF)
4//! `/stream/{topic}/info` — read stream metadata (JSON)
5//! `/stream/{topic}/qos` — read/select QoS (StreamOpt vocabulary as tokens)
6//! `/stream/{topic}/ctl` — write control commands (`cancel`, `qos …`, `resume …`)
7//!
8//! Follows Plan 9 `/net/tcp/{n}/data` pattern. Streams are created by
9//! dispatching streaming RPC methods via `RpcClient::open_stream()` and
10//! registered in the StreamRegistry.
11//!
12//! # Interface, not a byte-copy path (#819)
13//!
14//! This mount is the *interface*: naming, addressing, and open-time
15//! authorization. It is **not** a memcpy path that replaces the moq carrier.
16//! The registered [`StreamHandle`] IS the moq carrier subscription established
17//! at open — QUIC-native delivery (per-object streams, drop-stale, datagram,
18//! relay rendezvous) stays intact underneath. Two consumption modes ride the
19//! same handle:
20//!
21//! - **Floor (`Tread` on `data`)**: blocking push semantics, exactly Plan 9
22//! `/net/tcp/n/data`. Always works; correct and sufficient for low-rate
23//! streams (tokens). This is the floor, **not** the ceiling.
24//! - **Carrier handle (bulk)**: high-rate / bulk consumers take the
25//! carrier-backed handle directly ([`StreamRegistry::take_handle`]) and drive
26//! the moq subscriber, exactly as #817 hands out mmap-at-open for weights.
27//! The frames are **never** routed one-by-one through `Tread` — that would
28//! flatten moq's non-fungible delivery semantics to a lowest-common-
29//! denominator read, the anti-pattern this design exists to avoid.
30//!
31//! QoS that does not reduce to reliable-in-order is selected through a small
32//! vocabulary ([`StreamQos`]) on `qos` / `ctl` — StreamOpt's existing encoding
33//! (latest-wins, lossy-ok, drop-stale) moved *onto the file*, so the carrier's
34//! rich semantics stay first-class through the interface.
35//!
36//! Events (group-keyed EventService, #600) ride this same surface via
37//! [`StreamKind::Event`] rather than a separate plane — see [`StreamEntry`].
38
39use std::collections::HashMap;
40
41use parking_lot::Mutex;
42
43use async_trait::async_trait;
44use hyprstream_rpc::stream_consumer::{StreamHandle, StreamPayload};
45use hyprstream_rpc::stream_info::{
46 Completion, Delivery, Ordering, OverflowPolicy, Retention, StreamOpt,
47};
48use hyprstream_rpc::Subject;
49use hyprstream_vfs::{DirEntry, Fid, Mount, MountError, Stat};
50
51// ============================================================================
52// StreamKind — what plane a topic belongs to (#819: events ride the same surface)
53// ============================================================================
54
55/// Which plane a registered topic belongs to.
56///
57/// Both ride the *same* `/stream` surface (#819 requirement: the group-keyed
58/// EventService of #600 is not a separate plane). The kind is reflected in
59/// `info`/`stat` so a reader can tell a point-to-point stream from an event
60/// broadcast without a second namespace.
61#[derive(Clone, Copy, Debug, PartialEq, Eq)]
62pub enum StreamKind {
63 /// A point-to-point inference/data stream (the default — tokens, I/O).
64 Stream,
65 /// A group-keyed EventService broadcast (#600) surfaced as a stream file.
66 Event,
67}
68
69impl StreamKind {
70 fn as_str(self) -> &'static str {
71 match self {
72 StreamKind::Stream => "stream",
73 StreamKind::Event => "event",
74 }
75 }
76}
77
78// ============================================================================
79// StreamQos — the StreamOpt QoS vocabulary, moved onto the file (#819)
80// ============================================================================
81
82/// The consumer-selectable QoS vocabulary, wired from `StreamOpt` onto the file.
83///
84/// A stream's carrier (moq / iroh) has *non-fungible* delivery semantics: a
85/// reliable-in-order default plus richer modes that don't reduce to it. Rather
86/// than flatten those to a plain read, #819 exposes them as a small token
87/// vocabulary written to `qos` / `ctl`. Each token toggles the `StreamOpt`
88/// axes that already encode the behaviour (there is no new QoS model — this is
89/// StreamOpt's existing encoding, addressable through the file):
90///
91/// | token | StreamOpt effect |
92/// |---------------|-------------------------------------------------------------|
93/// | `reliable` | the fail-closed default: ordered · at-least-once · end-of-stream · lossless backpressure |
94/// | `latest-wins` | drop-oldest overflow (depth 1) + live retention — only the newest payload matters |
95/// | `lossy-ok` | at-most-once + no terminator required + unordered (gaps tolerated) |
96/// | `drop-stale` | drop-oldest overflow + live retention — shed backlog instead of blocking |
97///
98/// Tokens compose (`latest-wins drop-stale`); `reliable` resets to the floor.
99/// [`StreamQos::from_stream_opt`] / [`StreamQos::to_tokens`] round-trip the
100/// selection against the underlying `StreamOpt`.
101#[derive(Clone, Debug, PartialEq)]
102pub struct StreamQos {
103 opt: StreamOpt,
104}
105
106impl StreamQos {
107 /// The fail-closed reliable-in-order floor (matches StreamOpt's `@0`
108 /// strictest defaults: ordered + end-of-stream, plus at-least-once /
109 /// live / block backpressure).
110 pub fn reliable() -> Self {
111 Self {
112 opt: StreamOpt {
113 ordering: Ordering::Ordered,
114 delivery: Delivery::AtLeastOnce {
115 dedup_window: 4096,
116 resumable: true,
117 },
118 completion: Completion::EndOfStream,
119 retention: Retention::Live,
120 overflow_policy: OverflowPolicy::Block,
121 },
122 }
123 }
124
125 /// Wrap an existing `StreamOpt` (e.g. the producer-signed one from
126 /// `StreamInfo`) so it can be rendered as tokens / mutated by selection.
127 pub fn from_stream_opt(opt: StreamOpt) -> Self {
128 Self { opt }
129 }
130
131 /// The underlying `StreamOpt` this selection resolves to.
132 pub fn stream_opt(&self) -> &StreamOpt {
133 &self.opt
134 }
135
136 /// Whether this QoS tolerates loss / gaps (at-most-once **or** unordered).
137 ///
138 /// Under lossy QoS the mount surfaces a mid-stream carrier error as a soft
139 /// end-of-stream (EOF) rather than a hard read error — the consumer-visible
140 /// half of "lossy-ok". Reliable QoS keeps failing closed.
141 pub fn is_lossy(&self) -> bool {
142 matches!(self.opt.delivery, Delivery::AtMostOnce)
143 || matches!(self.opt.ordering, Ordering::Unordered { .. })
144 }
145
146 /// Apply one vocabulary token, mutating the relevant `StreamOpt` axes.
147 /// Unknown tokens return `false` (the caller reports the error).
148 pub fn apply_token(&mut self, token: &str) -> bool {
149 match token {
150 "reliable" => {
151 *self = Self::reliable();
152 true
153 }
154 "latest-wins" => {
155 self.opt.overflow_policy = OverflowPolicy::DropOldest { high_water_mark: 1 };
156 self.opt.retention = Retention::Live;
157 self.opt.completion = Completion::None;
158 true
159 }
160 "lossy-ok" => {
161 self.opt.delivery = Delivery::AtMostOnce;
162 self.opt.completion = Completion::None;
163 self.opt.ordering = Ordering::Unordered {
164 anti_replay_window: 64,
165 };
166 true
167 }
168 "drop-stale" => {
169 self.opt.overflow_policy = OverflowPolicy::DropOldest {
170 high_water_mark: 256,
171 };
172 self.opt.retention = Retention::Live;
173 true
174 }
175 _ => false,
176 }
177 }
178
179 /// Parse a whitespace-separated token list, applying each to `reliable`.
180 /// Returns the offending token on the first unknown one.
181 pub fn parse(spec: &str) -> Result<Self, String> {
182 let mut qos = Self::reliable();
183 for tok in spec.split_whitespace() {
184 if !qos.apply_token(tok) {
185 return Err(tok.to_owned());
186 }
187 }
188 Ok(qos)
189 }
190
191 /// Render the selection back to its non-default tokens (round-trips
192 /// `parse`/`apply_token`). Always non-empty — `reliable` when at the floor.
193 pub fn to_tokens(&self) -> Vec<&'static str> {
194 let mut tokens = Vec::new();
195 let dropping = matches!(self.opt.overflow_policy, OverflowPolicy::DropOldest { .. });
196 match self.opt.overflow_policy {
197 OverflowPolicy::DropOldest { high_water_mark } if high_water_mark <= 1 => {
198 tokens.push("latest-wins");
199 }
200 OverflowPolicy::DropOldest { .. } => tokens.push("drop-stale"),
201 OverflowPolicy::Block => {}
202 }
203 if self.is_lossy() {
204 tokens.push("lossy-ok");
205 }
206 if tokens.is_empty() && !dropping {
207 tokens.push("reliable");
208 }
209 tokens
210 }
211}
212
213impl Default for StreamQos {
214 fn default() -> Self {
215 Self::reliable()
216 }
217}
218
219// ============================================================================
220// Stream Registry — tracks active streams
221// ============================================================================
222
223/// Metadata and state for an active stream.
224///
225/// The `handle` is the moq **carrier subscription** established at open — the
226/// `data` file's blocking `Tread` is the floor push path over it, and bulk
227/// consumers take the same handle whole ([`StreamRegistry::take_handle`]). It is
228/// never rebuilt per read.
229pub struct StreamEntry {
230 /// Verified stream handle — does HMAC verification internally.
231 pub handle: Option<Box<dyn StreamHandle>>,
232 /// Owner identity (for access control)
233 pub owner: String,
234 /// Bytes received so far
235 pub bytes_received: u64,
236 /// Blocks received so far
237 pub blocks_received: u64,
238 /// Which plane this topic belongs to (#819 — events ride the same surface).
239 pub kind: StreamKind,
240 /// Consumer-selected QoS (StreamOpt vocabulary; see [`StreamQos`]).
241 pub qos: StreamQos,
242 /// Resume cursor (#169 seam): the next sequence/offset a resumed reader
243 /// wants. `0` = live/from-start. Full at-least-once dedup is #169 follow-up.
244 pub resume_seq: u64,
245}
246
247impl StreamEntry {
248 /// A point-to-point stream entry at the reliable-in-order floor.
249 pub fn stream(handle: Option<Box<dyn StreamHandle>>, owner: String) -> Self {
250 Self {
251 handle,
252 owner,
253 bytes_received: 0,
254 blocks_received: 0,
255 kind: StreamKind::Stream,
256 qos: StreamQos::reliable(),
257 resume_seq: 0,
258 }
259 }
260
261 /// An event entry (#600 group-keyed EventService surfaced on `/stream`).
262 ///
263 /// Events default to `latest-wins` — for lifecycle/telemetry the newest
264 /// state matters more than every intermediate one (mirrors the `EventLive`
265 /// StreamOpt preset). The `handle` is the event carrier subscription; see
266 /// the events seam note on [`StreamRegistry::register`].
267 pub fn event(handle: Option<Box<dyn StreamHandle>>, owner: String) -> Self {
268 let mut qos = StreamQos::reliable();
269 qos.apply_token("latest-wins");
270 Self {
271 handle,
272 owner,
273 bytes_received: 0,
274 blocks_received: 0,
275 kind: StreamKind::Event,
276 qos,
277 resume_seq: 0,
278 }
279 }
280}
281
282/// Registry of active streams, keyed by topic.
283pub struct StreamRegistry {
284 streams: Mutex<HashMap<String, StreamEntry>>,
285}
286
287impl StreamRegistry {
288 pub fn new() -> Self {
289 Self {
290 streams: Mutex::new(HashMap::new()),
291 }
292 }
293
294 /// Register a stream or event under `topic`.
295 ///
296 /// Both planes share this one registry (#819): a point-to-point stream
297 /// ([`StreamEntry::stream`]) and a group-keyed EventService broadcast
298 /// ([`StreamEntry::event`], #600) become topics on the same `/stream`
299 /// surface. The entry's `handle` is the carrier subscription — for events
300 /// the full EventService-consumer→[`StreamHandle`] adapter (group-key
301 /// decryption over the moq_event `OriginConsumer`) is the marked follow-up;
302 /// this seam is kind-aware and ready to carry it (an event entry with a
303 /// `None` handle is an announced-but-not-yet-subscribed topic).
304 pub fn register(&self, topic: String, entry: StreamEntry) {
305 self.lock().insert(topic, entry);
306 }
307
308 /// Check if a topic exists.
309 pub fn exists(&self, topic: &str) -> bool {
310 self.lock().contains_key(topic)
311 }
312
313 /// List active topic names (optionally filtered by owner).
314 pub fn list_topics(&self, owner_filter: Option<&str>) -> Vec<String> {
315 self.lock()
316 .iter()
317 .filter(|(_, e)| owner_filter.is_none() || owner_filter == Some(e.owner.as_str()))
318 .map(|(k, _)| k.clone())
319 .collect()
320 }
321
322 /// Remove a stream and return it for cleanup.
323 pub fn remove(&self, topic: &str) -> Option<StreamEntry> {
324 self.lock().remove(topic)
325 }
326
327 /// Whether a topic currently holds its carrier-backed handle.
328 ///
329 /// The handle is the moq carrier subscription established at open; this is
330 /// `false` while a `data` read has it checked out, or after
331 /// [`take_handle`](Self::take_handle) hands it to a bulk consumer.
332 pub fn has_carrier_handle(&self, topic: &str) -> bool {
333 self.lock()
334 .get(topic)
335 .map(|e| e.handle.is_some())
336 .unwrap_or(false)
337 }
338
339 /// Take the carrier-backed handle whole for the **bulk** consumption path
340 /// (#819 / same handle-at-open model as #817's mmap-for-weights).
341 ///
342 /// This is the ceiling: a high-rate consumer drives the moq subscriber
343 /// directly instead of pulling frame-by-frame through `Tread`, so moq's
344 /// QUIC-native delivery semantics are preserved rather than flattened into
345 /// a copy loop. Returns `None` if the topic is unknown or the handle is
346 /// already checked out. The entry stays registered (info/qos/ctl remain
347 /// addressable); the caller owns the subscription until it drops or
348 /// re-parks it.
349 pub fn take_handle(&self, topic: &str) -> Option<Box<dyn StreamHandle>> {
350 self.lock().get_mut(topic).and_then(|e| e.handle.take())
351 }
352
353 /// The plane a topic belongs to (stream vs event), if registered.
354 pub fn kind(&self, topic: &str) -> Option<StreamKind> {
355 self.lock().get(topic).map(|e| e.kind)
356 }
357
358 /// The consumer-selected QoS for a topic, if registered.
359 pub fn qos(&self, topic: &str) -> Option<StreamQos> {
360 self.lock().get(topic).map(|e| e.qos.clone())
361 }
362
363 /// Select QoS for a topic (the `qos`/`ctl` vocabulary write path).
364 /// Returns `false` if the topic is unknown.
365 pub fn set_qos(&self, topic: &str, qos: StreamQos) -> bool {
366 match self.lock().get_mut(topic) {
367 Some(e) => {
368 e.qos = qos;
369 true
370 }
371 None => false,
372 }
373 }
374
375 /// Set the resume cursor for a topic (#169 seam). Returns `false` if
376 /// the topic is unknown.
377 pub fn set_resume(&self, topic: &str, seq: u64) -> bool {
378 match self.lock().get_mut(topic) {
379 Some(e) => {
380 e.resume_seq = seq;
381 true
382 }
383 None => false,
384 }
385 }
386
387 /// Lock the stream map (`parking_lot` — no poison).
388 fn lock(&self) -> parking_lot::MutexGuard<'_, HashMap<String, StreamEntry>> {
389 self.streams.lock()
390 }
391}
392
393impl Default for StreamRegistry {
394 fn default() -> Self {
395 Self::new()
396 }
397}
398
399// ============================================================================
400// Fid state for stream paths
401// ============================================================================
402
403#[derive(Clone, Debug)]
404enum StreamFidState {
405 /// /stream/ root directory
406 Root,
407 /// /stream/{topic}/ directory
408 TopicDir { topic: String },
409 /// /stream/{topic}/data — active data pipe
410 Data { topic: String },
411 /// /stream/{topic}/info — metadata
412 Info { topic: String },
413 /// /stream/{topic}/qos — read/select QoS (StreamOpt vocabulary)
414 Qos { topic: String },
415 /// /stream/{topic}/ctl — control
416 Ctl { topic: String },
417}
418
419// ============================================================================
420// StreamMount — serves /stream/ namespace
421// ============================================================================
422
423/// VFS mount for streaming data pipes.
424///
425/// Streams appear as directories under `/stream/{topic}/` with `data`, `info`,
426/// and `ctl` pseudo-files. Reading from `data` blocks until the next verified
427/// payload arrives via the StreamHandle.
428///
429/// Native + wasm (#670): the `Mount` `read`/`write` path awaits
430/// [`StreamHandle`] methods, which now return `Send` futures (the
431/// `StreamHandle` trait dropped its `?Send`). That lets this mount be a
432/// genuinely `Send + Sync` `Mount` on native — served to a Cloud Hypervisor
433/// guest or any native namespace — while `#[async_trait(?Send)]` on wasm keeps
434/// the browser path working. `StreamRegistry`/`StreamEntry` above are
435/// target-agnostic so the generic service mount can register streams on any
436/// target.
437pub struct StreamMount {
438 registry: std::sync::Arc<StreamRegistry>,
439}
440
441impl StreamMount {
442 pub fn new(registry: std::sync::Arc<StreamRegistry>) -> Self {
443 Self { registry }
444 }
445}
446
447#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
448#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
449impl Mount for StreamMount {
450 async fn walk(&self, components: &[&str], _caller: &Subject) -> Result<Fid, MountError> {
451 let state = match components {
452 [] => StreamFidState::Root,
453 [topic] => {
454 if !self.registry.exists(topic) {
455 return Err(MountError::NotFound(topic.to_string()));
456 }
457 StreamFidState::TopicDir {
458 topic: topic.to_string(),
459 }
460 }
461 [topic, "data"] => StreamFidState::Data {
462 topic: topic.to_string(),
463 },
464 [topic, "info"] => StreamFidState::Info {
465 topic: topic.to_string(),
466 },
467 [topic, "qos"] => StreamFidState::Qos {
468 topic: topic.to_string(),
469 },
470 [topic, "ctl"] => StreamFidState::Ctl {
471 topic: topic.to_string(),
472 },
473 _ => {
474 return Err(MountError::NotFound(components.join("/")));
475 }
476 };
477 Ok(Fid::new(state))
478 }
479
480 /// Open-time authorization + subscription binding (#819).
481 ///
482 /// This is where the interface authorizes: the `caller` `Subject` is the
483 /// open-time credential a PEP checks before the carrier subscription is
484 /// handed out (the same "authorize once at open, then stream over the
485 /// carrier" model as #817's weights). MAC enforcement here is the epic's
486 /// reference-monitor seam (#547 / #568) and is deliberately *not* wired in
487 /// this app-half story — the mount fails closed with the caller threaded
488 /// through, ready for the PEP. It does not re-open the carrier per read:
489 /// the subscription established at registration IS the handle.
490 async fn open(&self, _fid: &mut Fid, _mode: u8, _caller: &Subject) -> Result<(), MountError> {
491 Ok(())
492 }
493
494 async fn read(
495 &self,
496 fid: &Fid,
497 offset: u64,
498 count: u32,
499 _caller: &Subject,
500 ) -> Result<Vec<u8>, MountError> {
501 let state = fid
502 .downcast_ref::<StreamFidState>()
503 .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
504
505 match state {
506 StreamFidState::Root => Err(MountError::IsDirectory("stream root".into())),
507 StreamFidState::TopicDir { .. } => {
508 Err(MountError::IsDirectory("stream topic dir".into()))
509 }
510 StreamFidState::Data { topic } => {
511 // Check completion + QoS WITHOUT holding borrow across await.
512 // `is_lossy` decides whether a mid-stream carrier error is
513 // surfaced as a hard read error (reliable) or a soft EOF
514 // (lossy-ok / latest-wins / drop-stale) — the consumer-visible
515 // half of the QoS vocabulary selected through the file (#819).
516 let (is_completed, is_lossy) = {
517 let streams = self.registry.lock();
518 let entry = streams
519 .get(topic.as_str())
520 .ok_or_else(|| MountError::NotFound(topic.clone()))?;
521 let done = entry
522 .handle
523 .as_ref()
524 .map(|h| h.is_completed())
525 .unwrap_or(true);
526 (done, entry.qos.is_lossy())
527 };
528
529 if is_completed {
530 return Ok(vec![]); // EOF
531 }
532
533 // Take handle out temporarily (avoids holding RefCell borrow across await)
534 let mut handle = {
535 let mut streams = self.registry.lock();
536 let entry = streams
537 .get_mut(topic.as_str())
538 .ok_or_else(|| MountError::NotFound(topic.clone()))?;
539 entry
540 .handle
541 .take()
542 .ok_or_else(|| MountError::Io("stream read in progress".into()))?
543 };
544
545 // Read next verified payload (await without holding borrow)
546 let result = handle.next_payload().await;
547
548 // Put handle back (its completion state is tracked internally).
549 {
550 let mut streams = self.registry.lock();
551 if let Some(entry) = streams.get_mut(topic.as_str()) {
552 entry.handle = Some(handle);
553 }
554 }
555
556 match result {
557 Ok(Some(StreamPayload::Data(data))) => {
558 let mut streams = self.registry.lock();
559 if let Some(entry) = streams.get_mut(topic.as_str()) {
560 entry.bytes_received += data.len() as u64;
561 entry.blocks_received += 1;
562 }
563 Ok(data)
564 }
565 Ok(Some(StreamPayload::Complete(meta))) => {
566 let mut streams = self.registry.lock();
567 if let Some(entry) = streams.get_mut(topic.as_str()) {
568 entry.blocks_received += 1;
569 }
570 Ok(meta)
571 }
572 Ok(Some(StreamPayload::Error(msg))) => {
573 if is_lossy {
574 // lossy-ok: tolerate the error as end-of-stream
575 // rather than failing the read (drop-stale/live).
576 Ok(vec![])
577 } else {
578 Err(MountError::Io(format!("stream error: {msg}")))
579 }
580 }
581 Ok(Some(StreamPayload::Tagged { payload, .. })) => {
582 let mut streams = self.registry.lock();
583 if let Some(entry) = streams.get_mut(topic.as_str()) {
584 entry.bytes_received += payload.len() as u64;
585 entry.blocks_received += 1;
586 }
587 Ok(payload)
588 }
589 Ok(None) => Ok(vec![]), // EOF
590 Err(e) => {
591 if is_lossy {
592 Ok(vec![]) // lossy-ok: soft EOF instead of a hard error
593 } else {
594 Err(MountError::Io(format!("stream read: {e}")))
595 }
596 }
597 }
598 }
599 StreamFidState::Info { topic } => {
600 let streams = self.registry.lock();
601 let entry = streams
602 .get(topic.as_str())
603 .ok_or_else(|| MountError::NotFound(topic.clone()))?;
604
605 let complete = entry
606 .handle
607 .as_ref()
608 .map(|h| h.is_completed())
609 .unwrap_or(true);
610 let info = serde_json::json!({
611 "topic": topic,
612 "kind": entry.kind.as_str(),
613 "bytesReceived": entry.bytes_received,
614 "blocksReceived": entry.blocks_received,
615 "complete": complete,
616 "carrierHandle": entry.handle.is_some(),
617 "qos": entry.qos.to_tokens(),
618 "resumeSeq": entry.resume_seq,
619 });
620 let bytes = serde_json::to_string_pretty(&info)
621 .unwrap_or_default()
622 .into_bytes();
623 let start = (offset as usize).min(bytes.len());
624 let end = (start + count as usize).min(bytes.len());
625 Ok(bytes[start..end].to_vec())
626 }
627 StreamFidState::Qos { topic } => {
628 // Read the current QoS selection as its token vocabulary
629 // (StreamOpt encoding, addressable through the file — #819).
630 let streams = self.registry.lock();
631 let entry = streams
632 .get(topic.as_str())
633 .ok_or_else(|| MountError::NotFound(topic.clone()))?;
634 let mut line = entry.qos.to_tokens().join(" ");
635 line.push('\n');
636 let bytes = line.into_bytes();
637 let start = (offset as usize).min(bytes.len());
638 let end = (start + count as usize).min(bytes.len());
639 Ok(bytes[start..end].to_vec())
640 }
641 StreamFidState::Ctl { .. } => {
642 // Ctl is write-only
643 Ok(vec![])
644 }
645 }
646 }
647
648 async fn write(
649 &self,
650 fid: &Fid,
651 _offset: u64,
652 data: &[u8],
653 _caller: &Subject,
654 ) -> Result<u32, MountError> {
655 let state = fid
656 .downcast_ref::<StreamFidState>()
657 .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
658
659 match state {
660 StreamFidState::Ctl { topic } => {
661 let line = std::str::from_utf8(data).unwrap_or("").trim();
662 let (cmd, arg) = match line.split_once(char::is_whitespace) {
663 Some((c, a)) => (c, a.trim()),
664 None => (line, ""),
665 };
666 match cmd {
667 "cancel" => {
668 if let Some(entry) = self.registry.remove(topic) {
669 if let Some(mut handle) = entry.handle {
670 let _ = handle.cancel().await;
671 }
672 }
673 Ok(data.len() as u32)
674 }
675 // QoS selection through ctl (#819): `qos latest-wins drop-stale`.
676 "qos" => {
677 let qos = StreamQos::parse(arg).map_err(|tok| {
678 MountError::InvalidArgument(format!("unknown qos token: {tok}"))
679 })?;
680 if !self.registry.set_qos(topic, qos) {
681 return Err(MountError::NotFound(topic.clone()));
682 }
683 Ok(data.len() as u32)
684 }
685 // Resume seam (#169): set the cursor a resumed reader wants.
686 // The floor path is `Tread` at offset; the carrier handle
687 // resumes its subscription from this seq. Full at-least-once
688 // dedup is the #169 follow-up.
689 "resume" => {
690 let seq: u64 = arg.parse().map_err(|_| {
691 MountError::InvalidArgument(format!("bad resume seq: {arg}"))
692 })?;
693 if !self.registry.set_resume(topic, seq) {
694 return Err(MountError::NotFound(topic.clone()));
695 }
696 Ok(data.len() as u32)
697 }
698 _ => Err(MountError::NotSupported(format!(
699 "unknown stream command: {}",
700 cmd
701 ))),
702 }
703 }
704 // The `qos` file is directly writable — same vocabulary as `ctl qos`.
705 StreamFidState::Qos { topic } => {
706 let spec = std::str::from_utf8(data).unwrap_or("").trim();
707 let qos = StreamQos::parse(spec).map_err(|tok| {
708 MountError::InvalidArgument(format!("unknown qos token: {tok}"))
709 })?;
710 if !self.registry.set_qos(topic, qos) {
711 return Err(MountError::NotFound(topic.clone()));
712 }
713 Ok(data.len() as u32)
714 }
715 _ => Err(MountError::NotSupported(
716 "stream files are read-only".into(),
717 )),
718 }
719 }
720
721 async fn readdir(&self, fid: &Fid, _caller: &Subject) -> Result<Vec<DirEntry>, MountError> {
722 let state = fid
723 .downcast_ref::<StreamFidState>()
724 .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
725
726 match state {
727 StreamFidState::Root => {
728 let topics = self.registry.list_topics(None);
729 Ok(topics
730 .into_iter()
731 .map(|name| DirEntry {
732 name,
733 is_dir: true,
734 size: 0,
735 stat: None,
736 })
737 .collect())
738 }
739 StreamFidState::TopicDir { .. } => Ok(vec![
740 DirEntry {
741 name: "data".into(),
742 is_dir: false,
743 size: 0,
744 stat: None,
745 },
746 DirEntry {
747 name: "info".into(),
748 is_dir: false,
749 size: 0,
750 stat: None,
751 },
752 DirEntry {
753 name: "qos".into(),
754 is_dir: false,
755 size: 0,
756 stat: None,
757 },
758 DirEntry {
759 name: "ctl".into(),
760 is_dir: false,
761 size: 0,
762 stat: None,
763 },
764 ]),
765 _ => Err(MountError::NotDirectory("not a directory".into())),
766 }
767 }
768
769 async fn stat(&self, fid: &Fid, _caller: &Subject) -> Result<Stat, MountError> {
770 let state = fid
771 .downcast_ref::<StreamFidState>()
772 .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
773 let (qtype, name) = match state {
774 StreamFidState::Root => (0x80, "stream"),
775 StreamFidState::TopicDir { topic } => (0x80, topic.as_str()),
776 StreamFidState::Data { .. } => (0, "data"),
777 StreamFidState::Info { .. } => (0, "info"),
778 StreamFidState::Qos { .. } => (0, "qos"),
779 StreamFidState::Ctl { .. } => (0, "ctl"),
780 };
781 Ok(Stat::unknown_qid(qtype, 0, name.to_string(), 0))
782 }
783
784 async fn clunk(&self, _fid: Fid, _caller: &Subject) {}
785}
786
787// ============================================================================
788// Tests
789// ============================================================================
790
791// #670: these assertions are meaningful only on native, where `StreamMount` is
792// `Send + Sync` and the `Mount::read` future must be `Send`. On wasm the mount
793// is `#[async_trait(?Send)]` by design (JS-backed transport), so gate them out.
794#[cfg(all(test, not(target_arch = "wasm32")))]
795#[allow(clippy::unwrap_used, clippy::expect_used)]
796mod tests {
797 use super::*;
798
799 fn assert_send_sync<T: Send + Sync>() {}
800 fn assert_send<F: std::future::Future + Send>(_f: F) {}
801
802 /// #670: `StreamMount` and its registry must be a native `Send + Sync`
803 /// `Mount`, so it can live behind `Arc<dyn Mount>` and be served from a
804 /// multi-threaded runtime / to a CH guest.
805 #[test]
806 fn stream_mount_is_native_send_sync() {
807 assert_send_sync::<StreamMount>();
808 assert_send_sync::<StreamRegistry>();
809
810 // Usable as a shared `Arc<dyn Mount>` — the whole point of un-gating it.
811 fn takes_mount(_m: std::sync::Arc<dyn Mount>) {}
812 let reg = std::sync::Arc::new(StreamRegistry::new());
813 takes_mount(std::sync::Arc::new(StreamMount::new(reg)));
814 }
815
816 /// The `read` future itself must be `Send` — this is exactly what #670
817 /// unblocks. `read`'s `Data` branch holds a `Box<dyn StreamHandle>` across
818 /// `handle.next_payload().await`; if `StreamHandle`'s futures regressed to
819 /// `!Send` the whole `read` future would be `!Send` and this stops
820 /// compiling, regardless of which match arm runs at runtime.
821 #[test]
822 fn stream_mount_read_future_is_send() {
823 let reg = std::sync::Arc::new(StreamRegistry::new());
824 let mount = StreamMount::new(reg);
825 assert_send(async move {
826 let fid = Fid::new(StreamFidState::Data {
827 topic: "topic".to_string(),
828 });
829 let caller = Subject::anonymous();
830 let _ = mount.read(&fid, 0, 0, &caller).await;
831 });
832 }
833
834 // ─── #819: a mock carrier handle for the surface/floor/handle tests ─────
835
836 /// A minimal in-memory [`StreamHandle`] standing in for a moq carrier
837 /// subscription. It hands out queued payloads; taking it whole out of the
838 /// registry proves the bulk path drives *this* subscription rather than a
839 /// per-read reconstruction.
840 struct MockHandle {
841 id: String,
842 queue: std::collections::VecDeque<StreamPayload>,
843 completed: bool,
844 cancelled: bool,
845 }
846
847 impl MockHandle {
848 fn new(id: &str, payloads: Vec<StreamPayload>) -> Self {
849 Self {
850 id: id.to_string(),
851 queue: payloads.into_iter().collect(),
852 completed: false,
853 cancelled: false,
854 }
855 }
856 }
857
858 #[async_trait]
859 impl StreamHandle for MockHandle {
860 async fn next_payload(&mut self) -> anyhow::Result<Option<StreamPayload>> {
861 match self.queue.pop_front() {
862 Some(p) => {
863 if matches!(p, StreamPayload::Complete(_) | StreamPayload::Error(_)) {
864 self.completed = true;
865 }
866 Ok(Some(p))
867 }
868 None => {
869 self.completed = true;
870 Ok(None)
871 }
872 }
873 }
874 async fn cancel(&mut self) -> anyhow::Result<()> {
875 self.cancelled = true;
876 Ok(())
877 }
878 fn stream_id(&self) -> &str {
879 &self.id
880 }
881 fn is_completed(&self) -> bool {
882 self.completed
883 }
884 }
885
886 fn boxed(h: MockHandle) -> Box<dyn StreamHandle> {
887 Box::new(h)
888 }
889
890 // ─── QoS vocabulary: StreamOpt encoding moved onto the file ─────────────
891
892 #[test]
893 fn qos_reliable_is_the_failclosed_floor() {
894 let q = StreamQos::reliable();
895 assert!(matches!(q.stream_opt().ordering, Ordering::Ordered));
896 assert!(matches!(q.stream_opt().completion, Completion::EndOfStream));
897 assert!(matches!(
898 q.stream_opt().overflow_policy,
899 OverflowPolicy::Block
900 ));
901 assert!(!q.is_lossy());
902 assert_eq!(q.to_tokens(), vec!["reliable"]);
903 }
904
905 #[test]
906 fn qos_tokens_map_onto_streamopt_axes() {
907 // latest-wins → drop-oldest depth 1 + live + no terminator required.
908 let mut lw = StreamQos::reliable();
909 assert!(lw.apply_token("latest-wins"));
910 assert!(matches!(
911 lw.stream_opt().overflow_policy,
912 OverflowPolicy::DropOldest { high_water_mark: 1 }
913 ));
914 assert!(matches!(lw.stream_opt().completion, Completion::None));
915
916 // lossy-ok → at-most-once + unordered (gaps tolerated).
917 let mut lo = StreamQos::reliable();
918 assert!(lo.apply_token("lossy-ok"));
919 assert!(matches!(lo.stream_opt().delivery, Delivery::AtMostOnce));
920 assert!(matches!(
921 lo.stream_opt().ordering,
922 Ordering::Unordered { .. }
923 ));
924 assert!(lo.is_lossy());
925
926 // drop-stale → drop-oldest overflow (shed backlog) + live retention.
927 let mut ds = StreamQos::reliable();
928 assert!(ds.apply_token("drop-stale"));
929 assert!(matches!(
930 ds.stream_opt().overflow_policy,
931 OverflowPolicy::DropOldest { .. }
932 ));
933
934 // Unknown token is rejected, not silently ignored.
935 assert!(!StreamQos::reliable().apply_token("bogus"));
936 }
937
938 #[test]
939 fn qos_parse_render_roundtrips() {
940 let q = StreamQos::parse("lossy-ok").unwrap();
941 assert!(q.to_tokens().contains(&"lossy-ok"));
942 assert_eq!(StreamQos::parse("nope").unwrap_err(), "nope");
943 // Compose two tokens.
944 let q2 = StreamQos::parse("latest-wins lossy-ok").unwrap();
945 assert!(q2.to_tokens().contains(&"latest-wins"));
946 assert!(q2.to_tokens().contains(&"lossy-ok"));
947 }
948
949 // ─── Tread floor + carrier handle (not a copy loop) ─────────────────────
950
951 /// The floor: a blocking `Tread` on `data` returns the next carrier
952 /// payload (push semantics), then EOF once the subscription completes.
953 #[tokio::test]
954 async fn tread_floor_reads_then_eof() {
955 let reg = std::sync::Arc::new(StreamRegistry::new());
956 reg.register(
957 "t".into(),
958 StreamEntry::stream(
959 Some(boxed(MockHandle::new(
960 "t",
961 vec![StreamPayload::Data(b"tok".to_vec())],
962 ))),
963 "owner".into(),
964 ),
965 );
966 let mount = StreamMount::new(std::sync::Arc::clone(®));
967 let caller = Subject::anonymous();
968 let fid = Fid::new(StreamFidState::Data { topic: "t".into() });
969
970 let first = mount.read(&fid, 0, 0, &caller).await.unwrap();
971 assert_eq!(first, b"tok");
972 // Handle exhausted → completed → EOF.
973 let eof = mount.read(&fid, 0, 0, &caller).await.unwrap();
974 assert!(eof.is_empty());
975 }
976
977 /// The ceiling: the carrier-backed handle is taken *whole* for the bulk
978 /// path and remains the same subscription — it is never reconstructed per
979 /// read. After `take_handle`, no carrier handle remains in the registry.
980 #[tokio::test]
981 async fn carrier_handle_is_takeable_not_a_copy_loop() {
982 let reg = std::sync::Arc::new(StreamRegistry::new());
983 reg.register(
984 "bulk".into(),
985 StreamEntry::stream(
986 Some(boxed(MockHandle::new(
987 "bulk",
988 vec![StreamPayload::Data(b"a".to_vec())],
989 ))),
990 "owner".into(),
991 ),
992 );
993 assert!(reg.has_carrier_handle("bulk"));
994
995 // A bulk consumer takes the subscription whole and drives it directly.
996 let mut handle = reg.take_handle("bulk").expect("carrier handle");
997 assert_eq!(handle.stream_id(), "bulk");
998 let p = handle.next_payload().await.unwrap();
999 assert!(matches!(p, Some(StreamPayload::Data(_))));
1000
1001 // The entry stays registered (info/qos/ctl addressable) but the handle
1002 // is now owned by the bulk consumer — not re-openable per read.
1003 assert!(reg.exists("bulk"));
1004 assert!(!reg.has_carrier_handle("bulk"));
1005 assert!(reg.take_handle("bulk").is_none());
1006 }
1007
1008 // ─── QoS ctl selection through the file interface ───────────────────────
1009
1010 #[tokio::test]
1011 async fn qos_ctl_selection_through_the_file() {
1012 let reg = std::sync::Arc::new(StreamRegistry::new());
1013 reg.register(
1014 "s".into(),
1015 StreamEntry::stream(Some(boxed(MockHandle::new("s", vec![]))), "owner".into()),
1016 );
1017 let mount = StreamMount::new(std::sync::Arc::clone(®));
1018 let caller = Subject::anonymous();
1019
1020 // Select QoS by writing the vocabulary to `ctl`.
1021 let ctl = Fid::new(StreamFidState::Ctl { topic: "s".into() });
1022 mount
1023 .write(&ctl, 0, b"qos latest-wins drop-stale", &caller)
1024 .await
1025 .unwrap();
1026 let q = reg.qos("s").unwrap();
1027 assert!(matches!(
1028 q.stream_opt().overflow_policy,
1029 OverflowPolicy::DropOldest { .. }
1030 ));
1031
1032 // Reading the `qos` file reflects the selection as tokens.
1033 let qfid = Fid::new(StreamFidState::Qos { topic: "s".into() });
1034 let shown = mount.read(&qfid, 0, 256, &caller).await.unwrap();
1035 let text = String::from_utf8(shown).unwrap();
1036 assert!(text.contains("latest-wins") || text.contains("drop-stale"));
1037
1038 // Writing the `qos` file directly works too.
1039 mount.write(&qfid, 0, b"reliable", &caller).await.unwrap();
1040 assert_eq!(reg.qos("s").unwrap().to_tokens(), vec!["reliable"]);
1041
1042 // An unknown token is rejected (fail-closed), not silently accepted.
1043 let err = mount.write(&ctl, 0, b"qos bogus", &caller).await;
1044 assert!(matches!(err, Err(MountError::InvalidArgument(_))));
1045 }
1046
1047 /// Under lossy QoS a mid-stream carrier error is a soft EOF, not a hard
1048 /// read error — the consumer-visible half of "lossy-ok" selected via ctl.
1049 #[tokio::test]
1050 async fn lossy_qos_tolerates_carrier_error_as_eof() {
1051 let reg = std::sync::Arc::new(StreamRegistry::new());
1052 reg.register(
1053 "e".into(),
1054 StreamEntry::stream(
1055 Some(boxed(MockHandle::new(
1056 "e",
1057 vec![StreamPayload::Error("boom".into())],
1058 ))),
1059 "owner".into(),
1060 ),
1061 );
1062 let mount = StreamMount::new(std::sync::Arc::clone(®));
1063 let caller = Subject::anonymous();
1064 let fid = Fid::new(StreamFidState::Data { topic: "e".into() });
1065
1066 // Reliable (default): the error surfaces as a hard read error.
1067 let hard = mount.read(&fid, 0, 0, &caller).await;
1068 assert!(matches!(hard, Err(MountError::Io(_))));
1069
1070 // Re-arm with a fresh error payload, now under lossy-ok.
1071 reg.register(
1072 "e".into(),
1073 StreamEntry::stream(
1074 Some(boxed(MockHandle::new(
1075 "e",
1076 vec![StreamPayload::Error("boom".into())],
1077 ))),
1078 "owner".into(),
1079 ),
1080 );
1081 reg.set_qos("e", StreamQos::parse("lossy-ok").unwrap());
1082 let soft = mount.read(&fid, 0, 0, &caller).await.unwrap();
1083 assert!(soft.is_empty()); // soft EOF
1084 }
1085
1086 // ─── Events ride the same surface (#600) ────────────────────────────────
1087
1088 #[tokio::test]
1089 async fn events_ride_the_same_surface() {
1090 let reg = std::sync::Arc::new(StreamRegistry::new());
1091 reg.register(
1092 "model-lifecycle".into(),
1093 StreamEntry::event(
1094 Some(boxed(MockHandle::new("model-lifecycle", vec![]))),
1095 "svc".into(),
1096 ),
1097 );
1098 assert_eq!(reg.kind("model-lifecycle"), Some(StreamKind::Event));
1099
1100 // The event topic is addressable on `/stream` and its `info` reports
1101 // `kind: event` — one surface, not a separate plane.
1102 let mount = StreamMount::new(std::sync::Arc::clone(®));
1103 let caller = Subject::anonymous();
1104 let info_fid = Fid::new(StreamFidState::Info {
1105 topic: "model-lifecycle".into(),
1106 });
1107 let info = mount.read(&info_fid, 0, 4096, &caller).await.unwrap();
1108 let text = String::from_utf8(info).unwrap();
1109 assert!(text.contains("\"kind\": \"event\""));
1110 // Events default to latest-wins (EventLive-style).
1111 assert!(text.contains("latest-wins"));
1112 }
1113
1114 // ─── #169 resume seam ───────────────────────────────────────────────────
1115
1116 #[tokio::test]
1117 async fn resume_cursor_seam_via_ctl() {
1118 let reg = std::sync::Arc::new(StreamRegistry::new());
1119 reg.register(
1120 "r".into(),
1121 StreamEntry::stream(Some(boxed(MockHandle::new("r", vec![]))), "o".into()),
1122 );
1123 let mount = StreamMount::new(std::sync::Arc::clone(®));
1124 let caller = Subject::anonymous();
1125 let ctl = Fid::new(StreamFidState::Ctl { topic: "r".into() });
1126
1127 mount.write(&ctl, 0, b"resume 42", &caller).await.unwrap();
1128
1129 let info_fid = Fid::new(StreamFidState::Info { topic: "r".into() });
1130 let info = mount.read(&info_fid, 0, 4096, &caller).await.unwrap();
1131 assert!(String::from_utf8(info)
1132 .unwrap()
1133 .contains("\"resumeSeq\": 42"));
1134
1135 // A non-numeric resume arg is rejected.
1136 assert!(matches!(
1137 mount.write(&ctl, 0, b"resume nope", &caller).await,
1138 Err(MountError::InvalidArgument(_))
1139 ));
1140 }
1141
1142 // ─── the topic dir exposes the canonical face set ───────────────────────
1143
1144 #[tokio::test]
1145 async fn topic_dir_exposes_data_info_qos_ctl() {
1146 let reg = std::sync::Arc::new(StreamRegistry::new());
1147 reg.register(
1148 "d".into(),
1149 StreamEntry::stream(Some(boxed(MockHandle::new("d", vec![]))), "o".into()),
1150 );
1151 let mount = StreamMount::new(reg);
1152 let caller = Subject::anonymous();
1153 let dir = mount.walk(&["d"], &caller).await.unwrap();
1154 let entries = mount.readdir(&dir, &caller).await.unwrap();
1155 let names: Vec<&str> = entries.iter().map(|e| e.name.as_str()).collect();
1156 assert!(names.contains(&"data"));
1157 assert!(names.contains(&"info"));
1158 assert!(names.contains(&"qos"));
1159 assert!(names.contains(&"ctl"));
1160 }
1161}