google-cloud-storage 1.2.0

// 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 Storage API.
#[derive(Clone, Debug)]
pub struct StorageControl {
    inner: std::sync::Arc<dyn super::stub::dynamic::StorageControl>,
}

impl StorageControl {
    /// 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::StorageControl + '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::StorageControl>> {
        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::StorageControl> {
        super::transport::StorageControl::new(conf).await
    }

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

    /// Permanently deletes an empty bucket.
    pub fn delete_bucket(&self) -> super::builder::storage_control::DeleteBucket {
        super::builder::storage_control::DeleteBucket::new(self.inner.clone())
    }

    /// Returns metadata for the specified bucket.
    pub fn get_bucket(&self) -> super::builder::storage_control::GetBucket {
        super::builder::storage_control::GetBucket::new(self.inner.clone())
    }

    /// Creates a new bucket.
    pub fn create_bucket(&self) -> super::builder::storage_control::CreateBucket {
        super::builder::storage_control::CreateBucket::new(self.inner.clone())
    }

    /// Retrieves a list of buckets for a given project.
    pub fn list_buckets(&self) -> super::builder::storage_control::ListBuckets {
        super::builder::storage_control::ListBuckets::new(self.inner.clone())
    }

    /// Locks retention policy on a bucket.
    pub fn lock_bucket_retention_policy(
        &self,
    ) -> super::builder::storage_control::LockBucketRetentionPolicy {
        super::builder::storage_control::LockBucketRetentionPolicy::new(self.inner.clone())
    }

    /// Updates a bucket. Equivalent to JSON API's storage.buckets.patch method.
    pub fn update_bucket(&self) -> super::builder::storage_control::UpdateBucket {
        super::builder::storage_control::UpdateBucket::new(self.inner.clone())
    }

    /// Concatenates a list of existing objects into a new object in the same
    /// bucket.
    pub fn compose_object(&self) -> super::builder::storage_control::ComposeObject {
        super::builder::storage_control::ComposeObject::new(self.inner.clone())
    }

    /// Deletes an object and its metadata. Deletions are permanent if versioning
    /// is not enabled for the bucket, or if the generation parameter is used, or
    /// if [soft delete](https://cloud.google.com/storage/docs/soft-delete) is not
    /// enabled for the bucket.
    /// When this API is used to delete an object from a bucket that has soft
    /// delete policy enabled, the object becomes soft deleted, and the
    /// `softDeleteTime` and `hardDeleteTime` properties are set on the object.
    /// This API cannot be used to permanently delete soft-deleted objects.
    /// Soft-deleted objects are permanently deleted according to their
    /// `hardDeleteTime`.
    ///
    /// You can use the [`RestoreObject`][google.storage.v2.Storage.RestoreObject]
    /// API to restore soft-deleted objects until the soft delete retention period
    /// has passed.
    ///
    /// **IAM Permissions**:
    ///
    /// Requires `storage.objects.delete`
    /// [IAM permission](https://cloud.google.com/iam/docs/overview#permissions) on
    /// the bucket.
    ///
    /// [google.storage.v2.Storage.RestoreObject]: crate::client::StorageControl::restore_object
    pub fn delete_object(&self) -> super::builder::storage_control::DeleteObject {
        super::builder::storage_control::DeleteObject::new(self.inner.clone())
    }

    /// Restores a soft-deleted object.
    pub fn restore_object(&self) -> super::builder::storage_control::RestoreObject {
        super::builder::storage_control::RestoreObject::new(self.inner.clone())
    }

    /// Retrieves object metadata.
    ///
    /// **IAM Permissions**:
    ///
    /// Requires `storage.objects.get`
    /// [IAM permission](https://cloud.google.com/iam/docs/overview#permissions) on
    /// the bucket. To return object ACLs, the authenticated user must also have
    /// the `storage.objects.getIamPolicy` permission.
    pub fn get_object(&self) -> super::builder::storage_control::GetObject {
        super::builder::storage_control::GetObject::new(self.inner.clone())
    }

    /// Updates an object's metadata.
    /// Equivalent to JSON API's storage.objects.patch.
    pub fn update_object(&self) -> super::builder::storage_control::UpdateObject {
        super::builder::storage_control::UpdateObject::new(self.inner.clone())
    }

    /// Retrieves a list of objects matching the criteria.
    ///
    /// **IAM Permissions**:
    ///
    /// The authenticated user requires `storage.objects.list`
    /// [IAM permission](https://cloud.google.com/iam/docs/overview#permissions)
    /// to use this method. To return object ACLs, the authenticated user must also
    /// have the `storage.objects.getIamPolicy` permission.
    pub fn list_objects(&self) -> super::builder::storage_control::ListObjects {
        super::builder::storage_control::ListObjects::new(self.inner.clone())
    }

    /// Rewrites a source object to a destination object. Optionally overrides
    /// metadata.
    pub fn rewrite_object(&self) -> super::builder::storage_control::RewriteObject {
        super::builder::storage_control::RewriteObject::new(self.inner.clone())
    }

    /// Moves the source object to the destination object in the same bucket.
    pub fn move_object(&self) -> super::builder::storage_control::MoveObject {
        super::builder::storage_control::MoveObject::new(self.inner.clone())
    }
}