coord

type BackendKind string

type Capability struct {
	// Supported is true when direct coordination is available.
	Supported bool
	// Backend identifies the backend that would coordinate the scope.
	Backend BackendKind
	// VolumeID is the owning Volume id.
	VolumeID string
	// ObjectStoreID is the ObjectStore id inside the Volume.
	ObjectStoreID string
	// Generation is the latest durable generation observed by the coordinator.
	Generation uint64
	// FallbackReason explains why Supported is false.
	FallbackReason FallbackReason
}

type Coordinator interface {
	// Capability reports whether the scoped ObjectStore supports direct
	// multi-writer coordination and why callers must fall back when it does not.
	Capability(ctx context.Context, scope Scope) (*Capability, error)
	// Snapshot returns the latest durable generation and root metadata.
	Snapshot(ctx context.Context, scope Scope) (*Snapshot, error)
	// Watch returns root, prefix, lock, and fallback events after generation.
	Watch(ctx context.Context, scope Scope, afterGeneration uint64) (Watch, error)
	// TryAcquireWriteLease attempts to acquire the logical write lease.
	TryAcquireWriteLease(ctx context.Context, scope Scope) (WriteLease, bool, error)
	// WaitAcquireWriteLease waits until the logical write lease is available.
	WaitAcquireWriteLease(ctx context.Context, scope Scope) (WriteLease, error)
}

type Event struct {
	// ProcessID identifies the process that produced or requested the event.
	ProcessID string
	// VolumeID is the owning Volume id.
	VolumeID string
	// ObjectStoreID is the ObjectStore id inside the Volume.
	ObjectStoreID string
	// Generation is the durable generation associated with this event.
	Generation uint64
	// WantLock is true when another participant is waiting for the write lease.
	WantLock bool
	// Unlocked is true when a participant released the write lease.
	Unlocked bool
	// RootChanged carries the accepted root after a commit.
	RootChanged *bucket.ObjectRef
	// KeyPrefixChanged carries a key prefix invalidated by a commit.
	KeyPrefixChanged []byte
	// FallbackReason carries a visible fallback reason when direct coordination fails.
	FallbackReason FallbackReason
}

type FallbackReason string

type Scope struct {
	// VolumeID is the owning Volume id.
	VolumeID string
	// ObjectStoreID is the ObjectStore id inside the Volume.
	ObjectStoreID string
	// ParticipantID identifies the process or handle performing the operation.
	ParticipantID string
}

type Snapshot struct {
	// VolumeID is the owning Volume id.
	VolumeID string
	// ObjectStoreID is the ObjectStore id inside the Volume.
	ObjectStoreID string
	// Generation is the latest durable generation.
	Generation uint64
	// Root is the latest durable ObjectStore root.
	Root *bucket.ObjectRef
}

type UnsupportedCoordinator struct {
	// Backend is the unsupported backend kind to report.
	Backend BackendKind
	// Reason is the fallback reason to report.
	Reason FallbackReason
}

type Watch interface {
	// Events returns the event stream for this watch.
	Events() <-chan Event
	// Close releases resources held by this watch.
	Close() error
}

type WriteLease interface {
	// Refresh returns the latest durable generation and root before writing.
	Refresh(ctx context.Context) (*Snapshot, error)
	// Publish records an accepted generation/root/prefix change.
	Publish(ctx context.Context, event Event) (*Snapshot, error)
	// Release releases the logical write lease.
	Release(ctx context.Context) error
}