store

type ActiveLease struct {
	ID      string
	Expires time.Time
}

type Candidate struct {
	Key        string
	Generation string
	Handle     string
	Filesystem Filesystem
}

type FencingToken uint64

type Filesystem struct {
	Type  string
	UUID  string
	Clean bool
}

type KeyMatcher interface {
	Match(ctx context.Context, exact string, restorePrefixes []string) (key, generation string, err error)
}

type Store interface {
	// Current reports the site's published generation for a key. ErrMiss means
	// there is no pointer. Publication policies use this only after a CAS conflict.
	Current(ctx context.Context, key string) (string, error)
	// Create maps a new, unformatted writable volume for a cold key.
	Create(ctx context.Context, key string, sizeBytes int64) (Volume, error)
	// Clone maps a writable clone of generation. Empty generation means the
	// site's current pointer; ErrMiss is a cold cache and never a job failure.
	Clone(ctx context.Context, key, generation string) (Volume, error)
	// RenewActive keeps a mounted generation out of eviction.
	RenewActive(ctx context.Context, volume Volume, until time.Time) error
	// AcquireWriter issues a separate storage lease and monotonically newer fence.
	// While another writer's lease is live it refuses with a *WriterHeldError.
	AcquireWriter(
		ctx context.Context, key, holder string, ttl time.Duration,
	) (WriterLease, FencingToken, error)
	// ReleaseWriter gives back a writer whose publication is not going to
	// happen, so the next writer need not wait out its lease. It removes exactly
	// the lease it is handed — matched by identity, expiry and fence — and
	// leaves anything else standing: a lease PublishCAS already consumed, one
	// that expired and was replaced, one this caller never held. Nothing else
	// moves: not the pointer, not a candidate, and never the fence, so a
	// released lease can publish no more than an expired one can.
	ReleaseWriter(ctx context.Context, lease WriterLease, fence FencingToken) error
	// Snapshot verifies an already-quiesced, unmounted volume and creates an
	// immutable candidate. The current pointer is unchanged on every failure.
	Snapshot(ctx context.Context, volume Volume) (Candidate, error)
	// PublishCAS advances the pointer only if expected, lease and fence are still
	// current. A caller not permitted to publish never calls this method.
	PublishCAS(
		ctx context.Context,
		key, expected string,
		candidate Candidate,
		lease WriterLease,
		fence FencingToken,
	) error
	// Discard releases a clone. It is idempotent.
	Discard(ctx context.Context, volume Volume) error
	// Evict removes inactive generations and abandoned candidates while preserving
	// every generation protected by a live active-clone lease.
	Evict(ctx context.Context, olderThan time.Duration) error
}

type Volume struct {
	Key        string
	Generation string
	Handle     string
	Device     string
	Lease      ActiveLease
	// Filesystem is proof collected after the cooperative guest unmounts a
	// remotely attached volume. A host-mapped backend verifies the device itself;
	// a remote EBS backend has no block path on the orchestrator and requires this.
	Filesystem Filesystem
}

type WriterHeldError struct {
	Key     string
	Holder  string
	Expires time.Time
}

type WriterLease struct {
	Key     string
	ID      string
	Expires time.Time
}