storage

type Addressing string

type And []Filter

type CORSRule struct {
	Origins, Methods, Headers []string
}

type Capability string

type CheckReport struct {
	Provider       string
	Endpoint       string
	PublicEndpoint string
	Bucket         string
	Prefix         string
	Steps          []CheckStep
	// ChecksumSHA256 is what the storage does with a signed x-amz-checksum-sha256:
	// "verified" (it rejects content that differs), "ignored" (it accepts it), or
	// "not tested".
	ChecksumSHA256 string
	// Encryption is the bucket's default encryption ("none", an algorithm, or
	// "unknown" when the provider doesn't expose it).
	Encryption string
	CORS       []CORSRule
	// LinkHost is the host a signed link is for (the public endpoint's when set).
	LinkHost string
}

type CheckStep struct {
	Name   string
	Level  string
	Detail string
}

type Condition struct {
	Field string
	Op    Operator
	Value any
}

type ConflictError struct {
	Fields []string // fields of the violated index, in API terms; may be empty
}

type Const bool

type Document = map[string]any

type ErasedFile struct {
	ID   string
	Size int64
	// Versions are the made copies of an image the file had, by version name, with their sizes.
	Versions map[string]int64
}

type Eraser interface {
	// CountOwned counts the documents whose _meta.owner is the user.
	CountOwned(ctx context.Context, owner string) (int64, error)
	// CountReferences counts the documents where field (an array of strings
	// when array is true, else a string) holds value.
	CountReferences(ctx context.Context, field, value string, array bool) (int64, error)
	// DeleteOwned deletes up to limit documents the user owns. It returns the files
	// the documents held in fileFields (the collection's file fields), exactly the
	// ones of the documents it deleted, so their objects can be queued for deletion.
	DeleteOwned(ctx context.Context, owner string, fileFields []string, limit int) (int64, []ErasedFile, error)
	// AnonymizeOwned removes the fields in remove, sets those in replace and
	// clears _meta.owner on up to limit documents the user owns. It returns the
	// files the documents held in fileFields (the file fields among remove) at the
	// moment they were removed.
	AnonymizeOwned(ctx context.Context, owner string, remove []string, replace map[string]any, fileFields []string, limit int, now time.Time) (int64, []ErasedFile, error)
	// PullReference removes value from the array field of up to limit
	// documents that contain it.
	PullReference(ctx context.Context, field, value string, limit int, now time.Time) (int64, error)
	// ClearReference unsets the string field of up to limit documents where
	// it equals value.
	ClearReference(ctx context.Context, field, value string, limit int, now time.Time) (int64, error)
}

type Filter interface {
	// contains filtered or unexported methods
}

type Link struct {
	URL       string
	ExpiresAt time.Time
	// Headers must be sent with the request (a signed PUT's content type, length
	// and checksum).
	Headers map[string]string
}

type Not struct{ Filter Filter }

type ObjectInfo struct {
	Key         string
	Size        int64
	ContentType string
	ETag        string
	SHA256      string // hex; "" when the storage keeps none (or keeps a composite one)
	// Checksum is the SHA-256 as the storage reports it: base64, and for an object made by a
	// multipart upload "<base64>-<parts>" (a composite checksum, see CompositeSHA256).
	Checksum     string
	LastModified time.Time
}

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

type ObjectsConfig struct {
	Provider       string
	Endpoint       string
	PublicEndpoint string // "" unless the provider allows it; only signed into links
	Region         string
	Bucket         string
	Prefix         string
	AccessKey      string
	SecretKey      string
}

type Operator string

type Or []Filter

type Page struct {
	Items   []Document
	HasMore bool
	Total   *int64 // set only when Query.Count is true
}

type Part struct {
	Number int32
	ETag   string
	Size   int64
	SHA256 string // hex
}

type Provider struct {
	Name  string // the value of storage.provider
	Label string // for people

	Addressing Addressing

	// EndpointRequired says whether storage.endpoint must be given; without it
	// DefaultEndpoint(region) is used.
	EndpointRequired bool
	DefaultEndpoint  func(region string) string
	// EndpointPattern is what an endpoint (scheme and host, with no path) must
	// match; Group 1, when the entry has RegionFromEndpoint, is the region.
	EndpointPattern *regexp.Regexp
	EndpointHelp    string // the shape, for error messages and the template
	// AllowHTTP lets the endpoint be plain http (development only: startup
	// refuses it unless BACKD_DEV=true).
	AllowHTTP bool

	// Region rules: FixedRegion is the only valid value ("" = free); with
	// RegionFromEndpoint the region is read from the endpoint and must agree with
	// one given; DefaultRegion is used when none is given.
	FixedRegion        string
	RegionFromEndpoint bool
	DefaultRegion      string

	// ChecksumSHA256 is whether the x-amz-checksum-sha256 header is accepted and
	// verified on a PUT, which direct uploads need.
	ChecksumSHA256 Capability
	// MaxSinglePut is the largest object one PUT can carry.
	MaxSinglePut int64
	// MultipartSHA256 is whether a multipart upload can carry a SHA-256 per part, which the
	// storage verifies and combines into the object's composite checksum: what direct uploads
	// above MaxSinglePut need. Unverified (not confirmed by a smoke test) counts as unsupported.
	MultipartSHA256 Capability
	// ReadsCORS and ReadsEncryption say whether `backd storage check` can read
	// the bucket's CORS rules and default encryption.
	ReadsCORS, ReadsEncryption bool
	// ChecksumsWhenRequired makes the client send request checksums only where an
	// operation needs them: recent AWS SDKs send CRC checksums on every upload,
	// which some S3-compatible services reject.
	ChecksumsWhenRequired bool
	// PublicEndpointAllowed lets a realm set public_endpoint: only for providers
	// whose address differs between backd and browsers (a self-hosted MinIO).
	PublicEndpointAllowed bool
	// OldestTested is the oldest version of a self-hosted provider the tests ran
	// against, stated in the docs ("" for hosted providers).
	OldestTested string
}

type Query struct {
	// Filter is the client's where: a tree of conditions combined with
	// And and Or. nil matches everything.
	Filter Filter
	Sort   []SortField // applied in order; ends with "id" as a tiebreaker
	Limit  int
	Skip   int
	Count  bool // also compute the total number of matching documents
	// Access restricts the query to documents the caller may read
	// (from access rules); nil means no restriction.
	Access Filter
	// After restricts the page to the documents positioned after a cursor in
	// Sort (query.ParseCursor builds it). It narrows the page, not the Total.
	After Filter
}

type Repository interface {
	// Create stores doc, which must already carry "id" and "_meta".
	Create(ctx context.Context, doc Document) error
	// Get returns the document with the given id, or ErrNotFound.
	Get(ctx context.Context, id string) (Document, error)
	// List returns a page of documents.
	List(ctx context.Context, q Query) (Page, error)
	// Replace overwrites the document with doc["id"] only if its stored
	// _meta.version equals ifVersion (0 means "stored without a version").
	// It returns ErrNotFound or ErrVersionMismatch otherwise.
	Replace(ctx context.Context, doc Document, ifVersion int64) error
	// Delete removes the document with the given id. When ifVersion is not
	// nil the stored version must equal it. It returns ErrNotFound or
	// ErrVersionMismatch otherwise.
	Delete(ctx context.Context, id string, ifVersion *int64) error
}

type Resolved struct {
	Endpoint string // no trailing slash
	Region   string
	HTTP     bool // the endpoint is plain http
}

type Scanner interface {
	// ScanAfter returns up to limit documents whose id sorts after afterID
	// ("" starts from the first), ordered by id.
	ScanAfter(ctx context.Context, afterID string, limit int) ([]Document, error)
	// EstimatedCount is the collection's approximate size, cheap to ask.
	EstimatedCount(ctx context.Context) (int64, error)
}

type SortField struct {
	Field string
	Desc  bool
}