google_cloud_tasks_v2/

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 Tasks API.
///
/// # Example
/// ```
/// # tokio_test::block_on(async {
/// # use google_cloud_tasks_v2::client::CloudTasks;
/// let client = CloudTasks::builder().build().await?;
/// // use `client` to make requests to the Cloud Tasks API.
/// # gax::client_builder::Result::<()>::Ok(()) });
/// ```
///
/// # Service Description
///
/// Cloud Tasks allows developers to manage the execution of background
/// work in their applications.
///
/// # Configuration
///
/// To configure `CloudTasks` use the `with_*` methods in the type returned
/// by [builder()][CloudTasks::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://cloudtasks.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::cloud_tasks::ClientBuilder::with_endpoint
/// [with_credentials()]: super::builder::cloud_tasks::ClientBuilder::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
///
/// `CloudTasks` holds a connection pool internally, it is advised to
/// create one and the reuse it.  You do not need to wrap `CloudTasks` 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 CloudTasks {
    inner: std::sync::Arc<dyn super::stub::dynamic::CloudTasks>,
}

impl CloudTasks {
    /// Returns a builder for [CloudTasks].
    ///
    /// ```
    /// # tokio_test::block_on(async {
    /// # use google_cloud_tasks_v2::client::CloudTasks;
    /// let client = CloudTasks::builder().build().await?;
    /// # gax::client_builder::Result::<()>::Ok(()) });
    /// ```
    pub fn builder() -> super::builder::cloud_tasks::ClientBuilder {
        gax::client_builder::internal::new_builder(super::builder::cloud_tasks::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: T) -> Self
    where
        T: super::stub::CloudTasks + 'static,
    {
        Self {
            inner: std::sync::Arc::new(stub),
        }
    }

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

    async fn build_inner(
        conf: gaxi::options::ClientConfig,
    ) -> gax::client_builder::Result<std::sync::Arc<dyn super::stub::dynamic::CloudTasks>> {
        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,
    ) -> gax::client_builder::Result<impl super::stub::CloudTasks> {
        super::transport::CloudTasks::new(conf).await
    }

    async fn build_with_tracing(
        conf: gaxi::options::ClientConfig,
    ) -> gax::client_builder::Result<impl super::stub::CloudTasks> {
        Self::build_transport(conf)
            .await
            .map(super::tracing::CloudTasks::new)
    }

    /// Lists queues.
    ///
    /// Queues are returned in lexicographical order.
    pub fn list_queues(&self) -> super::builder::cloud_tasks::ListQueues {
        super::builder::cloud_tasks::ListQueues::new(self.inner.clone())
    }

    /// Gets a queue.
    pub fn get_queue(&self) -> super::builder::cloud_tasks::GetQueue {
        super::builder::cloud_tasks::GetQueue::new(self.inner.clone())
    }

    /// Creates a queue.
    ///
    /// Queues created with this method allow tasks to live for a maximum of 31
    /// days. After a task is 31 days old, the task will be deleted regardless of
    /// whether it was dispatched or not.
    ///
    /// WARNING: Using this method may have unintended side effects if you are
    /// using an App Engine `queue.yaml` or `queue.xml` file to manage your queues.
    /// Read
    /// [Overview of Queue Management and
    /// queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using
    /// this method.
    pub fn create_queue(&self) -> super::builder::cloud_tasks::CreateQueue {
        super::builder::cloud_tasks::CreateQueue::new(self.inner.clone())
    }

    /// Updates a queue.
    ///
    /// This method creates the queue if it does not exist and updates
    /// the queue if it does exist.
    ///
    /// Queues created with this method allow tasks to live for a maximum of 31
    /// days. After a task is 31 days old, the task will be deleted regardless of
    /// whether it was dispatched or not.
    ///
    /// WARNING: Using this method may have unintended side effects if you are
    /// using an App Engine `queue.yaml` or `queue.xml` file to manage your queues.
    /// Read
    /// [Overview of Queue Management and
    /// queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using
    /// this method.
    pub fn update_queue(&self) -> super::builder::cloud_tasks::UpdateQueue {
        super::builder::cloud_tasks::UpdateQueue::new(self.inner.clone())
    }

    /// Deletes a queue.
    ///
    /// This command will delete the queue even if it has tasks in it.
    ///
    /// Note: If you delete a queue, a queue with the same name can't be created
    /// for 7 days.
    ///
    /// WARNING: Using this method may have unintended side effects if you are
    /// using an App Engine `queue.yaml` or `queue.xml` file to manage your queues.
    /// Read
    /// [Overview of Queue Management and
    /// queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using
    /// this method.
    pub fn delete_queue(&self) -> super::builder::cloud_tasks::DeleteQueue {
        super::builder::cloud_tasks::DeleteQueue::new(self.inner.clone())
    }

    /// Purges a queue by deleting all of its tasks.
    ///
    /// All tasks created before this method is called are permanently deleted.
    ///
    /// Purge operations can take up to one minute to take effect. Tasks
    /// might be dispatched before the purge takes effect. A purge is irreversible.
    pub fn purge_queue(&self) -> super::builder::cloud_tasks::PurgeQueue {
        super::builder::cloud_tasks::PurgeQueue::new(self.inner.clone())
    }

    /// Pauses the queue.
    ///
    /// If a queue is paused then the system will stop dispatching tasks
    /// until the queue is resumed via
    /// [ResumeQueue][google.cloud.tasks.v2.CloudTasks.ResumeQueue]. Tasks can
    /// still be added when the queue is paused. A queue is paused if its
    /// [state][google.cloud.tasks.v2.Queue.state] is
    /// [PAUSED][google.cloud.tasks.v2.Queue.State.PAUSED].
    ///
    /// [google.cloud.tasks.v2.CloudTasks.ResumeQueue]: crate::client::CloudTasks::resume_queue
    /// [google.cloud.tasks.v2.Queue.State.PAUSED]: crate::model::queue::State::Paused
    /// [google.cloud.tasks.v2.Queue.state]: crate::model::Queue::state
    pub fn pause_queue(&self) -> super::builder::cloud_tasks::PauseQueue {
        super::builder::cloud_tasks::PauseQueue::new(self.inner.clone())
    }

    /// Resume a queue.
    ///
    /// This method resumes a queue after it has been
    /// [PAUSED][google.cloud.tasks.v2.Queue.State.PAUSED] or
    /// [DISABLED][google.cloud.tasks.v2.Queue.State.DISABLED]. The state of a
    /// queue is stored in the queue's [state][google.cloud.tasks.v2.Queue.state];
    /// after calling this method it will be set to
    /// [RUNNING][google.cloud.tasks.v2.Queue.State.RUNNING].
    ///
    /// WARNING: Resuming many high-QPS queues at the same time can
    /// lead to target overloading. If you are resuming high-QPS
    /// queues, follow the 500/50/5 pattern described in
    /// [Managing Cloud Tasks Scaling
    /// Risks](https://cloud.google.com/tasks/docs/manage-cloud-task-scaling).
    ///
    /// [google.cloud.tasks.v2.Queue.State.DISABLED]: crate::model::queue::State::Disabled
    /// [google.cloud.tasks.v2.Queue.State.PAUSED]: crate::model::queue::State::Paused
    /// [google.cloud.tasks.v2.Queue.State.RUNNING]: crate::model::queue::State::Running
    /// [google.cloud.tasks.v2.Queue.state]: crate::model::Queue::state
    pub fn resume_queue(&self) -> super::builder::cloud_tasks::ResumeQueue {
        super::builder::cloud_tasks::ResumeQueue::new(self.inner.clone())
    }

    /// Gets the access control policy for a [Queue][google.cloud.tasks.v2.Queue].
    /// Returns an empty policy if the resource exists and does not have a policy
    /// set.
    ///
    /// Authorization requires the following
    /// [Google IAM](https://cloud.google.com/iam) permission on the specified
    /// resource parent:
    ///
    /// * `cloudtasks.queues.getIamPolicy`
    ///
    /// [google.cloud.tasks.v2.Queue]: crate::model::Queue
    pub fn get_iam_policy(&self) -> super::builder::cloud_tasks::GetIamPolicy {
        super::builder::cloud_tasks::GetIamPolicy::new(self.inner.clone())
    }

    /// Sets the access control policy for a [Queue][google.cloud.tasks.v2.Queue].
    /// Replaces any existing policy.
    ///
    /// Note: The Cloud Console does not check queue-level IAM permissions yet.
    /// Project-level permissions are required to use the Cloud Console.
    ///
    /// Authorization requires the following
    /// [Google IAM](https://cloud.google.com/iam) permission on the specified
    /// resource parent:
    ///
    /// * `cloudtasks.queues.setIamPolicy`
    ///
    /// [google.cloud.tasks.v2.Queue]: crate::model::Queue
    pub fn set_iam_policy(&self) -> super::builder::cloud_tasks::SetIamPolicy {
        super::builder::cloud_tasks::SetIamPolicy::new(self.inner.clone())
    }

    /// Returns permissions that a caller has on a
    /// [Queue][google.cloud.tasks.v2.Queue]. If the resource does not exist, this
    /// will return an empty set of permissions, not a
    /// [NOT_FOUND][google.rpc.Code.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.
    ///
    /// [google.cloud.tasks.v2.Queue]: crate::model::Queue
    pub fn test_iam_permissions(&self) -> super::builder::cloud_tasks::TestIamPermissions {
        super::builder::cloud_tasks::TestIamPermissions::new(self.inner.clone())
    }

    /// Lists the tasks in a queue.
    ///
    /// By default, only the [BASIC][google.cloud.tasks.v2.Task.View.BASIC] view is
    /// retrieved due to performance considerations;
    /// [response_view][google.cloud.tasks.v2.ListTasksRequest.response_view]
    /// controls the subset of information which is returned.
    ///
    /// The tasks may be returned in any order. The ordering may change at any
    /// time.
    ///
    /// [google.cloud.tasks.v2.ListTasksRequest.response_view]: crate::model::ListTasksRequest::response_view
    /// [google.cloud.tasks.v2.Task.View.BASIC]: crate::model::task::View::Basic
    pub fn list_tasks(&self) -> super::builder::cloud_tasks::ListTasks {
        super::builder::cloud_tasks::ListTasks::new(self.inner.clone())
    }

    /// Gets a task.
    pub fn get_task(&self) -> super::builder::cloud_tasks::GetTask {
        super::builder::cloud_tasks::GetTask::new(self.inner.clone())
    }

    /// Creates a task and adds it to a queue.
    ///
    /// Tasks cannot be updated after creation; there is no UpdateTask command.
    ///
    /// * The maximum task size is 100KB.
    pub fn create_task(&self) -> super::builder::cloud_tasks::CreateTask {
        super::builder::cloud_tasks::CreateTask::new(self.inner.clone())
    }

    /// Deletes a task.
    ///
    /// A task can be deleted if it is scheduled or dispatched. A task
    /// cannot be deleted if it has executed successfully or permanently
    /// failed.
    pub fn delete_task(&self) -> super::builder::cloud_tasks::DeleteTask {
        super::builder::cloud_tasks::DeleteTask::new(self.inner.clone())
    }

    /// Forces a task to run now.
    ///
    /// When this method is called, Cloud Tasks will dispatch the task, even if
    /// the task is already running, the queue has reached its
    /// [RateLimits][google.cloud.tasks.v2.RateLimits] or is
    /// [PAUSED][google.cloud.tasks.v2.Queue.State.PAUSED].
    ///
    /// This command is meant to be used for manual debugging. For
    /// example, [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask] can be used to
    /// retry a failed task after a fix has been made or to manually force a task
    /// to be dispatched now.
    ///
    /// The dispatched task is returned. That is, the task that is returned
    /// contains the [status][Task.status] after the task is dispatched but
    /// before the task is received by its target.
    ///
    /// If Cloud Tasks receives a successful response from the task's
    /// target, then the task will be deleted; otherwise the task's
    /// [schedule_time][google.cloud.tasks.v2.Task.schedule_time] will be reset to
    /// the time that [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask] was
    /// called plus the retry delay specified in the queue's
    /// [RetryConfig][google.cloud.tasks.v2.RetryConfig].
    ///
    /// [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask] returns
    /// [NOT_FOUND][google.rpc.Code.NOT_FOUND] when it is called on a
    /// task that has already succeeded or permanently failed.
    ///
    /// [google.cloud.tasks.v2.CloudTasks.RunTask]: crate::client::CloudTasks::run_task
    /// [google.cloud.tasks.v2.Queue.State.PAUSED]: crate::model::queue::State::Paused
    /// [google.cloud.tasks.v2.RateLimits]: crate::model::RateLimits
    /// [google.cloud.tasks.v2.RetryConfig]: crate::model::RetryConfig
    /// [google.cloud.tasks.v2.Task.schedule_time]: crate::model::Task::schedule_time
    pub fn run_task(&self) -> super::builder::cloud_tasks::RunTask {
        super::builder::cloud_tasks::RunTask::new(self.inner.clone())
    }

    /// Lists information about the supported locations for this service.
    pub fn list_locations(&self) -> super::builder::cloud_tasks::ListLocations {
        super::builder::cloud_tasks::ListLocations::new(self.inner.clone())
    }

    /// Gets information about a location.
    pub fn get_location(&self) -> super::builder::cloud_tasks::GetLocation {
        super::builder::cloud_tasks::GetLocation::new(self.inner.clone())
    }
}