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.
§Related
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§
- Allow
All - The default policy: every subscription (and, when installed as a
PublishPolicy, every publish) is allowed. - Connection
Context - 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::draindid. - Drop
Oldest - The default policy: always drop the oldest queued update, so the newest state wins and the gate of the client reports the loss.
- Emit
Deadline - 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.
- Link
Lost - 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.
- Node
Sink - One attached node, as a backplane holds it: a weak handle that reaches one registry while the registry lives.
- Opaque
Frame - One frame of the pub/sub profile: an
Opaquebody ofpayloadunder the message ididand the order stamporder. - Pubsub
Commands - Answers
sub/andunsub/command frames against one registry, consulting aSubscribePolicybefore any registration. With aPublishPolicyinstalled (with_publish), also answerspub/command frames. - Registry
Options - Registry construction knobs.
- Registry
View - 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_LENoctets that starts outside every command prefix, matched exactly. - Topic
Registry - Topic fan-out over multiplexed tightbeam connections.
- Unrouted
- The command-only application: every stream no command claims answers
Unimplemented.
Enums§
- Access
Verdict - Whether a connection may perform the guarded action on a topic.
- Backplane
Fault - Why the distribution fabric of a multi-node backplane failed a publish.
- Deliver
Error - Why a node refused one sequenced update.
- Delivery
Verdict - What to do when a subscriber’s bounded update queue is full.
- Publish
Error - Why a publish produced no fan-out.
- Settled
- What a settled emit of one frame came to, while the link stays up.
- Topic
Error - 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.
- Delivery
Policy - Decides the fate of an update that finds the queue of its subscriber, or the byte budget of its connection, full.
- Publish
Policy - Owns the
PermissionDenieddecision forpub/commands. - Subscribe
Policy - Owns the
PermissionDenieddecision forsub/commands.