#
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}