Skip to main content

hyprstream_rpc/
streaming.rs

1//! Generic streaming infrastructure for authenticated PUB/SUB communication.
2//!
3//! This module provides rate-controlled, MAC-authenticated streaming that works
4//! for both inference (UTF-8 tokens) and worker I/O (arbitrary binary data).
5//!
6//! # Architecture
7//!
8//! ```text
9//! Producer                     Consumer
10//! ────────                     ────────
11//! StreamChannel::publisher()   MoqStreamHandle::new()
12//!       │                             │
13//!       │ publish_data()              │ recv_next()
14//!       ▼                             ▼
15//! moq UDS track ──────────► StreamVerifier
16//! ```
17//!
18//! # Wire Format
19//!
20//! Moq track payload (binary):
21//!   capnp StreamBlock + 16-byte truncated HMAC appended
22//!
23//! # Security
24//!
25//! - DH key exchange: Ristretto255 ECDH derives topic + mac_key
26//! - MAC chain: Each block's MAC depends on previous, enforces ordering
27//!
28//! # Backend
29//!
30//! - Default: Blake3 `keyed_hash()` (~10+ GB/s with SIMD)
31//! - FIPS mode: HMAC-SHA256 (FIPS 198-1)
32
33use std::future::Future;
34use std::sync::Arc;
35
36use anyhow::Result;
37use capnp::message::Builder;
38use capnp::serialize;
39use serde::{Deserialize, Serialize};
40use tokio_util::sync::CancellationToken;
41
42use crate::auth::Claims;
43use crate::prelude::SigningKey;
44
45use crate::crypto::derive_stream_keys;
46
47// DH key types - Ristretto255 (default) or P-256 (FIPS)
48#[cfg(not(feature = "fips"))]
49use crate::crypto::{
50    ristretto_dh as dh_compute, RistrettoPublic as DhPublic, RistrettoSecret as DhSecret,
51};
52
53#[cfg(feature = "fips")]
54use crate::crypto::{p256_dh as dh_compute, P256PublicKey as DhPublic, P256SecretKey as DhSecret};
55use crate::streaming_capnp;
56
57// ============================================================================
58// StreamInfo — re-exported from target-independent module
59// ============================================================================
60
61pub use crate::stream_info::StreamInfo;
62
63// ============================================================================
64// Configuration
65// ============================================================================
66
67/// Configuration for adaptive batching (rate control).
68///
69/// Controls how payloads are batched based on throughput rate.
70/// Higher rates → larger batches (reduced overhead).
71/// Lower rates → smaller batches (reduced latency).
72#[derive(Debug, Clone, Serialize, Deserialize)]
73pub struct BatchingConfig {
74    /// Minimum payloads per block (1 = immediate send for slow streams)
75    #[serde(default = "default_min_batch_size")]
76    pub min_batch_size: usize,
77
78    /// Maximum payloads per block
79    #[serde(default = "default_max_batch_size")]
80    pub max_batch_size: usize,
81
82    /// Maximum block size in bytes
83    #[serde(default = "default_max_block_bytes")]
84    pub max_block_bytes: usize,
85
86    /// Minimum rate for logarithmic scaling (payloads/sec)
87    #[serde(default = "default_min_rate")]
88    pub min_rate: f32,
89
90    /// Maximum rate for logarithmic scaling (payloads/sec)
91    #[serde(default = "default_max_rate")]
92    pub max_rate: f32,
93}
94
95fn default_min_batch_size() -> usize {
96    1
97}
98fn default_max_batch_size() -> usize {
99    16
100}
101fn default_max_block_bytes() -> usize {
102    65536
103}
104fn default_min_rate() -> f32 {
105    1.0
106}
107fn default_max_rate() -> f32 {
108    100.0
109}
110
111impl Default for BatchingConfig {
112    fn default() -> Self {
113        Self {
114            min_batch_size: default_min_batch_size(),
115            max_batch_size: default_max_batch_size(),
116            max_block_bytes: default_max_block_bytes(),
117            min_rate: default_min_rate(),
118            max_rate: default_max_rate(),
119        }
120    }
121}
122
123// ============================================================================
124// Payload Types
125// ============================================================================
126
127/// Input payload for StreamBuilder (what gets serialized).
128///
129/// Stream identity comes from the DH-derived topic, not from payload fields.
130#[derive(Clone, Debug)]
131pub enum StreamPayloadData {
132    /// Generic binary data (tokens, I/O, etc.)
133    Data(Vec<u8>),
134    /// Error during streaming
135    Error(String),
136    /// Completion with app-specific metadata
137    Complete(Vec<u8>),
138    /// Internal identified-profile control plaintext. This variant must be
139    /// sealed into `Tagged` before Cap'n Proto serialization.
140    EpochCommit(crate::stream_epoch::StreamEpochCommit),
141    /// Encrypted tagged payload with key commitment
142    Tagged {
143        tag: Vec<u8>,
144        payload: Vec<u8>,
145        nonce: Vec<u8>,
146        key_commitment: Vec<u8>,
147    },
148}
149
150/// Output payload from StreamVerifier (what gets parsed).
151///
152/// Re-exported from `stream_consumer` for backwards compatibility.
153pub use crate::stream_consumer::StreamPayload;
154
155// ============================================================================
156// HMAC Chain State
157// ============================================================================
158
159/// HMAC chain state for StreamBlock with 16-byte truncated MACs.
160///
161/// MAC chain:
162// StreamHmacState was moved to crypto::hmac for cross-platform availability.
163// Re-exported here for backward compatibility.
164pub use crate::crypto::StreamHmacState;
165
166// ============================================================================
167// Stream Context (Encapsulates stream state for producers)
168// ============================================================================
169
170/// Encapsulates all state needed to produce a stream.
171///
172/// Created by an identified stream preparation API after the pinned hybrid
173/// post-quantum handshake, or by the explicitly named third-party
174/// interoperability DH edge.
175/// Contains everything needed to:
176/// - Return stream info to client (stream_id, server_pubkey)
177/// - Create a `StreamPublisher` for sending data
178///
179/// # Example
180///
181/// ```ignore
182/// // In service handler:
183/// let ctx = self.prepare_identified_stream(envelope_ctx, accepted_binding, 600).await?;
184///
185/// // Return to client:
186/// let response = Response::stream_started(ctx.stream_id(), ctx.server_pubkey());
187///
188/// // After response sent, create publisher:
189/// let mut publisher = StreamPublisher::new(&push_socket, &ctx)?;
190/// publisher.publish_data(b"hello")?;
191/// publisher.complete(b"{}")?;
192/// ```
193#[derive(Clone)]
194pub struct StreamContext {
195    /// Human-readable stream ID (for logging/display)
196    stream_id: String,
197    /// Key-exchange-derived topic (64 hex chars) - used for stream routing
198    topic: String,
199    /// Key-exchange-derived HMAC key for authenticated stream blocks
200    mac_key: [u8; 32],
201    /// Key-exchange-derived AES-256-GCM key for transport-level AEAD of payloads (#321).
202    /// `Some` on both keyed paths: identified hybrid streams and the explicitly
203    /// named third-party interoperability DH edge. The mesh/networked stream plane
204    /// seals each Data/Complete payload under this key. `None` on the keyless
205    /// `new()` path (e.g. NotificationService topics, whose payloads are already
206    /// E2E-encrypted at the app layer), where transport AEAD is not applied.
207    enc_key: Option<[u8; 32]>,
208    /// Server's ephemeral public key for the third-party interoperability DH edge.
209    server_pubkey: [u8; 32],
210    /// Key-exchange-derived control channel topic (64 hex chars)
211    ctrl_topic: String,
212    /// Key-exchange-derived control channel HMAC key
213    ctrl_mac_key: [u8; 32],
214    /// Cancellation token — fired by control listener or JWT expiry
215    cancel_token: CancellationToken,
216    /// QoS options advertised in StreamInfo and honoured by MoqStreamPublisher (#169).
217    qos: crate::stream_info::StreamOpt,
218    /// Per-stream relay selection applied when building this stream's reach (#384).
219    ///
220    /// Server-authored (like `qos` — never client-supplied). Defaults to
221    /// [`crate::moq_stream::RelayChoice::ServerDefault`] (the node's server-global
222    /// relay). Set to `Only` for an anonymized, relay-only stream, or `Override`
223    /// for per-tenant relay isolation.
224    relay_choice: crate::moq_stream::RelayChoice,
225    /// Per-stream reach inputs — the node/server's iroh + QUIC base reach (#384).
226    ///
227    /// Captured into the context at construction so [`reach`](Self::reach) builds
228    /// the `StreamInfo.reach` from THIS field, never re-reading the process-global
229    /// `OnceLock`s on every call. This is what makes heterogeneous per-server
230    /// reach work: a [`StreamChannel`] threaded with an explicit
231    /// [`ProducerReachConfig`](crate::moq_stream::ProducerReachConfig) via
232    /// [`StreamChannel::with_reach_config`] populates this so the base (iroh/QUIC)
233    /// reach is per-stream too, not just `relay_choice`.
234    ///
235    /// When no explicit config is threaded, the third-party interoperability
236    /// constructor seeds it
237    /// from an empty [`ProducerReachConfig`](crate::moq_stream::ProducerReachConfig) — a
238    /// one-time per-stream snapshot (the documented compat source), not a
239    /// per-`reach()`-call global read.
240    reach_config: crate::moq_stream::ProducerReachConfig,
241
242    /// Hybrid KEM ciphertexts to emit in `StreamInfo.kemCiphertexts` (S3 #554).
243    /// `Some` on the hybrid post-quantum path
244    /// ([`from_hybrid_identified`](Self::from_hybrid_identified));
245    /// `None` on the legacy classical
246    /// [`from_third_party_interop_dh`](Self::from_third_party_interop_dh) and the keyless
247    /// [`new`](Self::new) paths.
248    kem_ciphertexts: Option<Vec<u8>>,
249    /// Shared one-shot identified producer state. The outer `Option` is a
250    /// persistent profile marker; the inner state is consumed exactly once
251    /// across every clone before an identified publisher creates MoQ resources.
252    /// Legacy/keyless contexts have no claim and cannot ratchet into this profile.
253    epoch_ratchet: Option<Arc<parking_lot::Mutex<Option<crate::stream_epoch::StreamEpochRatchet>>>>,
254}
255
256impl StreamContext {
257    /// Create a new stream context with pre-computed DH values.
258    pub fn new(
259        stream_id: String,
260        topic: String,
261        mac_key: [u8; 32],
262        server_pubkey: [u8; 32],
263    ) -> Self {
264        Self {
265            stream_id,
266            topic,
267            mac_key,
268            // Keyless path: no shared transport AEAD key (see field docs).
269            enc_key: None,
270            server_pubkey,
271            ctrl_topic: String::new(),
272            ctrl_mac_key: [0u8; 32],
273            cancel_token: CancellationToken::new(),
274            qos: crate::stream_info::StreamOpt::default(),
275            relay_choice: crate::moq_stream::RelayChoice::default(),
276            // No DH/server context here (notification + standalone TUI paths,
277            // which never call `reach()`); default to an empty reach config. A
278            // networked producer threads a real one via `with_reach_config`.
279            reach_config: crate::moq_stream::ProducerReachConfig::default(),
280            // Keyless path: no hybrid KEM material.
281            kem_ciphertexts: None,
282            epoch_ratchet: None,
283        }
284    }
285
286    /// Create a stream context for the explicitly named third-party
287    /// interoperability edge by performing a classical DH key exchange.
288    ///
289    /// Same-cell and federated callers must use
290    /// [`Self::from_hybrid_identified`] instead.  Keeping this constructor
291    /// explicitly named prevents a verified HyKEM recipient from being
292    /// silently downgraded to classical AEAD.
293    ///
294    /// # Arguments
295    /// * `client_ephemeral_pubkey` - Client's ephemeral public key from request
296    ///
297    /// # Returns
298    /// Stream context with DH-derived topic and mac_key
299    #[cfg(not(feature = "fips"))]
300    pub fn from_third_party_interop_dh(client_ephemeral_pubkey: &[u8]) -> Result<Self> {
301        use crate::crypto::generate_ephemeral_keypair;
302
303        let (server_secret, server_pubkey) = generate_ephemeral_keypair();
304        let server_pubkey_bytes = server_pubkey.to_bytes();
305
306        let client_pub = DhPublic::from_slice(client_ephemeral_pubkey)
307            .ok_or_else(|| anyhow::anyhow!("Invalid client ephemeral public key"))?;
308        let shared_secret = dh_compute(&server_secret, &client_pub);
309
310        let client_pub_32 = pubkey_to_32(client_ephemeral_pubkey);
311        let server_pub_32 = pubkey_to_32(&server_pubkey_bytes);
312        let keys = derive_stream_keys(&shared_secret, &client_pub_32, &server_pub_32)?;
313
314        let stream_id = format!("stream-{}", uuid::Uuid::new_v4());
315
316        Ok(Self {
317            stream_id,
318            topic: keys.topic,
319            mac_key: *keys.mac_key,
320            // DH path: AEAD ON for the mesh stream plane (#321).
321            enc_key: Some(*keys.enc_key),
322            server_pubkey: server_pubkey_bytes,
323            ctrl_topic: keys.ctrl_topic,
324            ctrl_mac_key: *keys.ctrl_mac_key,
325            cancel_token: CancellationToken::new(),
326            qos: crate::stream_info::StreamOpt::default(),
327            relay_choice: crate::moq_stream::RelayChoice::default(),
328            reach_config: crate::moq_stream::ProducerReachConfig::default(),
329            // Classical (legacy) path: no hybrid KEM material; the client keys
330            // off the server ephemeral `dhPublic`. Removed at the S5 fail-closed
331            // flip (#556) once all call-sites use `from_hybrid_identified`.
332            kem_ciphertexts: None,
333            epoch_ratchet: None,
334        })
335    }
336
337    /// Create a stream context via the **hybrid post-quantum** handshake (S3 #554).
338    ///
339    /// `client_kem_public` is the client's encoded ephemeral `RecipientPublic`
340    /// (from `RequestEnvelope.clientKemPublic`). The server encapsulates to it and
341    /// derives the stream keys from the hybrid combiner secret; the per-component
342    /// ciphertexts are stored in [`kem_ciphertexts`](Self::kem_ciphertexts) for
343    /// emission in `StreamInfo.kemCiphertexts`. Forward secrecy comes from the
344    /// client's ephemeral keypair (X25519 + ML-KEM legs).
345    ///
346    /// Fail-closed: a malformed / wrong-suite `client_kem_public` is rejected.
347    /// This is the required path for same-cell and federated callers with a
348    /// verified identified-stream recipient.
349    pub fn from_hybrid_identified(
350        client_kem_public: &[u8],
351        binding: crate::stream_epoch::IdentifiedStreamBinding,
352    ) -> Result<Self> {
353        let (material, ratchet) =
354            crate::crypto::key_exchange::server_identified_stream_epoch(client_kem_public, binding)
355                .map_err(|e| anyhow::anyhow!("hybrid stream handshake: {e}"))?;
356        let keys = ratchet.current_keys();
357        let outbound = &keys.producer_to_consumer;
358        let inbound = &keys.consumer_to_producer;
359
360        let stream_id = format!("stream-{}", uuid::Uuid::new_v4());
361
362        Ok(Self {
363            stream_id,
364            topic: ratchet.route_topic().to_owned(),
365            mac_key: *outbound.mac_key,
366            // Hybrid path: AEAD ON for the mesh stream plane (#321), keyed by the
367            // post-quantum combiner secret.
368            enc_key: Some(*outbound.enc_key),
369            // No classical server ephemeral pubkey on the hybrid path; the client
370            // keys off `kem_ciphertexts`, not `dhPublic`.
371            server_pubkey: [0u8; 32],
372            ctrl_topic: ratchet.control_topic().to_owned(),
373            ctrl_mac_key: *inbound.control_mac_key,
374            cancel_token: CancellationToken::new(),
375            qos: crate::stream_info::StreamOpt::default(),
376            relay_choice: crate::moq_stream::RelayChoice::default(),
377            reach_config: crate::moq_stream::ProducerReachConfig::default(),
378            kem_ciphertexts: Some(material.encode()),
379            epoch_ratchet: Some(Arc::new(parking_lot::Mutex::new(Some(ratchet)))),
380        })
381    }
382
383    /// Whether this context was created for the identified epoch profile.
384    ///
385    /// This marker remains true after the producer claim is consumed so policy
386    /// checks such as the transport-AEAD requirement cannot be downgraded.
387    pub(crate) fn has_epoch_ratchet(&self) -> bool {
388        self.epoch_ratchet.is_some()
389    }
390
391    /// Build a publisher while holding the shared identified producer claim.
392    ///
393    /// The callback sees `Some` only once across every clone. It must consume
394    /// the state only after all fallible resource setup succeeds; if setup
395    /// fails first, the claim remains available for a retry. Legacy contexts
396    /// receive an unshared `None` slot.
397    pub(crate) fn with_publisher_epoch_ratchet<T>(
398        &self,
399        build: impl FnOnce(&mut Option<crate::stream_epoch::StreamEpochRatchet>) -> Result<T>,
400    ) -> Result<T> {
401        let Some(claim) = &self.epoch_ratchet else {
402            let mut legacy = None;
403            return build(&mut legacy);
404        };
405        let mut claim = claim.lock();
406        anyhow::ensure!(
407            claim.is_some(),
408            "identified stream publisher already claimed"
409        );
410        build(&mut claim)
411    }
412
413    /// The hybrid KEM ciphertexts to emit in `StreamInfo.kemCiphertexts` (S3 #554):
414    /// `Some` on the hybrid path
415    /// ([`from_hybrid_identified`](Self::from_hybrid_identified)), `None`
416    /// otherwise.
417    pub fn kem_ciphertexts(&self) -> Option<&[u8]> {
418        self.kem_ciphertexts.as_deref()
419    }
420
421    /// Get the stream ID (for logging/display).
422    pub fn stream_id(&self) -> &str {
423        &self.stream_id
424    }
425
426    /// Get the key-exchange-derived topic (for stream routing).
427    pub fn topic(&self) -> &str {
428        &self.topic
429    }
430
431    /// Get the MAC key (for HMAC chain).
432    pub fn mac_key(&self) -> &[u8; 32] {
433        &self.mac_key
434    }
435
436    /// Get the transport AEAD key (#321), if this is a keyed stream.
437    ///
438    /// `Some` on identified hybrid and third-party interoperability streams
439    /// (AEAD ON), `None` on the keyless `new()` path (payloads already
440    /// E2E-encrypted at the app layer).
441    pub fn enc_key(&self) -> Option<&[u8; 32]> {
442        self.enc_key.as_ref()
443    }
444
445    /// Disable transport-level AEAD for this stream (#321).
446    ///
447    /// Clears the AEAD key so a legacy publisher emits cleartext (HMAC-chained)
448    /// blocks. Identified epoch contexts retain an internal profile marker and
449    /// are rejected by `MoqStreamOrigin::publisher` if this escape hatch is used;
450    /// it exists only for legacy same-host streams whose consumer receives
451    /// `(mac_key, topic)` out of band and cannot derive the classical DH key.
452    pub fn without_aead(mut self) -> Self {
453        self.enc_key = None;
454        self
455    }
456
457    /// Get the server's ephemeral public key for the interoperability DH edge.
458    pub fn server_pubkey(&self) -> &[u8; 32] {
459        &self.server_pubkey
460    }
461
462    /// Get the control channel topic.
463    pub fn ctrl_topic(&self) -> &str {
464        &self.ctrl_topic
465    }
466
467    /// Get the control channel MAC key.
468    pub fn ctrl_mac_key(&self) -> &[u8; 32] {
469        &self.ctrl_mac_key
470    }
471
472    /// Get the cancellation token.
473    pub fn cancel_token(&self) -> &CancellationToken {
474        &self.cancel_token
475    }
476
477    /// Set the QoS options for this stream using a typed preset (#169).
478    ///
479    /// Call with a preset ZST: `.with_qos_preset::<Job>()`, `.with_qos_preset::<Pipe>()`.
480    pub fn with_qos_preset<Q: crate::stream_info::StreamOptPreset>(mut self) -> Self {
481        self.qos = Q::stream_opt();
482        self
483    }
484
485    /// Set the QoS options for this stream from a runtime value (#169).
486    pub fn with_qos(mut self, qos: crate::stream_info::StreamOpt) -> Self {
487        self.qos = qos;
488        self
489    }
490
491    /// Get the QoS options for this stream (#169).
492    pub fn qos(&self) -> &crate::stream_info::StreamOpt {
493        &self.qos
494    }
495
496    /// Set the per-stream relay choice (#384). Server-authored — never from a
497    /// client request. Use [`crate::moq_stream::RelayChoice::Only`] for an
498    /// anonymized relay-only stream, or `Override` for per-tenant isolation.
499    pub fn with_relay_choice(mut self, relay_choice: crate::moq_stream::RelayChoice) -> Self {
500        self.relay_choice = relay_choice;
501        self
502    }
503
504    /// Get the per-stream relay choice (#384).
505    pub fn relay_choice(&self) -> &crate::moq_stream::RelayChoice {
506        &self.relay_choice
507    }
508
509    /// Thread an explicit per-server reach config into this stream (#384).
510    ///
511    /// Supplies the per-server [`ProducerReachConfig`](crate::moq_stream::ProducerReachConfig)
512    /// for this stream,
513    /// so the base (iroh/QUIC) reach this stream advertises is the server's own —
514    /// [`StreamChannel::prepare_identified_stream_with_claims`] and
515    /// [`StreamChannel::prepare_third_party_interop_stream_with_claims`] apply their current service
516    /// config before it returns the context.
517    pub fn with_reach_config(
518        mut self,
519        reach_config: crate::moq_stream::ProducerReachConfig,
520    ) -> Self {
521        self.reach_config = reach_config;
522        self
523    }
524
525    /// Get this stream's reach config (#384).
526    pub fn reach_config(&self) -> &crate::moq_stream::ProducerReachConfig {
527        &self.reach_config
528    }
529
530    /// Build this stream's `StreamInfo.reach` from the node's per-server reach
531    /// config and this stream's [`relay_choice`](Self::relay_choice) (#384).
532    ///
533    /// A producer that holds a `StreamContext` calls this so
534    /// the stream's relay/anonymization posture **and** its base iroh/QUIC reach
535    /// are honoured per-stream. Both come from the context's own
536    /// [`reach_config`](Self::reach_config) field — captured at construction (and
537    /// overridable via [`with_reach_config`](Self::with_reach_config)) — so this
538    /// no longer reads the process-global `OnceLock`s on each call.
539    pub fn reach(&self) -> Vec<crate::stream_info::Destination> {
540        self.reach_config
541            .reach_with_relay(self.relay_choice.clone())
542    }
543
544    /// The server accepted-state witness carried with this signed StreamInfo.
545    /// A missing witness decodes as the default and is rejected before a native
546    /// Iroh admission exchange; it does not affect Quinn/UDS consumers.
547    pub fn moql_server_identity(&self) -> crate::stream_info::MoqlServerIdentity {
548        self.reach_config
549            .moql_server_identity
550            .clone()
551            .unwrap_or_default()
552    }
553}
554
555// ============================================================================
556// Progress Streaming (Bridges progress callbacks to streams)
557// ============================================================================
558
559/// Progress update message for channel-based streaming.
560#[derive(Debug, Clone)]
561pub enum ProgressUpdate {
562    /// Progress update: stage, current, total
563    Progress {
564        stage: String,
565        current: usize,
566        total: usize,
567    },
568    /// Operation completed successfully
569    Complete(Vec<u8>),
570    /// Operation failed with error
571    Error(String),
572}
573
574/// Channel-based progress sender for use with git2db or other progress-reporting operations.
575///
576/// This can be passed to operations that accept a progress callback (like git clone).
577/// Progress updates are sent through a channel and can be forwarded to a stream.
578///
579/// # Example
580///
581/// ```ignore
582/// // Create progress channel
583/// let (sender, receiver) = progress_channel();
584///
585/// // In spawn_blocking (runs the git operation):
586/// let reporter = ChannelProgressReporter::new(sender);
587/// git2db_clone_with_progress(..., reporter);
588/// reporter.complete(b"{}")?;
589///
590/// // In async context (publishes to stream):
591/// let mut publisher = StreamPublisher::new(&socket, &ctx);
592/// while let Ok(update) = receiver.recv() {
593///     match update {
594///         ProgressUpdate::Progress { stage, current, total } => {
595///             publisher.publish_progress(&stage, current, total)?;
596///         }
597///         ProgressUpdate::Complete(meta) => {
598///             publisher.complete(&meta)?;
599///             break;
600///         }
601///         ProgressUpdate::Error(msg) => {
602///             publisher.publish_error(&msg)?;
603///             break;
604///         }
605///     }
606/// }
607/// ```
608#[derive(Clone)]
609pub struct ChannelProgressReporter {
610    sender: tokio::sync::mpsc::Sender<ProgressUpdate>,
611}
612
613impl ChannelProgressReporter {
614    /// Create a new channel-based progress reporter.
615    pub fn new(sender: tokio::sync::mpsc::Sender<ProgressUpdate>) -> Self {
616        Self { sender }
617    }
618
619    /// Report progress (implements the same interface as git2db::ProgressReporter).
620    ///
621    /// Uses `blocking_send` since this is typically called from sync contexts.
622    pub fn report(&self, stage: &str, current: usize, total: usize) {
623        let _ = self.sender.blocking_send(ProgressUpdate::Progress {
624            stage: stage.to_owned(),
625            current,
626            total,
627        });
628    }
629
630    /// Signal successful completion with metadata.
631    pub fn complete(&self, metadata: Vec<u8>) -> Result<()> {
632        self.sender
633            .blocking_send(ProgressUpdate::Complete(metadata))
634            .map_err(|_| anyhow::anyhow!("Progress channel closed"))
635    }
636
637    /// Signal an error occurred.
638    pub fn error(&self, message: &str) -> Result<()> {
639        self.sender
640            .blocking_send(ProgressUpdate::Error(message.to_owned()))
641            .map_err(|_| anyhow::anyhow!("Progress channel closed"))
642    }
643}
644
645/// Create a progress channel for streaming operations.
646///
647/// Returns (sender, receiver) where:
648/// - sender: Pass to `ChannelProgressReporter::new()` for use in blocking operations
649/// - receiver: Poll in async context to forward updates to `StreamPublisher`
650pub fn progress_channel(
651    buffer_size: usize,
652) -> (
653    tokio::sync::mpsc::Sender<ProgressUpdate>,
654    tokio::sync::mpsc::Receiver<ProgressUpdate>,
655) {
656    tokio::sync::mpsc::channel(buffer_size)
657}
658
659// ============================================================================
660// Stream Verifier (Consumer helper)
661// ============================================================================
662
663// #224: the canonical StreamVerifier lives in `stream_consumer` (cross-target — compiles
664// on native + wasm). The native-only duplicate the cross-target extraction left here is
665// removed; re-export the shared one (mirrors the `StreamPayload` re-export above) so
666// `crate::StreamVerifier`, the moq path, and the wasm/browser consumer all use a single
667// verifier — the one place #163's policy-selected enforcement will land.
668pub use crate::stream_consumer::StreamVerifier;
669
670// ============================================================================
671// StreamChannel - Service-Level Streaming Infrastructure
672// ============================================================================
673
674/// Service-level async streaming infrastructure that encapsulates socket management
675/// and stream pre-authorization.
676///
677/// `StreamChannel` handles the complexity of:
678/// - Async PUSH socket creation and lazy initialization (via tmq)
679/// - identified hybrid key exchange via `StreamContext::from_hybrid_identified()`
680/// - Stream pre-authorization with StreamService
681/// - Endpoint discovery via the registry
682///
683/// # Example
684///
685/// ```ignore
686/// // In service initialization
687/// let stream_channel = StreamChannel::new(signing_key.clone());
688///
689/// // In a same-cell/federated request handler, after accepting the binding:
690/// let stream_ctx = stream_channel
691///     .prepare_identified_stream(&envelope_ctx, binding, 600)
692///     .await?;
693///
694/// // In async context
695/// let mut publisher = stream_channel.publisher(&stream_ctx).await?;
696/// publisher.publish_progress("processing", 0, 100).await?;
697/// // ... do work ...
698/// publisher.complete(&metadata).await?;
699/// ```
700pub struct StreamChannel {
701    /// Ed25519 signing key for stream authorization (wired into moq publish claims, N7)
702    /// and the per-host provenance signer (#321).
703    signing_key: SigningKey,
704    /// ML-DSA-65 signing key for the post-quantum half of the StreamRegister
705    /// composite signature. Mirrors `LocalSigner` on the RPC plane so the
706    /// streaming control plane signs under the same policy (#161). Derived
707    /// deterministically from the node's persistent Ed25519 signing key (#157)
708    /// in [`Self::new`]; override with [`Self::with_pq_key`].
709    pq_signing_key: Option<crate::crypto::pq::MlDsaSigningKey>,
710    /// Per-service reach source, updated by the service spawner after bind.
711    reach_config: crate::moq_stream::ProducerReachConfigHandle,
712    /// Optional service-scoped origin installed when this service links a relay.
713    moq_origin: crate::moq_stream::MoqStreamOriginHandle,
714}
715
716impl StreamChannel {
717    /// Create a new stream channel.
718    ///
719    /// The post-quantum half of the StreamRegister composite is the node's
720    /// **persistent** mesh ML-DSA-65 key, derived deterministically from
721    /// `signing_key` via [`crate::node_identity::derive_mesh_mldsa_key`] (#157),
722    /// mirroring `LocalSigner::new` on the RPC plane. This replaces the previous
723    /// ephemeral keygen so the streaming control plane's ML-DSA public key is
724    /// stable across restarts and equals the `#mesh-pq` key peers anchor. Use
725    /// [`Self::with_pq_key`] only to override with an externally supplied key.
726    pub fn new(signing_key: SigningKey) -> Self {
727        let pq_signing_key = Some(crate::node_identity::derive_mesh_mldsa_key(&signing_key));
728        Self {
729            signing_key,
730            pq_signing_key,
731            reach_config: std::sync::Arc::new(parking_lot::RwLock::new(
732                crate::moq_stream::ProducerReachConfig::default(),
733            )),
734            moq_origin: std::sync::Arc::new(parking_lot::RwLock::new(None)),
735        }
736    }
737
738    /// Initialize this channel's reach configuration.
739    pub fn with_reach_config(mut self, cfg: crate::moq_stream::ProducerReachConfig) -> Self {
740        self.reach_config = std::sync::Arc::new(parking_lot::RwLock::new(cfg));
741        self
742    }
743
744    /// Share a service-owned reach handle with this channel.
745    pub fn with_reach_config_handle(
746        mut self,
747        handle: crate::moq_stream::ProducerReachConfigHandle,
748    ) -> Self {
749        self.reach_config = handle;
750        self
751    }
752
753    /// Return this channel's service-owned reach handle.
754    pub fn reach_config_handle(&self) -> crate::moq_stream::ProducerReachConfigHandle {
755        self.reach_config.clone()
756    }
757
758    /// Share a service-owned MoQ origin handle with this channel.
759    pub fn with_moq_origin_handle(
760        mut self,
761        handle: crate::moq_stream::MoqStreamOriginHandle,
762    ) -> Self {
763        self.moq_origin = handle;
764        self
765    }
766
767    /// Return this channel's service-owned MoQ origin handle.
768    pub fn moq_origin_handle(&self) -> crate::moq_stream::MoqStreamOriginHandle {
769        self.moq_origin.clone()
770    }
771
772    fn selected_moq_origin(&self) -> Result<crate::moq_stream::MoqStreamOrigin> {
773        self.moq_origin
774            .read()
775            .clone()
776            .or_else(|| crate::moq_stream::global_moq_origin().cloned())
777            .ok_or_else(|| anyhow::anyhow!("no moq stream origin — server not initialized"))
778    }
779
780    /// Return the broadcast path on the exact origin this channel publishes to.
781    pub fn broadcast_path(&self, topic: &str) -> Result<String> {
782        Ok(self.selected_moq_origin()?.broadcast_path(topic))
783    }
784
785    /// Install the node's persistent ML-DSA-65 signing key, replacing the
786    /// auto-generated one. The matching public key must be anchored in the
787    /// StreamService verifier's PQ trust store for Hybrid verification to
788    /// succeed (peer attestation, #157).
789    pub fn with_pq_key(mut self, key: crate::crypto::pq::MlDsaSigningKey) -> Self {
790        self.pq_signing_key = Some(key);
791        self
792    }
793
794    /// Prepare an identified stream with the pinned hybrid post-quantum
795    /// handshake and pre-authorization.
796    ///
797    /// This method:
798    /// 1. Uses the authenticated recipient from the verified envelope
799    /// 2. Binds it to the accepted identified-stream state before deriving keys
800    /// 3. Pre-authorizes the stream with StreamService
801    ///
802    /// # Arguments
803    /// * `envelope_ctx` - Verified request context containing the HyKEM recipient
804    /// * `binding` - Accepted-current identity, capability, route, and epoch binding
805    /// * `expiry_secs` - Stream expiration in seconds from now
806    ///
807    /// # Returns
808    /// `StreamContext` ready for publishing
809    pub async fn prepare_identified_stream(
810        &self,
811        envelope_ctx: &crate::service::EnvelopeContext,
812        binding: crate::stream_epoch::IdentifiedStreamBinding,
813        expiry_secs: i64,
814    ) -> Result<StreamContext> {
815        self.prepare_identified_stream_with_claims(envelope_ctx, binding, expiry_secs, None)
816            .await
817    }
818
819    /// Prepare an identified stream with claims.
820    ///
821    /// The recipient is read only from the verified [`crate::service::EnvelopeContext`];
822    /// callers must supply the accepted-current binding.  This API deliberately
823    /// has no classical fallback: a request with a verified HyKEM recipient is
824    /// never downgraded to a DH-derived stream.
825    ///
826    /// # Arguments
827    /// * `envelope_ctx` - Verified request context containing the HyKEM recipient
828    /// * `binding` - Accepted-current identity, capability, route, and epoch binding
829    /// * `expiry_secs` - Stream expiration in seconds from now
830    /// * `claims` - Optional user claims for authorization
831    ///
832    /// # Returns
833    /// `StreamContext` ready for publishing
834    pub async fn prepare_identified_stream_with_claims(
835        &self,
836        envelope_ctx: &crate::service::EnvelopeContext,
837        binding: crate::stream_epoch::IdentifiedStreamBinding,
838        expiry_secs: i64,
839        claims: Option<Claims>,
840    ) -> Result<StreamContext> {
841        let recipient = envelope_ctx.stream_kem_recipient().ok_or_else(|| {
842            anyhow::anyhow!(
843                "identified stream preparation requires a verified HyKEM recipient in the request envelope"
844            )
845        })?;
846        self.prepare_identified_stream_for_verified_recipient_with_claims(
847            recipient,
848            binding,
849            expiry_secs,
850            claims,
851        )
852        .await
853    }
854
855    /// Perform identified setup after the envelope verification chokepoint has
856    /// yielded the recipient.  Keeping this seam private prevents arbitrary
857    /// request bytes from being treated as an authenticated recipient while
858    /// making the no-downgrade property directly testable.
859    async fn prepare_identified_stream_for_verified_recipient_with_claims(
860        &self,
861        recipient: &crate::crypto::hybrid_kem::RecipientPublic,
862        binding: crate::stream_epoch::IdentifiedStreamBinding,
863        expiry_secs: i64,
864        _claims: Option<Claims>,
865    ) -> Result<StreamContext> {
866        let stream_ctx = StreamContext::from_hybrid_identified(&recipient.encode(), binding)?
867            .with_reach_config(self.reach_config.read().clone());
868
869        self.arm_expiry(&stream_ctx, expiry_secs);
870
871        Ok(stream_ctx)
872    }
873
874    /// Prepare a legacy stream for an explicitly selected third-party
875    /// interoperability peer.
876    ///
877    /// This is the only `StreamChannel` entry point that uses classical DH.
878    /// Same-cell and federated callers must use
879    /// [`Self::prepare_identified_stream`] with their verified envelope and
880    /// accepted [`crate::stream_epoch::IdentifiedStreamBinding`].
881    pub async fn prepare_third_party_interop_stream(
882        &self,
883        client_ephemeral_pubkey: &[u8],
884        expiry_secs: i64,
885    ) -> Result<StreamContext> {
886        self.prepare_third_party_interop_stream_with_claims(
887            client_ephemeral_pubkey,
888            expiry_secs,
889            None,
890        )
891        .await
892    }
893
894    /// Same as [`Self::prepare_third_party_interop_stream`], with optional
895    /// authorization claims for the legacy third-party interoperability edge.
896    pub async fn prepare_third_party_interop_stream_with_claims(
897        &self,
898        client_ephemeral_pubkey: &[u8],
899        expiry_secs: i64,
900        _claims: Option<Claims>,
901    ) -> Result<StreamContext> {
902        let stream_ctx = StreamContext::from_third_party_interop_dh(client_ephemeral_pubkey)?
903            .with_reach_config(self.reach_config.read().clone());
904
905        self.arm_expiry(&stream_ctx, expiry_secs);
906
907        Ok(stream_ctx)
908    }
909
910    /// Spawn the universal stream-expiry backstop after key setup succeeds.
911    fn arm_expiry(&self, stream_ctx: &StreamContext, expiry_secs: i64) {
912        // Spawn JWT expiry timeout as universal backstop.
913        let token = stream_ctx.cancel_token().clone();
914        tokio::spawn(async move {
915            tokio::time::sleep(std::time::Duration::from_secs(expiry_secs.max(0) as u64)).await;
916            token.cancel();
917        });
918    }
919
920    /// Register a topic with the stream plane.
921    ///
922    /// No-op on the moq path — topics are published lazily by
923    /// `MoqStreamPublisher` on first frame; no pre-registration is needed.
924    /// Kept for API compatibility with callers such as `NotificationService`.
925    pub async fn register_topic(
926        &self,
927        _topic: &str,
928        _expiry: i64,
929        _claims: Option<Claims>,
930    ) -> Result<()> {
931        Ok(())
932    }
933
934    /// Create a publisher for a stream context.
935    ///
936    /// Fails loudly if the process-global moq stream origin has not been
937    /// initialized (server not started). In production the `streams` factory
938    /// always calls `init_global_moq_origin` before any service handles requests.
939    pub async fn publisher(
940        &self,
941        ctx: &StreamContext,
942    ) -> Result<crate::moq_stream::AnyStreamPublisher> {
943        let origin = self.selected_moq_origin()?;
944        // #321: on the DH (mesh) path, sign each StreamBlock with the node's per-host
945        // hybrid identity (Ed25519 + the deterministically-derived mesh ML-DSA key)
946        // so consumers can attribute blocks to this host (C-PROV / threat T3). The
947        // keyless notification path (no DH enc_key) carries no provenance.
948        let provenance = if ctx.enc_key().is_some() {
949            let signer = match &self.pq_signing_key {
950                Some(pq) => crate::stream_provenance::ProvenanceSigner::new(
951                    self.signing_key.clone(),
952                    pq.clone(),
953                ),
954                None => crate::stream_provenance::ProvenanceSigner::from_ed25519(
955                    self.signing_key.clone(),
956                ),
957            };
958            Some(signer)
959        } else {
960            None
961        };
962        origin.publisher_with_provenance(ctx, provenance)
963    }
964
965    /// Run a streaming operation with framework-guaranteed terminal frame.
966    ///
967    /// The closure receives an [`AnyStreamPublisher`] by value and **must return
968    /// it** alongside its result. The framework sends a terminal frame if the
969    /// closure didn't. Transport (moq-lite or ZMQ) is selected automatically
970    /// based on whether a global moq origin is registered.
971    ///
972    /// After the closure returns:
973    /// - If `Ok` and not terminated → framework sends `Complete` (empty metadata)
974    /// - If `Err` and not terminated → framework sends `Error` with the error message
975    /// - If already terminated → no-op (closure handled it)
976    pub async fn run_stream<F, Fut, R>(&self, ctx: &StreamContext, f: F) -> Result<R>
977    where
978        F: FnOnce(crate::moq_stream::AnyStreamPublisher) -> Fut,
979        Fut: Future<Output = (crate::moq_stream::AnyStreamPublisher, Result<R>)>,
980    {
981        let publisher = self.publisher(ctx).await?;
982        let (mut publisher, result) = f(publisher).await;
983
984        if !publisher.is_terminated() && !publisher.is_cancelled() {
985            match &result {
986                Ok(_) => {
987                    if let Err(e) = publisher.complete_ref(b"").await {
988                        tracing::error!("run_stream: failed to send Complete: {}", e);
989                    }
990                }
991                Err(e) => {
992                    if let Err(send_err) = publisher.publish_error(&e.to_string()).await {
993                        tracing::error!("run_stream: failed to send Error: {}", send_err);
994                    }
995                }
996            }
997        }
998
999        result
1000    }
1001
1002    /// Create a publisher for a pre-registered topic (no DH).
1003    ///
1004    /// Used by NotificationService where topics are registered via `register_topic()`
1005    /// and don't use DH-based key exchange. The transport MAC key is randomly generated
1006    /// (separate from notification E2E MAC which is embedded in the payload).
1007    pub async fn publisher_for_topic(
1008        &self,
1009        topic: &str,
1010    ) -> Result<crate::moq_stream::AnyStreamPublisher> {
1011        // Generate a random transport-level MAC key for the HMAC chain.
1012        // (Not the notification's E2E MAC — that's embedded in the payload.)
1013        let mut mac_key = [0u8; 32];
1014        rand::RngCore::fill_bytes(&mut rand::rngs::OsRng, &mut mac_key);
1015
1016        let ctx = StreamContext::new(
1017            format!("notify-{}", uuid::Uuid::new_v4()),
1018            topic.to_owned(),
1019            mac_key,
1020            [0u8; 32], // No server pubkey needed for notification delivery
1021        );
1022        self.publisher(&ctx).await
1023    }
1024}
1025
1026// ============================================================================
1027// ResponseStream - Unified Response + Stream Coordination
1028// ============================================================================
1029
1030/// Wrapper type for streaming responses that coordinates the REP-before-PUB pattern.
1031///
1032/// When a service handler needs to return a response AND start streaming,
1033/// `ResponseStream` bundles:
1034/// - The REP response bytes to send immediately
1035/// - The `StreamContext` for later publishing
1036/// - Application-specific pending work
1037///
1038/// This ensures consistent handling across all streaming services.
1039///
1040/// # Example
1041///
1042/// ```ignore
1043/// fn handle_clone_stream(&self, ...) -> Result<ResponseStream<CloneTask>> {
1044///     let stream_ctx = self
1045///         .stream_channel
1046///         .prepare_third_party_interop_stream(&pubkey, 600)
1047///         .await?;
1048///
1049///     let response = build_response(request_id, &stream_ctx);
1050///
1051///     Ok(ResponseStream::new(response, stream_ctx, CloneTask { url, name }))
1052/// }
1053/// ```
1054pub struct ResponseStream<T> {
1055    /// The REP response to send immediately
1056    pub response: Vec<u8>,
1057    /// Stream context for later publishing
1058    pub stream_ctx: StreamContext,
1059    /// Application-specific pending work
1060    pub pending: T,
1061}
1062
1063impl<T> ResponseStream<T> {
1064    /// Create a new response stream.
1065    pub fn new(response: Vec<u8>, stream_ctx: StreamContext, pending: T) -> Self {
1066        Self {
1067            response,
1068            stream_ctx,
1069            pending,
1070        }
1071    }
1072
1073    /// Get the stream ID.
1074    pub fn stream_id(&self) -> &str {
1075        self.stream_ctx.stream_id()
1076    }
1077
1078    /// Get the server's public key for client DH.
1079    pub fn server_pubkey(&self) -> &[u8; 32] {
1080        self.stream_ctx.server_pubkey()
1081    }
1082}
1083
1084// ============================================================================
1085// StreamGuard (Codegen hook for dispatch-level terminal frame enforcement)
1086// ============================================================================
1087
1088/// Codegen hook point for dispatch-level streaming continuation wrapping.
1089///
1090/// Currently a **no-op pass-through**. The real terminal-frame guarantee
1091/// lives in [`StreamChannel::run_stream()`], which service handlers call
1092/// directly. This struct exists so generated dispatch code has a single
1093/// place to wrap continuations — a future iteration can extend `wrap()`
1094/// to inject `run_stream` automatically (removing the need for handlers
1095/// to call it themselves).
1096pub struct StreamGuard;
1097
1098impl StreamGuard {
1099    /// Wrap a continuation (currently no-op pass-through).
1100    ///
1101    /// Terminal frame enforcement is provided by `StreamChannel::run_stream()`,
1102    /// not by this wrapper. See struct-level docs for roadmap.
1103    pub fn wrap(continuation: crate::service::Continuation) -> crate::service::Continuation {
1104        continuation
1105    }
1106}
1107
1108// ============================================================================
1109// Streaming-response concurrency (#186)
1110// ============================================================================
1111
1112/// Default ceiling on **concurrent server-side streaming responses per
1113/// service** — i.e. how many streaming RPCs one service may be actively pushing
1114/// data for at once. Overridable via [`install_max_concurrent_streams_per_service`]
1115/// (wired from `ServerConfig::max_concurrent_streams_per_service`).
1116///
1117/// This is the former per-`RequestLoop` `MAX_INFLIGHT_CONTINUATIONS` (16). When
1118/// the spawn moved out of the transport front-ends into the dispatch core
1119/// (#186) the bound is keyed by service name rather than living on each loop —
1120/// the *same* granularity, since each service has exactly one `RequestLoop`.
1121/// Keeping it per-service (not process-wide) preserves the original isolation:
1122/// one service's stuck or long-lived streams cannot starve another's.
1123pub const DEFAULT_MAX_CONCURRENT_STREAMS_PER_SERVICE: usize = 16;
1124
1125/// Process-global override for the per-service concurrent-streams cap.
1126/// First-write-wins, mirroring `install_verify_config`; installed once at
1127/// startup from the loaded `ServerConfig`. Read when a service's semaphore is
1128/// first created, so it must be installed before serving (it always is — the
1129/// daemon installs it right after loading config).
1130static MAX_CONCURRENT_STREAMS_PER_SERVICE: std::sync::OnceLock<usize> = std::sync::OnceLock::new();
1131
1132/// Install the per-service concurrent-streams cap. Call once at startup with
1133/// `ServerConfig::max_concurrent_streams_per_service`. Values are clamped to a
1134/// minimum of 1. Returns `Err(existing)` if already installed (first-write-wins).
1135pub fn install_max_concurrent_streams_per_service(n: usize) -> Result<(), usize> {
1136    MAX_CONCURRENT_STREAMS_PER_SERVICE.set(n.max(1))
1137}
1138
1139/// The effective cap: the installed value, or [`DEFAULT_MAX_CONCURRENT_STREAMS_PER_SERVICE`].
1140fn max_concurrent_streams_per_service() -> usize {
1141    MAX_CONCURRENT_STREAMS_PER_SERVICE
1142        .get()
1143        .copied()
1144        .unwrap_or(DEFAULT_MAX_CONCURRENT_STREAMS_PER_SERVICE)
1145}
1146
1147/// Per-service admission semaphores, created on first use at the effective cap.
1148/// A permit is held for the full lifetime of a streaming response (which is
1149/// itself bounded by the stream's JWT/TTL cancel token in `StreamChannel`, so
1150/// permits are always eventually released — there is no unbounded hold). The map
1151/// only ever grows by the number of distinct services (small, bounded), so it is
1152/// never pruned.
1153fn stream_admission_semaphore(service_name: &str) -> std::sync::Arc<tokio::sync::Semaphore> {
1154    use parking_lot::RwLock;
1155    use std::collections::HashMap;
1156    static MAP: std::sync::OnceLock<
1157        RwLock<HashMap<String, std::sync::Arc<tokio::sync::Semaphore>>>,
1158    > = std::sync::OnceLock::new();
1159    let map = MAP.get_or_init(|| RwLock::new(HashMap::new()));
1160    if let Some(sem) = map.read().get(service_name) {
1161        return std::sync::Arc::clone(sem);
1162    }
1163    std::sync::Arc::clone(
1164        map.write()
1165            .entry(service_name.to_owned())
1166            .or_insert_with(|| {
1167                std::sync::Arc::new(tokio::sync::Semaphore::new(
1168                    max_concurrent_streams_per_service(),
1169                ))
1170            }),
1171    )
1172}
1173
1174/// Spawn the server-side half of a streaming RPC — the task that keeps pushing
1175/// data *after* the `StreamInfo` reply has been sent — onto the current
1176/// `LocalSet`, bounded by a per-service admission permit.
1177///
1178/// Replaces the former "transport front-end spawns the continuation it got back
1179/// from `process_request`" model (#186): the dispatch core now spawns this task
1180/// itself and returns only the reply bytes, so the streaming lifecycle is no
1181/// longer threaded through every transport's request/response path. This is the
1182/// M1 shape; in M2 the streaming transport (`StreamChannel`) moves to a
1183/// service-owned moq broadcast and this coarse per-service cap is replaced by
1184/// the StreamOpt backpressure axes (#134).
1185///
1186/// `service_name` keys the per-service permit pool (see
1187/// [`DEFAULT_MAX_CONCURRENT_STREAMS_PER_SERVICE`] and
1188/// [`install_max_concurrent_streams_per_service`]). When the pool is saturated
1189/// the task waits for a permit rather than being dropped — and the wait is
1190/// logged so saturation is observable rather than a silent stall.
1191///
1192/// # Invariant
1193///
1194/// MUST be called from within a `tokio::task::LocalSet`: the task is `?Send`
1195/// (like every [`RequestService`](crate::service::RequestService)), and
1196/// `spawn_local` panics outside a `LocalSet`. Every
1197/// [`process_request`](crate::service::dispatch::process_request) caller already
1198/// runs on a `LocalSet` (ZMQ `RequestLoop`, the WebTransport server, and the
1199/// generic plane's `LocalServiceBridge`), which is the only place this is
1200/// invoked.
1201pub fn spawn_streaming_response(service_name: &str, continuation: crate::service::Continuation) {
1202    let sem = stream_admission_semaphore(service_name);
1203    let service_name = service_name.to_owned();
1204    tokio::task::spawn_local(async move {
1205        // Observe saturation: a permit that isn't immediately available means
1206        // this service is at its concurrent-streams cap and new streams are
1207        // queueing behind running ones.
1208        let permit = match sem.clone().try_acquire_owned() {
1209            Ok(p) => p,
1210            Err(_) => {
1211                tracing::warn!(
1212                    service = %service_name,
1213                    cap = max_concurrent_streams_per_service(),
1214                    "concurrent-streams cap reached; new stream waiting for a slot"
1215                );
1216                // The semaphore is a static that is never closed, so
1217                // acquire_owned cannot fail; if it somehow did, drop the stream.
1218                let Ok(p) = sem.acquire_owned().await else {
1219                    tracing::error!(service = %service_name, "stream admission semaphore closed; dropping stream");
1220                    return;
1221                };
1222                p
1223            }
1224        };
1225        let _permit = permit; // held for the streaming response's lifetime
1226        continuation.await;
1227    });
1228}
1229
1230// ============================================================================
1231// Helpers
1232// ============================================================================
1233
1234/// Encode a `StreamBlock` capnp message from a `prev_mac` + payload list.
1235///
1236/// Used by the moq streaming plane (`crate::moq_stream`) to produce
1237/// chained-HMAC StreamBlocks (§7.5 wire format).
1238pub fn encode_stream_block(
1239    prev_mac: &[u8],
1240    sequence_number: u64,
1241    epoch: u64,
1242    payloads: &[StreamPayloadData],
1243) -> Result<Vec<u8>> {
1244    encode_stream_block_with_provenance(prev_mac, sequence_number, epoch, payloads, None)
1245}
1246
1247/// Encode a `StreamBlock` with an optional per-host provenance signature (#321).
1248///
1249/// `provenance = None` produces the canonical *signed region* — byte-identical to
1250/// [`encode_stream_block`] — over which the provenance signature is computed (and
1251/// which the consumer reconstructs to verify). `provenance = Some((signer_kid,
1252/// sig))` additionally populates the wire `StreamBlock.provenance` field.
1253pub fn encode_stream_block_with_provenance(
1254    prev_mac: &[u8],
1255    sequence_number: u64,
1256    epoch: u64,
1257    payloads: &[StreamPayloadData],
1258    provenance: Option<(&[u8], &[u8])>,
1259) -> Result<Vec<u8>> {
1260    let mut msg = Builder::new_default();
1261    {
1262        let mut block = msg.init_root::<streaming_capnp::stream_block::Builder>();
1263        block.set_prev_mac(prev_mac);
1264        // Producer-assigned counter (#219); MAC-covered implicitly (whole block is signed).
1265        // epoch is 0 until the #223 key-epoch lifecycle lands.
1266        block.set_sequence_number(sequence_number);
1267        block.set_epoch(epoch);
1268
1269        // #321: per-host provenance. Set BEFORE the payload list so the canonical
1270        // serialization is deterministic regardless of field-set order. Absent ⇒
1271        // the field stays default (empty) — the signed-region encoding.
1272        if let Some((signer_kid, sig)) = provenance {
1273            let mut prov = block.reborrow().init_provenance();
1274            prov.set_signer_kid(signer_kid);
1275            prov.set_sig(sig);
1276        }
1277
1278        // Cap'n Proto uses u32 for list lengths
1279        let payloads_len = u32::try_from(payloads.len()).unwrap_or(u32::MAX);
1280        let mut list = block.init_payloads(payloads_len);
1281        for (i, payload) in payloads.iter().enumerate() {
1282            let idx = u32::try_from(i).unwrap_or(u32::MAX);
1283            let mut p = list.reborrow().get(idx);
1284            match payload {
1285                StreamPayloadData::Data(data) => {
1286                    p.set_data(data);
1287                }
1288                StreamPayloadData::Error(message) => {
1289                    let mut err = p.init_error();
1290                    err.set_message(message);
1291                    err.set_code("");
1292                    err.set_details("");
1293                }
1294                StreamPayloadData::Complete(data) => {
1295                    p.set_complete(data);
1296                }
1297                StreamPayloadData::EpochCommit(_) => {
1298                    anyhow::bail!(
1299                        "identified stream epoch control reached cleartext serialization"
1300                    );
1301                }
1302                StreamPayloadData::Tagged {
1303                    tag,
1304                    payload,
1305                    nonce,
1306                    key_commitment,
1307                } => {
1308                    let mut tagged = p.init_tagged();
1309                    tagged.set_tag(tag);
1310                    tagged.set_payload(payload);
1311                    tagged.set_nonce(nonce);
1312                    tagged.set_key_commitment(key_commitment);
1313                }
1314            }
1315        }
1316    }
1317
1318    let mut capnp_bytes = Vec::new();
1319    serialize::write_message(&mut capnp_bytes, &msg)?;
1320    Ok(capnp_bytes)
1321}
1322
1323/// Convert a public key to 32 bytes for derive_stream_keys.
1324///
1325/// - If 32 bytes: use as-is (Ristretto255)
1326/// - If different length: hash with Blake3/SHA-256 to get 32 bytes (P-256)
1327fn pubkey_to_32(pubkey: &[u8]) -> [u8; 32] {
1328    if pubkey.len() == 32 {
1329        let mut arr = [0u8; 32];
1330        arr.copy_from_slice(pubkey);
1331        arr
1332    } else {
1333        // Hash to 32 bytes for non-32-byte keys (P-256 is 33 bytes compressed)
1334        crate::crypto::keyed_mac(&[0u8; 32], pubkey)
1335    }
1336}
1337
1338/// Derive the `(mac_key, enc_key, topic)` triple from a client-side DH exchange (#321).
1339///
1340/// This is the consumer-side counterpart to
1341/// `StreamContext::from_third_party_interop_dh` (the server side).
1342/// Call this before constructing a `MoqStreamHandle` when you have the raw keys from
1343/// `generate_ephemeral_keypair()` and the server pubkey from `StreamInfo`.
1344pub fn derive_client_stream_keys(
1345    client_secret: &DhSecret,
1346    client_pubkey: &[u8],
1347    server_pubkey: &[u8],
1348) -> anyhow::Result<([u8; 32], [u8; 32], String)> {
1349    let server_pub = DhPublic::from_slice(server_pubkey)
1350        .ok_or_else(|| anyhow::anyhow!("invalid server pubkey length"))?;
1351    let shared = dh_compute(client_secret, &server_pub);
1352    let client_pub_32 = pubkey_to_32(client_pubkey);
1353    let server_pub_32 = pubkey_to_32(server_pubkey);
1354    let keys = crate::crypto::derive_stream_keys(&shared, &client_pub_32, &server_pub_32)?;
1355    // #321: also return the AEAD enc_key so the moq consumer can open Tagged blocks.
1356    Ok((*keys.mac_key, *keys.enc_key, keys.topic.clone()))
1357}
1358
1359// `constant_time_eq` removed with the duplicate StreamVerifier (#224) — the canonical
1360// verifier in `stream_consumer` has its own.
1361
1362#[cfg(test)]
1363mod tests {
1364    use super::*;
1365
1366    fn build_stream_register_envelope(
1367        topic: &str,
1368        expiry: i64,
1369        signing_key: &SigningKey,
1370        pq_signing_key: Option<&crate::crypto::pq::MlDsaSigningKey>,
1371        _claims: Option<Claims>,
1372    ) -> Vec<u8> {
1373        use crate::common_capnp;
1374        use crate::envelope::{RequestEnvelope, SignedEnvelope};
1375        use crate::ToCapnp;
1376
1377        let mut inner_msg = Builder::new_default();
1378        {
1379            let mut register =
1380                inner_msg.init_root::<crate::streaming_capnp::stream_register::Builder>();
1381            register.set_topic(topic);
1382            register.set_exp(expiry);
1383        }
1384        let mut inner_bytes = Vec::new();
1385        if let Err(e) = serialize::write_message(&mut inner_bytes, &inner_msg) {
1386            tracing::error!("Failed to serialize StreamRegister: {e}");
1387            return Vec::new();
1388        }
1389        let envelope = RequestEnvelope::new(inner_bytes);
1390        let policy = if pq_signing_key.is_some() {
1391            crate::crypto::CryptoPolicy::Hybrid
1392        } else {
1393            crate::crypto::CryptoPolicy::Classical
1394        };
1395        let signed = match SignedEnvelope::new_signed_with_policy(
1396            envelope,
1397            signing_key,
1398            pq_signing_key,
1399            policy,
1400        ) {
1401            Ok(signed) => signed,
1402            Err(e) => {
1403                tracing::error!("Failed to sign envelope: {e}");
1404                return Vec::new();
1405            }
1406        };
1407        let mut msg = Builder::new_default();
1408        {
1409            let mut builder = msg.init_root::<common_capnp::signed_envelope::Builder>();
1410            signed.write_to(&mut builder);
1411        }
1412        let mut bytes = Vec::new();
1413        if let Err(e) = serialize::write_message(&mut bytes, &msg) {
1414            tracing::error!("Failed to serialize SignedEnvelope: {e}");
1415            return Vec::new();
1416        }
1417        bytes
1418    }
1419
1420    /// #161 / WNS: a StreamRegister built with a PQ key is a Hybrid composite
1421    /// that ENFORCES the anchored ML-DSA outer when the signer's key is anchored
1422    /// in the PQ trust store, and falls back to the inner EdDSA (classical floor)
1423    /// when it isn't — per-identity, exactly mirroring the RPC plane. The
1424    /// unanchored fallback is no weaker than `verify_any_signer` (Classical),
1425    /// which already verifies the self-asserted `cnf`'s EdDSA without a pin.
1426    #[test]
1427    fn stream_register_hybrid_verifies_only_when_pq_anchored() -> anyhow::Result<()> {
1428        use crate::common_capnp;
1429        use crate::crypto::pq::{ml_dsa_generate_keypair, ml_dsa_vk_from_bytes};
1430        use crate::crypto::CryptoPolicy;
1431        use crate::envelope::{InMemoryNonceCache, KeyedPqTrustStore, SignedEnvelope};
1432        use crate::FromCapnp;
1433
1434        let signing_key = SigningKey::from_bytes(&[7u8; 32]);
1435        let (pq_sk, pq_vk) = ml_dsa_generate_keypair();
1436
1437        let bytes = build_stream_register_envelope(
1438            "deadbeef".repeat(8).as_str(),
1439            i64::MAX,
1440            &signing_key,
1441            Some(&pq_sk),
1442            None,
1443        );
1444        assert!(!bytes.is_empty(), "register envelope must serialize");
1445
1446        let reader = serialize::read_message(
1447            &mut std::io::Cursor::new(&bytes[..]),
1448            capnp::message::ReaderOptions::default(),
1449        )?;
1450        let signed =
1451            SignedEnvelope::read_from(reader.get_root::<common_capnp::signed_envelope::Reader>()?)?;
1452
1453        assert_eq!(
1454            signed.policy,
1455            CryptoPolicy::Hybrid,
1456            "must sign Hybrid with PQ key"
1457        );
1458
1459        // Anchored: the signer's ML-DSA vk is bound to its Ed25519 identity.
1460        let mut store = KeyedPqTrustStore::new();
1461        let vk = ml_dsa_vk_from_bytes(&crate::crypto::pq::ml_dsa_vk_bytes(&pq_vk))?;
1462        store.bind(signing_key.verifying_key().to_bytes(), &vk);
1463        let nonce_ok = InMemoryNonceCache::new();
1464        assert!(
1465            signed
1466                .verify_any_signer_with(&nonce_ok, Some(&store), CryptoPolicy::Hybrid)
1467                .is_ok(),
1468            "anchored Hybrid register must verify"
1469        );
1470
1471        // Not anchored: the mandatory Hybrid policy rejects the register even
1472        // though its self-asserted composite is cryptographically well formed.
1473        let empty = KeyedPqTrustStore::new();
1474        let nonce_empty = InMemoryNonceCache::new();
1475        assert!(
1476            signed
1477                .verify_any_signer_with(&nonce_empty, Some(&empty), CryptoPolicy::Hybrid)
1478                .is_err(),
1479            "unanchored Hybrid register must fail closed"
1480        );
1481
1482        // A tampered/forged inner EdDSA is also rejected.
1483        let mut forged = signed.clone();
1484        forged.cnf = SigningKey::from_bytes(&[9u8; 32])
1485            .verifying_key()
1486            .to_bytes();
1487        let nonce_forged = InMemoryNonceCache::new();
1488        assert!(
1489            forged
1490                .verify_any_signer_with(&nonce_forged, Some(&empty), CryptoPolicy::Hybrid)
1491                .is_err(),
1492            "swapping cnf without a matching inner EdDSA must still be rejected"
1493        );
1494        Ok(())
1495    }
1496
1497    #[test]
1498    fn test_batching_config_default() {
1499        let config = BatchingConfig::default();
1500        assert_eq!(config.min_batch_size, 1);
1501        assert_eq!(config.max_batch_size, 16);
1502        assert_eq!(config.max_block_bytes, 65536);
1503    }
1504
1505    #[test]
1506    fn test_hmac_chain() {
1507        let key = [0x42u8; 32];
1508        let topic = "test_topic".to_owned();
1509
1510        let mut state = StreamHmacState::new(key, topic);
1511
1512        let mac1 = state.compute_next(b"data1");
1513        let mac2 = state.compute_next(b"data2");
1514
1515        // MACs should be different
1516        assert_ne!(mac1, mac2);
1517
1518        // Chain state should advance to mac2
1519        assert_eq!(state.prev_mac_bytes(), &mac2[..]);
1520    }
1521
1522    #[tokio::test]
1523    async fn stream_channels_keep_distinct_service_reach() -> Result<()> {
1524        use crate::moq_stream::{NodeStreamReach, ProducerReachConfig};
1525        use crate::stream_info::TransportConfig;
1526
1527        let config = |port| -> Result<ProducerReachConfig> {
1528            Ok(ProducerReachConfig {
1529                moql_server_identity: None,
1530                relay_moql_server_identity: None,
1531                iroh_node_id: None,
1532                quic_reach: Some(NodeStreamReach {
1533                    addr: format!("127.0.0.1:{port}").parse()?,
1534                    server_name: format!("server-{port}"),
1535                    cert_hashes: vec![[port as u8; 32]],
1536                }),
1537                relay: None,
1538            })
1539        };
1540        let channel_a =
1541            StreamChannel::new(SigningKey::from_bytes(&[1; 32])).with_reach_config(config(4101)?);
1542        let channel_b =
1543            StreamChannel::new(SigningKey::from_bytes(&[2; 32])).with_reach_config(config(4102)?);
1544        let (_, client_pub) = crate::crypto::generate_ephemeral_keypair();
1545
1546        let stream_a = channel_a
1547            .prepare_third_party_interop_stream(&client_pub.to_bytes(), 60)
1548            .await?;
1549        let stream_b = channel_b
1550            .prepare_third_party_interop_stream(&client_pub.to_bytes(), 60)
1551            .await?;
1552
1553        let addr = |stream: &StreamContext| match &stream.reach()[0].transport {
1554            TransportConfig::Quic(reach) => reach.addr.clone(),
1555            other => panic!("expected QUIC reach, got {other:?}"),
1556        };
1557        assert_eq!(addr(&stream_a), "127.0.0.1:4101");
1558        assert_eq!(addr(&stream_b), "127.0.0.1:4102");
1559        Ok(())
1560    }
1561
1562    #[tokio::test]
1563    async fn identified_preparation_uses_hybrid_material_not_interop_dh() -> Result<()> {
1564        use crate::crypto::hybrid_kem::{generate_recipient, SuiteId};
1565        use crate::stream_epoch::{
1566            IdentifiedStreamBinding, StreamAcceptedState, StreamCarrierProfile, StreamRouteRole,
1567        };
1568
1569        let binding = IdentifiedStreamBinding::new(
1570            StreamCarrierProfile::OwnedHybridTransport,
1571            StreamRouteRole::Direct,
1572            "did:at9p:producer",
1573            "did:at9p:consumer",
1574            StreamAcceptedState {
1575                identity_did: "did:at9p:producer".into(),
1576                digest: [0x51; 64],
1577                epoch: 7,
1578            },
1579            StreamAcceptedState {
1580                identity_did: "did:at9p:consumer".into(),
1581                digest: [0x61; 64],
1582                epoch: 8,
1583            },
1584            "inference.generate",
1585            "infer:model:qwen",
1586            "local/streams/identified",
1587            "did:at9p:producer#mesh-kem",
1588            "urn:hyprstream:stream-client:one-shot",
1589            64,
1590        )?;
1591        let recipient = generate_recipient(SuiteId::HyKemX25519MlKem768)?;
1592        let channel = StreamChannel::new(SigningKey::from_bytes(&[4; 32]));
1593
1594        let stream = channel
1595            .prepare_identified_stream_for_verified_recipient_with_claims(
1596                &recipient.public(),
1597                binding,
1598                60,
1599                None,
1600            )
1601            .await?;
1602
1603        assert!(stream.kem_ciphertexts().is_some());
1604        assert!(stream.has_epoch_ratchet());
1605        assert_eq!(stream.server_pubkey(), &[0; 32]);
1606        Ok(())
1607    }
1608
1609    #[tokio::test]
1610    async fn stream_channel_uses_service_scoped_moq_origin() -> Result<()> {
1611        let scoped_origin = crate::moq_stream::MoqStreamOrigin::standalone().build();
1612        let origin_handle =
1613            std::sync::Arc::new(parking_lot::RwLock::new(Some(scoped_origin.clone())));
1614        let channel = StreamChannel::new(SigningKey::from_bytes(&[3; 32]))
1615            .with_moq_origin_handle(origin_handle);
1616        let (_, client_pub) = crate::crypto::generate_ephemeral_keypair();
1617        let stream = channel
1618            .prepare_third_party_interop_stream(&client_pub.to_bytes(), 60)
1619            .await?;
1620        let _publisher = channel.publisher(&stream).await?;
1621
1622        let path = scoped_origin.broadcast_path(stream.topic());
1623        assert_eq!(channel.broadcast_path(stream.topic())?, path);
1624        tokio::time::timeout(
1625            std::time::Duration::from_secs(1),
1626            scoped_origin.consumer().announced_broadcast(&path),
1627        )
1628        .await?
1629        .ok_or_else(|| anyhow::anyhow!("scoped origin did not announce {path}"))?;
1630        Ok(())
1631    }
1632
1633    #[test]
1634    #[allow(clippy::unwrap_used)]
1635    fn stream_block_carries_sequence_number_and_epoch() {
1636        // #219: the producer stamps sequenceNumber/epoch into the StreamBlock; since the
1637        // MAC covers the whole serialized block, they're authenticated implicitly. Confirm
1638        // the wire round-trips them (consumer enforcement is policy-selected, #163).
1639        let payloads = vec![StreamPayloadData::Data(b"hello".to_vec())];
1640        let bytes = encode_stream_block(&[0u8; 16], 42, 7, &payloads).unwrap();
1641        let reader = capnp::serialize::read_message(
1642            &mut std::io::Cursor::new(&bytes),
1643            capnp::message::ReaderOptions::default(),
1644        )
1645        .unwrap();
1646        let block = reader
1647            .get_root::<crate::streaming_capnp::stream_block::Reader>()
1648            .unwrap();
1649        assert_eq!(block.get_sequence_number(), 42);
1650        assert_eq!(block.get_epoch(), 7);
1651    }
1652
1653    #[test]
1654    #[allow(clippy::unwrap_used, clippy::expect_used)]
1655    fn flat_slice_parses_unaligned_block() {
1656        // The zero-copy verifier (`stream_consumer`) parses StreamBlocks via
1657        // `read_message_from_flat_slice` over `Bytes` that come straight from the
1658        // moq/quinn receive buffer — and those can start at ANY byte offset, not
1659        // an 8-byte boundary. capnp's flat-slice reader requires 8-byte alignment
1660        // unless the `unaligned` feature is on, so this guards that we keep it on.
1661        let payloads = vec![StreamPayloadData::Data(b"hello".to_vec())];
1662        let bytes = encode_stream_block(&[0u8; 16], 42, 7, &payloads).unwrap();
1663        // Force a deliberately unaligned view: offset the message by 1 byte.
1664        let mut padded = vec![0u8; 1];
1665        padded.extend_from_slice(&bytes);
1666        let unaligned = &padded[1..];
1667        assert_ne!(
1668            unaligned.as_ptr() as usize % 8,
1669            0,
1670            "test precondition: slice must be unaligned"
1671        );
1672        let mut slice: &[u8] = unaligned;
1673        let reader = capnp::serialize::read_message_from_flat_slice(
1674            &mut slice,
1675            capnp::message::ReaderOptions::default(),
1676        )
1677        .unwrap();
1678        let block = reader
1679            .get_root::<crate::streaming_capnp::stream_block::Reader>()
1680            .unwrap();
1681        assert_eq!(block.get_sequence_number(), 42);
1682        assert_eq!(block.get_epoch(), 7);
1683    }
1684}