google_cloud_pubsub/generated/gapic/

client.rs

// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// Code generated by sidekick. DO NOT EDIT.
#![allow(rustdoc::redundant_explicit_links)]
#![allow(rustdoc::broken_intra_doc_links)]

/// Implements a client for the Cloud Pub/Sub API.
///
/// # Example
/// ```
/// # use google_cloud_pubsub::client::TopicAdmin;
/// async fn sample(
///    project_id: &str,
///    topic_id: &str,
/// ) -> anyhow::Result<()> {
///     let client = TopicAdmin::builder().build().await?;
///     let response = client.get_topic()
///         .set_topic(format!("projects/{project_id}/topics/{topic_id}"))
///         .send().await?;
///     println!("response {:?}", response);
///     Ok(())
/// }
/// ```
///
/// # Service Description
///
/// The service that an application uses to manipulate topics.
///
/// # Configuration
///
/// To configure `TopicAdmin` use the `with_*` methods in the type returned
/// by [builder()][TopicAdmin::builder]. The default configuration should
/// work for most applications. Common configuration changes include
///
/// * [with_endpoint()]: by default this client uses the global default endpoint
///   (`https://pubsub.googleapis.com`). Applications using regional
///   endpoints or running in restricted networks (e.g. a network configured
///   with [Private Google Access with VPC Service Controls]) may want to
///   override this default.
/// * [with_credentials()]: by default this client uses
///   [Application Default Credentials]. Applications using custom
///   authentication may need to override this default.
///
/// [with_endpoint()]: super::builder::topic_admin::ClientBuilder::with_endpoint
/// [with_credentials()]: super::builder::topic_admin::ClientBuilder::with_credentials
/// [Private Google Access with VPC Service Controls]: https://cloud.google.com/vpc-service-controls/docs/private-connectivity
/// [Application Default Credentials]: https://cloud.google.com/docs/authentication#adc
///
/// # Pooling and Cloning
///
/// `TopicAdmin` holds a connection pool internally, it is advised to
/// create one and reuse it. You do not need to wrap `TopicAdmin` in
/// an [Rc](std::rc::Rc) or [Arc](std::sync::Arc) to reuse it, because it
/// already uses an `Arc` internally.
#[derive(Clone, Debug)]
pub struct TopicAdmin {
    inner: std::sync::Arc<dyn super::stub::dynamic::TopicAdmin>,
}

impl TopicAdmin {
    /// Returns a builder for [TopicAdmin].
    ///
    /// ```
    /// # async fn sample() -> google_cloud_gax::client_builder::Result<()> {
    /// # use google_cloud_pubsub::client::TopicAdmin;
    /// let client = TopicAdmin::builder().build().await?;
    /// # Ok(()) }
    /// ```
    pub fn builder() -> super::builder::topic_admin::ClientBuilder {
        crate::new_client_builder(super::builder::topic_admin::client::Factory)
    }

    /// Creates a new client from the provided stub.
    ///
    /// The most common case for calling this function is in tests mocking the
    /// client's behavior.
    pub fn from_stub<T>(stub: impl Into<std::sync::Arc<T>>) -> Self
    where
        T: super::stub::TopicAdmin + 'static,
    {
        Self { inner: stub.into() }
    }

    pub(crate) async fn new(
        config: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<Self> {
        let inner = Self::build_inner(config).await?;
        Ok(Self { inner })
    }

    async fn build_inner(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<std::sync::Arc<dyn super::stub::dynamic::TopicAdmin>> {
        if gaxi::options::tracing_enabled(&conf) {
            return Ok(std::sync::Arc::new(Self::build_with_tracing(conf).await?));
        }
        Ok(std::sync::Arc::new(Self::build_transport(conf).await?))
    }

    async fn build_transport(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<impl super::stub::TopicAdmin> {
        super::transport::TopicAdmin::new(conf).await
    }

    async fn build_with_tracing(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<impl super::stub::TopicAdmin> {
        Self::build_transport(conf)
            .await
            .map(super::tracing::TopicAdmin::new)
    }

    /// Creates the given topic with the given name. See the [resource name rules]
    /// (<https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names>).
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::TopicAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &TopicAdmin
    /// ) -> Result<()> {
    ///     let response = client.create_topic()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn create_topic(&self) -> super::builder::topic_admin::CreateTopic {
        super::builder::topic_admin::CreateTopic::new(self.inner.clone())
    }

    /// Updates an existing topic by updating the fields specified in the update
    /// mask. Note that certain properties of a topic are not modifiable.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::TopicAdmin;
    /// # extern crate wkt as google_cloud_wkt;
    /// use google_cloud_wkt::FieldMask;
    /// use google_cloud_pubsub::model::Topic;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &TopicAdmin, project_id: &str, topic_id: &str
    /// ) -> Result<()> {
    ///     let response = client.update_topic()
    ///         .set_topic(
    ///             Topic::new().set_name(format!("projects/{project_id}/topics/{topic_id}"))/* set fields */
    ///         )
    ///         .set_update_mask(FieldMask::default().set_paths(["updated.field.path1", "updated.field.path2"]))
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn update_topic(&self) -> super::builder::topic_admin::UpdateTopic {
        super::builder::topic_admin::UpdateTopic::new(self.inner.clone())
    }

    /// Gets the configuration of a topic.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::TopicAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &TopicAdmin, project_id: &str, topic_id: &str
    /// ) -> Result<()> {
    ///     let response = client.get_topic()
    ///         .set_topic(format!("projects/{project_id}/topics/{topic_id}"))
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn get_topic(&self) -> super::builder::topic_admin::GetTopic {
        super::builder::topic_admin::GetTopic::new(self.inner.clone())
    }

    /// Lists matching topics.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::TopicAdmin;
    /// use google_cloud_gax::paginator::ItemPaginator as _;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &TopicAdmin
    /// ) -> Result<()> {
    ///     let mut list = client.list_topics()
    ///         /* set fields */
    ///         .by_item();
    ///     while let Some(item) = list.next().await.transpose()? {
    ///         println!("{:?}", item);
    ///     }
    ///     Ok(())
    /// }
    /// ```
    pub fn list_topics(&self) -> super::builder::topic_admin::ListTopics {
        super::builder::topic_admin::ListTopics::new(self.inner.clone())
    }

    /// Lists the names of the attached subscriptions on this topic.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::TopicAdmin;
    /// use google_cloud_gax::paginator::ItemPaginator as _;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &TopicAdmin
    /// ) -> Result<()> {
    ///     let mut list = client.list_topic_subscriptions()
    ///         /* set fields */
    ///         .by_item();
    ///     while let Some(item) = list.next().await.transpose()? {
    ///         println!("{:?}", item);
    ///     }
    ///     Ok(())
    /// }
    /// ```
    pub fn list_topic_subscriptions(&self) -> super::builder::topic_admin::ListTopicSubscriptions {
        super::builder::topic_admin::ListTopicSubscriptions::new(self.inner.clone())
    }

    /// Lists the names of the snapshots on this topic. Snapshots are used in
    /// [Seek](https://cloud.google.com/pubsub/docs/replay-overview) operations,
    /// which allow you to manage message acknowledgments in bulk. That is, you can
    /// set the acknowledgment state of messages in an existing subscription to the
    /// state captured by a snapshot.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::TopicAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &TopicAdmin
    /// ) -> Result<()> {
    ///     let response = client.list_topic_snapshots()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn list_topic_snapshots(&self) -> super::builder::topic_admin::ListTopicSnapshots {
        super::builder::topic_admin::ListTopicSnapshots::new(self.inner.clone())
    }

    /// Deletes the topic with the given name. Returns `NOT_FOUND` if the topic
    /// does not exist. After a topic is deleted, a new topic may be created with
    /// the same name; this is an entirely new topic with none of the old
    /// configuration or subscriptions. Existing subscriptions to this topic are
    /// not deleted, but their `topic` field is set to `_deleted-topic_`.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::TopicAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &TopicAdmin, project_id: &str, topic_id: &str
    /// ) -> Result<()> {
    ///     client.delete_topic()
    ///         .set_topic(format!("projects/{project_id}/topics/{topic_id}"))
    ///         .send().await?;
    ///     Ok(())
    /// }
    /// ```
    pub fn delete_topic(&self) -> super::builder::topic_admin::DeleteTopic {
        super::builder::topic_admin::DeleteTopic::new(self.inner.clone())
    }

    /// Detaches a subscription from this topic. All messages retained in the
    /// subscription are dropped. Subsequent `Pull` and `StreamingPull` requests
    /// will return FAILED_PRECONDITION. If the subscription is a push
    /// subscription, pushes to the endpoint will stop.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::TopicAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &TopicAdmin
    /// ) -> Result<()> {
    ///     let response = client.detach_subscription()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn detach_subscription(&self) -> super::builder::topic_admin::DetachSubscription {
        super::builder::topic_admin::DetachSubscription::new(self.inner.clone())
    }
}

/// Implements a client for the Cloud Pub/Sub API.
///
/// # Example
/// ```
/// # use google_cloud_pubsub::client::SubscriptionAdmin;
/// async fn sample(
///    project_id: &str,
///    subscription_id: &str,
/// ) -> anyhow::Result<()> {
///     let client = SubscriptionAdmin::builder().build().await?;
///     let response = client.get_subscription()
///         .set_subscription(format!("projects/{project_id}/subscriptions/{subscription_id}"))
///         .send().await?;
///     println!("response {:?}", response);
///     Ok(())
/// }
/// ```
///
/// # Service Description
///
/// The service that an application uses to manipulate subscriptions.
///
/// # Configuration
///
/// To configure `SubscriptionAdmin` use the `with_*` methods in the type returned
/// by [builder()][SubscriptionAdmin::builder]. The default configuration should
/// work for most applications. Common configuration changes include
///
/// * [with_endpoint()]: by default this client uses the global default endpoint
///   (`https://pubsub.googleapis.com`). Applications using regional
///   endpoints or running in restricted networks (e.g. a network configured
///   with [Private Google Access with VPC Service Controls]) may want to
///   override this default.
/// * [with_credentials()]: by default this client uses
///   [Application Default Credentials]. Applications using custom
///   authentication may need to override this default.
///
/// [with_endpoint()]: super::builder::subscription_admin::ClientBuilder::with_endpoint
/// [with_credentials()]: super::builder::subscription_admin::ClientBuilder::with_credentials
/// [Private Google Access with VPC Service Controls]: https://cloud.google.com/vpc-service-controls/docs/private-connectivity
/// [Application Default Credentials]: https://cloud.google.com/docs/authentication#adc
///
/// # Pooling and Cloning
///
/// `SubscriptionAdmin` holds a connection pool internally, it is advised to
/// create one and reuse it. You do not need to wrap `SubscriptionAdmin` in
/// an [Rc](std::rc::Rc) or [Arc](std::sync::Arc) to reuse it, because it
/// already uses an `Arc` internally.
#[derive(Clone, Debug)]
pub struct SubscriptionAdmin {
    inner: std::sync::Arc<dyn super::stub::dynamic::SubscriptionAdmin>,
}

impl SubscriptionAdmin {
    /// Returns a builder for [SubscriptionAdmin].
    ///
    /// ```
    /// # async fn sample() -> google_cloud_gax::client_builder::Result<()> {
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// let client = SubscriptionAdmin::builder().build().await?;
    /// # Ok(()) }
    /// ```
    pub fn builder() -> super::builder::subscription_admin::ClientBuilder {
        crate::new_client_builder(super::builder::subscription_admin::client::Factory)
    }

    /// Creates a new client from the provided stub.
    ///
    /// The most common case for calling this function is in tests mocking the
    /// client's behavior.
    pub fn from_stub<T>(stub: impl Into<std::sync::Arc<T>>) -> Self
    where
        T: super::stub::SubscriptionAdmin + 'static,
    {
        Self { inner: stub.into() }
    }

    pub(crate) async fn new(
        config: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<Self> {
        let inner = Self::build_inner(config).await?;
        Ok(Self { inner })
    }

    async fn build_inner(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<std::sync::Arc<dyn super::stub::dynamic::SubscriptionAdmin>>
    {
        if gaxi::options::tracing_enabled(&conf) {
            return Ok(std::sync::Arc::new(Self::build_with_tracing(conf).await?));
        }
        Ok(std::sync::Arc::new(Self::build_transport(conf).await?))
    }

    async fn build_transport(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<impl super::stub::SubscriptionAdmin> {
        super::transport::SubscriptionAdmin::new(conf).await
    }

    async fn build_with_tracing(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<impl super::stub::SubscriptionAdmin> {
        Self::build_transport(conf)
            .await
            .map(super::tracing::SubscriptionAdmin::new)
    }

    /// Creates a subscription to a given topic. See the [resource name rules]
    /// (<https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names>).
    /// If the subscription already exists, returns `ALREADY_EXISTS`.
    /// If the corresponding topic doesn't exist, returns `NOT_FOUND`.
    ///
    /// If the name is not provided in the request, the server will assign a random
    /// name for this subscription on the same project as the topic, conforming
    /// to the [resource name format]
    /// (<https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names>). The
    /// generated name is populated in the returned Subscription object. Note that
    /// for REST API requests, you must specify a name in the request.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin
    /// ) -> Result<()> {
    ///     let response = client.create_subscription()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn create_subscription(&self) -> super::builder::subscription_admin::CreateSubscription {
        super::builder::subscription_admin::CreateSubscription::new(self.inner.clone())
    }

    /// Gets the configuration details of a subscription.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin, project_id: &str, subscription_id: &str
    /// ) -> Result<()> {
    ///     let response = client.get_subscription()
    ///         .set_subscription(format!("projects/{project_id}/subscriptions/{subscription_id}"))
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn get_subscription(&self) -> super::builder::subscription_admin::GetSubscription {
        super::builder::subscription_admin::GetSubscription::new(self.inner.clone())
    }

    /// Updates an existing subscription by updating the fields specified in the
    /// update mask. Note that certain properties of a subscription, such as its
    /// topic, are not modifiable.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// # extern crate wkt as google_cloud_wkt;
    /// use google_cloud_wkt::FieldMask;
    /// use google_cloud_pubsub::model::Subscription;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin, project_id: &str, subscription_id: &str
    /// ) -> Result<()> {
    ///     let response = client.update_subscription()
    ///         .set_subscription(
    ///             Subscription::new().set_name(format!("projects/{project_id}/subscriptions/{subscription_id}"))/* set fields */
    ///         )
    ///         .set_update_mask(FieldMask::default().set_paths(["updated.field.path1", "updated.field.path2"]))
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn update_subscription(&self) -> super::builder::subscription_admin::UpdateSubscription {
        super::builder::subscription_admin::UpdateSubscription::new(self.inner.clone())
    }

    /// Lists matching subscriptions.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// use google_cloud_gax::paginator::ItemPaginator as _;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin
    /// ) -> Result<()> {
    ///     let mut list = client.list_subscriptions()
    ///         /* set fields */
    ///         .by_item();
    ///     while let Some(item) = list.next().await.transpose()? {
    ///         println!("{:?}", item);
    ///     }
    ///     Ok(())
    /// }
    /// ```
    pub fn list_subscriptions(&self) -> super::builder::subscription_admin::ListSubscriptions {
        super::builder::subscription_admin::ListSubscriptions::new(self.inner.clone())
    }

    /// Deletes an existing subscription. All messages retained in the subscription
    /// are immediately dropped. Calls to `Pull` after deletion will return
    /// `NOT_FOUND`. After a subscription is deleted, a new one may be created with
    /// the same name, but the new one has no association with the old
    /// subscription or its topic unless the same topic is specified.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin, project_id: &str, subscription_id: &str
    /// ) -> Result<()> {
    ///     client.delete_subscription()
    ///         .set_subscription(format!("projects/{project_id}/subscriptions/{subscription_id}"))
    ///         .send().await?;
    ///     Ok(())
    /// }
    /// ```
    pub fn delete_subscription(&self) -> super::builder::subscription_admin::DeleteSubscription {
        super::builder::subscription_admin::DeleteSubscription::new(self.inner.clone())
    }

    /// Modifies the `PushConfig` for a specified subscription.
    ///
    /// This may be used to change a push subscription to a pull one (signified by
    /// an empty `PushConfig`) or vice versa, or change the endpoint URL and other
    /// attributes of a push subscription. Messages will accumulate for delivery
    /// continuously through the call regardless of changes to the `PushConfig`.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin
    /// ) -> Result<()> {
    ///     client.modify_push_config()
    ///         /* set fields */
    ///         .send().await?;
    ///     Ok(())
    /// }
    /// ```
    pub fn modify_push_config(&self) -> super::builder::subscription_admin::ModifyPushConfig {
        super::builder::subscription_admin::ModifyPushConfig::new(self.inner.clone())
    }

    /// Gets the configuration details of a snapshot. Snapshots are used in
    /// [Seek](https://cloud.google.com/pubsub/docs/replay-overview) operations,
    /// which allow you to manage message acknowledgments in bulk. That is, you can
    /// set the acknowledgment state of messages in an existing subscription to the
    /// state captured by a snapshot.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin, project_id: &str, snapshot_id: &str
    /// ) -> Result<()> {
    ///     let response = client.get_snapshot()
    ///         .set_snapshot(format!("projects/{project_id}/snapshots/{snapshot_id}"))
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn get_snapshot(&self) -> super::builder::subscription_admin::GetSnapshot {
        super::builder::subscription_admin::GetSnapshot::new(self.inner.clone())
    }

    /// Lists the existing snapshots. Snapshots are used in [Seek](
    /// <https://cloud.google.com/pubsub/docs/replay-overview>) operations, which
    /// allow you to manage message acknowledgments in bulk. That is, you can set
    /// the acknowledgment state of messages in an existing subscription to the
    /// state captured by a snapshot.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// use google_cloud_gax::paginator::ItemPaginator as _;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin
    /// ) -> Result<()> {
    ///     let mut list = client.list_snapshots()
    ///         /* set fields */
    ///         .by_item();
    ///     while let Some(item) = list.next().await.transpose()? {
    ///         println!("{:?}", item);
    ///     }
    ///     Ok(())
    /// }
    /// ```
    pub fn list_snapshots(&self) -> super::builder::subscription_admin::ListSnapshots {
        super::builder::subscription_admin::ListSnapshots::new(self.inner.clone())
    }

    /// Creates a snapshot from the requested subscription. Snapshots are used in
    /// [Seek](https://cloud.google.com/pubsub/docs/replay-overview) operations,
    /// which allow you to manage message acknowledgments in bulk. That is, you can
    /// set the acknowledgment state of messages in an existing subscription to the
    /// state captured by a snapshot.
    /// If the snapshot already exists, returns `ALREADY_EXISTS`.
    /// If the requested subscription doesn't exist, returns `NOT_FOUND`.
    /// If the backlog in the subscription is too old -- and the resulting snapshot
    /// would expire in less than 1 hour -- then `FAILED_PRECONDITION` is returned.
    /// See also the `Snapshot.expire_time` field. If the name is not provided in
    /// the request, the server will assign a random
    /// name for this snapshot on the same project as the subscription, conforming
    /// to the [resource name format]
    /// (<https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names>). The
    /// generated name is populated in the returned Snapshot object. Note that for
    /// REST API requests, you must specify a name in the request.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin
    /// ) -> Result<()> {
    ///     let response = client.create_snapshot()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn create_snapshot(&self) -> super::builder::subscription_admin::CreateSnapshot {
        super::builder::subscription_admin::CreateSnapshot::new(self.inner.clone())
    }

    /// Updates an existing snapshot by updating the fields specified in the update
    /// mask. Snapshots are used in
    /// [Seek](https://cloud.google.com/pubsub/docs/replay-overview) operations,
    /// which allow you to manage message acknowledgments in bulk. That is, you can
    /// set the acknowledgment state of messages in an existing subscription to the
    /// state captured by a snapshot.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// # extern crate wkt as google_cloud_wkt;
    /// use google_cloud_wkt::FieldMask;
    /// use google_cloud_pubsub::model::Snapshot;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin, project_id: &str, snapshot_id: &str
    /// ) -> Result<()> {
    ///     let response = client.update_snapshot()
    ///         .set_snapshot(
    ///             Snapshot::new().set_name(format!("projects/{project_id}/snapshots/{snapshot_id}"))/* set fields */
    ///         )
    ///         .set_update_mask(FieldMask::default().set_paths(["updated.field.path1", "updated.field.path2"]))
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn update_snapshot(&self) -> super::builder::subscription_admin::UpdateSnapshot {
        super::builder::subscription_admin::UpdateSnapshot::new(self.inner.clone())
    }

    /// Removes an existing snapshot. Snapshots are used in [Seek]
    /// (<https://cloud.google.com/pubsub/docs/replay-overview>) operations, which
    /// allow you to manage message acknowledgments in bulk. That is, you can set
    /// the acknowledgment state of messages in an existing subscription to the
    /// state captured by a snapshot.
    /// When the snapshot is deleted, all messages retained in the snapshot
    /// are immediately dropped. After a snapshot is deleted, a new one may be
    /// created with the same name, but the new one has no association with the old
    /// snapshot or its subscription, unless the same subscription is specified.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin, project_id: &str, snapshot_id: &str
    /// ) -> Result<()> {
    ///     client.delete_snapshot()
    ///         .set_snapshot(format!("projects/{project_id}/snapshots/{snapshot_id}"))
    ///         .send().await?;
    ///     Ok(())
    /// }
    /// ```
    pub fn delete_snapshot(&self) -> super::builder::subscription_admin::DeleteSnapshot {
        super::builder::subscription_admin::DeleteSnapshot::new(self.inner.clone())
    }

    /// Seeks an existing subscription to a point in time or to a given snapshot,
    /// whichever is provided in the request. Snapshots are used in [Seek]
    /// (<https://cloud.google.com/pubsub/docs/replay-overview>) operations, which
    /// allow you to manage message acknowledgments in bulk. That is, you can set
    /// the acknowledgment state of messages in an existing subscription to the
    /// state captured by a snapshot. Note that both the subscription and the
    /// snapshot must be on the same topic.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SubscriptionAdmin;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SubscriptionAdmin
    /// ) -> Result<()> {
    ///     let response = client.seek()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn seek(&self) -> super::builder::subscription_admin::Seek {
        super::builder::subscription_admin::Seek::new(self.inner.clone())
    }
}

/// Implements a client for the Cloud Pub/Sub API.
///
/// # Example
/// ```
/// # use google_cloud_pubsub::client::SchemaService;
/// use google_cloud_gax::paginator::ItemPaginator as _;
/// async fn sample(
///    parent: &str,
/// ) -> anyhow::Result<()> {
///     let client = SchemaService::builder().build().await?;
///     let mut list = client.list_schemas()
///         .set_parent(parent)
///         .by_item();
///     while let Some(item) = list.next().await.transpose()? {
///         println!("{:?}", item);
///     }
///     Ok(())
/// }
/// ```
///
/// # Service Description
///
/// Service for doing schema-related operations.
///
/// # Configuration
///
/// To configure `SchemaService` use the `with_*` methods in the type returned
/// by [builder()][SchemaService::builder]. The default configuration should
/// work for most applications. Common configuration changes include
///
/// * [with_endpoint()]: by default this client uses the global default endpoint
///   (`https://pubsub.googleapis.com`). Applications using regional
///   endpoints or running in restricted networks (e.g. a network configured
///   with [Private Google Access with VPC Service Controls]) may want to
///   override this default.
/// * [with_credentials()]: by default this client uses
///   [Application Default Credentials]. Applications using custom
///   authentication may need to override this default.
///
/// [with_endpoint()]: super::builder::schema_service::ClientBuilder::with_endpoint
/// [with_credentials()]: super::builder::schema_service::ClientBuilder::with_credentials
/// [Private Google Access with VPC Service Controls]: https://cloud.google.com/vpc-service-controls/docs/private-connectivity
/// [Application Default Credentials]: https://cloud.google.com/docs/authentication#adc
///
/// # Pooling and Cloning
///
/// `SchemaService` holds a connection pool internally, it is advised to
/// create one and reuse it. You do not need to wrap `SchemaService` in
/// an [Rc](std::rc::Rc) or [Arc](std::sync::Arc) to reuse it, because it
/// already uses an `Arc` internally.
#[derive(Clone, Debug)]
pub struct SchemaService {
    inner: std::sync::Arc<dyn super::stub::dynamic::SchemaService>,
}

impl SchemaService {
    /// Returns a builder for [SchemaService].
    ///
    /// ```
    /// # async fn sample() -> google_cloud_gax::client_builder::Result<()> {
    /// # use google_cloud_pubsub::client::SchemaService;
    /// let client = SchemaService::builder().build().await?;
    /// # Ok(()) }
    /// ```
    pub fn builder() -> super::builder::schema_service::ClientBuilder {
        crate::new_client_builder(super::builder::schema_service::client::Factory)
    }

    /// Creates a new client from the provided stub.
    ///
    /// The most common case for calling this function is in tests mocking the
    /// client's behavior.
    pub fn from_stub<T>(stub: impl Into<std::sync::Arc<T>>) -> Self
    where
        T: super::stub::SchemaService + 'static,
    {
        Self { inner: stub.into() }
    }

    pub(crate) async fn new(
        config: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<Self> {
        let inner = Self::build_inner(config).await?;
        Ok(Self { inner })
    }

    async fn build_inner(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<std::sync::Arc<dyn super::stub::dynamic::SchemaService>> {
        if gaxi::options::tracing_enabled(&conf) {
            return Ok(std::sync::Arc::new(Self::build_with_tracing(conf).await?));
        }
        Ok(std::sync::Arc::new(Self::build_transport(conf).await?))
    }

    async fn build_transport(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<impl super::stub::SchemaService> {
        super::transport::SchemaService::new(conf).await
    }

    async fn build_with_tracing(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<impl super::stub::SchemaService> {
        Self::build_transport(conf)
            .await
            .map(super::tracing::SchemaService::new)
    }

    /// Creates a schema.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::model::Schema;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService, project_id: &str
    /// ) -> Result<()> {
    ///     let response = client.create_schema()
    ///         .set_parent(format!("projects/{project_id}"))
    ///         .set_schema_id("schema_id_value")
    ///         .set_schema(
    ///             Schema::new()/* set fields */
    ///         )
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn create_schema(&self) -> super::builder::schema_service::CreateSchema {
        super::builder::schema_service::CreateSchema::new(self.inner.clone())
    }

    /// Gets a schema.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService, project_id: &str, schema_id: &str
    /// ) -> Result<()> {
    ///     let response = client.get_schema()
    ///         .set_name(format!("projects/{project_id}/schemas/{schema_id}"))
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn get_schema(&self) -> super::builder::schema_service::GetSchema {
        super::builder::schema_service::GetSchema::new(self.inner.clone())
    }

    /// Lists schemas in a project.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_gax::paginator::ItemPaginator as _;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService, parent: &str
    /// ) -> Result<()> {
    ///     let mut list = client.list_schemas()
    ///         .set_parent(parent)
    ///         .by_item();
    ///     while let Some(item) = list.next().await.transpose()? {
    ///         println!("{:?}", item);
    ///     }
    ///     Ok(())
    /// }
    /// ```
    pub fn list_schemas(&self) -> super::builder::schema_service::ListSchemas {
        super::builder::schema_service::ListSchemas::new(self.inner.clone())
    }

    /// Lists all schema revisions for the named schema.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_gax::paginator::ItemPaginator as _;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService
    /// ) -> Result<()> {
    ///     let mut list = client.list_schema_revisions()
    ///         /* set fields */
    ///         .by_item();
    ///     while let Some(item) = list.next().await.transpose()? {
    ///         println!("{:?}", item);
    ///     }
    ///     Ok(())
    /// }
    /// ```
    pub fn list_schema_revisions(&self) -> super::builder::schema_service::ListSchemaRevisions {
        super::builder::schema_service::ListSchemaRevisions::new(self.inner.clone())
    }

    /// Commits a new schema revision to an existing schema.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService
    /// ) -> Result<()> {
    ///     let response = client.commit_schema()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn commit_schema(&self) -> super::builder::schema_service::CommitSchema {
        super::builder::schema_service::CommitSchema::new(self.inner.clone())
    }

    /// Creates a new schema revision that is a copy of the provided revision_id.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService
    /// ) -> Result<()> {
    ///     let response = client.rollback_schema()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn rollback_schema(&self) -> super::builder::schema_service::RollbackSchema {
        super::builder::schema_service::RollbackSchema::new(self.inner.clone())
    }

    /// Deletes a specific schema revision.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService, project_id: &str, schema_id: &str
    /// ) -> Result<()> {
    ///     let response = client.delete_schema_revision()
    ///         .set_name(format!("projects/{project_id}/schemas/{schema_id}"))
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn delete_schema_revision(&self) -> super::builder::schema_service::DeleteSchemaRevision {
        super::builder::schema_service::DeleteSchemaRevision::new(self.inner.clone())
    }

    /// Deletes a schema.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService, project_id: &str, schema_id: &str
    /// ) -> Result<()> {
    ///     client.delete_schema()
    ///         .set_name(format!("projects/{project_id}/schemas/{schema_id}"))
    ///         .send().await?;
    ///     Ok(())
    /// }
    /// ```
    pub fn delete_schema(&self) -> super::builder::schema_service::DeleteSchema {
        super::builder::schema_service::DeleteSchema::new(self.inner.clone())
    }

    /// Validates a schema.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService
    /// ) -> Result<()> {
    ///     let response = client.validate_schema()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn validate_schema(&self) -> super::builder::schema_service::ValidateSchema {
        super::builder::schema_service::ValidateSchema::new(self.inner.clone())
    }

    /// Validates a message against a schema.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService
    /// ) -> Result<()> {
    ///     let response = client.validate_message()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn validate_message(&self) -> super::builder::schema_service::ValidateMessage {
        super::builder::schema_service::ValidateMessage::new(self.inner.clone())
    }

    /// Sets the access control policy on the specified resource. Replaces
    /// any existing policy.
    ///
    /// Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED`
    /// errors.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService
    /// ) -> Result<()> {
    ///     let response = client.set_iam_policy()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn set_iam_policy(&self) -> super::builder::schema_service::SetIamPolicy {
        super::builder::schema_service::SetIamPolicy::new(self.inner.clone())
    }

    /// Gets the access control policy for a resource. Returns an empty policy
    /// if the resource exists and does not have a policy set.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService
    /// ) -> Result<()> {
    ///     let response = client.get_iam_policy()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn get_iam_policy(&self) -> super::builder::schema_service::GetIamPolicy {
        super::builder::schema_service::GetIamPolicy::new(self.inner.clone())
    }

    /// Returns permissions that a caller has on the specified resource. If the
    /// resource does not exist, this will return an empty set of
    /// permissions, not a `NOT_FOUND` error.
    ///
    /// Note: This operation is designed to be used for building
    /// permission-aware UIs and command-line tools, not for authorization
    /// checking. This operation may "fail open" without warning.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_pubsub::client::SchemaService;
    /// use google_cloud_pubsub::Result;
    /// async fn sample(
    ///    client: &SchemaService
    /// ) -> Result<()> {
    ///     let response = client.test_iam_permissions()
    ///         /* set fields */
    ///         .send().await?;
    ///     println!("response {:?}", response);
    ///     Ok(())
    /// }
    /// ```
    pub fn test_iam_permissions(&self) -> super::builder::schema_service::TestIamPermissions {
        super::builder::schema_service::TestIamPermissions::new(self.inner.clone())
    }
}