# streamnative/pulsar-rs architecture

> Architecture diagram of the GitHub repository streamnative/pulsar-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/streamnative/pulsar-rs
- Repository: https://github.com/streamnative/pulsar-rs

## Overview

pulsar-rs is an asynchronous Rust client for Apache Pulsar. Its principal workflow is to build a client, establish and maintain broker connections, then publish messages or subscribe, receive, and acknowledge them; the library also exposes readers and administrative operations. The graph preserves documented connection, authentication, TLS, retry, batching, compression, multi-topic, and executor capabilities. Some implementation links are based on SOURCE INDEX references or README descriptions rather than complete excerpts, so uncertain links are omitted or marked unverified.

Main entry points: [`src/client.rs`](https://github.com/streamnative/pulsar-rs/blob/master/src/client.rs) (Pulsar Client), [`src/producer.rs`](https://github.com/streamnative/pulsar-rs/blob/master/src/producer.rs) (Producer), [`src/connection_manager.rs`](https://github.com/streamnative/pulsar-rs/blob/master/src/connection_manager.rs) (Connection Manager), [`src/consumer/mod.rs`](https://github.com/streamnative/pulsar-rs/blob/master/src/consumer/mod.rs) (Consumer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client API"]
  node_client["Pulsar Client<br/>[client.rs]"]
  node_admin["Admin API<br/>[admin.rs]"]
end

subgraph group_messaging["Messaging"]
  node_producer["Producer<br/>[producer.rs]"]
  node_consumer["Consumer<br/>[mod.rs]"]
  node_consumer_builder["Consumer Builder<br/>[builder.rs]"]
  node_consumer_engine["Consumer Engine<br/>[engine.rs]"]
  node_multi_consumer["Multi-topic Consumer<br/>[multi.rs]"]
  node_reader["Reader<br/>[reader.rs]"]
  node_message["Message Framing<br/>[message.rs]"]
end

subgraph group_transport["Transport"]
  node_connection_manager["Connection Manager"]
  node_connection["Broker Connection<br/>[connection.rs]"]
  node_discovery["Service Discovery"]
end

subgraph group_support["Runtime Support"]
  node_authentication["Authentication<br/>[authentication.rs]"]
  node_oauth["OAuth2 Auth<br/>[oauth2.rs]"]
  node_routing["Partition Routing<br/>[routing_policy.rs]"]
  node_compression["Compression<br/>[compression.rs]"]
  node_executor["Async Executor<br/>[executor.rs]"]
  node_retry["Retry Operations<br/>[retry_op.rs]"]
end

node_application(("Application"))
node_broker[("Pulsar Broker")]

node_application -->|"builds"| node_client
node_client -->|"creates builder"| node_consumer_builder
node_consumer_builder -.->|"builds"| node_consumer
node_client -->|"exposes"| node_admin
node_application -->|"publishes with"| node_producer
node_producer -->|"routes partitions"| node_routing
node_producer -->|"encodes messages"| node_message
node_application -->|"subscribes with"| node_consumer
node_consumer -.->|"receives through"| node_consumer_engine
node_consumer -->|"supports multi-topic"| node_multi_consumer
node_consumer_engine -->|"decodes messages"| node_message
node_application -->|"reads with"| node_reader
node_connection_manager -->|"creates and manages"| node_connection
node_connection -.->|"exchanges protocol data"| node_broker
node_connection_manager -->|"initializes auth"| node_authentication
node_oauth -->|"implements"| node_authentication
node_client -.->|"uses connections"| node_connection_manager
node_client -.->|"resolves broker"| node_discovery
node_connection_manager -->|"runs async tasks"| node_executor
node_client -->|"configures retries"| node_retry
node_producer -.->|"compresses payloads"| node_compression

click node_client "https://github.com/streamnative/pulsar-rs/blob/master/src/client.rs"
click node_admin "https://github.com/streamnative/pulsar-rs/blob/master/src/admin.rs"
click node_producer "https://github.com/streamnative/pulsar-rs/blob/master/src/producer.rs"
click node_consumer "https://github.com/streamnative/pulsar-rs/blob/master/src/consumer/mod.rs"
click node_consumer_builder "https://github.com/streamnative/pulsar-rs/blob/master/src/consumer/builder.rs"
click node_consumer_engine "https://github.com/streamnative/pulsar-rs/blob/master/src/consumer/engine.rs"
click node_multi_consumer "https://github.com/streamnative/pulsar-rs/blob/master/src/consumer/multi.rs"
click node_reader "https://github.com/streamnative/pulsar-rs/blob/master/src/reader.rs"
click node_message "https://github.com/streamnative/pulsar-rs/blob/master/src/message.rs"
click node_connection_manager "https://github.com/streamnative/pulsar-rs/blob/master/src/connection_manager.rs"
click node_connection "https://github.com/streamnative/pulsar-rs/blob/master/src/connection.rs"
click node_discovery "https://github.com/streamnative/pulsar-rs/blob/master/src/service_discovery.rs"
click node_authentication "https://github.com/streamnative/pulsar-rs/blob/master/src/authentication.rs"
click node_oauth "https://github.com/streamnative/pulsar-rs/blob/master/src/authentication/oauth2.rs"
click node_routing "https://github.com/streamnative/pulsar-rs/blob/master/src/routing_policy.rs"
click node_compression "https://github.com/streamnative/pulsar-rs/blob/master/src/compression.rs"
click node_executor "https://github.com/streamnative/pulsar-rs/blob/master/src/executor.rs"
click node_retry "https://github.com/streamnative/pulsar-rs/blob/master/src/retry_op.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_admin toneBlue
class node_producer,node_consumer,node_consumer_builder,node_consumer_engine,node_multi_consumer,node_reader,node_message,node_broker toneAmber
class node_connection_manager,node_connection,node_discovery toneMint
class node_authentication,node_oauth,node_routing,node_compression,node_executor,node_retry toneRose
class node_application toneIndigo
```

## Components

### Client API

- [Pulsar Client](https://github.com/streamnative/pulsar-rs/blob/master/src/client.rs): `src/client.rs`
- [Admin API](https://github.com/streamnative/pulsar-rs/blob/master/src/admin.rs): `src/admin.rs`

### Messaging

- [Producer](https://github.com/streamnative/pulsar-rs/blob/master/src/producer.rs): `src/producer.rs`
- [Consumer](https://github.com/streamnative/pulsar-rs/blob/master/src/consumer/mod.rs): `src/consumer/mod.rs`
- [Consumer Builder](https://github.com/streamnative/pulsar-rs/blob/master/src/consumer/builder.rs): `src/consumer/builder.rs`
- [Consumer Engine](https://github.com/streamnative/pulsar-rs/blob/master/src/consumer/engine.rs): `src/consumer/engine.rs`
- [Multi-topic Consumer](https://github.com/streamnative/pulsar-rs/blob/master/src/consumer/multi.rs): `src/consumer/multi.rs`
- [Reader](https://github.com/streamnative/pulsar-rs/blob/master/src/reader.rs): `src/reader.rs`
- [Message Framing](https://github.com/streamnative/pulsar-rs/blob/master/src/message.rs): `src/message.rs`

### Transport

- [Connection Manager](https://github.com/streamnative/pulsar-rs/blob/master/src/connection_manager.rs): `src/connection_manager.rs`
- [Broker Connection](https://github.com/streamnative/pulsar-rs/blob/master/src/connection.rs): `src/connection.rs`
- [Service Discovery](https://github.com/streamnative/pulsar-rs/blob/master/src/service_discovery.rs): `src/service_discovery.rs`

### Runtime Support

- [Authentication](https://github.com/streamnative/pulsar-rs/blob/master/src/authentication.rs): `src/authentication.rs`
- [OAuth2 Auth](https://github.com/streamnative/pulsar-rs/blob/master/src/authentication/oauth2.rs): `src/authentication/oauth2.rs`
- [Partition Routing](https://github.com/streamnative/pulsar-rs/blob/master/src/routing_policy.rs): `src/routing_policy.rs`
- [Compression](https://github.com/streamnative/pulsar-rs/blob/master/src/compression.rs): `src/compression.rs`
- [Async Executor](https://github.com/streamnative/pulsar-rs/blob/master/src/executor.rs): `src/executor.rs`
- [Retry Operations](https://github.com/streamnative/pulsar-rs/blob/master/src/retry_op.rs): `src/retry_op.rs`

### Other components

- **Application**
- **Pulsar Broker**

## Connections

- Application → Pulsar Client: builds (evidence: `README.md`)
- Pulsar Client → Consumer Builder: creates builder (evidence: `src/client.rs`)
- Consumer Builder → Consumer: builds (evidence: `src/consumer/mod.rs`)
- Pulsar Client → Admin API: exposes (evidence: `src/client.rs`)
- Application → Producer: publishes with (evidence: `README.md`)
- Producer → Partition Routing: routes partitions (evidence: `src/producer.rs`)
- Producer → Message Framing: encodes messages (evidence: `src/producer.rs`)
- Application → Consumer: subscribes with (evidence: `README.md`)
- Consumer → Consumer Engine: receives through (evidence: `src/consumer/mod.rs`)
- Consumer → Multi-topic Consumer: supports multi-topic (evidence: `README.md`)
- Consumer Engine → Message Framing: decodes messages (evidence: `src/consumer/engine.rs`)
- Application → Reader: reads with (evidence: `README.md`)
- Connection Manager → Broker Connection: creates and manages (evidence: `src/connection_manager.rs`)
- Broker Connection → Pulsar Broker: exchanges protocol data
- Connection Manager → Authentication: initializes auth (evidence: `src/connection_manager.rs`)
- OAuth2 Auth → Authentication: implements (evidence: `src/authentication.rs`)
- Pulsar Client → Connection Manager: uses connections
- Pulsar Client → Service Discovery: resolves broker
- Connection Manager → Async Executor: runs async tasks (evidence: `src/connection_manager.rs`)
- Pulsar Client → Retry Operations: configures retries (evidence: `src/client.rs`)
- Producer → Compression: compresses payloads