Design

Where ruststream-gcp-pubsub sits: between the RustStream runtime and the google-cloud-pubsub clients, a streaming pull per subscription, a publisher per topic.

The diagram as text

1. Your service: #[subscriber] handlers; RustStream::new(..) .with_broker(..)
2. RustStream core: Runtime: dispatch, workers, settlement
3. ruststream-gcp-pubsub: PubSubSubscriber a pump task per subscription; PubSubPublisher a client publisher per topic; PubSubMessage holds the lease; PubSubBroker configuration; GooglePubSub the subscription; In-process transport under testing
4. google-cloud-pubsub: Subscriber streaming pull; Publisher, TopicAdmin, ...
5. #[subscriber] handlers → Runtime: dispatch, workers, settlement: mounted
6. Runtime: dispatch, workers, settlement → PubSubSubscriber a pump task per subscription: polls the stream
7. PubSubSubscriber a pump task per subscription → Subscriber streaming pull
8. PubSubPublisher a client publisher per topic → Publisher, TopicAdmin, ...
9. Subscriber streaming pull → Pub/Sub, or the emulator
10. Publisher, TopicAdmin, ... → Pub/Sub, or the emulator

The crate implements the core's broker traits over Google's google-cloud-pubsub client. The runtime above it is the same for every broker. Everything Pub/Sub-specific is in this crate: the subscription descriptor, what each handler outcome does to a lease, and how a publish carries its ordering key.

Connect builds four clients and shares them for the life of the connection: a Subscriber, a BasePublisher, a TopicAdmin and a SubscriptionAdmin. The admins create the topology a descriptor declares and write the dead-letter policy a registration declares. emulator points every client at a local emulator with anonymous credentials. Otherwise they use endpoint and credentials where given, and Application Default Credentials where not.

Each subscription runs a pump task. It reads the client's stream and forwards each delivery into a channel of 16, which the runtime polls. Batches are assembled on that channel. The client's lease travels inside each PubSubMessage, so a settlement goes straight to the client.

The publishers of a connection share one client publisher per topic, created on its first publish. The client batches what they send.

Under the testing feature, TestApp connects the same broker to an in-process transport instead of the clients. It models topics and subscriptions, competing subscribers, acknowledgement and redelivery, attempt counting and dead-lettering. A build without the feature carries none of it.

How the pieces start and stop is on Lifecycle, and the way of one message on Path.