tightbeam-pubsub 0.6.0

Topic pub/sub extension for the tightbeam messaging protocol
Documentation

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.