Kit.Core/LibExternal/Minio/ApiEndpoints/IBucketOperations.cs

389 lines
25 KiB
C#

/*
* MinIO .NET Library for Amazon S3 Compatible Cloud Storage,
* (C) 2017-2021 MinIO, Inc.
*
* 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
*
* http://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.
*/
using Minio.DataModel;
using Minio.DataModel.Args;
using Minio.DataModel.Encryption;
using Minio.DataModel.ILM;
using Minio.DataModel.Notification;
using Minio.DataModel.ObjectLock;
using Minio.DataModel.Replication;
using Minio.DataModel.Result;
using Minio.DataModel.Tags;
using Minio.Exceptions;
namespace Minio.ApiEndpoints;
public interface IBucketOperations
{
/// <summary>
/// Create a bucket with the given name.
/// </summary>
/// <param name="args">MakeBucketArgs Arguments Object that has bucket info like name, location. etc</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns> Task </returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucketName is invalid</exception>
/// <exception cref="NotImplementedException">When object-lock or another extension is not implemented</exception>
Task MakeBucketAsync(MakeBucketArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// List all objects in a bucket
/// </summary>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns>Task with an iterator lazily populated with objects</returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
Task<ListAllMyBucketsResult> ListBucketsAsync(CancellationToken cancellationToken = default);
/// <summary>
/// Check if a private bucket with the given name exists.
/// </summary>
/// <param name="args">BucketExistsArgs Arguments Object which has bucket identifier information - bucket name, region</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns> Task </returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
Task<bool> BucketExistsAsync(BucketExistsArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Remove the bucket with the given name.
/// </summary>
/// <param name="args">RemoveBucketArgs Arguments Object which has bucket identifier information like bucket name .etc.</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns> Task </returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
Task RemoveBucketAsync(RemoveBucketArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// List all objects non-recursively in a bucket with a given prefix, optionally emulating a directory
/// </summary>
/// <param name="args">
/// ListObjectsArgs Arguments Object with information like Bucket name, prefix, recursive listing,
/// versioning
/// </param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns>An observable of items that client can subscribe to</returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="InvalidOperationException">
/// For example, if you call ListObjectsAsync on a bucket with versioning
/// enabled or object lock enabled
/// </exception>
IObservable<Item> ListObjectsAsync(ListObjectsArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Gets notification configuration for this bucket
/// </summary>
/// <param name="args">GetBucketNotificationsArgs Arguments Object with information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
Task<BucketNotification> GetBucketNotificationsAsync(GetBucketNotificationsArgs args,
CancellationToken cancellationToken = default);
/// <summary>
/// Sets the notification configuration for this bucket
/// </summary>
/// <param name="args">
/// SetBucketNotificationsArgs Arguments Object with information like Bucket name, notification object
/// with configuration to set
/// </param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task SetBucketNotificationsAsync(SetBucketNotificationsArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Removes all bucket notification configurations stored on the server.
/// </summary>
/// <param name="args">RemoveAllBucketNotificationsArgs Arguments Object with information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task RemoveAllBucketNotificationsAsync(RemoveAllBucketNotificationsArgs args,
CancellationToken cancellationToken = default);
/// <summary>
/// Subscribes to bucket change notifications (a Minio-only extension)
/// </summary>
/// <param name="args">
/// ListenBucketNotificationsArgs Arguments Object with information like Bucket name, listen events,
/// prefix filter keys, suffix fileter keys
/// </param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns>An observable of JSON-based notification events</returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
IObservable<MinioNotificationRaw> ListenBucketNotificationsAsync(ListenBucketNotificationsArgs args,
CancellationToken cancellationToken = default);
/// <summary>
/// Gets Tagging values set for this bucket
/// </summary>
/// <param name="args">GetBucketTagsArgs Arguments Object with information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns>Tagging Object with key-value tag pairs</returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
Task<Tagging> GetBucketTagsAsync(GetBucketTagsArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Sets the Tagging values for this bucket
/// </summary>
/// <param name="args">SetBucketTagsArgs Arguments Object with information like Bucket name, tag key-value pairs</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task SetBucketTagsAsync(SetBucketTagsArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Removes Tagging values stored for the bucket.
/// </summary>
/// <param name="args">RemoveBucketTagsArgs Arguments Object with information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task RemoveBucketTagsAsync(RemoveBucketTagsArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Sets the Object Lock Configuration on this bucket
/// </summary>
/// <param name="args">
/// SetObjectLockConfigurationArgs Arguments Object with information like Bucket name, object lock
/// configuration to set
/// </param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="MissingObjectLockConfigurationException">When object lock configuration on bucket is not set</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task SetObjectLockConfigurationAsync(SetObjectLockConfigurationArgs args,
CancellationToken cancellationToken = default);
/// <summary>
/// Gets the Object Lock Configuration on this bucket
/// </summary>
/// <param name="args">GetObjectLockConfigurationArgs Arguments Object with information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns>ObjectLockConfiguration object</returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="MissingObjectLockConfigurationException">When object lock configuration on bucket is not set</exception>
Task<ObjectLockConfiguration> GetObjectLockConfigurationAsync(GetObjectLockConfigurationArgs args,
CancellationToken cancellationToken = default);
/// <summary>
/// Removes the Object Lock Configuration on this bucket
/// </summary>
/// <param name="args">RemoveObjectLockConfigurationArgs Arguments Object with information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="MissingObjectLockConfigurationException">When object lock configuration on bucket is not set</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task RemoveObjectLockConfigurationAsync(RemoveObjectLockConfigurationArgs args,
CancellationToken cancellationToken = default);
/// <summary>
/// Get Versioning information on the bucket with given bucket name
/// </summary>
/// <param name="args">GetVersioningArgs takes bucket as argument. </param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns> GetVersioningResponse with information populated from REST response </returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
Task<VersioningConfiguration> GetVersioningAsync(GetVersioningArgs args,
CancellationToken cancellationToken = default);
/// <summary>
/// Set Versioning as specified on the bucket with given bucket name
/// </summary>
/// <param name="args">SetVersioningArgs Arguments Object with information like Bucket name, Versioning configuration</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns> Task </returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task SetVersioningAsync(SetVersioningArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Sets the Encryption Configuration for the bucket.
/// </summary>
/// <param name="args">SetBucketEncryptionArgs Arguments Object with information like Bucket name, encryption config</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns> Task </returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task SetBucketEncryptionAsync(SetBucketEncryptionArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Returns the Encryption Configuration for the bucket.
/// </summary>
/// <param name="args">GetBucketEncryptionArgs Arguments Object encapsulating information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns> An object of type ServerSideEncryptionConfiguration </returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
Task<ServerSideEncryptionConfiguration> GetBucketEncryptionAsync(GetBucketEncryptionArgs args,
CancellationToken cancellationToken = default);
/// <summary>
/// Removes the Encryption Configuration for the bucket.
/// </summary>
/// <param name="args">RemoveBucketEncryptionArgs Arguments Object encapsulating information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns> Task </returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task RemoveBucketEncryptionAsync(RemoveBucketEncryptionArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Sets the Lifecycle configuration for this bucket
/// </summary>
/// <param name="args">SetBucketLifecycleArgs Arguments Object with information like Bucket name, tag key-value pairs</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task SetBucketLifecycleAsync(SetBucketLifecycleArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Gets Lifecycle configuration set for this bucket returned in an object
/// </summary>
/// <param name="args">GetBucketLifecycleArgs Arguments Object with information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns>Lifecycle Object with key-value tag pairs</returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
Task<LifecycleConfiguration> GetBucketLifecycleAsync(GetBucketLifecycleArgs args,
CancellationToken cancellationToken = default);
/// <summary>
/// Removes Lifecycle configuration stored for the bucket.
/// </summary>
/// <param name="args">RemoveBucketLifecycleArgs Arguments Object with information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="MalFormedXMLException">When configuration XML provided is invalid</exception>
Task RemoveBucketLifecycleAsync(RemoveBucketLifecycleArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Gets Replication configuration set for this bucket
/// </summary>
/// <param name="args">GetBucketReplicationArgs Arguments Object with information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns>Replication configuration object</returns>
/// <exception cref="AuthorizationException">When access or secret key provided is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="MissingBucketReplicationConfigurationException">When bucket replication configuration is not set</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
Task<ReplicationConfiguration> GetBucketReplicationAsync(GetBucketReplicationArgs args,
CancellationToken cancellationToken = default);
/// <summary>
/// Sets the Replication configuration for this bucket
/// </summary>
/// <param name="args">
/// SetBucketReplicationArgs Arguments Object with information like Bucket name, Replication
/// Configuration object
/// </param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key provided is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="MissingBucketReplicationConfigurationException">When bucket replication configuration is not set</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
Task SetBucketReplicationAsync(SetBucketReplicationArgs args, CancellationToken cancellationToken = default);
/// <summary>
/// Removes Replication configuration stored for the bucket.
/// </summary>
/// <param name="args">RemoveBucketReplicationArgs Arguments Object with information like Bucket name</param>
/// <param name="cancellationToken">Optional cancellation token to cancel the operation</param>
/// <returns></returns>
/// <exception cref="AuthorizationException">When access or secret key provided is invalid</exception>
/// <exception cref="InvalidBucketNameException">When bucket name is invalid</exception>
/// <exception cref="MissingBucketReplicationConfigurationException">When bucket replication configuration is not set</exception>
/// <exception cref="NotImplementedException">When a functionality or extension is not implemented</exception>
/// <exception cref="BucketNotFoundException">When bucket is not found</exception>
Task RemoveBucketReplicationAsync(RemoveBucketReplicationArgs args, CancellationToken cancellationToken = default);
Task<string> GetPolicyAsync(GetPolicyArgs args, CancellationToken cancellationToken = default);
IObservable<MinioNotificationRaw> ListenBucketNotificationsAsync(string bucketName, IList<EventType> events,
string prefix = "", string suffix = "", CancellationToken cancellationToken = default);
Task RemovePolicyAsync(RemovePolicyArgs args, CancellationToken cancellationToken = default);
Task SetPolicyAsync(SetPolicyArgs args, CancellationToken cancellationToken = default);
}