minio

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 12, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package minio provides functionality for interacting with MinIO/S3-compatible object storage.

The minio package offers a simplified interface for working with object storage systems that are compatible with the S3 API, including MinIO, Amazon S3, and others. It provides functionality for object operations, bucket management, and presigned URL generation with a focus on ease of use and reliability.

Multi-Bucket Support

This package supports multi-bucket operations. All operations require an explicit bucket parameter, enabling you to work with multiple buckets from a single client instance. For convenience when working with a single bucket repeatedly, use the BucketClient wrapper.

Architecture

This package follows the "accept interfaces, return structs" design pattern:

  • Client interface: Defines the contract for MinIO/S3 operations
  • MinioClient struct: Concrete implementation of the Client interface
  • BucketClient struct: Lightweight wrapper for scoped bucket operations
  • NewClient constructor: Returns *MinioClient (concrete type)
  • FX module: Provides both *MinioClient and Client interface for dependency injection

Core Features:

  • Multi-bucket operations (work with multiple buckets seamlessly)
  • Bucket management (create, delete, check existence, list)
  • Object operations (upload, download, delete)
  • Presigned URL generation for temporary access
  • Multipart upload and download support for large files
  • Notification configuration
  • Integration with the Logger package for structured logging
  • Integration with Observability package for metrics and tracing

Direct Usage (Without FX)

For simple applications or tests, create a client directly: 

import (
	"github.com/Aleph-Alpha/std/v1/minio"
	"context"
)

// Create a new MinIO client (returns concrete *MinioClient)
client, err := minio.NewClient(minio.Config{
	Connection: minio.ConnectionConfig{
		Endpoint:        "play.min.io",
		AccessKeyID:     "minioadmin",
		SecretAccessKey: "minioadmin",
		UseSSL:          true,
	},
})
if err != nil {
	return err
}

ctx := context.Background()

// Create a bucket
err = client.CreateBucket(ctx, "mybucket")
if err != nil {
	return err
}

// Use the client with explicit bucket parameter
_, err = client.Put(ctx, "mybucket", "path/to/object.txt", file,
	minio.WithSize(fileInfo.Size()))

// Or use BucketClient for convenience
bucket := client.Bucket("mybucket")
_, err = bucket.Put(ctx, "path/to/object.txt", file,
	minio.WithSize(fileInfo.Size()))

FX Module Integration

For production applications using Uber's fx, use the FXModule which provides both the concrete type and interface: 

import (
	"github.com/Aleph-Alpha/std/v1/minio"
	"github.com/Aleph-Alpha/std/v1/logger"
	"go.uber.org/fx"
)

app := fx.New(
	logger.FXModule, // Optional: provides std logger
	minio.FXModule,  // Provides *MinioClient and minio.Client interface
	fx.Provide(func() minio.Config {
		return minio.Config{
			Connection: minio.ConnectionConfig{
				Endpoint:        "play.min.io",
				AccessKeyID:     "minioadmin",
				SecretAccessKey: "minioadmin",
			},
		}
	}),
	fx.Invoke(func(client *minio.MinioClient) {
		// Use concrete type directly with explicit bucket
		ctx := context.Background()
		client.CreateBucket(ctx, "mybucket")
		client.Put(ctx, "mybucket", "key", reader, minio.WithSize(size))
	}),
	// ... other modules
)
app.Run()

Observability (Observer Hook)

MinIO supports optional observability through the Observer interface from the observability package. This allows external systems to track operations without coupling the MinIO package to specific metrics/tracing implementations.

Using WithObserver (non-FX usage): 

client, err := minio.NewClient(config)
if err != nil {
    return err
}
client = client.WithObserver(myObserver).WithLogger(myLogger)
defer client.GracefulShutdown()

Using FX (automatic injection): 

app := fx.New(
    minio.FXModule,
    logger.FXModule,  // Optional: provides logger
    fx.Provide(
        func() minio.Config { return loadConfig() },
        func() observability.Observer { return myObserver },  // Optional
    ),
)

The observer receives events for all storage operations:

  • Component: "minio"
  • Operations: "put", "get", "stream_get", "delete", "presigned_get", "presigned_put", "presigned_head"
  • Resource: bucket name
  • SubResource: object key
  • Duration: operation duration
  • Error: any error that occurred
  • Size: bytes transferred (for put/get operations)
  • Metadata: operation-specific details (e.g., chunk_size for stream_get)

Type Aliases in Consumer Code

To simplify your code and make it storage-agnostic, use type aliases: 

package myapp

import stdMinio "github.com/Aleph-Alpha/std/v1/minio"

// Use type alias to reference std's interface
type MinioClient = stdMinio.Client

// Now use MinioClient throughout your codebase
func MyFunction(client MinioClient) {
	client.Get(ctx, "key")
}

This eliminates the need for adapters and allows you to switch implementations by only changing the alias definition.

Basic Operations 

// Create a bucket
err = client.CreateBucket(ctx, "mybucket")

// Upload a file
file, _ := os.Open("/local/path/file.txt")
defer file.Close()
fileInfo, _ := file.Stat()
_, err = client.Put(ctx, "path/to/object.txt", file, fileInfo.Size())

// Generate a presigned URL for downloading
url, err := client.PreSignedGet(ctx, "path/to/object.txt")

Multipart Operations

For large files, the package provides multipart upload and download capabilities:

Multipart Upload Example: 

// Generate multipart upload URLs for a 1GB file
upload, err := client.GenerateMultipartUploadURLs(
	ctx,
	"large-file.zip",
	1024*1024*1024, // 1GB
	"application/zip",
	2*time.Hour, // URLs valid for 2 hours
)
if err != nil {
	log.Error("Failed to generate upload URLs", err, nil)
}

// Use the returned URLs to upload each part
urls := upload.GetPresignedURLs()
partNumbers := upload.GetPartNumbers()

// After uploading parts, complete the multipart upload
err = client.CompleteMultipartUpload(
	ctx,
	upload.GetObjectKey(),
	upload.GetUploadID(),
	partNumbers,
	etags, // ETags returned from each part upload
)

Multipart Download Example: 

// Generate multipart download URLs for a large file
download, err := client.GenerateMultipartPresignedGetURLs(
	ctx,
	"large-file.zip",
	10*1024*1024, // 10MB parts
	1*time.Hour,  // URLs valid for 1 hour
)
if err != nil {
	log.Error("Failed to generate download URLs", err, nil)
}

// Use the returned URLs to download each part
urls := download.GetPresignedURLs()
ranges := download.GetPartRanges()

// Each URL can be used with an HTTP client to download a specific part
// by setting the Range header to the corresponding value from ranges

FX Module Integration:

This package provides an fx module for easy integration with optional logger injection: 

// With logger module (recommended)
app := fx.New(
	logger.FXModule,  // Provides structured logger
	fx.Provide(func(log *logger.Logger) minio.MinioLogger {
		return minio.NewLoggerAdapter(log)
	}),
	minio.FXModule,   // Will automatically use the provided logger
	// ... other modules
)
app.Run()

// Without logger module (uses fallback logger)
app := fx.New(
	minio.FXModule,   // Will use fallback logger
	// ... other modules
)
app.Run()

Security Considerations:

When using this package, follow these security best practices:

  • Use environment variables or a secure secrets manager for credentials
  • Always enable TLS (UseSSL=true) in production environments
  • Use presigned URLs with the shortest viable expiration time
  • Set appropriate bucket policies and access controls
  • Consider using server-side encryption for sensitive data

Error Handling:

All operations return clear error messages that can be logged: 

data, err := client.Get(ctx, "object.txt")
if err != nil {
	if strings.Contains(err.Error(), "The specified key does not exist") {
		// Handle not found case
	} else {
		// Handle other errors
		log.Error("Download failed", err, nil)
	}
}

Thread Safety:

All methods on the MinioClient type are safe for concurrent use by multiple goroutines. The underlying `*minio.Client` and `*minio.Core` pointers are stored in atomic pointers and can be swapped during reconnection without racing with concurrent operations.

Index

Constants

View Source 
const (

	// MultipartThreshold is the default size threshold (50 MiB) above which uploads
	// will automatically use multipart uploading for better performance and reliability.
	MultipartThreshold int64 = 50 * 1024 * 1024

	// MaxObjectSize is the maximum size (5 TiB) for a single object in MinIO/S3.
	// This is a limit imposed by the S3 specification.
	MaxObjectSize int64 = 5 * 1024 * 1024 * 1024 * 1024

	// UploadDefaultContentType is the default MIME type to use for uploaded objects.
	UploadDefaultContentType string = "application/octet-stream"

	MultipartDownloadDefaultPartSize int64 = 5 * 1024 * 1024
)

Constants for MinIO client configuration and behavior.

Variables

View Source 
var (
	// ErrObjectNotFound is returned when an object doesn't exist in the bucket
	ErrObjectNotFound = errors.New("object not found")

	// ErrBucketNotFound is returned when a bucket doesn't exist
	ErrBucketNotFound = errors.New("bucket not found")

	// ErrBucketAlreadyExists is returned when trying to create a bucket that already exists
	ErrBucketAlreadyExists = errors.New("bucket already exists")

	// ErrInvalidBucketName is returned when bucket name is invalid
	ErrInvalidBucketName = errors.New("invalid bucket name")

	// ErrInvalidObjectName is returned when object name is invalid
	ErrInvalidObjectName = errors.New("invalid object name")

	// ErrAccessDenied is returned when access is denied to bucket or object
	ErrAccessDenied = errors.New("access denied")

	// ErrInsufficientPermissions is returned when user lacks necessary permissions
	ErrInsufficientPermissions = errors.New("insufficient permissions")

	// ErrInvalidCredentials is returned when credentials are invalid
	ErrInvalidCredentials = errors.New("invalid credentials")

	// ErrCredentialsExpired is returned when credentials have expired
	ErrCredentialsExpired = errors.New("credentials expired")

	// ErrConnectionFailed is returned when connection to MinIO server fails
	ErrConnectionFailed = errors.New("connection failed")

	// ErrConnectionLost is returned when connection to MinIO server is lost
	ErrConnectionLost = errors.New("connection lost")

	// ErrTimeout is returned when operation times out
	ErrTimeout = errors.New("operation timeout")

	// ErrInvalidRange is returned when byte range is invalid
	ErrInvalidRange = errors.New("invalid range")

	// ErrObjectTooLarge is returned when object exceeds size limits
	ErrObjectTooLarge = errors.New("object too large")

	// ErrInvalidChecksum is returned when object checksum doesn't match
	ErrInvalidChecksum = errors.New("invalid checksum")

	// ErrInvalidMetadata is returned when object metadata is invalid
	ErrInvalidMetadata = errors.New("invalid metadata")

	// ErrInvalidContentType is returned when content type is invalid
	ErrInvalidContentType = errors.New("invalid content type")

	// ErrInvalidEncryption is returned when encryption parameters are invalid
	ErrInvalidEncryption = errors.New("invalid encryption")

	// ErrServerError is returned for internal MinIO server errors
	ErrServerError = errors.New("server error")

	// ErrServiceUnavailable is returned when MinIO service is unavailable
	ErrServiceUnavailable = errors.New("service unavailable")

	// ErrTooManyRequests is returned when rate limit is exceeded
	ErrTooManyRequests = errors.New("too many requests")

	// ErrInvalidResponse is returned when server response is invalid
	ErrInvalidResponse = errors.New("invalid response")

	// ErrNetworkError is returned for network-related errors
	ErrNetworkError = errors.New("network error")

	// ErrInvalidURL is returned when URL is malformed
	ErrInvalidURL = errors.New("invalid URL")

	// ErrQuotaExceeded is returned when storage quota is exceeded
	ErrQuotaExceeded = errors.New("quota exceeded")

	// ErrBucketNotEmpty is returned when trying to delete non-empty bucket
	ErrBucketNotEmpty = errors.New("bucket not empty")

	// ErrPreconditionFailed is returned when precondition check fails
	ErrPreconditionFailed = errors.New("precondition failed")

	// ErrInvalidPart is returned when multipart upload part is invalid
	ErrInvalidPart = errors.New("invalid part")

	// ErrInvalidUploadID is returned when multipart upload ID is invalid
	ErrInvalidUploadID = errors.New("invalid upload ID")

	// ErrPartTooSmall is returned when multipart upload part is too small
	ErrPartTooSmall = errors.New("part too small")

	// ErrNotImplemented is returned for unsupported operations
	ErrNotImplemented = errors.New("operation not implemented")

	// ErrInvalidArgument is returned when function arguments are invalid
	ErrInvalidArgument = errors.New("invalid argument")

	// ErrCancelled is returned when operation is cancelled
	ErrCancelled = errors.New("operation cancelled")

	// ErrConfigurationError is returned for configuration-related errors
	ErrConfigurationError = errors.New("configuration error")

	// ErrVersioningNotEnabled is returned when versioning is required but not enabled
	ErrVersioningNotEnabled = errors.New("versioning not enabled")

	// ErrInvalidVersion is returned when object version is invalid
	ErrInvalidVersion = errors.New("invalid version")

	// ErrLockConfigurationError is returned for object lock configuration errors
	ErrLockConfigurationError = errors.New("lock configuration error")

	// ErrObjectLocked is returned when object is locked and cannot be deleted
	ErrObjectLocked = errors.New("object locked")

	// ErrRetentionPolicyError is returned for retention policy errors
	ErrRetentionPolicyError = errors.New("retention policy error")

	// ErrMalformedXML is returned when XML is malformed
	ErrMalformedXML = errors.New("malformed XML")

	// ErrInvalidStorageClass is returned when storage class is invalid
	ErrInvalidStorageClass = errors.New("invalid storage class")

	// ErrReplicationError is returned for replication-related errors
	ErrReplicationError = errors.New("replication error")

	// ErrLifecycleError is returned for lifecycle configuration errors
	ErrLifecycleError = errors.New("lifecycle error")

	// ErrNotificationError is returned for notification configuration errors
	ErrNotificationError = errors.New("notification error")

	// ErrTaggingError is returned for object tagging errors
	ErrTaggingError = errors.New("tagging error")

	// ErrPolicyError is returned for bucket policy errors
	ErrPolicyError = errors.New("policy error")

	// ErrWebsiteError is returned for website configuration errors
	ErrWebsiteError = errors.New("website configuration error")

	// ErrCORSError is returned for CORS configuration errors
	ErrCORSError = errors.New("CORS configuration error")

	// ErrLoggingError is returned for logging configuration errors
	ErrLoggingError = errors.New("logging configuration error")

	// ErrEncryptionError is returned for encryption configuration errors
	ErrEncryptionError = errors.New("encryption configuration error")

	// ErrUnknownError is returned for unknown/unhandled errors
	ErrUnknownError = errors.New("unknown error")
)

Common object storage error types that can be used by consumers of this package. These provide a standardized set of errors that abstract away the underlying MinIO-specific error details.

View Source 
var FXModule = fx.Module("minio",
	fx.Provide(
		NewMinioClientWithDI,

		fx.Annotate(
			func(m *MinioClient) Client { return m },
			fx.As(new(Client)),
		),
	),
	fx.Invoke(RegisterLifecycle),
)

FXModule is an fx.Module that provides and configures the MinIO client. This module registers the MinIO client with the Fx dependency injection framework, making it available to other components in the application.

The module provides: 1. *MinioClient (concrete type) for direct use 2. Client interface for dependency injection 3. Lifecycle management for graceful startup and shutdown

Note: The client supports multi-bucket operations. Bucket names must be specified explicitly in each operation call.

Usage: 

app := fx.New(
    minio.FXModule,
    // other modules...
)

Functions

func RegisterLifecycle 

func RegisterLifecycle(params MinioLifeCycleParams)

RegisterLifecycle registers the MinIO client with the fx lifecycle system. This function sets up proper initialization and graceful shutdown of the MinIO client, including starting and stopping the connection monitoring goroutines.

Parameters:

  • lc: The fx lifecycle controller
  • mi: The MinIO client instance
  • logger: Logger for recording lifecycle events

The function registers two background goroutines: 1. A connection monitor that checks for connection health 2. A retry mechanism that handles reconnection when needed

On application shutdown, it ensures these goroutines are properly terminated and waits for their completion before allowing the application to exit.

Types

type AMQPNotification 

type AMQPNotification struct {
	// Embed the common notification properties
	BaseNotification

	// URL is the AMQP server connection URL
	URL string

	// Exchange is the name of the AMQP exchange
	Exchange string

	// RoutingKey defines how messages are routed to queues
	RoutingKey string

	// ExchangeType defines the AMQP exchange type (e.g., "fanout", "direct")
	ExchangeType string

	// Mandatory flag requires messages to be routable
	Mandatory bool

	// Immediate flag requires immediate delivery
	Immediate bool

	// Durable flag makes the exchange survive broker restarts
	Durable bool

	// Internal flag makes the exchange only accessible to other exchanges
	Internal bool

	// NoWait flag makes declare operations non-blocking
	NoWait bool

	// AutoDeleted flag automatically deletes the exchange when no longer used
	AutoDeleted bool
}

AMQPNotification defines an AMQP notification target. AMQP notifications can be used with systems like RabbitMQ.

type BaseNotification 

type BaseNotification struct {
	// Events is a list of event types to subscribe to
	// Examples: "s3:ObjectCreated:*", "s3:ObjectRemoved:*"
	Events []string

	// Prefix filters notifications to only objects with this key prefix
	// Example: "uploads/" to only get events for objects in the uploads directory
	Prefix string

	// Suffix filters notifications to only objects with this key suffix
	// Example: ".jpg" to only get events for JPEG images
	Suffix string

	// Name is a unique identifier for this notification configuration
	Name string
}

BaseNotification contains common properties for all notification types. This is embedded in specific notification target types.

type BucketClient added in v1.3.0 

type BucketClient struct {
	// contains filtered or unexported fields
}

BucketClient is a convenience wrapper that automatically applies a bucket name to all operations. This is useful when performing multiple operations on the same bucket to avoid repeating the bucket name.

BucketClient is a lightweight wrapper with no state or lifecycle management - it simply forwards all calls to the underlying MinioClient with the bucket name pre-filled.

func (*BucketClient) AbortMultipartUpload added in v1.3.0 

func (bc *BucketClient) AbortMultipartUpload(ctx context.Context, objectKey, uploadID string) error

AbortMultipartUpload cancels a multipart upload in the bucket.

func (*BucketClient) CleanupIncompleteUploads added in v1.3.0 

func (bc *BucketClient) CleanupIncompleteUploads(ctx context.Context, prefix string, olderThan time.Duration) error

CleanupIncompleteUploads removes stale incomplete multipart uploads in the bucket.

func (*BucketClient) CompleteMultipartUpload added in v1.3.0 

func (bc *BucketClient) CompleteMultipartUpload(ctx context.Context, objectKey, uploadID string, partNumbers []int, etags []string) error

CompleteMultipartUpload finalizes a multipart upload in the bucket.

func (*BucketClient) Delete added in v1.3.0 

func (bc *BucketClient) Delete(ctx context.Context, objectKey string) error

Delete removes an object from the bucket associated with this BucketClient.

func (*BucketClient) GenerateMultipartPresignedGetURLs added in v1.3.0 

func (bc *BucketClient) GenerateMultipartPresignedGetURLs(
	ctx context.Context,
	objectKey string,
	partSize int64,
	expiry ...time.Duration,
) (MultipartPresignedGet, error)

GenerateMultipartPresignedGetURLs generates presigned URLs for downloading parts of an object from the bucket.

func (*BucketClient) GenerateMultipartUploadURLs added in v1.3.0 

func (bc *BucketClient) GenerateMultipartUploadURLs(
	ctx context.Context,
	objectKey string,
	fileSize int64,
	contentType string,
	expiry ...time.Duration,
) (MultipartUpload, error)

GenerateMultipartUploadURLs generates presigned URLs for multipart upload to the bucket.

func (*BucketClient) Get added in v1.3.0 

func (bc *BucketClient) Get(ctx context.Context, objectKey string, opts ...GetOption) ([]byte, error)

Get retrieves an object from the bucket associated with this BucketClient.

func (*BucketClient) ListIncompleteUploads added in v1.3.0 

func (bc *BucketClient) ListIncompleteUploads(ctx context.Context, prefix string) ([]minio.ObjectMultipartInfo, error)

ListIncompleteUploads lists all incomplete multipart uploads in the bucket.

func (*BucketClient) PreSignedGet added in v1.3.0 

func (bc *BucketClient) PreSignedGet(ctx context.Context, objectKey string) (string, error)

PreSignedGet generates a presigned URL for downloading an object from the bucket.

func (*BucketClient) PreSignedHeadObject added in v1.3.0 

func (bc *BucketClient) PreSignedHeadObject(ctx context.Context, objectKey string) (string, error)

PreSignedHeadObject generates a presigned URL for retrieving object metadata from the bucket.

func (*BucketClient) PreSignedPut added in v1.3.0 

func (bc *BucketClient) PreSignedPut(ctx context.Context, objectKey string) (string, error)

PreSignedPut generates a presigned URL for uploading an object to the bucket.

func (*BucketClient) Put added in v1.3.0 

func (bc *BucketClient) Put(ctx context.Context, objectKey string, reader io.Reader, opts ...PutOption) (int64, error)

Put uploads an object to the bucket associated with this BucketClient.

func (*BucketClient) StreamGet added in v1.3.0 

func (bc *BucketClient) StreamGet(ctx context.Context, objectKey string, chunkSize int) (<-chan []byte, <-chan error)

StreamGet retrieves an object in chunks from the bucket associated with this BucketClient.

type BucketInfo added in v1.3.0 

type BucketInfo struct {
	// Name is the name of the bucket
	Name string

	// CreationDate is when the bucket was created
	CreationDate time.Time
}

BucketInfo contains information about a bucket.

type BucketOption added in v1.3.0 

type BucketOption func(*BucketOptions)

BucketOption is a functional option for configuring bucket operations.

func WithObjectLocking added in v1.3.0 

func WithObjectLocking(enabled bool) BucketOption

WithObjectLocking enables object locking for the bucket. Object locking prevents objects from being deleted or overwritten.

Example: 

err := client.CreateBucket(ctx, "my-bucket",
    minio.WithObjectLocking(true))

func WithRegion added in v1.3.0 

func WithRegion(region string) BucketOption

WithRegion sets the region for bucket creation.

Example: 

err := client.CreateBucket(ctx, "my-bucket",
    minio.WithRegion("us-west-2"))

type BucketOptions added in v1.3.0 

type BucketOptions struct {
	// Region specifies the region where the bucket should be created
	Region string

	// ObjectLocking enables object locking for the bucket
	ObjectLocking bool
}

BucketOptions contains options for bucket operations.

type BufferPool 

type BufferPool struct {
	// contains filtered or unexported fields
}

BufferPool implements an advanced pool of bytes.Buffers with size limits and monitoring. It prevents memory leaks by limiting buffer sizes and pool capacity.

func NewBufferPool 

func NewBufferPool() *BufferPool

NewBufferPool creates a new BufferPool instance with default configuration. The pool will create new bytes.Buffer instances as needed when none are available, with built-in size limits to prevent memory leaks.

Returns a configured BufferPool ready for use.

func NewBufferPoolWithConfig 

func NewBufferPoolWithConfig(config BufferPoolConfig) *BufferPool

NewBufferPoolWithConfig creates a new BufferPool with custom configuration. This allows fine-tuning of buffer sizes and pool limits for specific use cases.

Parameters:

  • config: Configuration for buffer pool behavior

Returns a configured BufferPool ready for use.

func (*BufferPool) Cleanup 

func (bp *BufferPool) Cleanup()

Cleanup forces cleanup of the buffer pool, releasing all buffers. This is useful during shutdown or when memory pressure is high.

func (*BufferPool) Get 

func (bp *BufferPool) Get() *bytes.Buffer

Get returns a buffer from the pool. The returned buffer may be newly allocated or reused from a previous Put call. The buffer is automatically reset and ready for use.

Returns a *bytes.Buffer that should be returned to the pool when no longer needed.

func (*BufferPool) GetStats 

func (bp *BufferPool) GetStats() BufferPoolStats

GetStats returns current buffer pool statistics for monitoring. This is useful for understanding memory usage patterns and pool effectiveness.

func (*BufferPool) Put 

func (bp *BufferPool) Put(b *bytes.Buffer)

Put returns a buffer to the pool for future reuse. The buffer will be discarded if it exceeds the maximum size limit or if the pool is full. This prevents memory leaks from oversized buffers accumulating in the pool.

Parameters:

  • b: The buffer to return to the pool

type BufferPoolConfig 

type BufferPoolConfig struct {
	// MaxBufferSize is the maximum size a buffer can grow to before being discarded
	MaxBufferSize int
	// MaxPoolSize is the maximum number of buffers to keep in the pool
	MaxPoolSize int
	// InitialBufferSize is the initial size for new buffers
	InitialBufferSize int
}

BufferPoolConfig contains configuration for the buffer pool

func DefaultBufferPoolConfig 

func DefaultBufferPoolConfig() BufferPoolConfig

DefaultBufferPoolConfig returns the default buffer pool configuration

type BufferPoolStats 

type BufferPoolStats struct {
	// CurrentPoolSize is the current number of buffers in the pool
	CurrentPoolSize int64 `json:"currentPoolSize"`
	// TotalBuffersCreated is the total number of buffers created since start
	TotalBuffersCreated int64 `json:"totalBuffersCreated"`
	// TotalBuffersReused is the total number of buffer reuses
	TotalBuffersReused int64 `json:"totalBuffersReused"`
	// TotalBuffersDiscarded is the total number of buffers discarded due to limits
	TotalBuffersDiscarded int64 `json:"totalBuffersDiscarded"`
	// MaxBufferSize is the maximum allowed buffer size
	MaxBufferSize int `json:"maxBufferSize"`
	// MaxPoolSize is the maximum allowed pool size
	MaxPoolSize int `json:"maxPoolSize"`
	// ReuseRatio is the ratio of reused buffers to created buffers
	ReuseRatio float64 `json:"reuseRatio"`
}

Stats returns statistics about buffer pool usage for monitoring and debugging.

type ByteRange added in v1.3.0 

type ByteRange struct {
	// Start is the starting byte position (inclusive)
	Start int64

	// End is the ending byte position (inclusive)
	End int64
}

ByteRange represents a byte range for partial object retrieval.

type Client added in v0.12.0 

type Client interface {

	// Put uploads an object to the specified bucket in MinIO storage.
	Put(ctx context.Context, bucket, objectKey string, reader io.Reader, opts ...PutOption) (int64, error)

	// Get retrieves an object from the specified bucket in MinIO storage and returns its contents.
	Get(ctx context.Context, bucket, objectKey string, opts ...GetOption) ([]byte, error)

	// StreamGet retrieves an object from the specified bucket in chunks, useful for large files.
	StreamGet(ctx context.Context, bucket, objectKey string, chunkSize int) (<-chan []byte, <-chan error)

	// Delete removes an object from the specified bucket in MinIO storage.
	Delete(ctx context.Context, bucket, objectKey string) error

	// CreateBucket creates a new bucket with the specified name and options.
	CreateBucket(ctx context.Context, bucket string, opts ...BucketOption) error

	// DeleteBucket removes an empty bucket.
	DeleteBucket(ctx context.Context, bucket string) error

	// BucketExists checks if a bucket exists.
	BucketExists(ctx context.Context, bucket string) (bool, error)

	// ListBuckets returns a list of all buckets.
	ListBuckets(ctx context.Context) ([]BucketInfo, error)

	// PreSignedPut generates a presigned URL for uploading an object to the specified bucket.
	PreSignedPut(ctx context.Context, bucket, objectKey string) (string, error)

	// PreSignedGet generates a presigned URL for downloading an object from the specified bucket.
	PreSignedGet(ctx context.Context, bucket, objectKey string) (string, error)

	// PreSignedHeadObject generates a presigned URL for retrieving object metadata from the specified bucket.
	PreSignedHeadObject(ctx context.Context, bucket, objectKey string) (string, error)

	// GenerateMultipartUploadURLs generates presigned URLs for multipart upload to the specified bucket.
	GenerateMultipartUploadURLs(
		ctx context.Context,
		bucket, objectKey string,
		fileSize int64,
		contentType string,
		expiry ...time.Duration,
	) (MultipartUpload, error)

	// CompleteMultipartUpload finalizes a multipart upload in the specified bucket.
	CompleteMultipartUpload(ctx context.Context, bucket, objectKey, uploadID string, partNumbers []int, etags []string) error

	// AbortMultipartUpload cancels a multipart upload in the specified bucket.
	AbortMultipartUpload(ctx context.Context, bucket, objectKey, uploadID string) error

	// ListIncompleteUploads lists all incomplete multipart uploads in the specified bucket.
	ListIncompleteUploads(ctx context.Context, bucket, prefix string) ([]minio.ObjectMultipartInfo, error)

	// CleanupIncompleteUploads removes stale incomplete multipart uploads in the specified bucket.
	CleanupIncompleteUploads(ctx context.Context, bucket, prefix string, olderThan time.Duration) error

	// GenerateMultipartPresignedGetURLs generates presigned URLs for downloading parts of an object from the specified bucket.
	GenerateMultipartPresignedGetURLs(
		ctx context.Context,
		bucket, objectKey string,
		partSize int64,
		expiry ...time.Duration,
	) (MultipartPresignedGet, error)

	// GetBufferPoolStats returns buffer pool statistics.
	GetBufferPoolStats() BufferPoolStats

	// CleanupResources performs cleanup of buffer pools and forces garbage collection.
	CleanupResources()

	// TranslateError converts MinIO-specific errors into standardized application errors.
	TranslateError(err error) error

	// GetErrorCategory returns the category of an error.
	GetErrorCategory(err error) ErrorCategory

	// IsRetryableError checks if an error can be retried.
	IsRetryableError(err error) bool

	// IsTemporaryError checks if an error is temporary.
	IsTemporaryError(err error) bool

	// IsPermanentError checks if an error is permanent.
	IsPermanentError(err error) bool

	// GracefulShutdown safely terminates all MinIO client operations.
	GracefulShutdown()

	// Bucket returns a BucketClient that automatically uses the specified bucket for all operations.
	// This is a convenience wrapper for when you perform multiple operations on the same bucket.
	Bucket(name string) *BucketClient
}

Client provides a high-level interface for interacting with MinIO/S3-compatible storage. It abstracts object storage operations with features like multipart uploads, presigned URLs, and resource monitoring.

This interface is implemented by the concrete *MinioClient type.

Multi-bucket support: All object operations now require an explicit bucket parameter, enabling operations across multiple buckets with a single client instance.

type Config 

type Config struct {
	// Connection contains basic connection parameters for the MinIO server
	Connection ConnectionConfig

	// UploadConfig defines parameters related to uploading objects
	UploadConfig UploadConfig

	// DownloadConfig defines parameters related to downloading objects
	DownloadConfig DownloadConfig

	// PresignedConfig contains settings for generating presigned URLs
	PresignedConfig PresignedConfig

	// Notification defines event notification configuration
	Notification NotificationConfig
}

Config defines the top-level configuration for MinIO. This structure contains all configuration options for the MinIO client, organized into logical sections for different aspects of functionality.

type ConnectionConfig 

type ConnectionConfig struct {
	// Endpoint is the MinIO server address (e.g., "minio.example.com:9000")
	Endpoint string

	// AccessKeyID is the MinIO access key (similar to a username)
	AccessKeyID string

	// SecretAccessKey is the MinIO secret key (similar to a password)
	SecretAccessKey string

	// UseSSL determines whether to use HTTPS (true) or HTTP (false)
	UseSSL bool

	// Region specifies the S3 region (e.g., "us-east-1")
	Region string
}

ConnectionConfig contains MinIO server connection details. These parameters are required to establish a connection to a MinIO server.

type ConnectionPoolConfig 

type ConnectionPoolConfig struct {
	// MaxIdleConnections is the maximum number of idle connections to maintain
	MaxIdleConnections int
	// MaxConnectionsPerHost is the maximum connections per host
	MaxConnectionsPerHost int
	// IdleConnectionTimeout is how long to keep idle connections
	IdleConnectionTimeout time.Duration
	// ConnectionTimeout is the timeout for establishing connections
	ConnectionTimeout time.Duration
}

ConnectionPoolConfig contains configuration for connection management

func DefaultConnectionPoolConfig 

func DefaultConnectionPoolConfig() ConnectionPoolConfig

DefaultConnectionPoolConfig returns default connection pool configuration

type DownloadConfig 

type DownloadConfig struct {
	// SmallFileThreshold is the size in bytes below which a file is considered "small"
	// Small files use a simpler, direct download approach
	SmallFileThreshold int64

	// InitialBufferSize is the starting buffer size in bytes for downloading large files
	// This affects memory usage when downloading large objects
	InitialBufferSize int

	// DefaultMultipartDownload is the default size of parts to download at each part
	DefaultMultipartDownload int
}

DownloadConfig defines parameters that control download behavior. These settings optimize memory usage when downloading objects of different sizes.

type ErrorCategory 

type ErrorCategory int

ErrorCategory represents different categories of MinIO errors 

const (
	CategoryUnknown ErrorCategory = iota
	CategoryConnection
	CategoryAuthentication
	CategoryPermission
	CategoryNotFound
	CategoryConflict
	CategoryValidation
	CategoryServer
	CategoryNetwork
	CategoryTimeout
	CategoryQuota
	CategoryConfiguration
	CategoryVersioning
	CategoryLocking
	CategoryOperation
)

type GetOption added in v1.3.0 

type GetOption func(*GetOptions)

GetOption is a functional option for configuring Get operations.

func WithByteRange added in v1.3.0 

func WithByteRange(start, end int64) GetOption

WithByteRange retrieves only a specific byte range of an object. Useful for partial downloads or streaming specific portions.

Example: 

data, err := client.Get(ctx, bucket, key,
    minio.WithByteRange(0, 1023)) // First 1KB

func WithVersionID added in v1.3.0 

func WithVersionID(versionID string) GetOption

WithVersionID retrieves a specific version of an object (for versioned buckets).

Example: 

data, err := client.Get(ctx, bucket, key,
    minio.WithVersionID("version-id-here"))

type GetOptions added in v1.3.0 

type GetOptions struct {
	// VersionID specifies a particular version of an object to retrieve
	VersionID string

	// Range specifies a byte range to retrieve
	Range *ByteRange
}

GetOptions contains options for Get operations.

type KafkaNotification 

type KafkaNotification struct {
	// Embed the common notification properties
	BaseNotification

	// Brokers is a list of Kafka broker addresses
	Brokers []string

	// Topic is the Kafka topic where events will be published
	Topic string

	// SASL contains optional SASL authentication details for Kafka
	SASL *KafkaSASLAuth
}

KafkaNotification defines a Kafka notification target. Kafka notifications publish events to a Kafka topic.

type KafkaSASLAuth 

type KafkaSASLAuth struct {
	// Enable turns on SASL authentication
	Enable bool

	// Username for SASL authentication
	Username string

	// Password for SASL authentication
	Password string
}

KafkaSASLAuth contains Kafka SASL authentication details. SASL is used for authenticating with Kafka brokers.

type Logger added in v0.13.0 

type Logger interface {
	// InfoWithContext logs an informational message with trace context.
	InfoWithContext(ctx context.Context, msg string, err error, fields ...map[string]interface{})

	// WarnWithContext logs a warning message with trace context.
	WarnWithContext(ctx context.Context, msg string, err error, fields ...map[string]interface{})

	// ErrorWithContext logs an error message with trace context.
	ErrorWithContext(ctx context.Context, msg string, err error, fields ...map[string]interface{})
}

Logger is an interface that matches the std/v1/logger.Logger interface. It provides context-aware structured logging with optional error and field parameters.

type MQTTNotification 

type MQTTNotification struct {
	// Embed the common notification properties
	BaseNotification

	// Broker is the MQTT broker address (host:port)
	Broker string

	// Topic is the MQTT topic where events will be published
	Topic string

	// QoS (Quality of Service) level for message delivery:
	// 0: At most once (fire and forget)
	// 1: At least once (acknowledged delivery)
	// 2: Exactly once (assured delivery)
	QoS byte

	// Username for MQTT broker authentication
	Username string

	// Password for MQTT broker authentication
	Password string

	// Reconnect flag enables automatic reconnection on connection loss
	Reconnect bool
}

MQTTNotification defines an MQTT notification target. MQTT notifications publish events to an MQTT broker.

type MinioClient added in v0.12.0 

type MinioClient struct {
	// contains filtered or unexported fields
}

MinioClient represents a MinIO client with additional functionality. It wraps the standard MinIO client with features for connection management, reconnection handling, and resource monitoring.

func NewClient 

func NewClient(config Config) (*MinioClient, error)

NewClient creates and validates a new MinIO client. It establishes connections to both the standard and core MinIO APIs, validates the connection, and ensures the configured bucket exists.

Parameters:

  • config: Configuration for the MinIO client

Returns a configured and validated MinioClient or an error if initialization fails.

Example: 

client, err := minio.NewClient(config)
if err != nil {
    return fmt.Errorf("failed to initialize MinIO client: %w", err)
}

// Optionally attach logger and observer
client = client.
    WithLogger(myLogger).
    WithObserver(myObserver)

defer client.GracefulShutdown()

func NewMinioClientWithDI 

func NewMinioClientWithDI(params MinioParams) (*MinioClient, error)

func (*MinioClient) AbortMultipartUpload added in v0.12.0 

func (m *MinioClient) AbortMultipartUpload(ctx context.Context, bucket, objectKey, uploadID string) error

AbortMultipartUpload aborts a multipart upload. This method cancels an in-progress multipart upload and removes any parts that have already been uploaded.

Parameters:

  • ctx: Context for the operation
  • objectKey: Path and name of the object in the bucket
  • uploadID: The upload ID to abort

Returns an error if the abort operation fails.

Example: 

err := minioClient.AbortMultipartUpload(ctx, "uploads/myfile.zip", uploadID)

func (*MinioClient) Bucket added in v1.3.0 

func (m *MinioClient) Bucket(name string) *BucketClient

Bucket returns a BucketClient that automatically uses the specified bucket for all operations. This is a convenience method for when you perform multiple operations on the same bucket.

Parameters:

  • name: The name of the bucket to use for all operations

Returns a BucketClient that wraps the underlying client.

Example: 

// Get a scoped client for a specific bucket
userBucket := client.Bucket("user-uploads")

// All operations use "user-uploads" bucket automatically
userBucket.Put(ctx, "avatar.jpg", file)
data, _ := userBucket.Get(ctx, "profile.jpg")
userBucket.Delete(ctx, "old-file.txt")

func (*MinioClient) BucketExists added in v1.3.0 

func (m *MinioClient) BucketExists(ctx context.Context, bucket string) (bool, error)

BucketExists checks if a bucket exists.

Parameters:

  • ctx: Context for controlling the operation
  • bucket: Name of the bucket to check

Returns true if the bucket exists, false otherwise, or an error if the check fails.

Example: 

exists, err := minioClient.BucketExists(ctx, "my-bucket")
if err != nil {
    log.Fatalf("Failed to check bucket: %v", err)
}
if !exists {
    fmt.Println("Bucket does not exist")
}

func (*MinioClient) CleanupIncompleteUploads added in v0.12.0 

func (m *MinioClient) CleanupIncompleteUploads(ctx context.Context, bucket, prefix string, olderThan time.Duration) error

CleanupIncompleteUploads aborts any incomplete uploads older than the given duration. This method helps maintain storage hygiene by removing abandoned upload sessions.

Parameters:

  • ctx: Context for the operation
  • prefix: Optional prefix to filter objects by key
  • olderThan: Only abort uploads older than this duration

Return an error if the cleanup operation fails.

Example: 

// Abort all incomplete uploads in the "uploads/" prefix that are older than 24 hours
err := minioClient.CleanupIncompleteUploads(ctx, "uploads/", 24*time.Hour)

func (*MinioClient) CleanupResources added in v0.12.0 

func (m *MinioClient) CleanupResources()

CleanupResources performs cleanup of buffer pools and forces garbage collection. This method is useful during shutdown or when memory pressure is high.

Example: 

// Clean up resources during shutdown
defer minioClient.CleanupResources()

func (*MinioClient) CompleteMultipartUpload added in v0.12.0 

func (m *MinioClient) CompleteMultipartUpload(ctx context.Context, bucket, objectKey, uploadID string, partNumbers []int, etags []string) error

CompleteMultipartUpload finalizes a multipart upload by combining all parts. This method tells MinIO/S3 to assemble all the uploaded parts into the final object.

Parameters:

  • ctx: Context for the operation
  • objectKey: Path and name of the object in the bucket
  • uploadID: The upload ID of the multipart upload
  • partNumbers: Slice of part numbers in the order they were uploaded
  • etags: Slice of ETags for each part, must correspond to partNumbers

Returns an error if the completion fails.

Example: 

err := minioClient.CompleteMultipartUpload(
    ctx,
    "uploads/myfile.zip",
    uploadID,
    []int{1, 2, 3},
    []string{"etag1", "etag2", "etag3"},
)

func (*MinioClient) CreateBucket added in v1.3.0 

func (m *MinioClient) CreateBucket(ctx context.Context, bucket string, opts ...BucketOption) error

CreateBucket creates a new bucket with the specified name and options. This method creates a bucket if it doesn't already exist.

Parameters:

  • ctx: Context for controlling the operation
  • bucket: Name of the bucket to create
  • opts: Optional functional options for bucket configuration

Returns an error if the bucket creation fails.

Example: 

err := minioClient.CreateBucket(ctx, "my-bucket")
if err != nil {
    log.Fatalf("Failed to create bucket: %v", err)
}

func (*MinioClient) Delete added in v0.12.0 

func (m *MinioClient) Delete(ctx context.Context, bucket, objectKey string) error

Delete removes an object from the specified bucket. This method permanently deletes the object from MinIO storage.

Parameters:

  • ctx: Context for controlling the delete operation
  • bucket: Name of the bucket containing the object
  • objectKey: Path and name of the object to delete

Returns an error if the deletion fails.

Example: 

err := minioClient.Delete(ctx, "my-bucket", "documents/old-report.pdf")
if err == nil {
    fmt.Println("Object successfully deleted")
}

func (*MinioClient) DeleteBucket added in v1.3.0 

func (m *MinioClient) DeleteBucket(ctx context.Context, bucket string) error

DeleteBucket removes an empty bucket. The bucket must be empty before it can be deleted.

Parameters:

  • ctx: Context for controlling the operation
  • bucket: Name of the bucket to delete

Returns an error if the deletion fails.

Example: 

err := minioClient.DeleteBucket(ctx, "old-bucket")
if err != nil {
    log.Fatalf("Failed to delete bucket: %v", err)
}

func (*MinioClient) GenerateMultipartPresignedGetURLs added in v0.12.0 

func (m *MinioClient) GenerateMultipartPresignedGetURLs(
	ctx context.Context,
	bucket, objectKey string,
	partSize int64,
	expiry ...time.Duration,
) (MultipartPresignedGet, error)

GenerateMultipartPresignedGetURLs generates URLs for downloading an object in parts This method is useful for large objects that may benefit from parallel downloads or resumable downloads by clients.

Parameters:

  • ctx: Context for the operation
  • objectKey: Path and name of the object in the bucket
  • partSize: Size of each part in bytes (must be at least 5 MiB)
  • expiry: Optional custom expiration duration for the presigned URLs

Returns:

  • MultipartPresignedGet: Interface providing access to download details
  • error: Any error that occurred during setup

Example: 

download, err := minioClient.GenerateMultipartPresignedGetURLs(
    ctx,
    "documents/large-file.zip",
    10*1024*1024, // 10 MiB parts
    2*time.Hour,
)

func (*MinioClient) GenerateMultipartUploadURLs added in v0.12.0 

func (m *MinioClient) GenerateMultipartUploadURLs(
	ctx context.Context,
	bucket, objectKey string,
	fileSize int64,
	contentType string,
	expiry ...time.Duration,
) (MultipartUpload, error)

GenerateMultipartUploadURLs initiates a multipart upload and generates all necessary URLs. This method prepares everything needed for a client to directly upload multiple parts to MinIO/S3 without further server interaction until the upload is complete.

Parameters:

  • ctx: Context for the operation
  • objectKey: Path and name of the object in the bucket
  • fileSize: Total size of the file in bytes
  • contentType: MIME type of the file (defaults to "application/octet-stream" if empty)
  • expiry: Optional custom expiration duration for the presigned URLs

Returns:

  • MultipartUpload: Interface providing access to upload details
  • error: Any error that occurred during setup

Example: 

upload, err := minioClient.GenerateMultipartUploadURLs(
    ctx,
    "uploads/myfile.zip",
    fileSize,
    "application/zip",
    2*time.Hour,
)

func (*MinioClient) Get added in v0.12.0 

func (m *MinioClient) Get(ctx context.Context, bucket, objectKey string, opts ...GetOption) ([]byte, error)

Get retrieves an object from the specified bucket and returns its contents as a byte slice. This method is optimized for both small and large files with safety considerations for buffer use. For small files, it uses direct allocation, while for larger files it leverages a buffer pool to reduce memory pressure.

Parameters:

  • ctx: Context for controlling the download operation
  • bucket: Name of the bucket to download from
  • objectKey: Path and name of the object in the bucket
  • opts: Optional functional options for configuring the download (version, range, etc.)

Returns:

  • []byte: The object's contents as a byte slice
  • error: Any error that occurred during the download

Note: For very large files, consider using a streaming approach rather than loading the entire file into memory with this method.

Example: 

data, err := minioClient.Get(ctx, "my-bucket", "documents/report.pdf")
if err == nil {
    fmt.Printf("Downloaded %d bytes\n", len(data))
    ioutil.WriteFile("report.pdf", data, 0644)
}

func (*MinioClient) GetBufferPoolStats added in v0.12.0 

func (m *MinioClient) GetBufferPoolStats() BufferPoolStats

GetBufferPoolStats returns buffer pool statistics for monitoring buffer efficiency. This is useful for understanding memory usage patterns and optimizing buffer sizes.

Returns:

  • BufferPoolStats: Statistics about buffer pool usage and efficiency

Example: 

stats := minioClient.GetBufferPoolStats()
fmt.Printf("Buffer reuse ratio: %.2f%%\n", stats.ReuseRatio*100)
fmt.Printf("Buffers in pool: %d\n", stats.CurrentPoolSize)

func (*MinioClient) GetErrorCategory added in v0.12.0 

func (m *MinioClient) GetErrorCategory(err error) ErrorCategory

GetErrorCategory returns the category of the given error

func (*MinioClient) GracefulShutdown added in v0.12.0 

func (m *MinioClient) GracefulShutdown()

GracefulShutdown safely terminates all MinIO client operations and closes associated resources. This method ensures a clean shutdown process by using sync.Once to guarantee each channel is closed exactly once, preventing "close of closed channel" panics that could occur when multiple shutdown paths execute concurrently.

The shutdown process: 1. Safely closes the shutdownSignal channel to notify all monitoring goroutines to stop 2. Safely closes the reconnectSignal channel to terminate any reconnection attempts

This method is designed to be called from multiple potential places (such as application shutdown hooks, context cancellation handlers, or defer statements) without causing resource management issues. The use of sync.Once ensures that even if called multiple times, each cleanup operation happens exactly once.

Example usage: 

// In application shutdown code
func shutdownApp() {
    minioClient.GracefulShutdown()
    // other cleanup...
}

// Or with defer
func processFiles() {
    defer minioClient.GracefulShutdown()
    // processing logic...
}

func (*MinioClient) IsPermanentError added in v0.12.0 

func (m *MinioClient) IsPermanentError(err error) bool

IsPermanentError returns true if the error is permanent and should not be retried

func (*MinioClient) IsRetryableError added in v0.12.0 

func (m *MinioClient) IsRetryableError(err error) bool

IsRetryableError returns true if the error is retryable

func (*MinioClient) IsTemporaryError added in v0.12.0 

func (m *MinioClient) IsTemporaryError(err error) bool

IsTemporaryError returns true if the error is temporary

func (*MinioClient) ListBuckets added in v1.3.0 

func (m *MinioClient) ListBuckets(ctx context.Context) ([]BucketInfo, error)

ListBuckets returns a list of all buckets.

Parameters:

  • ctx: Context for controlling the operation

Returns a list of bucket information or an error if the listing fails.

Example: 

buckets, err := minioClient.ListBuckets(ctx)
if err != nil {
    log.Fatalf("Failed to list buckets: %v", err)
}
for _, bucket := range buckets {
    fmt.Printf("Bucket: %s, Created: %v\n", bucket.Name, bucket.CreationDate)
}

func (*MinioClient) ListIncompleteUploads added in v0.12.0 

func (m *MinioClient) ListIncompleteUploads(ctx context.Context, bucket, prefix string) ([]minio.ObjectMultipartInfo, error)

ListIncompleteUploads lists all incomplete multipart uploads for cleanup. This method retrieves information about multipart uploads that were started but never completed or aborted.

Parameters:

  • ctx: Context for the operation
  • prefix: Optional prefix to filter objects by key

Returns:

  • []minio.ObjectMultipartInfo: Information about incomplete uploads
  • error: Any error that occurred during the listing

Example: 

uploads, err := minioClient.ListIncompleteUploads(ctx, "uploads/")
if err == nil {
    for _, upload := range uploads {
        fmt.Printf("Incomplete upload: %s, started: %v\n", upload.Key, upload.Initiated)
    }
}

func (*MinioClient) PreSignedGet added in v0.12.0 

func (m *MinioClient) PreSignedGet(ctx context.Context, bucket, objectKey string) (string, error)

PreSignedGet generates a pre-signed URL for GetObject operations. This method creates a temporary URL that allows downloading an object without additional authentication.

Parameters:

  • ctx: Context for the operation
  • objectKey: Path and name of the object in the bucket

Returns:

  • string: The presigned URL for downloading the object
  • error: Any error that occurred during URL generation

Example: 

url, err := minioClient.PreSignedGet(ctx, "documents/report.pdf")
if err == nil {
    fmt.Printf("Download link: %s\n", url)
}

func (*MinioClient) PreSignedHeadObject added in v0.12.0 

func (m *MinioClient) PreSignedHeadObject(ctx context.Context, bucket, objectKey string) (string, error)

PreSignedHeadObject generates a pre-signed URL for HeadObject operations. This method creates a temporary URL that allows checking object metadata without downloading the object itself.

Parameters:

  • ctx: Context for the operation
  • objectKey: Path and name of the object in the bucket

Returns:

  • string: The presigned URL for the HEAD operation
  • error: Any error that occurred during URL generation

Example: 

url, err := minioClient.PreSignedHeadObject(ctx, "documents/report.pdf")
if err == nil {
    fmt.Printf("Use this URL to check if the object exists: %s\n", url)
}

func (*MinioClient) PreSignedPut added in v0.12.0 

func (m *MinioClient) PreSignedPut(ctx context.Context, bucket, objectKey string) (string, error)

PreSignedPut generates a pre-signed URL for PutObject operations. This method creates a temporary URL that allows uploading an object without additional authentication.

Parameters:

  • ctx: Context for the operation
  • objectKey: Path and name of the object in the bucket

Returns:

  • string: The presigned URL for uploading the object
  • error: Any error that occurred during URL generation

Example: 

url, err := minioClient.PreSignedPut(ctx, "documents/report.pdf")
if err == nil {
    fmt.Printf("Upload link: %s\n", url)
}

func (*MinioClient) Put added in v0.12.0 

func (m *MinioClient) Put(ctx context.Context, bucket, objectKey string, reader io.Reader, opts ...PutOption) (int64, error)

Put uploads an object to the specified bucket. This method handles the direct upload of data to MinIO, managing both the transfer and proper error handling.

Parameters:

  • ctx: Context for controlling the upload operation
  • bucket: Name of the bucket to upload to
  • objectKey: Path and name of the object in the bucket
  • reader: Source of the data to upload
  • opts: Optional functional options for configuring the upload (size, content type, etc.)

Returns:

  • int64: The number of bytes uploaded
  • error: Any error that occurred during the upload

Example: 

file, _ := os.Open("document.pdf")
defer file.Close()

fileInfo, _ := file.Stat()
size, err := minioClient.Put(ctx, "my-bucket", "documents/document.pdf", file,
    WithSize(fileInfo.Size()),
    WithContentType("application/pdf"))
if err == nil {
    fmt.Printf("Uploaded %d bytes\n", size)
}

func (*MinioClient) StreamGet added in v0.12.0 

func (m *MinioClient) StreamGet(ctx context.Context, bucket, objectKey string, chunkSize int) (<-chan []byte, <-chan error)

StreamGet downloads a file from the specified bucket and sends chunks through a channel.

Parameters:

  • ctx: Context for controlling the download operation
  • bucket: Name of the bucket to download from
  • objectKey: Path and name of the object in the bucket
  • chunkSize: Size of each chunk in bytes

Returns:

  • <-chan []byte: Channel that receives data chunks
  • <-chan error: Channel that receives any error that occurred

func (*MinioClient) TranslateError added in v0.12.0 

func (m *MinioClient) TranslateError(err error) error

TranslateError converts MinIO-specific errors into standardized application errors. This function provides abstraction from the underlying MinIO implementation details, allowing application code to handle errors in a MinIO-agnostic way.

It maps common MinIO errors to the standardized error types defined above. If an error doesn't match any known type, it's returned unchanged.

func (*MinioClient) WithLogger added in v0.13.0 

func (m *MinioClient) WithLogger(logger Logger) *MinioClient

WithLogger attaches a logger to the MinIO client for internal logging. This method uses the builder pattern and returns the client for method chaining.

The logger will be used for lifecycle events, connection monitoring, and error logging. This is particularly useful for debugging and monitoring connection health.

This is useful for non-FX usage where you want to enable logging after creating the client. When using FX, the logger is automatically injected via NewClientWithDI.

Example: 

client, err := minio.NewClient(config)
if err != nil {
    return err
}
client = client.WithLogger(myLogger)
defer client.GracefulShutdown()

func (*MinioClient) WithObserver added in v0.13.0 

func (m *MinioClient) WithObserver(observer observability.Observer) *MinioClient

WithObserver attaches an observer to the MinIO client for observability hooks. This method uses the builder pattern and returns the client for method chaining.

The observer will be notified of all storage operations, allowing external systems to track metrics, traces, or other observability data.

This is useful for non-FX usage where you want to attach an observer after creating the client. When using FX, the observer is automatically injected via NewClientWithDI.

Example: 

client, err := minio.NewClient(config)
if err != nil {
    return err
}
client = client.WithObserver(myObserver)
defer client.GracefulShutdown()

type MinioLifeCycleParams 

type MinioLifeCycleParams struct {
	fx.In

	Lifecycle fx.Lifecycle
	Minio     *MinioClient
}

type MinioParams 

type MinioParams struct {
	fx.In

	Config   Config
	Logger   Logger                 `optional:"true"`
	Observer observability.Observer `optional:"true"`
}

type MultipartPresignedGet 

type MultipartPresignedGet interface {
	// GetObjectKey returns the object key for this download
	GetObjectKey() string

	// GetPresignedURLs returns all presigned URLs for this download
	GetPresignedURLs() []string

	// GetPartRanges returns all byte ranges corresponding to the URLs
	GetPartRanges() []string

	// GetExpiryTimestamp returns the Unix timestamp when these URLs expire
	GetExpiryTimestamp() int64

	// GetTotalSize returns the total size of the object in bytes
	GetTotalSize() int64

	// GetContentType returns the content type of the object
	GetContentType() string

	// GetETag returns the ETag of the object
	GetETag() string

	// IsExpired checks if the download URLs have expired
	IsExpired() bool
}

MultipartPresignedGet is an interface for accessing multipart download info

type MultipartPresignedGetInfo 

type MultipartPresignedGetInfo struct {
	// ObjectKey is the path and name of the object in the bucket
	ObjectKey string `json:"objectKey"`

	// PresignedUrls is a slice of temporary URLs for downloading each part
	PresignedUrls []string `json:"presignedUrls"`

	// PartRanges contains the byte ranges for each part
	PartRanges []string `json:"partRanges"`

	// ExpiresAt is the Unix timestamp when the presigned URLs will expire
	ExpiresAt int64 `json:"expiresAt"`

	// TotalSize is the total size of the object in bytes
	TotalSize int64 `json:"totalSize"`

	// ContentType is the MIME type of the object
	ContentType string `json:"contentType"`

	// ETag is the entity tag of the object
	ETag string `json:"etag"`
}

MultipartPresignedGetInfo contains information for downloading an object in parts

type MultipartUpload 

type MultipartUpload interface {
	// GetUploadID returns the unique identifier for this multipart upload
	GetUploadID() string

	// GetObjectKey returns the object key for this upload
	GetObjectKey() string

	// GetPresignedURLs returns all presigned URLs for this upload
	GetPresignedURLs() []string

	// GetPartNumbers returns all part numbers corresponding to the URLs
	GetPartNumbers() []int

	// GetExpiryTimestamp returns the Unix timestamp when this upload expires
	GetExpiryTimestamp() int64

	// GetRecommendedPartSize returns the recommended size for each part in bytes
	GetRecommendedPartSize() int64

	// GetMaxParts returns the maximum number of parts allowed
	GetMaxParts() int

	// GetContentType returns the content type of the object
	GetContentType() string

	// GetTotalSize returns the total size of the object in bytes
	GetTotalSize() int64

	// IsExpired checks if the upload has expired
	IsExpired() bool
}

MultipartUpload represents a multipart upload session. This interface provides methods to access information about a multipart upload while hiding the internal implementation details.

type MultipartUploadInfo 

type MultipartUploadInfo struct {
	// UploadID is the unique identifier for the multipart upload provided by MinIO/S3
	UploadID string `json:"uploadId"`

	// ObjectKey is the path and name of the object in the bucket
	ObjectKey string `json:"objectKey"`

	// PresignedUrls is a slice of temporary URLs for uploading each part
	PresignedUrls []string `json:"presignedUrls"`

	// PartNumbers contains the part numbers corresponding to each URL in PresignedUrls
	PartNumbers []int `json:"partNumbers"`

	// ExpiresAt is the Unix timestamp when the presigned URLs will expire
	ExpiresAt int64 `json:"expiresAt"`

	// RecommendedPartSize is the suggested size in bytes for each part for optimal performance
	RecommendedPartSize int64 `json:"recommendedPartSize"`

	// MaxParts is the maximum number of parts allowed for this upload (S3 limit)
	MaxParts int `json:"maxParts"`

	// ContentType is the MIME type of the object being uploaded
	ContentType string `json:"contentType"`

	// TotalSize is the total size of the object in bytes
	TotalSize int64 `json:"totalSize"`
}

MultipartUploadInfo contains all information needed for a multipart upload. This structure holds all the details required for managing and completing a multipart upload, including upload identifiers, presigned URLs for each part, and sizing information.

type NotificationConfig 

type NotificationConfig struct {
	// Enabled determines whether event notifications are active
	Enabled bool

	// Webhook contains configuration for webhook notification targets
	Webhook []WebhookNotification

	// AMQP contains configuration for AMQP (RabbitMQ, etc.) notification targets
	AMQP []AMQPNotification

	// Redis contains configuration for Redis notification targets
	Redis []RedisNotification

	// Kafka contains configuration for Kafka notification targets
	Kafka []KafkaNotification

	// MQTT contains configuration for MQTT notification targets
	MQTT []MQTTNotification
}

NotificationConfig defines the configuration for event notifications. MinIO can send notifications when events occur on buckets (e.g., object created).

type PresignedConfig 

type PresignedConfig struct {
	// Enabled determines whether presigned URL functionality is available
	Enabled bool

	// ExpiryDuration sets how long presigned URLs remain valid
	// Example: 15 * time.Minute for 15-minute expiration
	ExpiryDuration time.Duration

	// BaseURL allows overriding the host/domain in generated presigned URLs
	// Useful when using a CDN or custom domain in front of MinIO
	// Example: "https://cdn.example.com"
	BaseURL string
}

PresignedConfig contains configuration options for presigned URLs. Presigned URLs allow temporary access to objects without requiring AWS credentials.

type PutOption added in v1.3.0 

type PutOption func(*PutOptions)

PutOption is a functional option for configuring Put operations.

func WithContentType added in v1.3.0 

func WithContentType(contentType string) PutOption

WithContentType sets the MIME type of the object being uploaded.

Example: 

client.Put(ctx, bucket, key, reader,
    minio.WithSize(fileSize),
    minio.WithContentType("application/json"))

func WithMetadata added in v1.3.0 

func WithMetadata(metadata map[string]string) PutOption

WithMetadata adds custom metadata to the object being uploaded. Metadata is stored as key-value pairs and can be retrieved later.

Example: 

client.Put(ctx, bucket, key, reader,
    minio.WithMetadata(map[string]string{
        "user-id": "12345",
        "version": "v2",
    }))

func WithPartSize added in v1.3.0 

func WithPartSize(partSize uint64) PutOption

WithPartSize sets a custom part size for multipart uploads. This overrides the default part size from the configuration.

Example: 

client.Put(ctx, bucket, key, reader,
    minio.WithPartSize(10 * 1024 * 1024)) // 10 MB parts

func WithSize added in v1.3.0 

func WithSize(size int64) PutOption

WithSize sets the size of the object being uploaded. This is important for optimal upload performance and progress tracking.

Example: 

client.Put(ctx, bucket, key, reader, minio.WithSize(fileSize))

type PutOptions added in v1.3.0 

type PutOptions struct {
	// Size is the size of the object in bytes. If not specified, size is unknown.
	Size int64

	// ContentType is the MIME type of the object
	ContentType string

	// Metadata is custom metadata to attach to the object
	Metadata map[string]string

	// PartSize is the part size for multipart uploads
	PartSize uint64
}

PutOptions contains options for Put operations.

type RedisNotification 

type RedisNotification struct {
	// Embed the common notification properties
	BaseNotification

	// Addr is the Redis server address (host:port)
	Addr string

	// Password is the Redis server password, if required
	Password string

	// Key is the Redis key where events will be published
	Key string
}

RedisNotification defines a Redis notification target. Redis notifications publish events to a Redis pub/sub channel or list.

type UploadConfig 

type UploadConfig struct {
	// MaxObjectSize is the maximum size in bytes allowed for a single object
	// Default: 5 TiB (S3 specification limit)
	MaxObjectSize int64

	// MinPartSize is the minimum size in bytes for each part in a multipart upload
	// Default: 5 MiB (S3 specification minimum)
	MinPartSize uint64

	// MultipartThreshold is the size in bytes above which an upload automatically
	// switches to multipart mode for better performance
	// Default: 50 MiB
	MultipartThreshold int64

	// DefaultContentType is the default MIME type to use for uploaded objects
	DefaultContentType string
}

UploadConfig defines the configuration for upload constraints. These parameters control how objects are uploaded, particularly for large objects.

type WebhookNotification 

type WebhookNotification struct {
	// Embed the common notification properties
	BaseNotification

	// Endpoint is the URL where webhook notifications will be sent
	Endpoint string

	// AuthToken is an optional token for authenticating with the webhook endpoint
	AuthToken string
}

WebhookNotification defines a webhook notification target. Webhook notifications send HTTP POST requests to a specified endpoint.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.