storage

type Info struct {
	// Driver is local, s3, spaces, r2 or minio.
	Driver string `json:"driver"`
	Bucket string `json:"bucket"`
	// Endpoint is the service's address (the directory for local).
	Endpoint string `json:"endpoint,omitempty"`
	Region   string `json:"region,omitempty"`
	// Local reports a store on this machine, safe to change freely.
	Local bool `json:"local"`
	// PublicURL is where objects are reachable without a signature, when
	// the bucket is public; empty otherwise.
	PublicURL string `json:"public_url,omitempty"`
}

type ListOptions struct {
	// Prefix keeps keys starting with it.
	Prefix string
	// Recursive lists every key under the prefix; otherwise keys with a
	// slash after the prefix are folded into Prefixes (directories).
	Recursive bool
	// Cursor continues a previous page.
	Cursor string
	// Limit is the page size (default [DefaultListLimit], at most
	// [MaxListLimit]).
	Limit int
}

type Object struct {
	Key          string            `json:"key"`
	Size         int64             `json:"size"`
	ContentType  string            `json:"content_type"`
	ETag         string            `json:"etag,omitempty"`
	LastModified time.Time         `json:"last_modified"`
	Metadata     map[string]string `json:"metadata,omitempty"`
}

type Page struct {
	Objects []Object `json:"objects"`
	// Prefixes are the "directories" folded when not recursive.
	Prefixes []string `json:"prefixes"`
	// NextCursor continues the listing; empty at the end.
	NextCursor string `json:"next_cursor,omitempty"`
}

type PutOptions struct {
	// ContentType of the object; guessed from the key when empty.
	ContentType string
	// Metadata is kept with the object (S3 user metadata; a sidecar file
	// on disk). Keys are lowercased; values must be plain text.
	Metadata map[string]string
}

type Store interface {
	// Info describes the store.
	Info() Info
	// Ping checks the service answers; [ErrUnavailable] wraps the reason.
	Ping(ctx context.Context) error
	// Put stores r under key, replacing any object there.
	Put(ctx context.Context, key string, r io.Reader, size int64, opts PutOptions) (Object, error)
	// Get opens the object for reading; the caller closes it.
	Get(ctx context.Context, key string) (io.ReadCloser, Object, error)
	// Stat describes the object without reading it.
	Stat(ctx context.Context, key string) (Object, error)
	// Delete removes the object; a missing key isn't an error.
	Delete(ctx context.Context, key string) error
	// Copy duplicates src to dst.
	Copy(ctx context.Context, src, dst string) (Object, error)
	// List returns a page of objects under a prefix.
	List(ctx context.Context, opts ListOptions) (Page, error)
	// SignedURL returns a URL that lets its holder GET (download) or PUT
	// (upload) the key until expiry, without other credentials.
	SignedURL(ctx context.Context, key string, method string, expiry time.Duration) (string, error)
}