storage

type BoundedWriter interface {
	Storage
	// BoundedWrites declares the guarantee; it does nothing.
	BoundedWrites()
}

type DirectUploader interface {
	// UploadURL returns the request that stores exactly one object: under
	// key, of exactly opts.Size bytes, with opts.ContentType and
	// opts.Metadata, until opts.Expires after the start of the second it is
	// signed in (the model of storage.SignedURL). The backend refuses a
	// request that differs in any of these (a different length, type,
	// metadata, or key), so the grant is scoped to that one object. It
	// stores only where nothing is stored yet (S3 answers 412, the app's
	// storage route a D10 409 conflict, otherwise): once used,
	// the object cannot be replaced through the grant, so bytes checked
	// after the upload stay the bytes stored. It authorizes nobody: decide
	// who may upload first, and check what arrived (upload.Confirm) before
	// using it.
	UploadURL(ctx context.Context, key string, opts UploadURLOptions) (UploadRequest, error)
}

type Error struct {
	Op  string // "put", "open", "stat", "delete", "url"
	Key string
	Err error
}

type Lister interface {
	// List calls fn with every object whose key starts with prefix ("" for
	// all), in an order the driver chooses, until fn returns an error,
	// which List then returns. Each ObjectInfo has the Key, Size, ETag, and
	// ModTime; ContentType and Metadata may be empty (an S3 listing does
	// not carry them: Stat the object for them). fn may delete the object
	// it is given. An object stored or deleted while List runs may or may
	// not be seen.
	List(ctx context.Context, prefix string, fn func(ObjectInfo) error) error
}

type ObjectInfo struct {
	// Key is the object's key.
	Key string
	// Size is the object's length in bytes.
	Size int64
	// ContentType is the object's media type (DefaultContentType when it
	// was stored without one).
	ContentType string
	// ETag identifies this version of the object's bytes, when the driver
	// has one; it changes when the object is replaced with different
	// bytes. A driver reports it from Put, Open, and Stat alike, or from
	// none of them (empty: unsupported). It is opaque: compare ETags, never
	// compute or interpret one. (S3's depends on how the object was stored
	// and on the bucket's encryption, and is not a checksum of the bytes in
	// general; the local and memory drivers happen to use a SHA-256, which
	// is not part of the contract.)
	ETag string
	// ModTime is when the object was last stored (for an object written
	// once, as uploads under generated keys are, when it was created).
	// Stat, Open, and List always report it; the ObjectInfo Put returns
	// may leave it zero when the backend does not say (S3's PutObject),
	// rather than cost a second request.
	ModTime time.Time
	// Metadata is the user metadata the object was stored with (nil when
	// none). Every ObjectInfo a driver returns has a map of its own: the
	// caller may change it without changing the stored object or any other
	// result.
	Metadata map[string]string
}

type Publisher interface {
	// PreparePublish readies a copy of the object at src (its bytes,
	// ContentType and Metadata) to dst, and returns a token naming it (at
	// most MaxPublicationToken bytes, by construction). Nothing is published yet: record the
	// token durably before Publish, so that the copy can be fenced whatever
	// happens to the caller. A missing src is ErrNotFound. When it fails
	// but returns a token, something of the copy may remain (a request
	// whose answer was lost): record the token and Fence it.
	PreparePublish(ctx context.Context, src, dst string) (string, error)
	// Publish publishes the prepared copy at dst. A failure whose outcome
	// is unknown (the request sent, no definite answer) is
	// ErrUnknownOutcome: the copy may be published, now or later; Fence
	// settles it.
	Publish(ctx context.Context, token string) (ObjectInfo, error)
	// Fence makes sure the copy named by token can never be published
	// after it returns nil: it was published already, or never will be.
	// It also removes what it can of an unpublished copy, but proves no
	// more than that nothing will be published (on S3 a part still being
	// processed may be stored afterwards; it is never an object). It is
	// idempotent. An error means nothing is proven yet: try again.
	Fence(ctx context.Context, token string) error
}

type PutOptions struct {
	// ContentType is the object's media type ("image/png"), parameters
	// allowed ("text/plain; charset=utf-8"). Empty stores
	// DefaultContentType. It must be a type/subtype media type.
	ContentType string

	// Size, when set, is the exact length r will produce (zero for an empty
	// object). Put then fails with ErrSizeMismatch, storing nothing, if r
	// ends early or runs long. Nil means unknown: Put reads r to EOF. Build
	// it with KnownSize, or from an HTTP request's Content-Length with
	// SizeFromContentLength (-1, unknown, is nil).
	Size *int64

	// Metadata is small user metadata stored with the object and returned
	// in its ObjectInfo exactly as given. Names are lower-case ASCII
	// letters, digits, and '-'; values are UTF-8 without control
	// characters or leading or trailing spaces (HTTP trims header values);
	// see ValidateMetadata for the size limit. A driver whose backend
	// carries only ASCII (S3 headers) encodes values reversibly. Put copies
	// the map: changing it afterwards changes nothing stored.
	Metadata map[string]string

	// IfAbsent stores the object only where no object is stored under key:
	// when one is, Put fails with ErrExists and leaves it as it is. The
	// check and the store are one atomic step on every driver, against
	// concurrent Puts from this process and from any other sharing the
	// backend (the local driver publishes with a rename that refuses to
	// replace; S3 with a conditional write, "If-None-Match: *"), so of two
	// IfAbsent Puts to one empty key exactly one succeeds.
	IfAbsent bool
}

type Storage interface {
	// Put stores the bytes read from r under key, replacing any object
	// already there. It streams: r is read to EOF in pieces, never required
	// to be seekable or of known length.
	//
	// Put is atomic. When it fails (r returns an error, ctx ends, the
	// length differs from a declared opts.Size), key keeps the object it
	// had before, or stays absent; no reader ever sees a partial object.
	// Concurrent Puts to one key leave one of them whole, and a reader
	// during a Put reads the previous object whole.
	//
	// The one exception is a failure that matches ErrUnknownOutcome: a
	// driver whose backend is across a network sent the request that
	// publishes the object and never learned whether it took effect. The
	// key then holds the previous object or the new one, whole; which, the
	// driver cannot say. Every other failure, ctx ending before the object
	// was sent included, leaves the key as it was.
	//
	// Put observes ctx between reads of r: once ctx has ended, it makes no
	// further Read, and it fails with ctx's error and stores nothing, even
	// if r then reaches EOF. (If ctx ends while a remote backend is
	// publishing the object, the error may match ErrUnknownOutcome as well
	// as ctx's error.) It cannot interrupt a Read of r already in
	// progress (an io.Reader has no way to be interrupted, and r is the
	// caller's): a source that can block must be made to return by its
	// owner, as an HTTP server closes a request body when the client goes
	// away, or a caller closes the pipe it writes.
	Put(ctx context.Context, key string, r io.Reader, opts PutOptions) (ObjectInfo, error)

	// Open returns the object's bytes as a stream, and its ObjectInfo. The
	// caller must Close the reader. A missing object is ErrNotFound. The
	// reader stays bound to ctx until it is closed: once ctx ends, Read
	// fails with ctx's error on every driver, and a Read blocked in the
	// backend returns (an HTTP response body does this by itself;
	// ContextReadCloser does it for a reader whose Close interrupts a Read),
	// so keep ctx alive for as long as the stream is read.
	Open(ctx context.Context, key string) (io.ReadCloser, ObjectInfo, error)

	// Stat returns the object's ObjectInfo without its bytes. A missing
	// object is ErrNotFound.
	Stat(ctx context.Context, key string) (ObjectInfo, error)

	// Delete removes the object. Deleting a missing object is not an error,
	// so a retried Delete is safe.
	Delete(ctx context.Context, key string) error

	// URL returns a URL a client can fetch the object from: a permanent
	// public URL for a public object (ErrNotPublic for a private one; see
	// IsPublic), or a signed one that works for any object until it
	// expires (see URLOptions; at most MaxURLExpiry). A driver that cannot
	// produce one returns ErrUnsupported. URL does not check that the
	// object exists, and it does not authorize anyone: decide who may have
	// the URL before asking for it.
	URL(ctx context.Context, key string, opts URLOptions) (string, error)
}

type URLOptions struct {
	// Signed asks for a URL that grants access only until Expires has
	// passed. Unsigned asks for a permanent public URL.
	Signed bool
	// Expires is how long a signed URL is valid: it must be positive for a
	// signed URL, and zero for a public one (ErrInvalidOptions otherwise),
	// so a zero or negative lifetime can never widen into a permanent URL.
	// It is a whole number of seconds (ErrInvalidOptions otherwise),
	// counted from the start of the second the URL is signed in, as S3
	// counts it, on every driver.
	Expires time.Duration
}

type UploadRequest struct {
	Method  string            `json:"method"`
	URL     string            `json:"url"`
	Header  map[string]string `json:"headers"`
	Expires time.Time         `json:"expires"`
}

type UploadURLOptions struct {
	// Expires is how long the upload URL works, counted from the start of
	// the second it is signed in, as for SignedURL (so for more than
	// Expires minus a second, and at most Expires): a positive whole number
	// of seconds, at most MaxURLExpiry. Keep it short (minutes): the URL is
	// a bearer grant.
	Expires time.Duration
	// Size is the exact length the client will upload, in bytes (zero for
	// an empty object). A request of any other length is refused.
	Size int64
	// ContentType is the object's media type, which the client must send
	// as its Content-Type (DefaultContentType when empty). It is what the
	// client declares, not what the bytes are: check them afterwards.
	ContentType string
	// Metadata is stored with the object (the rules of
	// PutOptions.Metadata).
	Metadata map[string]string
}

type UploadVerifier interface {
	VerifyUpload(ctx context.Context, key string) error
}