Data and primitivesLive stream publication and subscriptions

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

ObjectOwner and contentsWhat it does not contain
StreamRefStream id, schema, producer, and session_idConsumer credentials or a live handle
StreamDescriptorReference plus scope, expires_at, delivery_policy, and transportsA guarantee that the producer is currently reachable
StreamPublisherProducer-owned descriptor, reference, and publication lifetimeShared ownership of consumer receivers
StreamSubscriptionOne consumer's receiver and cancellation lifetimeAuthority transferable to another consumer
StreamSampleTyped payload with sequence, session identity, and observation timeAn 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.

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.