pub struct StreamChannel { /* private fields */ }Expand description
Service-level async streaming infrastructure that encapsulates socket management and stream pre-authorization.
StreamChannel handles the complexity of:
- Async PUSH socket creation and lazy initialization (via tmq)
- identified hybrid key exchange via
StreamContext::from_hybrid_identified() - Stream pre-authorization with StreamService
- Endpoint discovery via the registry
§Example
// In service initialization
let stream_channel = StreamChannel::new(signing_key.clone());
// In a same-cell/federated request handler, after accepting the binding:
let stream_ctx = stream_channel
.prepare_identified_stream(&envelope_ctx, binding, 600)
.await?;
// In async context
let mut publisher = stream_channel.publisher(&stream_ctx).await?;
publisher.publish_progress("processing", 0, 100).await?;
// ... do work ...
publisher.complete(&metadata).await?;Implementations§
Source§impl StreamChannel
impl StreamChannel
Sourcepub fn new(signing_key: SigningKey) -> Self
pub fn new(signing_key: SigningKey) -> Self
Create a new stream channel.
The post-quantum half of the StreamRegister composite is the node’s
persistent mesh ML-DSA-65 key, derived deterministically from
signing_key via crate::node_identity::derive_mesh_mldsa_key (#157),
mirroring LocalSigner::new on the RPC plane. This replaces the previous
ephemeral keygen so the streaming control plane’s ML-DSA public key is
stable across restarts and equals the #mesh-pq key peers anchor. Use
Self::with_pq_key only to override with an externally supplied key.
Sourcepub fn with_reach_config(self, cfg: ProducerReachConfig) -> Self
pub fn with_reach_config(self, cfg: ProducerReachConfig) -> Self
Initialize this channel’s reach configuration.
Sourcepub fn with_reach_config_handle(self, handle: ProducerReachConfigHandle) -> Self
pub fn with_reach_config_handle(self, handle: ProducerReachConfigHandle) -> Self
Share a service-owned reach handle with this channel.
Sourcepub fn reach_config_handle(&self) -> ProducerReachConfigHandle
pub fn reach_config_handle(&self) -> ProducerReachConfigHandle
Return this channel’s service-owned reach handle.
Sourcepub fn with_moq_origin_handle(self, handle: MoqStreamOriginHandle) -> Self
pub fn with_moq_origin_handle(self, handle: MoqStreamOriginHandle) -> Self
Share a service-owned MoQ origin handle with this channel.
Sourcepub fn moq_origin_handle(&self) -> MoqStreamOriginHandle
pub fn moq_origin_handle(&self) -> MoqStreamOriginHandle
Return this channel’s service-owned MoQ origin handle.
Sourcepub fn broadcast_path(&self, topic: &str) -> Result<String>
pub fn broadcast_path(&self, topic: &str) -> Result<String>
Return the broadcast path on the exact origin this channel publishes to.
Sourcepub fn with_pq_key(self, key: MlDsaSigningKey) -> Self
pub fn with_pq_key(self, key: MlDsaSigningKey) -> Self
Install the node’s persistent ML-DSA-65 signing key, replacing the auto-generated one. The matching public key must be anchored in the StreamService verifier’s PQ trust store for Hybrid verification to succeed (peer attestation, #157).
Sourcepub async fn prepare_identified_stream(
&self,
envelope_ctx: &EnvelopeContext,
binding: IdentifiedStreamBinding,
expiry_secs: i64,
) -> Result<StreamContext>
pub async fn prepare_identified_stream( &self, envelope_ctx: &EnvelopeContext, binding: IdentifiedStreamBinding, expiry_secs: i64, ) -> Result<StreamContext>
Prepare an identified stream with the pinned hybrid post-quantum handshake and pre-authorization.
This method:
- Uses the authenticated recipient from the verified envelope
- Binds it to the accepted identified-stream state before deriving keys
- Pre-authorizes the stream with StreamService
§Arguments
envelope_ctx- Verified request context containing the HyKEM recipientbinding- Accepted-current identity, capability, route, and epoch bindingexpiry_secs- Stream expiration in seconds from now
§Returns
StreamContext ready for publishing
Sourcepub async fn prepare_identified_stream_with_claims(
&self,
envelope_ctx: &EnvelopeContext,
binding: IdentifiedStreamBinding,
expiry_secs: i64,
claims: Option<Claims>,
) -> Result<StreamContext>
pub async fn prepare_identified_stream_with_claims( &self, envelope_ctx: &EnvelopeContext, binding: IdentifiedStreamBinding, expiry_secs: i64, claims: Option<Claims>, ) -> Result<StreamContext>
Prepare an identified stream with claims.
The recipient is read only from the verified crate::service::EnvelopeContext;
callers must supply the accepted-current binding. This API deliberately
has no classical fallback: a request with a verified HyKEM recipient is
never downgraded to a DH-derived stream.
§Arguments
envelope_ctx- Verified request context containing the HyKEM recipientbinding- Accepted-current identity, capability, route, and epoch bindingexpiry_secs- Stream expiration in seconds from nowclaims- Optional user claims for authorization
§Returns
StreamContext ready for publishing
Sourcepub async fn prepare_third_party_interop_stream(
&self,
client_ephemeral_pubkey: &[u8],
expiry_secs: i64,
) -> Result<StreamContext>
pub async fn prepare_third_party_interop_stream( &self, client_ephemeral_pubkey: &[u8], expiry_secs: i64, ) -> Result<StreamContext>
Prepare a legacy stream for an explicitly selected third-party interoperability peer.
This is the only StreamChannel entry point that uses classical DH.
Same-cell and federated callers must use
Self::prepare_identified_stream with their verified envelope and
accepted crate::stream_epoch::IdentifiedStreamBinding.
Sourcepub async fn prepare_third_party_interop_stream_with_claims(
&self,
client_ephemeral_pubkey: &[u8],
expiry_secs: i64,
_claims: Option<Claims>,
) -> Result<StreamContext>
pub async fn prepare_third_party_interop_stream_with_claims( &self, client_ephemeral_pubkey: &[u8], expiry_secs: i64, _claims: Option<Claims>, ) -> Result<StreamContext>
Same as Self::prepare_third_party_interop_stream, with optional
authorization claims for the legacy third-party interoperability edge.
Sourcepub async fn register_topic(
&self,
_topic: &str,
_expiry: i64,
_claims: Option<Claims>,
) -> Result<()>
pub async fn register_topic( &self, _topic: &str, _expiry: i64, _claims: Option<Claims>, ) -> Result<()>
Register a topic with the stream plane.
No-op on the moq path — topics are published lazily by
MoqStreamPublisher on first frame; no pre-registration is needed.
Kept for API compatibility with callers such as NotificationService.
Sourcepub async fn publisher(&self, ctx: &StreamContext) -> Result<AnyStreamPublisher>
pub async fn publisher(&self, ctx: &StreamContext) -> Result<AnyStreamPublisher>
Create a publisher for a stream context.
Fails loudly if the process-global moq stream origin has not been
initialized (server not started). In production the streams factory
always calls init_global_moq_origin before any service handles requests.
Sourcepub async fn run_stream<F, Fut, R>(
&self,
ctx: &StreamContext,
f: F,
) -> Result<R>
pub async fn run_stream<F, Fut, R>( &self, ctx: &StreamContext, f: F, ) -> Result<R>
Run a streaming operation with framework-guaranteed terminal frame.
The closure receives an [AnyStreamPublisher] by value and must return
it alongside its result. The framework sends a terminal frame if the
closure didn’t. Transport (moq-lite or ZMQ) is selected automatically
based on whether a global moq origin is registered.
After the closure returns:
- If
Okand not terminated → framework sendsComplete(empty metadata) - If
Errand not terminated → framework sendsErrorwith the error message - If already terminated → no-op (closure handled it)
Sourcepub async fn publisher_for_topic(
&self,
topic: &str,
) -> Result<AnyStreamPublisher>
pub async fn publisher_for_topic( &self, topic: &str, ) -> Result<AnyStreamPublisher>
Create a publisher for a pre-registered topic (no DH).
Used by NotificationService where topics are registered via register_topic()
and don’t use DH-based key exchange. The transport MAC key is randomly generated
(separate from notification E2E MAC which is embedded in the payload).
Auto Trait Implementations§
impl Freeze for StreamChannel
impl !RefUnwindSafe for StreamChannel
impl Send for StreamChannel
impl Sync for StreamChannel
impl Unpin for StreamChannel
impl UnsafeUnpin for StreamChannel
impl !UnwindSafe for StreamChannel
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more