app

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

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNotFound      = errors.New("concurrencyauthority: lease not found")
	ErrUnavailable   = errors.New("concurrencyauthority: unavailable")
	ErrInvalidInput  = errors.New("concurrencyauthority: invalid input")
	ErrSnapshotEmpty = errors.New("concurrencyauthority: rule snapshot unavailable")
)

Sentinel application errors.

Functions

func IsAmbiguousRenewError

func IsAmbiguousRenewError(err error) bool

IsAmbiguousRenewError reports whether err means occupancy may still be held after an unconfirmed renew attempt (timeout/transport/unavailable).

func SnapshotStateFromReadiness

func SnapshotStateFromReadiness(r domain.Readiness) economics.SnapshotState

SnapshotStateFromReadiness maps concurrency readiness onto economics.SnapshotState.

func WrapError

func WrapError(op string, err error) error

WrapError annotates err with an operation name.

Types

type AcquireCommand

type AcquireCommand struct {
	Lease      domain.Lease
	RuleID     string
	Dimensions domain.Dimensions
	Limit      int
	Mode       domain.RuleMode
	Now        time.Time
}

AcquireCommand requests an idempotent lease insert under a capacity limit.

type AcquireResult

type AcquireResult struct {
	Lease            domain.Lease
	Replayed         bool
	RemainingSlots   int
	CapacityExceeded bool
	Rejected         bool
}

AcquireResult is the store outcome for one acquire attempt.

type AcquireSetCommand

type AcquireSetCommand struct {
	SetID       string
	RequestID   string
	Members     []AcquireSetMember
	TTL         time.Duration
	RenewBefore time.Duration
	Now         time.Time
}

AcquireSetCommand requests atomic multi-rule occupancy for one logical request.

type AcquireSetMember

type AcquireSetMember struct {
	Lease      domain.Lease
	RuleID     string
	Dimensions domain.Dimensions
	Limit      int
	Mode       domain.RuleMode
}

AcquireSetMember is one rule occupancy proposed for an atomic set acquire.

type AcquireSetResult

type AcquireSetResult struct {
	Set              domain.LeaseSet
	Replayed         bool
	RemainingSlots   int
	CapacityExceeded bool
	Rejected         bool
	LockOrder        []string
	DenyingRuleID    string
}

AcquireSetResult is the store outcome for one set acquire/replay.

type AdmitInput

type AdmitInput struct {
	RequestID      string
	Scope          scope.PrincipalScopeView
	Namespace      string
	TTL            time.Duration
	BoundVersion   economics.PolicySnapshotRef
	IdempotencyKey string
	Lifecycle      metering.LifecycleScope
	ParentLeaseID  string
	AuxPolicy      domain.AuxPolicy
	RuleID         string
}

AdmitInput is application-level lease admission input.

type AdmitResult

type AdmitResult struct {
	Kind            domain.DecisionKind
	LeaseID         string
	Generation      int64
	ExpiresAt       time.Time
	RemainingSlots  int
	Readiness       domain.Readiness
	BoundVersion    economics.PolicySnapshotRef
	Evidence        domain.Evidence
	Acquired        bool
	Replayed        bool
	RuleID          string
	RenewBefore     time.Duration
	TTL             time.Duration
	FailureBehavior domain.FailureBehavior
	// Leases holds all rule occupancies from this Admit. It is empty on deny,
	// and on error every lease acquired by this Admit is rolled back.
	Leases []AdmittedLease
	SetID  string
}

AdmitResult is the application admit outcome.

For multi-rule allow, scalar LeaseID/Generation/... are the primary lease (last successfully acquired / lastAllow) for backward compatibility. Leases lists every occupancy acquired or replayed in this Admit.

type AdmittedLease

type AdmittedLease struct {
	LeaseID         string
	RuleID          string
	Generation      int64
	ExpiresAt       time.Time
	RenewBefore     time.Duration
	TTL             time.Duration
	FailureBehavior domain.FailureBehavior
	Acquired        bool
	Replayed        bool
}

AdmittedLease is one rule occupancy acquired or replayed during Admit.

type Clock

type Clock interface {
	Now() time.Time
}

Clock reports the current time for deterministic orchestration and tests.

type Error

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

Error wraps an operation failure without leaking store details.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type LeaseSetOccupancyCounts

type LeaseSetOccupancyCounts struct {
	Active    int
	Uncertain int
	Expiring  int
	Released  int
	Failed    int
}

LeaseSetOccupancyCounts is a bounded control-plane projection of set states.

type LeaseStore

type LeaseStore interface {
	Acquire(ctx context.Context, cmd AcquireCommand) (AcquireResult, error)
	Renew(ctx context.Context, cmd RenewCommand) (RenewResult, error)
	Release(ctx context.Context, cmd ReleaseCommand) (ReleaseResult, error)
	Query(ctx context.Context, q QueryCommand) (QueryResult, error)
	CheckReadiness(ctx context.Context) (domain.Readiness, error)

	// Atomic lease-set operations (Phase 6 / requirements 10.3–10.9).
	AcquireSet(ctx context.Context, cmd AcquireSetCommand) (AcquireSetResult, error)
	RenewSet(ctx context.Context, cmd RenewSetCommand) (RenewSetResult, error)
	ReleaseSet(ctx context.Context, cmd ReleaseSetCommand) (ReleaseSetResult, error)
	QuerySets(ctx context.Context, q QuerySetsCommand) (QuerySetsResult, error)
	MarkSetUncertain(ctx context.Context, setID string, now time.Time) error
}

LeaseStore is the persistence port implemented by task 8.2 dialects.

type Provider

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

Provider adapts Service onto authority.ConcurrencyProvider.

func NewProvider

func NewProvider(svc *Service) *Provider

NewProvider returns a ConcurrencyProvider backed by svc.

func (*Provider) AdmitLease

AdmitLease implements authority.ConcurrencyProvider.

func (*Provider) MarkLeaseSetUncertain

func (p *Provider) MarkLeaseSetUncertain(ctx context.Context, setID string) error

MarkLeaseSetUncertain marks a set conservatively occupied after ambiguous renew.

func (*Provider) QueryLeases

QueryLeases implements authority.ConcurrencyProvider.

func (*Provider) ReleaseLease

func (p *Provider) ReleaseLease(ctx context.Context, in authority.LeaseRelease) error

ReleaseLease implements authority.ConcurrencyProvider.

func (*Provider) RenewLease

RenewLease implements authority.ConcurrencyProvider.

type QueryCommand

type QueryCommand struct {
	LeaseID   string
	RequestID string
	RuleID    string
	State     domain.LeaseState
	Now       time.Time
	Limit     int
}

QueryCommand is a bounded lease query.

type QueryResult

type QueryResult struct {
	Leases []domain.Lease
}

QueryResult is a bounded page of leases.

type QuerySetsCommand

type QuerySetsCommand struct {
	SetID     string
	RequestID string
	State     domain.LeaseSetState
	Now       time.Time
	Limit     int
}

QuerySetsCommand is a bounded lease-set query.

type QuerySetsResult

type QuerySetsResult struct {
	Sets []domain.LeaseSet
}

QuerySetsResult is a bounded page of lease sets.

type ReleaseCommand

type ReleaseCommand struct {
	LeaseID   string
	RequestID string
	Reason    string
	Now       time.Time
}

ReleaseCommand releases a lease idempotently.

type ReleaseInput

type ReleaseInput struct {
	LeaseID   string
	RequestID string
	Reason    string
	SetID     string
}

ReleaseInput is application-level lease release input.

type ReleaseResult

type ReleaseResult struct {
	Applied bool
	Lease   domain.Lease
}

ReleaseResult is the store outcome for release.

type ReleaseSetCommand

type ReleaseSetCommand struct {
	SetID     string
	RequestID string
	Reason    string
	Now       time.Time
}

ReleaseSetCommand releases an entire lease set idempotently.

type ReleaseSetResult

type ReleaseSetResult struct {
	Applied bool
	Set     domain.LeaseSet
}

ReleaseSetResult is the store outcome for set release.

type RenewCommand

type RenewCommand struct {
	LeaseID            string
	RequestID          string
	ExpectedGeneration int64
	TTL                time.Duration
	Now                time.Time
}

RenewCommand extends a lease with generation CAS.

type RenewInput

type RenewInput struct {
	LeaseID            string
	RequestID          string
	ExpectedGeneration int64
	TTL                time.Duration
	SetID              string
	RenewBefore        time.Duration
}

RenewInput is application-level lease renewal input.

type RenewResult

type RenewResult struct {
	Lease domain.Lease
}

RenewResult is the store outcome for renew.

type RenewSetCommand

type RenewSetCommand struct {
	SetID              string
	RequestID          string
	ExpectedGeneration int64
	TTL                time.Duration
	RenewBefore        time.Duration
	Now                time.Time
}

RenewSetCommand renews every member of a lease set under one generation CAS.

type RenewSetResult

type RenewSetResult struct {
	Set       domain.LeaseSet
	Uncertain bool
}

RenewSetResult is the store outcome for set renew.

type RuleSnapshot

type RuleSnapshot struct {
	ID          string
	Version     string
	EffectiveAt time.Time
	FetchedAt   time.Time
	State       economics.SnapshotState
	Readiness   domain.Readiness
	Rules       []domain.Rule
}

RuleSnapshot is the immutable rule set consumed by admit orchestration.

func (RuleSnapshot) PolicyRef

PolicyRef returns the bindable policy snapshot identity for this rule set.

type RuleSource

type RuleSource interface {
	Snapshot(ctx context.Context) (RuleSnapshot, error)
}

RuleSource provides immutable concurrency rule snapshots.

type Service

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

Service owns concurrency-lease orchestration for admit, renew, release, query, and readiness. Persistence dialects implement LeaseStore (task 8.2).

func NewService

func NewService(rules RuleSource, store LeaseStore, clock Clock) *Service

NewService constructs a service with explicit dependencies. A nil clock uses the system wall clock.

func (*Service) Admit

func (s *Service) Admit(ctx context.Context, in AdmitInput) (AdmitResult, error)

Admit acquires or replays occupancy for matching rules. Strict multi-rule matches use one atomic lease set; advisory rules still use per-lease Acquire. If admission fails after occupancy was acquired, the leases newly acquired by this call are rolled back (replayed pre-existing leases are left untouched).

func (*Service) LeaseSetOccupancyCounts

func (s *Service) LeaseSetOccupancyCounts(ctx context.Context) (LeaseSetOccupancyCounts, error)

LeaseSetOccupancyCounts returns bounded occupancy counts by set state.

func (*Service) Query

func (s *Service) Query(ctx context.Context, q QueryCommand) (QueryResult, error)

Query returns a bounded lease page.

func (*Service) Readiness

func (s *Service) Readiness(ctx context.Context) (authority.Readiness, error)

Readiness maps domain readiness onto the public authority readiness enum.

func (*Service) ReadinessDomain

func (s *Service) ReadinessDomain(ctx context.Context) (domain.Readiness, error)

ReadinessDomain returns domain readiness from store (and optional snapshot). Uncertain or failed lease-set occupancy degrades readiness (task 6.4 remediation).

func (*Service) ReconcileUncertainSets

func (s *Service) ReconcileUncertainSets(ctx context.Context) ([]string, error)

ReconcileUncertainSets conservatively keeps uncertain sets occupied and returns their IDs for durable release-work resumption (startup reconciliation).

func (*Service) Release

func (s *Service) Release(ctx context.Context, in ReleaseInput) error

Release releases a lease or lease set idempotently.

func (*Service) Renew

func (s *Service) Renew(ctx context.Context, in RenewInput) (AdmitResult, error)

Renew extends an active lease or lease set with generation CAS.

func (*Service) RulesSnapshot

func (s *Service) RulesSnapshot(ctx context.Context) (RuleSnapshot, error)

RulesSnapshot returns the current immutable rule set for capacity queries.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL