minio/README.md

# minio

MinIO (S3-compatible) client with [go-kit](https://code.nochebuena.dev/go) launcher lifecycle and health check integration.

## Install

```sh
go get code.nochebuena.dev/go/minio
```

## Usage

```go
package main

import (
    miniomw "code.nochebuena.dev/go/minio"
    "code.nochebuena.dev/go/health"
    "code.nochebuena.dev/go/launcher"
    "code.nochebuena.dev/go/logz"
)

func main() {
    logger := logz.New(logz.Options{})

    cfg := miniomw.Config{
        Endpoint:  "minio:9000",
        AccessKey: "minioadmin",
        SecretKey: "minioadmin",
        UseSSL:    false,
        Bucket:    "my-app-assets",
        Region:    "us-east-1",
    }

    mc := miniomw.New(logger, cfg)

    lc := launcher.New(logger)
    lc.Append(mc)

    lc.BeforeStart(func() error {
        // Register health check
        _ = health.NewHandler(logger, mc)

        // Use the native minio-go client for direct SDK operations
        native := mc.Native()
        _ = native // PutObject, RemoveObject, PresignedGetObject, etc.

        return nil
    })

    if err := lc.Run(); err != nil {
        panic(err)
    }
}
```

## Config environment variables

| Variable          | Required | Default      | Description                                  |
|-------------------|----------|--------------|----------------------------------------------|
| `MINIO_ENDPOINT`  | Yes      | —            | MinIO API host and port, e.g. `minio:9000`   |
| `MINIO_ACCESS_KEY`| Yes      | —            | Access key (username)                        |
| `MINIO_SECRET_KEY`| Yes      | —            | Secret key (password)                        |
| `MINIO_BUCKET`    | Yes      | —            | Default bucket; created at startup if absent |
| `MINIO_USE_SSL`   | No       | `false`      | Enable TLS for the connection                |
| `MINIO_REGION`    | No       | `us-east-1`  | Region; default covers all self-hosted MinIO |

## Lifecycle

| Hook       | Behaviour                                                        |
|------------|------------------------------------------------------------------|
| `OnInit`   | Constructs the minio-go SDK client; no network call              |
| `OnStart`  | Checks whether the configured bucket exists; creates it if not  |
| `OnStop`   | No-op — the minio-go client is stateless                         |

## Health check

`HealthCheck(ctx)` calls `BucketExists` on the configured bucket. Priority is `health.LevelCritical`.

## Multiple buckets

Each `Component` is bound to one bucket for health checks and startup init. For multiple buckets, instantiate multiple components with different configs. Use object key namespacing (e.g. `products/{id}/{uuid}.ext`) for logical separation within a single bucket.

## Direct SDK access

`Native()` returns the underlying `*minio.Client` from `github.com/minio/minio-go/v7`. Use it for all object operations:

```go
native := mc.Native()

// Upload
_, err := native.PutObject(ctx, "my-bucket", "products/abc/img.jpg", reader, size,
    minio.PutObjectOptions{ContentType: "image/jpeg"})

// Delete
err = native.RemoveObject(ctx, "my-bucket", "products/abc/img.jpg",
    minio.RemoveObjectOptions{})

// Presigned URL (e.g. 1 hour)
url, err := native.PresignedGetObject(ctx, "my-bucket", "products/abc/img.jpg",
    time.Hour, nil)
```