Skip to main content

StreamChannel

Struct StreamChannel 

Source
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

Source

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.

Source

pub fn with_reach_config(self, cfg: ProducerReachConfig) -> Self

Initialize this channel’s reach configuration.

Source

pub fn with_reach_config_handle(self, handle: ProducerReachConfigHandle) -> Self

Share a service-owned reach handle with this channel.

Source

pub fn reach_config_handle(&self) -> ProducerReachConfigHandle

Return this channel’s service-owned reach handle.

Source

pub fn with_moq_origin_handle(self, handle: MoqStreamOriginHandle) -> Self

Share a service-owned MoQ origin handle with this channel.

Source

pub fn moq_origin_handle(&self) -> MoqStreamOriginHandle

Return this channel’s service-owned MoQ origin handle.

Source

pub fn broadcast_path(&self, topic: &str) -> Result<String>

Return the broadcast path on the exact origin this channel publishes to.

Source

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).

Source

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:

  1. Uses the authenticated recipient from the verified envelope
  2. Binds it to the accepted identified-stream state before deriving keys
  3. Pre-authorizes the stream with StreamService
§Arguments
  • envelope_ctx - Verified request context containing the HyKEM recipient
  • binding - Accepted-current identity, capability, route, and epoch binding
  • expiry_secs - Stream expiration in seconds from now
§Returns

StreamContext ready for publishing

Source

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 recipient
  • binding - Accepted-current identity, capability, route, and epoch binding
  • expiry_secs - Stream expiration in seconds from now
  • claims - Optional user claims for authorization
§Returns

StreamContext ready for publishing

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub async fn run_stream<F, Fut, R>( &self, ctx: &StreamContext, f: F, ) -> Result<R>
where F: FnOnce(AnyStreamPublisher) -> Fut, Fut: Future<Output = (AnyStreamPublisher, 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 Ok and not terminated → framework sends Complete (empty metadata)
  • If Err and not terminated → framework sends Error with the error message
  • If already terminated → no-op (closure handled it)
Source

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§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts 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
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> ServiceExt for T

§

fn map_response_body<F>(self, f: F) -> MapResponseBody<Self, F>
where Self: Sized,

Apply a transformation to the response body. Read more
§

fn trace_for_http(self) -> Trace<Self, SharedClassifier<ServerErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using HTTP status codes. Read more
§

fn trace_for_grpc(self) -> Trace<Self, SharedClassifier<GrpcErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using gRPC headers. Read more
§

fn follow_redirects(self) -> FollowRedirect<Self>
where Self: Sized,

Follow redirect resposes using the Standard policy. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

impl<T> ErasedDestructor for T
where T: 'static,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSync for T
where T: Sync,

§

impl<T> MaybeSync for T
where T: Sync,