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//! **WARNING:** this crate is under active development. We expect multiple
18//! breaking changes in the upcoming releases. Testing is also incomplete, we do
19//! **not** recommend that you use this crate in production. We welcome feedback
20//! about the APIs, documentation, missing features, bugs, etc.
21//!
22//! This crate contains traits, types, and functions to interact with
23//! [Pub/Sub]. Most applications will use the structs defined in the
24//! [client] module.
25//!
26//! For administrative operations:
27//! * [TopicAdmin][client::TopicAdmin]
28//! * [SubscriptionAdmin][client::SubscriptionAdmin]
29//! * [SchemaService][client::SchemaService]
30//!
31//! For publishing messages:
32//! * [Client][client::Client] and [Publisher][client::Publisher]
33//!
34//! For receiving messages:
35//! * [Subscriber][client::Subscriber]
36//!
37//! Receiving messages is not yet supported by this crate.
38//!
39//! **NOTE:** This crate used to contain a different implementation, with a
40//! different surface. [@yoshidan](https://github.com/yoshidan) generously
41//! donated the crate name to Google. Their crate continues to live as
42//! [gcloud-pubsub].
43//!
44//! [pub/sub]: https://cloud.google.com/pubsub
45//! [gcloud-pubsub]: https://crates.io/crates/gcloud-pubsub
46
47#[allow(rustdoc::broken_intra_doc_links)]
48pub(crate) mod generated;
49
50pub(crate) mod publisher;
51/// Types related to receiving messages with a [Subscriber][client::Subscriber]
52/// client.
53pub mod subscriber;
54
55pub use gax::Result;
56pub use gax::error::Error;
57
58/// Request and client builders.
59pub mod builder {
60    /// Request and client builders for the [Publisher][crate::client::Publisher] client.
61    pub mod publisher {
62        // TODO(#3959) - remove internal types from the public API.
63        #[doc(hidden)]
64        pub use crate::generated::gapic_dataplane::builder::publisher::*;
65        pub use crate::publisher::client::ClientBuilder;
66        pub use crate::publisher::publisher::PublisherBuilder;
67    }
68    /// Request and client builders for the [SchemaService][crate::client::SchemaService] client.
69    pub use crate::generated::gapic::builder::schema_service;
70    /// Request and client builders for the [Subscriber][crate::client::Subscriber] client.
71    pub mod subscriber {
72        // TODO(#3959) - remove internal types from the public API.
73        #[doc(hidden)]
74        pub use crate::generated::gapic_dataplane::builder::subscriber::*;
75        pub use crate::subscriber::builder::StreamingPull;
76        pub use crate::subscriber::client_builder::ClientBuilder;
77    }
78    /// Request and client builders for the [SubscriptionAdmin][crate::client::SubscriptionAdmin] client.
79    pub use crate::generated::gapic::builder::subscription_admin;
80    /// Request and client builders for the [TopicAdmin][crate::client::TopicAdmin] client.
81    pub use crate::generated::gapic::builder::topic_admin;
82}
83
84/// The messages and enums that are part of this client library.
85pub mod model {
86    pub use crate::generated::gapic::model::*;
87    pub use crate::generated::gapic_dataplane::model::PubsubMessage;
88    pub(crate) use crate::generated::gapic_dataplane::model::*;
89}
90
91/// Extends [model] with types that improve type safety and/or ergonomics.
92pub mod model_ext {
93    pub use crate::publisher::model_ext::*;
94}
95
96/// Clients to interact with Google Cloud Pub/Sub.
97///
98/// This module contains the primary entry points for the library, including
99/// clients for publishing messages and managing topics and subscriptions.
100///
101/// # Example: Publishing Messages
102///
103/// ```
104/// # async fn sample() -> anyhow::Result<()> {
105/// use google_cloud_pubsub::client::Client;
106/// use google_cloud_pubsub::model::PubsubMessage;
107///
108/// // Create a client for creating publishers.
109/// let client = Client::builder().build().await?;
110///
111/// // Create a publisher that handles batching for a specific topic.
112/// let publisher = client.publisher("projects/my-project/topics/my-topic").build();
113///
114/// // Publish several messages.
115/// // The client will automatically batch them in the background.
116/// let mut handles = Vec::new();
117/// for i in 0..10 {
118///     let msg = PubsubMessage::new().set_data(format!("message {}", i));
119///     handles.push(publisher.publish(msg));
120/// }
121///
122/// // The handles are futures that resolve to the server-assigned message IDs.
123/// // You can await them to get the results. Messages will still be sent even
124/// // if the handles are dropped.
125/// for (i, handle) in handles.into_iter().enumerate() {
126///     let message_id = handle.await?;
127///     println!("Message {} sent with ID: {}", i, message_id);
128/// }
129/// # Ok(())
130/// # }
131/// ```
132pub mod client {
133    pub use crate::generated::gapic::client::*;
134    pub use crate::publisher::client::Client;
135    pub use crate::publisher::publisher::Publisher;
136    pub use crate::subscriber::client::Subscriber;
137}
138
139/// Traits to mock the clients in this library.
140pub mod stub {
141    pub use crate::generated::gapic::stub::*;
142}
143
144const DEFAULT_HOST: &str = "https://pubsub.googleapis.com";
145
146mod info {
147    const NAME: &str = env!("CARGO_PKG_NAME");
148    const VERSION: &str = env!("CARGO_PKG_VERSION");
149    lazy_static::lazy_static! {
150        pub(crate) static ref X_GOOG_API_CLIENT_HEADER: String = {
151            let ac = gaxi::api_header::XGoogApiClient{
152                name:          NAME,
153                version:       VERSION,
154                library_type:  gaxi::api_header::GAPIC,
155            };
156            ac.grpc_header_value()
157        };
158    }
159}
160
161#[allow(dead_code)]
162pub(crate) mod google {
163    pub mod pubsub {
164        #[allow(clippy::enum_variant_names)]
165        pub mod v1 {
166            include!("generated/protos/pubsub/google.pubsub.v1.rs");
167            include!("generated/convert/pubsub/convert.rs");
168        }
169    }
170}
google_cloud_pubsub/lib.rs

google_cloud_pubsub/
lib.rs
