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}