Live stream publication and subscriptions
Advertise typed producer data and manage independent authorized consumer subscriptions.
Advertise a live stream to deliver continuing typed samples without saving every sample as a durable record. Each authorized consumer opens and owns its subscription.
Closing one consumer subscription leaves other subscriptions and the producer running.
Reference, descriptor, and subscription
| Object | Owner and contents | What it does not contain |
|---|---|---|
StreamRef | Stream id, schema, producer, and session_id | Consumer credentials or a live handle |
StreamDescriptor | Reference plus scope, expires_at, delivery_policy, and transports | A guarantee that the producer is currently reachable |
StreamPublisher | Producer-owned descriptor, reference, and publication lifetime | Shared ownership of consumer receivers |
StreamSubscription | One consumer's receiver and cancellation lifetime | Authority transferable to another consumer |
StreamSample | Typed payload with sequence, session identity, and observation time | An automatic durable history |
Match producer, stream ID, session ID, and complete schema identity (id, version, and digest) when identifying a stream version. A stale reference never switches producers silently. The session ID distinguishes restarts so an old sequence cannot overwrite a new session.
Advertise and publish
Supply the approved schema and StreamOptions with scope, authority, expiry, capacity, and delivery policy. Advertisement precedes sharing the reference.
entity is optional when no durable record is associated with the stream. Application transport configuration controls permitted paths.
SampleResult reports the publication outcome. Acceptance into a local sending path is not acknowledgment by every consumer. Save durable state at the application's chosen cadence, separately from sample production.
Open a consumer-owned subscription
SubscriptionOptions bounds capacity and the subscription operation. Each subscription requires independent read authority. A StreamRef, discoverable address, or received event grants no access. The application owns sample freshness checks.
Do not place an endless sample loop inside an event receiver. Start a bounded worker per active record or stream. Capture each event's reference by value. Cancel and join a replaced worker outside the receive loop.
Bound slow-consumer behavior
The delivery policy limits buffered samples. latest discards older queued items to admit current items within capacity. Report gaps and dropped samples. Do not interpret missing sequence numbers as proof of a producer restart.
reject-overflow rejects the overflowing sample, discards pending samples, and ends only that receiver. next() reports CapacityExceeded once. Later receives return Closed and no samples. One terminal latch bounds error storage. Always cancel the receiver and join owned application workers after overflow.
The first terminal transition wins. Receiver cancellation first reports Canceled once, then Closed. Producer close first discards pending samples and reports Closed. A pending overflow error survives later cancellation or producer close. No terminal receiver resumes.
Transport backpressure is distinct from sensor sampling. A constrained transport can shed lower-priority frames. That behavior does not automatically change the producer's sampling rate. If the application adapts sampling, document that policy separately.
End, expiry, reconnect, and cancellation
An ended producer, expired descriptor, revoked capability, unavailable path, or closed session changes the live state. Preserve a last sample with its timestamp and a stale indicator. Do not display it as continuing live delivery.
On reconnect, resolve the current descriptor and open a fresh authorized subscription. Do not assume missed live samples replay. Use saved state or a separately designed history service for recovery.
StaleDescriptor requires current discovery. SchemaMismatch requires a compatible decoder. Unauthorized and Revoked require authority repair, not an infinite retry. Unavailable follows your permitted routing and retry policy.
Canceling one pending next() call does not cancel its subscription. cancel() is idempotent. It stops new delivery and joins receiver resources. A subscription cancellation is not a producer shutdown. Call StreamPublisher.close() when production ends. It ends advertisement and sample publication. Stop issuing its reference.