admission

type Authorizer interface {
	AuthorizeControl(ctx context.Context, principal identity.Principal, session sessionwire.SessionID, kind sessionstore.CommandKind) error

	// AuthorizeServiceSweep covers the cross-tenant due-work sweep over the
	// service-control shards. It is never reachable by a tenant principal and
	// its records never become a cross-tenant public response.
	AuthorizeServiceSweep(ctx context.Context, principal identity.Principal) error
}

type Catalog interface {
	GetCatalogEntry(context.Context, sessionstore.GetCatalogEntryRequest) (sessionstore.CatalogEntry, error)
	CreateCatalogEntry(context.Context, sessionstore.CreateCatalogEntryRequest) (sessionstore.CatalogEntry, bool, error)
}

type Claims interface {
	AcquireReconciliationClaim(context.Context, sessionstore.AcquireReconciliationClaimRequest) (sessionstore.ReconciliationClaimEntry, error)
	ReleaseReconciliationClaim(context.Context, sessionstore.ReleaseReconciliationClaimRequest) (sessionstore.ReconciliationClaimEntry, error)
}

type Clock interface {
	Now() time.Time
	// AfterFunc runs f after d and returns a stop function reporting whether
	// it prevented the call.
	AfterFunc(d time.Duration, f func()) (stop func() bool)
}

type CommandStore interface {
	AdmitCommand(context.Context, sessionstore.AdmitCommandRequest) (sessionstore.InboxEntry, bool, error)
	GetCommand(context.Context, sessionstore.GetCommandRequest) (sessionstore.InboxEntry, error)
}

type Commands interface {
	AdmitCommand(ctx context.Context, req sessionstore.AdmitCommandRequest) (sessionstore.InboxEntry, bool, error)
	GetCommand(ctx context.Context, req sessionstore.GetCommandRequest) (sessionstore.InboxEntry, error)
	RejectCommand(ctx context.Context, req sessionstore.RejectCommandRequest) (sessionstore.InboxEntry, error)
	ListDueCommands(ctx context.Context, req sessionstore.ListDueCommandsRequest) (sessionstore.DueCommandPage, error)
	AcquireReconciliationClaim(ctx context.Context, req sessionstore.AcquireReconciliationClaimRequest) (sessionstore.ReconciliationClaimEntry, error)
	ReleaseReconciliationClaim(ctx context.Context, req sessionstore.ReleaseReconciliationClaimRequest) (sessionstore.ReconciliationClaimEntry, error)
}

type Config struct {
	Authorizer Authorizer
	Targets    TargetResolver
	Catalog    Catalog
	Commands   CommandStore
	Directory  OwnerDirectory
	Clock      Clock
	IDs        UUIDSource

	// PublicCreates is the durable public-create plane a V1 create admits
	// into. It is OPTIONAL, and its absence is a supported composition rather
	// than a broken one: without it, and without Binding, AdmitCreate refuses
	// and every other entry point is unaffected.
	PublicCreates PublicCreateStore

	// Binding is the deployment-configuration half of the immutable binding a
	// V1 create pins. Optional for the same reason.
	Binding SessionBindingTemplate

	ApplyDeadline time.Duration
}

type Directory interface {
	// Owner reports the observed registration for a session. The boolean is
	// false when no owner is observed, which is not an error.
	Owner(ctx context.Context, tenant sessionwire.TenantID, session sessionwire.SessionID) (sessionwire.HostLinkRegistryObservation, bool, error)

	// Candidates pages compatible accepting Hosts. Capacity is not authority:
	// a candidate confers nothing until the session lease is acquired.
	Candidates(ctx context.Context, req sessionstore.ListCompatibleHostsRequest) (sessionstore.HostTargetPage, error)
}

type Disposition uint8

type DueCommands interface {
	ControlShards() int
	ListDueCommands(context.Context, sessionstore.ListDueCommandsRequest) (sessionstore.DueCommandPage, error)
}

type Error struct {
	Code  sessionwire.ErrorCode
	Cause error
}

type LegacyCreateRequest struct {
	AgentID sessionwire.AgentID
	Blocks  json.RawMessage
}

type LegacyCreateResult struct {
	SessionID sessionwire.SessionID
	Entry     sessionstore.InboxEntry
}

type OwnerDirectory interface {
	Owner(context.Context, sessionwire.TenantID, sessionwire.SessionID) (sessionwire.HostLinkRegistryObservation, bool, error)
}

type PlacementController interface {
	EnsurePlacement(ctx context.Context, desired sessionstore.DesiredWorkload) error
	ReleasePlacement(ctx context.Context, tenant sessionwire.TenantID, session sessionwire.SessionID) error
}

type PublicCreateStore interface {
	PreparePublicCreate(context.Context, sessionstore.PreparePublicCreateRequest) (sessionstore.PublicCreatePreparation, error)
	PutCommandPayload(context.Context, sessionstore.PutCommandPayloadRequest) (sessionwire.ObjectMetadata, error)
	AdmitPublicCreate(context.Context, sessionstore.AdmitPublicCreateRequest) (sessionstore.DispositionInboxEntry, bool, error)
}

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

type ReconcilerConfig struct {
	// Authorizer decides the sweep. The method called is AuthorizeServiceSweep
	// and never AuthorizeControl: see Reconciler.Sweep.
	Authorizer Authorizer

	Due        DueCommands
	Settlement Settlement
	Claims     Claims
	Clock      Clock

	// HolderID names this replica in a reconciliation claim. It is not
	// authority -- the claim licenses nothing -- but it must be stable for a
	// process, because extending one's own claim and taking over a crashed
	// replica's lapsed one are the same store write and the holder is what
	// tells them apart.
	HolderID string

	// ClaimTTL is how long this replica claims a session's reconciliation work
	// for.
	ClaimTTL time.Duration

	// PageLimit bounds one due page.
	PageLimit int

	// MaxPages bounds ONE sweep of ONE shard.
	//
	// It is the periodic bound, and it is a bound on a PASS rather than on the
	// work: a shard with more due rows than MaxPages*PageLimit is reported
	// Truncated and finished by the next pass over that shard. That is chosen
	// over draining the shard because the sweep is periodic and the alternative
	// lets one busy shard hold the rotor -- and therefore every other shard's
	// reconciliation -- for as long as its backlog lasts.
	MaxPages int
}

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

type SessionBindingTemplate struct {
	StorageBindingID string
	BindingVersion   string
}

type Settlement interface {
	RejectCommand(context.Context, sessionstore.RejectCommandRequest) (sessionstore.InboxEntry, error)
}

type SweepResult struct {
	// Shard is the control shard this sweep visited.
	Shard int

	// Pages, Examined and Unreadable are the store's own cost report,
	// accumulated across the pages this sweep read. Examined is rows the
	// provider returned and Unreadable is rows the store could not vouch for;
	// both are reported rather than folded, because Examined == Pages*PageLimit
	// with nothing returned is a different state from "nothing is due".
	Pages      int
	Examined   int
	Unreadable int

	// Due is the number of readable due rows this sweep considered.
	Due int

	// Rejected counts the commands this sweep settled.
	Rejected int

	// Claimed and Released count the reconciliation claims this sweep took and
	// gave back. They are separate counters rather than one, because a
	// difference between them is the thing worth seeing.
	Claimed  int
	Released int

	// Dispositions counts every recorded outcome by kind. DispositionSettleable
	// never appears in it.
	Dispositions map[Disposition]int

	// Queries counts the store calls this sweep made that reach a provider:
	// due pages, claim acquisitions, claim releases and settlements.
	// ControlShards is deliberately not counted -- it is a read of a decision
	// the store already holds in memory and makes no provider request.
	Queries int

	// ReleaseFailures counts releases that failed.
	//
	// A release failure is deliberately SWALLOWED -- replacing a correct
	// settlement with a release error would report the wrong thing about the
	// command, and a claim licenses nothing, so a claim left to lapse costs a
	// delayed takeover of work that was already safe to do concurrently. This
	// counter is what keeps "swallowed" from meaning "invisible", which is the
	// shape a destructive call site with no observable takes.
	ReleaseFailures int

	// Truncated reports that MaxPages was reached with a continuation still
	// outstanding. The remaining rows are still due and are met by the next
	// pass over this shard.
	Truncated bool
}

type Target struct {
	Key      sessionstore.HostTargetKey
	Workload sessionstore.DesiredWorkload
}

type TargetResolver interface {
	ResolveAgent(context.Context, sessionwire.AgentID) (Target, bool, error)
	IsKnown(context.Context, sessionstore.HostTargetKey) (bool, error)
}

type UUIDSource interface {
	NewUUID() (string, error)
}