google_cloud_pubsub/subscriber/
client_builder.rs

1// Copyright 2026 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
15use super::client::Subscriber;
16use gax::client_builder::Result as BuilderResult;
17use gaxi::options::ClientConfig;
18
19/// A builder for [Subscriber].
20///
21/// # Example
22/// ```
23/// # use google_cloud_pubsub::client::Subscriber;
24/// # async fn sample() -> anyhow::Result<()> {
25/// let builder = Subscriber::builder();
26/// let client = builder
27///     .with_endpoint("https://pubsub.googleapis.com")
28///     .build()
29///     .await?;
30/// # Ok(()) }
31/// ```
32pub struct ClientBuilder {
33    pub(super) config: ClientConfig,
34}
35
36impl ClientBuilder {
37    pub(super) fn new() -> Self {
38        Self {
39            config: ClientConfig::default(),
40        }
41    }
42
43    /// Creates a new client.
44    ///
45    /// # Example
46    /// ```
47    /// # use google_cloud_pubsub::client::Subscriber;
48    /// # async fn sample() -> anyhow::Result<()> {
49    /// let client = Subscriber::builder().build().await?;
50    /// # Ok(()) }
51    /// ```
52    pub async fn build(self) -> BuilderResult<Subscriber> {
53        Subscriber::new(self).await
54    }
55
56    /// Sets the endpoint.
57    ///
58    /// # Example
59    /// ```
60    /// # use google_cloud_pubsub::client::Subscriber;
61    /// # async fn sample() -> anyhow::Result<()> {
62    /// let client = Subscriber::builder()
63    ///     .with_endpoint("https://private.googleapis.com")
64    ///     .build()
65    ///     .await?;
66    /// # Ok(()) }
67    /// ```
68    pub fn with_endpoint<V: Into<String>>(mut self, v: V) -> Self {
69        self.config.endpoint = Some(v.into());
70        self
71    }
72
73    /// Configures the authentication credentials.
74    ///
75    /// More information about valid credentials types can be found in the
76    /// [google-cloud-auth] crate documentation.
77    ///
78    /// # Example
79    /// ```
80    /// # use google_cloud_pubsub::client::Subscriber;
81    /// # async fn sample() -> anyhow::Result<()> {
82    /// use auth::credentials::mds;
83    /// let client = Subscriber::builder()
84    ///     .with_credentials(
85    ///         mds::Builder::default()
86    ///             .with_scopes(["https://www.googleapis.com/auth/cloud-platform.read-only"])
87    ///             .build()?)
88    ///     .build()
89    ///     .await?;
90    /// # Ok(()) }
91    /// ```
92    ///
93    /// [google-cloud-auth]: https://docs.rs/google-cloud-auth
94    pub fn with_credentials<V: Into<auth::credentials::Credentials>>(mut self, v: V) -> Self {
95        self.config.cred = Some(v.into());
96        self
97    }
98
99    /// Configure the number of subchannels used by the client.
100    ///
101    /// # Example
102    /// ```
103    /// # use google_cloud_pubsub::client::Subscriber;
104    /// # async fn sample() -> anyhow::Result<()> {
105    /// let count = std::thread::available_parallelism()?.get();
106    /// let client = Subscriber::builder()
107    ///     .with_grpc_subchannel_count(std::cmp::max(1, count))
108    ///     .build()
109    ///     .await?;
110    /// # Ok(()) }
111    /// ```
112    ///
113    /// gRPC-based clients may exhibit high latency if many requests need to be
114    /// demuxed over a single HTTP/2 connection (often called a *subchannel* in
115    /// gRPC).
116    ///
117    /// Consider using more subchannels if your application makes many
118    /// concurrent requests. Consider using fewer subchannels if your
119    /// application needs the file descriptors for other purposes.
120    pub fn with_grpc_subchannel_count(mut self, v: usize) -> Self {
121        self.config.grpc_subchannel_count = Some(v);
122        self
123    }
124}
125
126#[cfg(test)]
127mod tests {
128    use super::*;
129    use auth::credentials::anonymous::Builder as Anonymous;
130
131    #[test]
132    fn defaults() {
133        let builder = ClientBuilder::new();
134        assert!(builder.config.endpoint.is_none());
135        assert!(builder.config.cred.is_none());
136        assert!(builder.config.grpc_subchannel_count.is_none());
137    }
138
139    #[test]
140    fn setters() {
141        let builder = ClientBuilder::new()
142            .with_endpoint("test-endpoint.com")
143            .with_credentials(Anonymous::new().build())
144            .with_grpc_subchannel_count(16);
145        assert_eq!(
146            builder.config.endpoint,
147            Some("test-endpoint.com".to_string())
148        );
149        assert!(builder.config.cred.is_some());
150        assert_eq!(builder.config.grpc_subchannel_count, Some(16));
151    }
152}
google_cloud_pubsub/subscriber/client_builder.rs

google_cloud_pubsub/subscriber/
client_builder.rs
