Skip to main content

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(&reg));
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(&reg));
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(&reg));
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(&reg));
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(&reg));
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}