Documentation
¶
Overview ¶
Package s3 provides a thin adapter over aws-sdk-go-v2 for S3-compatible object storage. It implements the ObjectUploader interface used by cells/auditcore and other consumers.
This package intentionally does NOT re-export SDK types. For operations beyond Upload and Health (e.g., download, delete, presigned URLs), use the aws-sdk-go-v2 S3 client directly.
ref: github.com/aws/aws-sdk-go-v2/service/s3
Index ¶
- Constants
- type Client
- func (c *Client) Close(ctx context.Context) error
- func (c *Client) Health(ctx context.Context) error
- func (c *Client) Probes() []healthz.Probe
- func (c *Client) SDK() *awss3.Client
- func (c *Client) Upload(ctx context.Context, key string, data []byte, contentType string) error
- func (c *Client) Worker() worker.Worker
- type Config
Constants ¶
const ( ErrAdapterS3Config errcode.Code = "ERR_ADAPTER_S3_CONFIG" ErrAdapterS3Upload errcode.Code = "ERR_ADAPTER_S3_UPLOAD" ErrAdapterS3Health errcode.Code = "ERR_ADAPTER_S3_HEALTH" )
S3 adapter error codes.
const ( // ProbeReady is the ops-contract name for the S3 readiness probe registered // by Checkers(). It is a healthz.ProbeName-typed const (snake_case + // "_ready" suffix), funneled by archtest PROBENAME-SEALED-FUNNEL-01 so // production code and tests reference the same identifier without drift. ProbeReady healthz.ProbeName = "s3_ready" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a thin S3 adapter backed by aws-sdk-go-v2. It implements lifecycle.ManagedResource: Checkers() reads the last known health state without network I/O; Worker() drives a background ticker that re-probes HeadBucket on each tick and updates state.
ref: runtime/websocket/hub.go — state-machine + worker adapter pattern. ref: kubernetes/kubernetes pkg/util/healthz — named health checkers.
func New ¶
New creates a Client with ctx, clk and cfg. It synchronously runs one HeadBucket probe; failure returns a wrapped ErrAdapterS3Health error (fail-fast, symmetric to oidc adapter).
func (*Client) Close ¶
Close implements lifecycle.ManagedResource. It signals the worker to stop and waits for the goroutine to drain, bounded by ctx. Idempotent — safe to call from both Worker.Stop and ManagedResource.Close teardown paths.
Fast path: if the worker goroutine was never started (e.g. bootstrap aborted before Worker.Start was called), workerDone will never be closed. In that case we skip the select so we do not burn the shutdown budget on a non-existent drain.
ref: runtime/websocket/hub.go Close — idempotent + ctx-bounded pattern.
func (*Client) Health ¶
Health checks bucket accessibility via a direct HeadBucket network call. This is useful for one-shot diagnostics. The background worker and Checkers use the internal state, not this method.
Requires a full SDK client (c.s3 non-nil). When constructed via newClientWithHead with a mock (tests), c.s3 is nil and Health returns ErrAdapterS3Health rather than panicking on nil dereference.
func (*Client) Probes ¶
Probes implements lifecycle.ManagedResource. It returns a single typed probe with name ProbeReady ("s3_ready") that reads the latest health state without any network call.
probe name follows the observability rule: snake_case + "_ready" suffix. ProbeReady is the single source of truth; both this method and tests reference it so the name cannot drift.
ref: runtime/websocket/hub.go Probes — state-read probe pattern.
func (*Client) SDK ¶
SDK returns the underlying aws-sdk-go-v2 S3 client for operations not covered by this thin adapter (download, delete, presigned URLs, etc.).
func (*Client) Upload ¶
Upload stores an object via PutObject. Used by cells implementing object archival.
Requires a full SDK client (c.s3 non-nil). When constructed via newClientWithHead with a mock (tests), c.s3 is nil and Upload returns ErrAdapterS3Upload rather than panicking on nil dereference.
type Config ¶
type Config struct {
Endpoint string
Region string
Bucket string
AccessKeyID string
SecretAccessKey string
UsePathStyle bool
HTTPTimeout time.Duration // default 30s
HealthInterval time.Duration // default 30s; background probe cadence
}
Config holds the S3 connection configuration.
func ConfigFromEnv ¶
func ConfigFromEnv() Config
ConfigFromEnv creates a Config from environment variables.
Callers must pass a clock.Clock as the second argument to New(). Composition root: pass clock.Real(); tests: pass clockmock.New(...).
Source Files