admission

type Authorizer ¶

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
}

Authorizer decides both tenant command admission and the service sweep. Admission repeats the edge's control decision deliberately: it is a durable mutation boundary that can later be called by transports other than HTTP and ClientLink, and no such caller may acquire an authorization-free path.

type Catalog ¶

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

type Claims ¶

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

Claims is the short-lived reconciliation claim of specification section 10.

It SUPPRESSES DUPLICATE WORK AND IS NEVER A FENCE, which is a property of SessionStore's record rather than a promise made here: the record cannot name ownership, and nothing in that package reads a claim to decide a write. What makes two replicas sweeping one shard safe is the compare-and-swap on the command's own revision and the store's evidence rule; the claim only stops them both paying for it.

type Clock ¶

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)
}

Clock is the time seam.

It names only standard-library and builtin types on purpose. Factory's public option surface declares an identical Clock, and a shape with a named Timer type would make the two interfaces mutually unassignable across the internal/ boundary; AfterFunc's stop function is an unnamed func type, so they remain the same interface without an adapter.

type CommandStore ¶

type CommandStore interface {
	AdmitDispositionCommand(context.Context, sessionstore.AdmitDispositionCommandRequest) (sessionstore.DispositionInboxEntry, bool, error)
	GetDispositionCommand(context.Context, sessionstore.GetDispositionCommandRequest) (sessionstore.DispositionInboxEntry, error)
	PutCommandPayload(context.Context, sessionstore.PutCommandPayloadRequest) (sessionwire.ObjectMetadata, error)
}

CommandStore is the durable command plane every command but a create is admitted into. It is the DISPOSITION family and only that family: see ErrLegacySessionUnsupported for why a legacy inbox write would be a command no Host could ever apply.

PutCommandPayload is here, and not borrowed from PublicCreateStore, because an oversized input is stored by reference exactly as an oversized create is (runbook A3.1 step 5), and PublicCreates is an OPTIONAL seam: a composition serving no creates must still be able to admit a large input.

type Commands ¶

type Commands interface {
	AdmitDispositionCommand(ctx context.Context, req sessionstore.AdmitDispositionCommandRequest) (sessionstore.DispositionInboxEntry, bool, error)
	GetDispositionCommand(ctx context.Context, req sessionstore.GetDispositionCommandRequest) (sessionstore.DispositionInboxEntry, error)
	PutCommandPayload(ctx context.Context, req sessionstore.PutCommandPayloadRequest) (sessionwire.ObjectMetadata, error)
	RejectDispositionCommand(ctx context.Context, req sessionstore.RejectDispositionCommandRequest) (sessionstore.DispositionInboxEntry, bool, error)
	ListDueDispositionCommands(ctx context.Context, req sessionstore.ListDueDispositionCommandsRequest) (sessionstore.DispositionDueCommandPage, 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)
}

Commands is the durable command plane admission uses.

Admission writes and reads the DISPOSITION family only. The two legacy methods left here, RejectCommand and ListDueCommands, belong to the legacy deadline sweep (Reconciler), which still settles legacy rows a store may already hold; nothing in this package admits into that family any more.

type Config ¶

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

	// GateResponders decides whether a gate response may be admitted for the
	// owner that would apply it. OPTIONAL, and nil REFUSES every gate response
	// with gate_not_resumable (ErrGateResponseUnsupported): the safe default is
	// the one that never hands a Host a command it cannot apply.
	GateResponders      GateResponders
	StampPrincipal      bool
	PrincipalResponders PrincipalResponders

	// 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
	// OnAdmitted is a best-effort notification after a durable admission.
	// The durable pending sweep remains responsible for lost notifications.
	OnAdmitted func(placement.AdmissionNotice)
}

type Directory ¶

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)
}

Directory is the observed target directory: which Host currently owns a session, and which Hosts could accept one.

type Disposition ¶

type Disposition uint8

Disposition is what one sweep did about one due row, or why it did nothing.

It is a closed vocabulary with a rendering for every member including an unrecognized one, for the reason placement.Outcome is: a row's fate is operational data, and "" is not a fate.

const (
	// DispositionSettleable is the predicate's positive answer and never a
	// recorded outcome: a row that reaches it goes on to be settled, deferred
	// or refused, and the recorded disposition is one of those.
	DispositionSettleable Disposition = iota

	// DispositionRejected means this sweep settled the command as rejected.
	DispositionRejected

	// DispositionUnexpired means the apply deadline has not passed. A Host may
	// still claim and apply the command, so nothing here may settle it.
	DispositionUnexpired

	// DispositionClaimLive means a live command claim holds the row: a Host is
	// working on it now.
	DispositionClaimLive

	// DispositionApplying means an application is in flight. Only the NEXT
	// lease holder can settle it, because the safety of that settlement rests
	// on a journal fence written at an epoch above the applying one -- and this
	// reconciler holds no lease and names no epoch.
	DispositionApplying

	// DispositionTerminal means the command had already reached applied or
	// rejected. inboxDue files a terminal command not-due, so this is a row
	// that settled between the page and the write.
	DispositionTerminal

	// DispositionEvidence means the store refused the settlement because the
	// session's journal does not prove the command had no effect. That is the
	// prefix winning, and it is an ordinary outcome rather than a fault.
	DispositionEvidence

	// DispositionRaceLost means the record moved between the page and the
	// compare-and-swap.
	DispositionRaceLost

	// DispositionDeferred means another replica holds this session's
	// reconciliation claim, so this one did nothing about the row.
	DispositionDeferred

	// DispositionUnrecognized means the record is in a state this build does
	// not know. It is refused rather than guessed at, so a newer store's state
	// cannot be rejected by an older sweeper. Only the disposition sweep
	// reports it: the legacy predicate's arms are total over its own states.
	DispositionUnrecognized
)

func (d Disposition) String() string

type DispositionDue ¶ added in v0.3.0

type DispositionDue interface {
	ControlShards() int
	ListDueDispositionCommands(context.Context, sessionstore.ListDueDispositionCommandsRequest) (sessionstore.DispositionDueCommandPage, error)
}

DispositionDue is the disposition family's service-plane due query. It is the same two methods as DueCommands for the same reasons, over the other family's index.

type DispositionReconciler ¶ added in v0.3.0

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

DispositionReconciler sweeps expired disposition commands in fixed control shards, round-robin, one shard per pass and at most MaxPages*PageLimit rows.

It REMEMBERS WHERE EACH SHARD'S PASS STOPPED, and that is what keeps it from starving. The due view is deadline-ordered from the head, and the head is exactly where the rows this sweep may NOT reject accumulate: applying commands (a successor's business) and claimed ones whose claim is still live, each filed at its long-past deadline. A sweep that re-read from the head every pass would, once a shard held more than MaxPages*PageLimit of those, never again reach a rejectable row behind them. So a truncated pass keeps the store's continuation for its shard and the next pass over that shard resumes from it; only a pass that reaches the end re-arms at the head against a fresh bound. The position is advice, like the rotor: a restarted replica starts every shard at the head and loses nothing but time.

func NewDispositionReconciler(cfg DispositionReconcilerConfig) (*DispositionReconciler, error)

func (r *DispositionReconciler) Sweep(ctx context.Context, principal identity.Principal) (SweepResult, error)

type DispositionReconcilerConfig ¶ added in v0.3.0

type DispositionReconcilerConfig struct {
	Authorizer Authorizer
	Due        DispositionDue
	Settlement DispositionSettlement
	Claims     Claims
	Clock      Clock
	HolderID   string
	ClaimTTL   time.Duration
	PageLimit  int
	MaxPages   int
}

DispositionReconcilerConfig is one replica's disposition deadline sweep. Its members mean exactly what ReconcilerConfig's do.

type DispositionSettlement ¶ added in v0.3.0

type DispositionSettlement interface {
	RejectDispositionCommand(context.Context, sessionstore.RejectDispositionCommandRequest) (sessionstore.DispositionInboxEntry, bool, error)
}

DispositionSettlement is the one durable write the disposition sweep makes. It is the pre-dispatch rejection and nothing else, for Settlement's reason: every other disposition transition belongs to a residency holder.

type DueCommands ¶

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

DueCommands is the service-plane due-work query.

It is TWO methods because a sweeper needs both halves and neither can come from anywhere else. ControlShards is a READ of the count the backend is committed to, not a setting: the shard is a pure function of (TenantID, SessionID) computed identically by the writer and the sweeper, so a sweeper configured with its own count would silently never visit some shards. ListDueCommands answers one shard at a time, deliberately -- a store that swept every shard in one call would hold the whole deployment's reconciliation in one request's latency.

type Error ¶

type Error struct {
	Code  sessionwire.ErrorCode
	Cause error
}

func (e *Error) Error() string

func (e *Error) Unwrap() error

type GateResponders ¶ added in v0.5.0

type GateResponders interface {
	// AcceptsGateResponses reports whether owner can apply a gate response.
	// (false, nil) is a decision about the Host; an error is a fault -- the
	// Host could not be asked -- and is never read as "cannot".
	AcceptsGateResponses(ctx context.Context, owner sessionwire.HostLinkRegistryObservation) (bool, error)
}

GateResponders answers whether a session's live owner can apply a gate_response command. The composition implements it over the HostLink pool, asking the owner's link for the session's tenant and deciding with hostlink.GateResponseCapable -- the one predicate. See ErrGateResponseUnsupported.

type LegacyCreateRequest ¶

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

type LegacyCreateResult ¶

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

type OwnerDirectory ¶

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

type PlacementController ¶

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

PlacementController drives desired placement. It is idempotent in both directions: a repeated Ensure for the same desired workload creates nothing twice, and a repeated Release is not an error.

type PrincipalResponders ¶ added in v0.12.0

type PrincipalResponders interface {
	AcceptsCommandPrincipal(context.Context, sessionwire.HostLinkRegistryObservation) (bool, error)
}

PrincipalResponders asks whether a resident Host reads attribution members.

type PublicCreateStore ¶

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)
}

PublicCreateStore is the durable public-create plane.

It is the disposition family, not the legacy inbox, and that is forced rather than chosen: a Host takes residency through AcquireResidency, which pins ProtocolModeDisposition, so a legacy-bound session is one no Host can ever run.

type Reconciler ¶

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

Reconciler sweeps due commands in fixed control shards, round-robin.

It holds exactly one piece of state, the rotor, and that state is advice rather than position: a restarted replica resumes at shard zero and re-derives everything else from the store within the call.

func NewReconciler(cfg ReconcilerConfig) (*Reconciler, error)

func (r *Reconciler) Sweep(ctx context.Context, principal identity.Principal) (SweepResult, error)

type ReconcilerConfig ¶

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
}

ReconcilerConfig is one replica's due-command sweep configuration.

type Service ¶

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

func NewService(cfg Config) (*Service, error)

func (s *Service) AdmitCreate(ctx context.Context, principal identity.Principal, req sessionwire.CreateRequest) (sessionstore.DispositionInboxEntry, bool, error)

func (s *Service) AdmitGateResponse(ctx context.Context, principal identity.Principal, req sessionwire.GateResponseRequest) (sessionstore.DispositionInboxEntry, bool, error)

func (s *Service) AdmitInput(ctx context.Context, principal identity.Principal, req sessionwire.InputRequest) (sessionstore.DispositionInboxEntry, bool, error)

func (s *Service) AdmitInterrupt(ctx context.Context, principal identity.Principal, req sessionwire.InterruptRequest) (sessionstore.DispositionInboxEntry, bool, error)

func (s *Service) AdmitLegacyCreate(ctx context.Context, principal identity.Principal, req LegacyCreateRequest) (LegacyCreateResult, error)

func (s *Service) AdmitRestore(ctx context.Context, principal identity.Principal, req sessionwire.RestoreRequest) (sessionstore.DispositionInboxEntry, bool, error)

func (s *Service) FenceAdmissions() <-chan struct{}

func (s *Service) GateResponsesAnswerable(ctx context.Context, tenant sessionwire.TenantID, session sessionwire.SessionID, record sessionstore.CatalogRecord) (bool, error)

func (s *Service) Quiesce(ctx context.Context) error

type SessionBindingTemplate ¶

type SessionBindingTemplate struct {
	StorageBindingID string
	BindingVersion   string
}

SessionBindingTemplate is the deployment-configuration half of the immutable SessionBinding a V1 create pins into its session, forever.

It carries only the two members a DEPLOYMENT owns. The other two are not configuration and are deliberately absent: RuntimeSessionID is derived per create (see deriveRuntimeSessionID) and ProtocolMode is this module's own choice, not a knob -- see bind.

Why these two are exactly the deployment's: they are the two members ObjectStoreResolver keys on. A resolver "refuses any configuration this deployment does not know", so a create that pinned a StorageBindingID the resolver cannot resolve would write a session whose objects are permanently unreadable -- and SessionBinding is immutable after create, so there is no repair. The composition therefore refuses this template without a resolver, which is what makes this configuration rather than a guess.

type Settlement ¶

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

Settlement is the one durable write this reconciler makes.

It is exactly one method, and the narrowness is the point rather than tidiness: the settlements a due row could invite are reject, claim, begin applying and complete, and three of those are a LEASE HOLDER's. A reconciler holds no session lease and names no epoch, so a seam offering them would be authority this package cannot legitimately exercise.

type SweepResult ¶

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

	// Resumed reports that this pass continued from the position an earlier
	// truncated pass over the same shard kept, rather than from the head.
	// Only the disposition sweep keeps positions; the legacy one always reads
	// from the head.
	Resumed bool
}

SweepResult is what one sweep of one shard did, and what producing it cost.

type Target ¶

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

Target is the configured immutable launch identity selected for a create. It is configuration, not current Host capacity and not an ownership claim.

type TargetResolver ¶

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

type UUIDSource ¶

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

UUIDSource supplies the random identifiers Factory proposes, notably the SessionID it allocates before a Host exists to allocate one.