google_cloud_pubsub/
lib.rs

1// Copyright 2025 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Google Cloud Client Libraries for Rust - Pub/Sub
16//!
17//! This crate contains traits, types, and functions to interact with
18//! [Pub/Sub]. Most applications will use the structs defined in the
19//! [client] module.
20//!
21//! For publishing messages:
22//! * [Publisher][client::Publisher]
23//!
24//! For receiving messages:
25//! * [Subscriber][client::Subscriber]
26//!
27//! For administrative operations:
28//! * [TopicAdmin][client::TopicAdmin]
29//! * [SubscriptionAdmin][client::SubscriptionAdmin]
30//! * [SchemaService][client::SchemaService]
31//!
32//! **NOTE:** This crate used to contain a different implementation, with a
33//! different surface. [@yoshidan](https://github.com/yoshidan) generously
34//! donated the crate name to Google. Their crate continues to live as
35//! [gcloud-pubsub].
36//!
37//! # Features
38//!
39//! - `default-rustls-provider`: enabled by default. Use the default rustls crypto
40//!   provider ([aws-lc-rs]) for TLS and authentication. Applications with specific
41//!   requirements for cryptography (such as exclusively using the [ring] crate)
42//!   should disable this default and call
43//!   `rustls::crypto::CryptoProvider::install_default()`.
44//! - `unstable-stream`: enable the (unstable) features to convert several types to
45//!   a `future::Stream`.
46//!
47//! [aws-lc-rs]: https://crates.io/crates/aws-lc-rs
48//! [pub/sub]: https://cloud.google.com/pubsub
49//! [gcloud-pubsub]: https://crates.io/crates/gcloud-pubsub
50//! [ring]: https://crates.io/crates/ring
51
52#![cfg_attr(docsrs, feature(doc_cfg))]
53#![warn(missing_docs)]
54
55#[allow(rustdoc::broken_intra_doc_links)]
56pub(crate) mod generated;
57
58/// Types related to publishing messages with a [Publisher][client::Publisher]
59/// client.
60pub mod publisher;
61/// Types related to receiving messages with a [Subscriber][client::Subscriber]
62/// client.
63pub mod subscriber;
64
65pub use google_cloud_gax::Result;
66pub use google_cloud_gax::error::Error;
67// Define some shortcuts for imported crates.
68pub(crate) use google_cloud_gax::client_builder::ClientBuilder;
69pub(crate) use google_cloud_gax::client_builder::Result as ClientBuilderResult;
70pub(crate) use google_cloud_gax::client_builder::internal::ClientFactory;
71pub(crate) use google_cloud_gax::client_builder::internal::new_builder as new_client_builder;
72pub(crate) use google_cloud_gax::options::RequestOptions;
73pub(crate) use google_cloud_gax::options::internal::RequestBuilder;
74pub(crate) use google_cloud_gax::response::Response;
75
76/// Request and client builders.
77pub mod builder {
78    /// Request and client builders for the [Publisher][crate::client::Publisher] client.
79    pub mod publisher {
80        pub use crate::publisher::builder::BasePublisherBuilder;
81        pub use crate::publisher::builder::PublisherBuilder;
82        pub use crate::publisher::builder::PublisherPartialBuilder;
83    }
84    pub use crate::generated::gapic::builder::schema_service;
85    /// Request and client builders for the [Subscriber][crate::client::Subscriber] client.
86    pub mod subscriber {
87        pub use crate::subscriber::builder::ClientBuilder;
88        pub use crate::subscriber::builder::Subscribe;
89    }
90    pub use crate::generated::gapic::builder::subscription_admin;
91    pub use crate::generated::gapic::builder::topic_admin;
92}
93
94/// The messages and enums that are part of this client library.
95pub mod model {
96    pub use crate::generated::gapic::model::*;
97    pub use crate::generated::gapic_dataplane::model::PubsubMessage as Message;
98    pub(crate) use crate::generated::gapic_dataplane::model::*;
99}
100
101/// Clients to interact with Cloud Pub/Sub.
102///
103/// This module contains the primary entry points for the library, including
104/// clients for publishing and receiving messages, as well as managing topics,
105/// subscriptions, and schemas.
106///
107/// # Example: Publishing Messages
108///
109/// ```
110/// # async fn sample() -> anyhow::Result<()> {
111/// use google_cloud_pubsub::client::Publisher;
112/// use google_cloud_pubsub::model::Message;
113///
114/// // Create a publisher that handles batching for a specific topic.
115/// let publisher = Publisher::builder("projects/my-project/topics/my-topic").build().await?;
116///
117/// // Publish several messages.
118/// // The client will automatically batch them in the background.
119/// let mut futures = Vec::new();
120/// for i in 0..10 {
121///     let msg = Message::new().set_data(format!("message {}", i));
122///     futures.push(publisher.publish(msg));
123/// }
124///
125/// // The futures resolve to the server-assigned message IDs.
126/// // You can await them to get the results. Messages will still be sent even
127/// // if the futures are dropped.
128/// for (i, future) in futures.into_iter().enumerate() {
129///     let message_id = future.await?;
130///     println!("Message {} sent with ID: {}", i, message_id);
131/// }
132/// # Ok(())
133/// # }
134/// ```
135///
136/// # Example: Receiving Messages
137///
138/// ```
139/// # async fn sample() -> anyhow::Result<()> {
140/// use google_cloud_pubsub::client::Subscriber;
141///
142/// // Create a subscriber client.
143/// let client = Subscriber::builder().build().await?;
144///
145/// // Start a message stream from a subscription.
146/// let mut stream = client
147///     .subscribe("projects/my-project/subscriptions/my-subscription")
148///     .build();
149///
150/// // Receive messages from the stream.
151/// while let Some((m, h)) = stream.next().await.transpose()? {
152///     println!("Received message m={m:?}");
153///
154///     // Acknowledge the message.
155///     h.ack();
156/// }
157/// # Ok(()) }
158/// ```
159pub mod client {
160    pub use crate::generated::gapic::client::*;
161    pub use crate::publisher::client::BasePublisher;
162    pub use crate::publisher::client::Publisher;
163    pub use crate::subscriber::client::Subscriber;
164}
165
166pub mod error;
167pub mod retry_policy;
168
169/// Traits to mock the clients in this library.
170pub mod stub {
171    pub use crate::generated::gapic::stub::*;
172}
173
174const DEFAULT_HOST: &str = "https://pubsub.googleapis.com";
175
176mod info {
177    use std::sync::LazyLock;
178
179    const NAME: &str = env!("CARGO_PKG_NAME");
180    const VERSION: &str = env!("CARGO_PKG_VERSION");
181    pub(crate) static X_GOOG_API_CLIENT_HEADER: LazyLock<String> = LazyLock::new(|| {
182        let ac = gaxi::api_header::XGoogApiClient {
183            name: NAME,
184            version: VERSION,
185            library_type: gaxi::api_header::GAPIC,
186        };
187        ac.grpc_header_value()
188    });
189}
190
191#[allow(dead_code)]
192pub(crate) mod google {
193    pub mod pubsub {
194        #[allow(clippy::enum_variant_names)]
195        pub mod v1 {
196            include!("generated/protos/pubsub/google.pubsub.v1.rs");
197            include!("generated/convert/pubsub/convert.rs");
198        }
199    }
200}
google_cloud_pubsub/lib.rs

google_cloud_pubsub/
lib.rs
