authoritycoord

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package authoritycoord orchestrates multi-provider logical-request and backend-attempt authority admission with reverse compensation (Phase 6). Lease stores and usage-authority kernel rewrites remain later phases.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrQuotaReader identifies a bounded failure while reading the immutable
	// account-window evidence source. The underlying cause is available through
	// errors.Is/As, while Error deliberately contains no provider payload.
	ErrQuotaReader = errors.New("authoritycoord: quota observation reader failed")
	// ErrQuotaReaderProtocol identifies a reader that violates pagination or
	// bounded-result requirements. It is separate from store availability.
	ErrQuotaReaderProtocol = errors.New("authoritycoord: invalid quota observation reader response")
)

Functions

func AggregateReadiness 

func AggregateReadiness(values ...authority.Readiness) authority.Readiness

AggregateReadiness picks the most severe readiness among inputs.

func IsDenied 

func IsDenied(err error) bool

Types

type AttemptCoordinator 

type AttemptCoordinator struct {
	Slots          []AttemptSlot
	CleanupTimeout time.Duration
	Now            func() time.Time
}

func (*AttemptCoordinator) Admit 

func (c *AttemptCoordinator) Admit(ctx context.Context, in authority.AttemptAdmission) (CompositeDecision, error)

func (*AttemptCoordinator) PreviewClamps 

func (c *AttemptCoordinator) PreviewClamps(ctx context.Context, in authority.AttemptAdmission) ([]authority.Clamp, error)

func (*AttemptCoordinator) Release 

func (c *AttemptCoordinator) Release(ctx context.Context, stack CompensationStack) []CompensateFailed

func (*AttemptCoordinator) Settle 

func (c *AttemptCoordinator) Settle(parent context.Context, stack CompensationStack, in authority.AttemptSettlement) error

type AttemptPriorityClass 

type AttemptPriorityClass int
const (
	AttemptPriorityUnknown AttemptPriorityClass = iota
	AttemptPriorityHardSpend
	AttemptPriorityQuotaRate
	AttemptPriorityAdvisory
)

type AttemptSlot 

type AttemptSlot struct {
	ID              string
	Class           AttemptPriorityClass
	Provider        authority.AttemptProvider
	Strength        authority.Strength
	FailureBehavior authority.FailureBehavior
	Descriptor      *authority.ProviderDescriptor
	Stage           authority.Stage
}

type CompensateFailed 

type CompensateFailed struct {
	ProviderID string
	Handle     string
	Err        error
	Evidence   authority.SafeEvidence
}

CompensateFailed is recorded when reverse compensation fails (do not pretend released).

type CompensationStack 

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

CompensationStack holds successful admits in acquisition order. settle is a shared pointer so pass-by-value Settle calls retain per-provider settlement state across retries and concurrent callers (requirements 7.7, 8.6).

func (*CompensationStack) Entries 

func (s *CompensationStack) Entries() []StackEntry

Entries returns a copy of stack entries in acquisition order.

func (*CompensationStack) Handles 

func (s *CompensationStack) Handles() []string

Handles returns reservation handles in acquisition order.

func (*CompensationStack) Push 

func (s *CompensationStack) Push(e StackEntry)

Push appends a successful hold.

func (*CompensationStack) ReverseCompensate 

func (s *CompensationStack) ReverseCompensate(parent context.Context, timeout time.Duration) []CompensateFailed

ReverseCompensate releases entries in reverse order using a fresh bounded context derived from parent without inheriting cancellation (requirements 15.2, 15.3).

func (CompensationStack) SettleWaitingCount 

func (s CompensationStack) SettleWaitingCount(providerID string) int

SettleWaitingCount reports in-flight waiters for providerID (test/observability).

func (CompensationStack) UnfinishedSettleProviders 

func (s CompensationStack) UnfinishedSettleProviders() []string

UnfinishedSettleProviders returns stack provider IDs that still need settle (never successfully completed). Concurrency entries are omitted. Order follows first appearance on the stack (requirements 7.7, 8.6; Phase 4.5).

type Compensator 

type Compensator func(ctx context.Context) error

Compensator releases a prior successful admit hold.

type CompositeDecision 

type CompositeDecision struct {
	Kind               authority.DecisionKind
	Clamps             []authority.Clamp
	Stack              CompensationStack
	ProviderDecisions  []authority.Decision
	Readiness          authority.Readiness
	CompensateFailures []CompensateFailed
	Evidence           authority.SafeEvidence
	DeniedBy           string
	// Lease captures concurrency admit metadata for heartbeat/release (Phase 8).
	Lease authority.LeaseDecision
	// BoundVersions aggregates policy snapshot refs from providers and lease admit (11.2).
	BoundVersions []economics.PolicySnapshotRef
}

CompositeDecision is the aggregated admit result across providers.

type DeniedError 

type DeniedError struct {
	ProviderID string
	Decision   authority.Decision
}

DeniedError is returned when a required provider denies admission.

func (*DeniedError) Error 

func (e *DeniedError) Error() string

type PriorityClass 

type PriorityClass int

PriorityClass is the deterministic evaluation order for request providers (requirement 8.1 / design priority classes — not registration order). 

const (
	PriorityUnknown PriorityClass = iota
	PriorityConcurrency
	PriorityCreditWallet
	PriorityQuotaBudgetRate
	PriorityAdvisory
)

type QuotaReaderError 

type QuotaReaderError struct {
	Operation string
	Cause     error
}

QuotaReaderError is returned when an account-window reader cannot provide a complete immutable history. It is typed so a host can classify the result as unavailable without parsing provider text; the bounded Error string never includes the underlying provider error.

func (*QuotaReaderError) Error 

func (e *QuotaReaderError) Error() string

func (*QuotaReaderError) Unwrap 

func (e *QuotaReaderError) Unwrap() []error

type QuotaRequestProvider 

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

QuotaRequestProvider adapts nonfinancial provider allowance gauges to the generic request authority contract. It never emits reservations, exposure, customer credit, provider debit, or settlement money.

func NewQuotaRequestProvider 

func NewQuotaRequestProvider(cfg QuotaRequestProviderConfig) (*QuotaRequestProvider, error)

NewQuotaRequestProvider validates the immutable binding and constructs a request-stage provider. A nil reader is retained as unavailable telemetry so the policy's explicit unavailable action is evaluated instead of silently allowing a request.

func (*QuotaRequestProvider) AdmitRequest 

func (p *QuotaRequestProvider) AdmitRequest(ctx context.Context, _ authority.RequestAdmission) (authority.Decision, error)

AdmitRequest reads every page of the bound account-window history and maps the pure quota result into the generic request authority vocabulary.

func (*QuotaRequestProvider) Describe 

func (p *QuotaRequestProvider) Describe() authority.ProviderDescriptor

Describe declares a required fail-closed request-stage authority. A host may explicitly wrap this provider in an advisory registration, but no adapter default turns unavailable telemetry into an implicit allow.

func (*QuotaRequestProvider) GenerationScopedRequestProvider 

func (*QuotaRequestProvider) GenerationScopedRequestProvider()

GenerationScopedRequestProvider marks quota evaluation as candidate-local. The runtime uses this marker to keep a reloaded quota policy active even when the request also binds an older process-level executable snapshot.

func (*QuotaRequestProvider) PolicyRef 

func (p *QuotaRequestProvider) PolicyRef() authority.QuotaPolicyRef

PolicyRef returns the immutable policy identity used by this provider.

func (*QuotaRequestProvider) ReleaseRequest 

func (p *QuotaRequestProvider) ReleaseRequest(context.Context, authority.RequestRelease) error

ReleaseRequest is a no-op because the quota adapter never acquires a hold.

func (*QuotaRequestProvider) SettleRequest 

func (p *QuotaRequestProvider) SettleRequest(_ context.Context, _ authority.RequestSettlement) (authority.Settlement, error)

SettleRequest is intentionally nonfinancial. Quota gauge observations do not create a hold, so settlement returns an explicit unavailable result and carries no handle, money, quantity, or payable evidence.

type QuotaRequestProviderConfig 

type QuotaRequestProviderConfig struct {
	ID       string
	Policy   *authority.QuotaPolicy
	Store    coremetering.AccountWindowStore
	Now      func() time.Time
	PageSize int
}

QuotaRequestProviderConfig binds one immutable policy to one account-window reader. Policy and all identity values are generation-scoped: rebuilding a host for a config reload creates a new provider and therefore freezes the policy reference for requests admitted by that generation.

type RequestCoordinator 

type RequestCoordinator struct {
	Concurrency           authority.ConcurrencyProvider
	ConcurrencyDescriptor *authority.ProviderDescriptor
	Slots                 []RequestSlot
	CleanupTimeout        time.Duration
	Now                   func() time.Time
}

RequestCoordinator evaluates concurrency (optional) then classified request providers in deterministic priority-class order (requirements 4.5, 8.1, 15.1–15.4).

func (*RequestCoordinator) Admit 

func (c *RequestCoordinator) Admit(ctx context.Context, in authority.RequestAdmission) (CompositeDecision, error)

func (*RequestCoordinator) HasGenerationScopedRequestProviders 

func (c *RequestCoordinator) HasGenerationScopedRequestProviders() bool

HasGenerationScopedRequestProviders reports whether c contains an evaluator compiled from the candidate generation. The coordinator remains immutable after construction, so this read is safe during concurrent request admits.

func (*RequestCoordinator) Release 

func (c *RequestCoordinator) Release(ctx context.Context, stack CompensationStack) []CompensateFailed

func (*RequestCoordinator) ReleaseLease 

func (c *RequestCoordinator) ReleaseLease(parent context.Context, leaseID, requestID, reason string) error

func (*RequestCoordinator) ReleaseLeaseSet 

func (c *RequestCoordinator) ReleaseLeaseSet(parent context.Context, setID, leaseID, requestID, reason string) error

func (*RequestCoordinator) ReleaseLeases 

func (c *RequestCoordinator) ReleaseLeases(parent context.Context, leaseIDs []string, requestID, reason string) error

func (*RequestCoordinator) RenewLease 

func (c *RequestCoordinator) RenewLease(ctx context.Context, in authority.LeaseRenew) (authority.LeaseDecision, error)

func (*RequestCoordinator) Settle 

func (c *RequestCoordinator) Settle(parent context.Context, stack CompensationStack, in authority.RequestSettlement) error

type RequestSlot 

type RequestSlot struct {
	ID              string
	Class           PriorityClass
	Provider        authority.RequestProvider
	Strength        authority.Strength
	FailureBehavior authority.FailureBehavior
	Descriptor      *authority.ProviderDescriptor
	Stage           authority.Stage
}

RequestSlot is one classified logical-request authority provider.

type StackEntry 

type StackEntry struct {
	ProviderID  string
	Handle      string
	Reservation authority.Reservation
	Compensate  Compensator
	Evidence    authority.SafeEvidence
}

StackEntry records one successful reservation for reverse compensation.

type StageSettleObservability 

type StageSettleObservability int

StageSettleObservability controls whether settle failures remain observable for reconciliation regardless of admission-time posture (requirement 15.5). 

const (
	StageSettleUnspecified StageSettleObservability = iota
	// StageSettleRecordAllFailures retains every provider settle failure (req 15.5).
	StageSettleRecordAllFailures
)

type UnavailableError 

type UnavailableError struct {
	ProviderID string
	Err        error
	// Decision preserves a provider's fail-closed posture and safe evidence
	// when its admission call returns both a decision and an error.
	Decision authority.Decision
}

UnavailableError is returned when required infrastructure fails closed.

func (*UnavailableError) Error 

func (e *UnavailableError) Error() string

func (*UnavailableError) Unwrap 

func (e *UnavailableError) Unwrap() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.