feat(storage-minio): initial implementation — MinIO/S3 object storage with lifecycle (v1.0.0)

Introduces code.nochebuena.dev/einherjar/storage-minio — the object storage
starter for the Einherjar framework. Absorbs the minio package from micro-lib,
replacing fmt.Errorf wrapping with core/xerrors.

Interfaces (CT-6: one TypeSpec per file):
- Provider — PutObject, RemoveObject, GetObject, PresignedGetObject, HandleError
- Component — lifecycle.Component + observability.Checkable + Provider + Native()

Implementation:
- New(logger, cfg) Component — client not created until OnInit
- OnInit: minio.New with credentials and transport; bucket existence check
- OnStart: BucketExists PING; logs "minio: connected"
- OnStop: logs "minio: closing client" (minio-go is stateless; no explicit close)
- HealthCheck: BucketExists check; Priority LevelCritical
- Native() *miniogo.Client — escape hatch for operations not in Provider
- HandleError: maps minio-go errors to xerrors (NotFound, AlreadyExists, Internal)

Config (EINHERJAR_MINIO_* env vars):
  Endpoint(required), AccessKey(required), SecretKey(required),
  Bucket(required), UseSSL(false), Region(us-east-1)

- Component interface embeds observability.Identifiable; identifiable.go implements
  ModulePath and ModuleVersion via runtime/debug.ReadBuildInfo() — prints in launcher banner
This commit is contained in:
2026-05-29 16:03:52 +00:00
commit 1a34b84ee9
17 changed files with 1976 additions and 0 deletions

43
doc.go Normal file
View File

@@ -0,0 +1,43 @@
// Package minio provides a MinIO/S3-compatible object storage component with
// lifecycle management and health check integration.
//
// # Lifecycle
//
// The component follows the lifecycle.Component contract:
// - OnInit: initializes the minio-go SDK client from Config.
// - OnStart: verifies the configured bucket exists; creates it if absent.
// - OnStop: releases the client reference.
//
// Register with the launcher and health aggregator before starting:
//
// mc := minio.New(logger, cfg)
// launcher.Register(mc)
// health.Register(mc)
//
// # Operations
//
// Component embeds Provider, which covers the four most common bucket operations.
// For operations outside that set, use Native() to access the underlying minio-go client:
//
// _, err := mc.PutObject(ctx, bucket, key, reader, size, miniogo.PutObjectOptions{})
// native := mc.Native() // *miniogo.Client
//
// # Error Handling
//
// All Provider methods translate minio-go errors to core/xerrors types at the boundary.
// The standalone HandleError function provides the same translation for callers using Native():
//
// xerrors.ErrNotFound — NoSuchBucket, NoSuchKey
// xerrors.ErrPermissionDenied — AccessDenied, InvalidAccessKeyID
// xerrors.ErrAlreadyExists — BucketAlreadyExists, BucketAlreadyOwnedByYou
// xerrors.ErrInternal — all other errors
//
// # Configuration
//
// EINHERJAR_MINIO_ENDPOINT — required; MinIO server address (e.g. "minio:9000")
// EINHERJAR_MINIO_ACCESS_KEY — required
// EINHERJAR_MINIO_SECRET_KEY — required
// EINHERJAR_MINIO_BUCKET — required; bucket checked/created at startup
// EINHERJAR_MINIO_USE_SSL — optional; default false
// EINHERJAR_MINIO_REGION — optional; default "us-east-1"
package minio