blob

type Description struct {
	Type      string `json:"type"`
	Bucket    string `json:"bucket,omitempty"`
	Container string `json:"container,omitempty"`
	Account   string `json:"account,omitempty"`
	Prefix    string `json:"prefix,omitempty"`
	Region    string `json:"region,omitempty"`
	Endpoint  string `json:"endpoint,omitempty"`
}

type DigestReporter interface {
	// StatSHA256 returns the object's metadata (as Stat) together with the
	// lowercase hex SHA-256 of its full content as verified by the storage
	// service, or "" when the service holds no such digest for this object
	// version. A digest always describes the object the returned info
	// describes. It returns ErrNotFound for a missing object and
	// ErrNotSupported when the store cannot report digests at all (callers
	// then read the object).
	StatSHA256(ctx context.Context, key string) (*ObjectInfo, string, error)
}

type ListResult struct {
	Objects []ObjectInfo
	// Prefixes are the "directories" (ending in "/") found when a delimiter is used.
	Prefixes []string
}

type ObjectInfo struct {
	Key         string    `json:"key"`
	Size        int64     `json:"size"`
	ETag        string    `json:"etag"` // opaque, changes whenever content changes; never empty
	ContentType string    `json:"content_type,omitempty"`
	ModTime     time.Time `json:"mod_time"`
}

type PresignPutOptions struct {
	// ContentType is signed into the URL and stored with the object; ""
	// derives it from the key's extension.
	ContentType string
	// Size is the exact body size in bytes, or -1 when unknown.
	Size int64
	// SHA256 is the lowercase or uppercase hex SHA-256 of the body; "" when
	// unknown. Ignored by backends that cannot enforce it.
	SHA256 string
}

type PresignedRequest struct {
	Method    string            `json:"method"`
	URL       string            `json:"url"`
	Headers   map[string]string `json:"headers,omitempty"` // must be sent verbatim
	ExpiresAt time.Time         `json:"expires_at"`
}

type Store interface {
	// Get opens an object for reading. The caller must close the reader.
	Get(ctx context.Context, key string) (io.ReadCloser, *ObjectInfo, error)
	// GetRange reads length bytes starting at offset (length < 0 = to end).
	GetRange(ctx context.Context, key string, offset, length int64) (io.ReadCloser, *ObjectInfo, error)
	// Stat returns object metadata or ErrNotFound.
	Stat(ctx context.Context, key string) (*ObjectInfo, error)
	// Put writes an object, replacing any existing one. size may be -1 if unknown.
	Put(ctx context.Context, key string, r io.Reader, size int64, contentType string) (*ObjectInfo, error)
	// Delete removes an object. Deleting a missing object is not an error.
	Delete(ctx context.Context, key string) error
	// DeletePrefix removes every object whose key starts with prefix.
	DeletePrefix(ctx context.Context, prefix string) error
	// List returns all objects under prefix (all pages). With delimiter "/",
	// objects in "sub-directories" are folded into Prefixes; with "" the
	// listing is recursive. Results are sorted by key.
	List(ctx context.Context, prefix, delimiter string) (*ListResult, error)
	// PresignPut returns a URL that accepts a PUT of the object's bytes as
	// described by opts (content type, and as far as the backend can enforce
	// them, size and SHA-256). The returned Headers must be sent verbatim.
	// Returns ErrNotSupported when the backend cannot presign.
	PresignPut(ctx context.Context, key string, opts PresignPutOptions, ttl time.Duration) (*PresignedRequest, error)
	// PresignGet returns a time-limited download URL or ErrNotSupported.
	PresignGet(ctx context.Context, key string, ttl time.Duration) (*PresignedRequest, error)
	// Ping checks connectivity/permissions cheaply (used by /readyz).
	Ping(ctx context.Context) error
	// Describe returns non-secret details advertised to CLIs for direct sync
	// (type, bucket/container, account, prefix, region).
	Describe() Description
	// Close releases resources.
	Close() error
}