storage

type S3Options struct {
	Bucket   string
	Prefix   string // optional key prefix within the bucket
	Region   string
	Endpoint string // optional custom endpoint for S3-compatible services (MinIO, R2)
}

type Store interface {
	// Put writes the full contents of r under key, durably and atomically: the
	// key either resolves to the complete object or does not resolve at all — a
	// reader that fails mid-stream, or a cancelled context, must not leave a
	// partial object visible under key. Overwriting an existing key is allowed
	// and replaces it. Put reads r to EOF.
	Put(ctx context.Context, key string, r io.Reader) error

	// Get opens key for reading. The returned ReadCloser is a one-shot forward
	// stream — callers must not assume it is seekable — and must be closed. A
	// missing key returns an error wrapping ErrNotFound.
	Get(ctx context.Context, key string) (io.ReadCloser, error)

	// Delete removes key. Deleting a key that does not exist is NOT an error
	// (delete is idempotent), so callers can prune without racing existence.
	Delete(ctx context.Context, key string) error

	// List returns every key currently present in the store, in no guaranteed
	// order.
	List(ctx context.Context) ([]string, error)

	// Stat reports the size in bytes and existence of key. A missing key returns
	// (0, false, nil) — absence is not an error for Stat. A transport failure
	// returns a non-nil error.
	Stat(ctx context.Context, key string) (size int64, exists bool, err error)
}