blobstore

type GetOptions struct {
	// TTL is how long the URL stays valid. Zero means DefaultTTL; it must be
	// at most MaxTTL.
	TTL time.Duration
	// DownloadName, when set, makes the response a download
	// (Content-Disposition: attachment) saved under this file name.
	DownloadName string
}

type ListOptions struct {
	// After lists only keys after this one: the previous page's Next.
	After string
	// Limit caps the page. Zero means MaxListLimit, and so does anything
	// above it.
	Limit int
}

type ListPage struct {
	Objects []Object
	// Next is the ListOptions.After that continues the listing; empty when
	// this page is the last.
	Next string
}

type Memory struct {
	// contains filtered or unexported fields
}

type Object struct {
	// Key is the object's key, as the caller of this store names it (a
	// Scoped store reports keys without its prefix).
	Key          string
	Size         int64
	ContentType  string
	ETag         string
	LastModified time.Time
}

type PresignedRequest struct {
	// Method is the HTTP method: PUT for an upload, GET for a download.
	Method string
	// URL is the signed URL, valid until ExpiresAt.
	URL string
	// Headers are the headers the request must carry, exactly. For an upload
	// that is Content-Type. Content-Length is signed too, but a browser sets
	// it from the body and refuses to let a script set it; send a body of the
	// size that was presigned.
	Headers map[string]string
	// ExpiresAt is when the URL stops working.
	ExpiresAt time.Time
}

type PutOptions struct {
	// ContentType is the upload's media type. Required: it is signed, so the
	// client must send exactly this Content-Type header.
	ContentType string
	// ContentLength is the upload's exact size in bytes. Required and > 0:
	// it is signed, so the storage service refuses a body of any other size.
	ContentLength int64
	// MaxBytes, when > 0, refuses to presign a ContentLength above it
	// (ErrTooLarge). The caller's own limit, checked before anything is
	// signed.
	MaxBytes int64
	// TTL is how long the URL stays valid. Zero means DefaultTTL; it must be
	// at most MaxTTL.
	TTL time.Duration
}

type S3 struct {
	// contains filtered or unexported fields
}

type S3Config struct {
	// Endpoint is the S3 API's base URL as THIS process reaches it, scheme
	// included: "http://localhost:9000" (MinIO in dev),
	// "https://s3.us-east-1.amazonaws.com", "https://<account>.r2.cloudflarestorage.com",
	// "https://storage.googleapis.com" (GCS interoperability). Required.
	Endpoint string
	// PublicEndpoint is the base URL a BROWSER reaches the same service at,
	// when that differs from Endpoint: a pod dials MinIO at
	// http://host.k3d.internal:9000 while the browser beside it uses
	// http://localhost:9000. Presigned URLs are signed for this host (the
	// host is part of the signature, so a URL cannot be rewritten after
	// signing). Empty means Endpoint.
	PublicEndpoint string
	// Region is the bucket's region. Empty means "us-east-1", which is what
	// MinIO and GCS interoperability accept; R2 takes "auto". Always set
	// explicitly on the client, so presigning never makes a network call to
	// look the region up.
	Region string
	// Bucket is the bucket every key lives in. Required.
	Bucket string
	// AccessKeyID and SecretAccessKey are the S3 credentials (an HMAC key
	// for GCS). Required.
	AccessKeyID     string
	SecretAccessKey string
	// PathStyle addresses the bucket as <endpoint>/<bucket>/<key> rather
	// than <bucket>.<endpoint>/<key>. MinIO needs it; for the others false
	// lets the client choose.
	PathStyle bool

	// Transport is the base RoundTripper (nil: http.DefaultTransport). It is
	// wrapped by observe.NewHTTPTransport, so every request to the storage
	// service is a client span carrying the caller's trace context.
	Transport http.RoundTripper
	// Logger receives the instrumentation's call records. nil: slog.Default.
	Logger *slog.Logger
	// Chain replaces the default instrumentation: a span, the
	// blobstore.{calls,errors,duration} metrics and a log record per call,
	// with ErrNotFound logged as an expected outcome. Build one with
	// observe.NewComponentChain to change it.
	Chain *observe.ComponentChain
}

type Store interface {
	// PresignPut returns the request a client sends to upload key: a PUT of
	// exactly opts.ContentLength bytes of opts.ContentType. An existing
	// object at key is replaced by the upload.
	PresignPut(ctx context.Context, key string, opts PutOptions) (PresignedRequest, error)
	// PresignGet returns a GET request for key. It does not check that the
	// object exists; the URL answers 404 when it does not.
	PresignGet(ctx context.Context, key string, opts GetOptions) (PresignedRequest, error)
	// Stat reports the object at key, or ErrNotFound.
	Stat(ctx context.Context, key string) (Object, error)
	// Delete removes the object at key. Deleting a missing object is not an
	// error.
	Delete(ctx context.Context, key string) error
	// List returns one page of the objects whose keys start with prefix, in
	// key order. An empty prefix lists everything the store can see.
	List(ctx context.Context, prefix string, opts ListOptions) (ListPage, error)
}