clients3

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 16 Imported by: 0

README

client-s3

S3-compatible object storage client for omcrgnt apps (AWS S3 / MinIO): ecfg catalog resource, AWS SDK Go v2 under the hood, OpenTelemetry traces via otelaws + smithy adapters.

One client instance binds to one bucket. Credentials are a separate SDI port (CredentialsProvider), wired like srv-http.Server[T].

Catalog

import clients3 "github.com/omcrgnt/client-s3"

type static = clients3.CredentialsStatic[clients3.Default]

type catalog struct {
	S3     *clients3.Client[*static] `ecfg:"S3"`
	S3Cred *static                   `ecfg:"S3_CREDENTIALS_STATIC"`
}

Client[C] depends on concrete credentials type C.
CredentialsStatic[Tag] — Tag is a phantom type for SDI when you need more than one static set. A local alias (type static = …) keeps the catalog readable.

Examples

Path Case
example/app One client + one CredentialsStatic[Default]
example/shared-creds Two clients, one shared credentials slot
example/two-creds Two clients, two credentials slots (distinct Tags)

Environment

Prefix comes from the app (EnvPrefix); fields below are relative to each slot.

S3 (client)
Variable Description
S3_LABEL Resource label (otel)
S3_ENDPOINT S3 API base URL (http.v1.URL, required http/https)
S3_REGION Region (default us-east-1)
S3_BUCKET Bucket name (required)
S3_USE_PATH_STYLE Reserved (path-style is always on for custom endpoints)
S3_CREDENTIALS_STATIC
Variable Description
S3_CREDENTIALS_STATIC_ACCESS_KEY Access key (required)
S3_CREDENTIALS_STATIC_SECRET_KEY Secret key (required)

API

Method Role
Put Upload object (PutOptions: ContentType, ContentLength)
Get Download body + Head metadata
Head Metadata only
Delete Remove object
PresignGet Time-limited GET URL
Ready HeadBucket reachability check
ProbeReady Ops readiness (ProbeReadiness); delegates to Ready

ErrNotFound / IsNotFound map missing-object errors.

SDK client is created in Inject after SDI resolves credentials (not in Build).

Telemetry

On Inject, the package attaches OpenTelemetry middleware so S3 calls emit spans to the process TracerProvider (set by omcrgnt/telemetry before runner.Run).

Docker (MinIO)

Fragment for local app / system tests: docker/service/minio.yml (minio + minio-init bucket create).

docker compose -f docker/service/minio.yml up -d
# or: task deps:up
Env Default
MINIO_ROOT_USER / MINIO_ROOT_PASSWORD minioadmin
MINIO_API_PORT / MINIO_CONSOLE_PORT 9000 / 9001
MINIO_BUCKET assets

App compose via git include (#main):

include:
  - path: https://github.com/omcrgnt/client-s3.git#main:docker/service/minio.yml

Or extends (rename / override ports):

services:
  minio:
    extends:
      file: path/to/client-s3/docker/service/minio.yml
      service: minio
    ports:
      - "9100:9000"
      - "9101:9001"

Catalog env for the Go client stays on the app side, for example:

# example env (app prefix CLIENT_S3_EXAMPLE)
CLIENT_S3_EXAMPLE_S3_LABEL=assets
CLIENT_S3_EXAMPLE_S3_ENDPOINT=http://127.0.0.1:9000
CLIENT_S3_EXAMPLE_S3_REGION=us-east-1
CLIENT_S3_EXAMPLE_S3_BUCKET=assets

CLIENT_S3_EXAMPLE_S3_CREDENTIALS_STATIC_ACCESS_KEY=minioadmin
CLIENT_S3_EXAMPLE_S3_CREDENTIALS_STATIC_SECRET_KEY=minioadmin

See examples above for shared vs split credentials layouts.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotFound = errors.New("clients3: not found")

ErrNotFound is returned when the object (or bucket for Ready) does not exist.

Functions

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound reports whether err is or wraps ErrNotFound.

Types

type AccessKey 

type AccessKey string

AccessKey is a static access key id.

func (AccessKey) String 

func (a AccessKey) String() string

func (AccessKey) Usage 

func (AccessKey) Usage() string

func (AccessKey) Validate 

func (a AccessKey) Validate() error

type Bucket 

type Bucket string

Bucket is the object bucket bound to this client.

func (Bucket) String 

func (b Bucket) String() string

func (Bucket) Usage 

func (Bucket) Usage() string

func (Bucket) Validate 

func (b Bucket) Validate() error

type Client 

type Client[C CredentialsProvider] struct {
	// contains filtered or unexported fields
}

Client is an S3-compatible object client bound to one bucket and credentials type C. Catalog field: *Client[C] (Configurable); C is a concrete CredentialsProvider (e.g. *CredentialsStatic[Default]). SDI wires C via Deps/Inject (same pattern as srv-http.Server[T]).

func NewTestClient 

func NewTestClient[C CredentialsProvider](inner *s3.Client, bucket string) *Client[C]

NewTestClient constructs a Client around an existing SDK client (tests only).

func (*Client[C]) Bucket 

func (c *Client[C]) Bucket() string

Bucket returns the bucket this client is bound to.

func (*Client[C]) BuildConfig 

func (*Client[C]) BuildConfig() (app.Materializer, error)

BuildConfig returns the config spec for materialize.

func (*Client[C]) Close 

func (c *Client[C]) Close(_ context.Context) error

Close is a no-op; retained for lifecycle symmetry with other resources.

func (*Client[C]) Delete 

func (c *Client[C]) Delete(ctx context.Context, key string) error

Delete removes an object.

func (*Client[C]) Deps 

func (c *Client[C]) Deps() []any

Deps declares the concrete credentials implementor C.

func (*Client[C]) Get 

func (c *Client[C]) Get(ctx context.Context, key string) (io.ReadCloser, Head, error)

Get downloads an object. Caller must Close the returned body.

func (*Client[C]) Head 

func (c *Client[C]) Head(ctx context.Context, key string) (Head, error)

Head fetches object metadata without the body.

func (*Client[C]) Inject 

func (c *Client[C]) Inject(args []any)

Inject receives credentials and materializes the AWS SDK client.

func (*Client[C]) Label 

func (c *Client[C]) Label() string

Label returns the configured resource label.

func (*Client[C]) PresignGet 

func (c *Client[C]) PresignGet(ctx context.Context, key string, ttl time.Duration) (string, error)

PresignGet returns a time-limited GET URL for key.

func (*Client[C]) ProbeReady 

func (c *Client[C]) ProbeReady(ctx context.Context) error

ProbeReady reports S3 traffic readiness via HeadBucket (ops duck typing).

func (*Client[C]) Put 

func (c *Client[C]) Put(ctx context.Context, key string, body io.Reader, opts PutOptions) error

Put uploads an object at key.

func (*Client[C]) Ready 

func (c *Client[C]) Ready(ctx context.Context) error

Ready checks that the configured bucket exists and is reachable.

type Config 

type Config[C CredentialsProvider] struct {
	Label        common.Label
	Endpoint     httpv1.URL
	Region       Region
	Bucket       Bucket
	UsePathStyle UsePathStyle
}

Config is the client-s3 spec; ecfg fills before Build. Endpoint is protovalidated by ecfg as http.v1.URL (non-empty http/https). Credentials come from SDI via Client[C] → CredentialsProvider implementor C.

func (*Config[C]) Build 

func (cfg *Config[C]) Build() (any, error)

Build returns a Client resource; AWS SDK is wired in Inject after credentials resolve.

type CredentialsProvider 

type CredentialsProvider interface {
	Retrieve(ctx context.Context) (aws.Credentials, error)
}

CredentialsProvider is the SDI port for S3 credentials (static, Vault, STS, …). Catalog: declare a concrete implementor (e.g. *CredentialsStatic[Default]) and bind Client[C] to that type.

type CredentialsStatic 

type CredentialsStatic[Tag any] struct {
	// contains filtered or unexported fields
}

CredentialsStatic is long-lived access/secret credentials (MinIO / IAM user keys). Tag distinguishes multiple static sets in one process for SDI. One set: CredentialsStatic[Default]. Two sets: CredentialsStatic[assets], CredentialsStatic[backups], … Catalog: *CredentialsStatic[Tag]; wire Client[*CredentialsStatic[Tag]].

func (*CredentialsStatic[Tag]) BuildConfig 

func (*CredentialsStatic[Tag]) BuildConfig() (app.Materializer, error)

BuildConfig returns the config spec for materialize.

func (*CredentialsStatic[Tag]) Retrieve 

func (c *CredentialsStatic[Tag]) Retrieve(_ context.Context) (aws.Credentials, error)

Retrieve implements aws.CredentialsProvider / CredentialsProvider.

type CredentialsStaticConfig 

type CredentialsStaticConfig[Tag any] struct {
	AccessKey AccessKey
	SecretKey SecretKey
}

CredentialsStaticConfig is the ecfg spec for CredentialsStatic.

func (*CredentialsStaticConfig[Tag]) Build 

func (c *CredentialsStaticConfig[Tag]) Build() (any, error)

Build returns a CredentialsStatic resource.

type Default 

type Default struct{}

Default tags the single static credentials set in a process (most apps). Also used when several clients share one credentials resource. 

type Head struct {
	ContentType   string
	ContentLength int64
	ETag          string
	SHA256        string
}

Head holds object metadata from HeadObject / GetObject.

type PutOptions 

type PutOptions struct {
	ContentType   string
	ContentLength int64 // 0 = omit (SDK may buffer)
}

PutOptions controls optional PutObject fields.

type Region 

type Region string

Region is the AWS / S3 region name.

func (Region) String 

func (r Region) String() string

func (Region) Usage 

func (Region) Usage() string

func (Region) Validate 

func (r Region) Validate() error

type SecretKey 

type SecretKey string

SecretKey is a static secret access key.

func (SecretKey) String 

func (s SecretKey) String() string

func (SecretKey) Usage 

func (SecretKey) Usage() string

func (SecretKey) Validate 

func (s SecretKey) Validate() error

type UsePathStyle 

type UsePathStyle bool

UsePathStyle enables path-style addressing (required for typical MinIO setups).

func (UsePathStyle) Usage 

func (UsePathStyle) Usage() string

func (UsePathStyle) Validate 

func (UsePathStyle) Validate() error

Source Files

View all Source files

Directories

Path Synopsis
example
app command
shared-creds command
Two S3 clients share one static credentials resource (same Tag / one env block).
 Two S3 clients share one static credentials resource (same Tag / one env block).
two-creds command
Two S3 clients with two different static credential sets (distinct Tags).
 Two S3 clients with two different static credential sets (distinct Tags).

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.