store

type Entry struct {
	Key         string
	Size        int64
	Modified    time.Time
	RetainUntil time.Time
	// LegalHold is whether a hold is on the object. A listing does not carry
	// it — S3 does not report it per key — so it is set by Head and left false
	// by List.
	LegalHold bool
	// Metadata is the object's user-defined metadata, as Head returns it. A
	// listing carries none — S3 does not report it per key — so it is nil from
	// List. It is what lets a reader of the v1 layout learn an object's
	// sha256 and record count from a HEAD and never a body.
	Metadata map[string]string
}

type Object struct {
	Key  string
	Body []byte
	// RetainUntil is when the object may first be deleted. The store is
	// expected to refuse a deletion before it, and to refuse shortening it.
	RetainUntil time.Time
	ContentType string
	// Encoding is the content encoding, "zstd" for a batch of records.
	Encoding string
	// Metadata is small, and is there so an object can say what it is without
	// being opened.
	Metadata map[string]string
	// LegalHold keeps an object undeletable for as long as it is set,
	// independently of RetainUntil and without any expiry of its own.
	//
	// It is set at write time rather than afterwards because a hold is placed
	// on a prefix and objects keep arriving under it: an object written into a
	// held prefix and only held by a later sweep is an object that was
	// deletable in between, which is the window a hold exists to close.
	LegalHold bool
}

type Presigner interface {
	// Presign returns a URL to an object, valid for the given time.
	Presign(ctx context.Context, key string, valid time.Duration) (string, error)
}

type RecordObject struct {
	Profile, Tenant string
	// Hour is the hour of ingest time the key names.
	Hour time.Time
	ULID string
}

type SealObject struct {
	Profile, Tenant string
	Hour            time.Time
}

type Store interface {
	// Put writes an object. It fails with ErrExists rather than overwriting.
	Put(ctx context.Context, o Object) error
	// Get returns an object's body.
	Get(ctx context.Context, key string) ([]byte, error)
	// Head returns an object's listing entry without its body.
	Head(ctx context.Context, key string) (Entry, error)
	// List returns entries under a prefix, in key order, starting after a key.
	List(ctx context.Context, prefix, after string, limit int) ([]Entry, error)
	// SetLegalHold places or releases a hold on an object that already exists.
	// Placing a hold covers what an archive already holds; releasing one is
	// governed outside this interface, by whatever the deployment's break-glass
	// role is, and this only makes the call.
	SetLegalHold(ctx context.Context, key string, on bool) error
	// ExtendRetention lengthens an object's retention to until. It only ever
	// lengthens: compliance mode refuses a shorter date, and so must every
	// implementation, or a test could shorten what a real bucket would keep.
	// A caller that is not sure the new date is later checks with Head first.
	ExtendRetention(ctx context.Context, key string, until time.Time) error
	// Prefixes returns the distinct groups one level under a prefix, as S3's
	// common prefixes: listing "records/security/" with "/" gives the tenants
	// without walking the objects beneath them.
	//
	// The archive puts the tenant between the profile and the hour, so a job
	// that works a range of hours cannot build its prefix without first
	// knowing which tenants exist. Walking every object to find out would cost
	// the whole profile every time.
	Prefixes(ctx context.Context, prefix, delimiter string) ([]string, error)
}