Skip to main content

Crate tightbeam_pubsub

Crate tightbeam_pubsub 

Source
Expand description

§tightbeam-pubsub

Topic pub/sub extension for the tightbeam messaging protocol.

§Status

This project is under active development. Public APIs MAY change without notice. No security audit has been conducted. Use this software at your own risk.

§Abstract

This crate adds topic membership and publish fan-out to the tightbeam mux. A subscription is an ordinary command stream that the client opens, and an update is a push that the server initiates. The crate therefore adds no transport protocol and no broker, and any carrier of the mux carries it, WebSocket or raw TCP. Topic names follow the exact-match model of MQTT 5.0 § 4.7, with no wildcards.

§Install

cargo add tightbeam-pubsub

§Publishing

TopicRegistry::publish wraps a payload in an update frame, and publish_frame relays a whole tightbeam frame as the payload, so the signatures and the seal of its publisher hold end to end. Implementation: docs/pubsub.md.

§Topics and delivery

TopicRegistry owns membership, stamps each update with a dense sequence for its topic, and bounds what each connection queues. A delivery policy decides what a full queue drops. Implementation: docs/pubsub.md.

§Authorization

A subscribe policy and an optional publish policy decide each topic against the peer that the handshake proved. Client publish stays off until a publish policy is installed. Implementation: docs/pubsub.md.

§Serving connections

PubsubCommands::serve runs the whole life of one accepted connection, and it hands every unary stream that no command claims to the routes of the application. Implementation: docs/pubsub.md.

§Drain

A drain completes every subscription, waits for each completion to leave, and then dismisses every connection with a GoAway. It keeps each sequence dense. Implementation: docs/pubsub.md.

§Scaling out

A backplane assigns the sequence of each topic and carries a publish to every node. The in-process Local backplane is the default, and an implementation over Redis, Postgres, or NATS meets the same contract. testing::BackplaneConformance checks the clauses of the contract that the implementation page names for it. Implementation: docs/pubsub.md.

§Command convention

Topic names travel in the frame id behind the command prefixes sub/, unsub/, pub/, and end/, and every answer is a gRPC canonical status. Implementation: docs/pubsub.md.

§Features

instrument records the audit trail of each served connection: its admission, departure, and expulsion, its refused commands, and its dropped updates. Implementation: docs/pubsub.md.

testing adds loopback WebSocket links and peers for tests, and the backplane contract suite. Implementation: docs/pubsub.md.

The TypeScript counterpart is @wahidgroup/tightbeam-pubsub-client (client), which consumes these conventions over @wahidgroup/tightbeam-ws-client. A runnable server is examples/pubsub_demo_server.rs, the same binary the dockerized e2e suite drives. See the repository README for development and release workflows.

§License

Licensed under either of MIT or Apache-2.0 at your option.

Modules§

events
The events of the audit trail of a served connection. The page docs/pubsub.md (Connection serve) states the label and value of each.

Structs§

AllowAll
The default policy: every subscription (and, when installed as a PublishPolicy, every publish) is allowed.
ConnectionContext
What one served connection’s application handler works with: its emitter, and its standing in the registry that admitted it.
Delivered
What one node did with a delivered update: the topics that lost their last local member while it fanned the update out, because the delivery policy expelled a connection.
Drained
What one TopicRegistry::drain did.
DropOldest
The default policy: always drop the oldest queued update, so the newest state wins and the gate of the client reports the loss.
EmitDeadline
How long one emit may take to settle.
Emitter
The emitter of one link: the handle each frame leaves on, the clock and the deadline that bound each emit, and the sort of each failed emit.
LinkLost
An emit that counts as the end of the link it ran on.
Local
The in-process backplane: one counter per topic, direct delivery to every attached registry. The default.
NodeSink
One attached node, as a backplane holds it: a weak handle that reaches one registry while the registry lives.
OpaqueFrame
One frame of the pub/sub profile: an Opaque body of payload under the message id id and the order stamp order.
PubsubCommands
Answers sub/ and unsub/ command frames against one registry, consulting a SubscribePolicy before any registration. With a PublishPolicy installed (with_publish), also answers pub/ command frames.
RegistryOptions
Registry construction knobs.
RegistryView
A borrowed view of a TopicRegistry, for the reads a policy weighs.
Topic
A validated topic name: non-empty UTF-8 of at most Topic::MAX_LEN octets that starts outside every command prefix, matched exactly.
TopicRegistry
Topic fan-out over multiplexed tightbeam connections.
Unrouted
The command-only application: every stream no command claims answers Unimplemented.

Enums§

AccessVerdict
Whether a connection may perform the guarded action on a topic.
BackplaneFault
Why the distribution fabric of a multi-node backplane failed a publish.
DeliverError
Why a node refused one sequenced update.
DeliveryVerdict
What to do when a subscriber’s bounded update queue is full.
PublishError
Why a publish produced no fan-out.
Settled
What a settled emit of one frame came to, while the link stays up.
TopicError
Why a topic name failed validation.

Constants§

END_PREFIX
The prefix the registry completes a topic with: end/<topic>.
PUB_PREFIX
The prefix a client publishes with: pub/<topic>.
SUB_PREFIX
The prefix a client subscribes with: sub/<topic>.
UNSUB_PREFIX
The prefix a client unsubscribes with: unsub/<topic>.

Traits§

AppRoutes
The application handler for the unary streams that no command claims.
Backplane
Per-topic sequencing and distribution behind the registry.
DeliveryPolicy
Decides the fate of an update that finds the queue of its subscriber, or the byte budget of its connection, full.
PublishPolicy
Owns the PermissionDenied decision for pub/ commands.
SubscribePolicy
Owns the PermissionDenied decision for sub/ commands.