Documentation
¶
Overview ¶
Package sessionclassification provides the standard featurehost's bounded process-local adapter for feature-owned session classification state.
Index ¶
- Variables
- type BunStore
- func (s *BunStore) ClaimRemote(ctx context.Context, key featurestate.Key, now time.Time, maxAttempts uint32, ...) (featurestate.RemoteClaim, featurestate.Record, bool, error)
- func (s *BunStore) CompleteRemote(ctx context.Context, claim featurestate.RemoteClaim, ...) (featurestate.Record, error)
- func (s *BunStore) EnsureSchema(ctx context.Context) error
- func (s *BunStore) Load(ctx context.Context, key featurestate.Key) (featurestate.Record, bool, error)
- func (s *BunStore) Promote(ctx context.Context, key featurestate.Key, proposal session.Classification, ...) (featurestate.Record, bool, error)
- type Coordinator
- func (c *Coordinator) ClaimRemote(ctx context.Context, key featurestate.Key, now time.Time, maxAttempts uint32, ...) (featurestate.RemoteClaim, featurestate.Record, bool, error)
- func (c *Coordinator) CompleteRemote(ctx context.Context, claim featurestate.RemoteClaim, ...) (featurestate.Record, error)
- func (c *Coordinator) Load(ctx context.Context, key featurestate.Key) (featurestate.Record, bool, error)
- func (c *Coordinator) Promote(ctx context.Context, key featurestate.Key, proposal session.Classification, ...) (featurestate.Record, bool, error)
- type CoordinatorConfig
- type MemoryStore
- func (s *MemoryStore) ClaimRemote(ctx context.Context, key featurestate.Key, now time.Time, maxAttempts uint32, ...) (featurestate.RemoteClaim, featurestate.Record, bool, error)
- func (s *MemoryStore) CompleteRemote(ctx context.Context, claim featurestate.RemoteClaim, ...) (featurestate.Record, error)
- func (s *MemoryStore) Load(ctx context.Context, key featurestate.Key) (featurestate.Record, bool, error)
- func (s *MemoryStore) Promote(ctx context.Context, key featurestate.Key, proposal session.Classification, ...) (featurestate.Record, bool, error)
- type MemoryStoreConfig
- type MemoryStoreOption
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidBunDB = errors.New("session classification: invalid Bun database") ErrUnsupportedBunDialect = errors.New("session classification: unsupported Bun dialect") ErrBunSchema = errors.New("session classification: schema operation failed") ErrBunLoad = errors.New("session classification: durable load failed") ErrBunPromote = errors.New("session classification: durable promotion failed") ErrBunRemoteClaim = errors.New("session classification: durable remote claim failed") ErrBunRemoteComplete = errors.New("session classification: durable remote completion failed") ErrInvalidBunRecord = errors.New("session classification: invalid durable record") ErrBunRecordMissing = errors.New("session classification: durable winner disappeared") )
var ErrInvalidCoordinatorConfig = errors.New("session classification: invalid coordinator config")
ErrInvalidCoordinatorConfig reports a missing store or non-finite coordinator bounds.
Functions ¶
This section is empty.
Types ¶
type BunStore ¶
type BunStore struct {
// contains filtered or unexported fields
}
BunStore persists bounded session-classification state in the feature-owned logical table. The Bun DB is borrowed from featurehost and remains owned by its host.
func NewBunStore ¶
NewBunStore validates and retains a borrowed Bun DB without performing I/O.
func (*BunStore) ClaimRemote ¶
func (s *BunStore) ClaimRemote(ctx context.Context, key featurestate.Key, now time.Time, maxAttempts uint32, leaseTTL time.Duration, retryBackoff time.Duration) (featurestate.RemoteClaim, featurestate.Record, bool, error)
ClaimRemote atomically consumes one finite attempt and records its lease before the caller performs remote I/O. A single conditional upsert arbitrates claimers across store instances without a process-wide lock or open transaction.
func (*BunStore) CompleteRemote ¶
func (s *BunStore) CompleteRemote(ctx context.Context, claim featurestate.RemoteClaim, result featurestate.RemoteCompletion, now time.Time) (featurestate.Record, error)
CompleteRemote accepts only the currently held, unexpired lease. The guarded update lets a concurrent local promotion win without rewriting its positive.
func (*BunStore) EnsureSchema ¶
EnsureSchema creates the classification table when the owning lifecycle is ready to initialize durable feature state. It never drops or resets rows.
func (*BunStore) Load ¶
func (s *BunStore) Load(ctx context.Context, key featurestate.Key) (featurestate.Record, bool, error)
Load returns the record for a proxy-authority key without creating missing rows.
func (*BunStore) Promote ¶
func (s *BunStore) Promote(ctx context.Context, key featurestate.Key, proposal session.Classification, now time.Time) (featurestate.Record, bool, error)
Promote atomically records the first valid positive classification. The single dialect-neutral UPSERT installs a positive row or updates an unknown row while preserving its remote-attempt history.
type Coordinator ¶
type Coordinator struct {
// contains filtered or unexported fields
}
Coordinator wraps the feature-owned authoritative state store. Its cache retains only positive classification records; all unknown turns remain visible to future Loads through the authoritative store.
func NewCoordinator ¶
func NewCoordinator(store featurestate.Store, config CoordinatorConfig) (*Coordinator, error)
NewCoordinator creates a bounded process-local coordinator without performing storage I/O or taking ownership of the supplied store.
func (*Coordinator) ClaimRemote ¶
func (c *Coordinator) ClaimRemote(ctx context.Context, key featurestate.Key, now time.Time, maxAttempts uint32, leaseTTL time.Duration, retryBackoff time.Duration) (featurestate.RemoteClaim, featurestate.Record, bool, error)
ClaimRemote delegates attempt-budget and lease authority to Store. A cached positive short-circuits a new claim after validating its inputs.
func (*Coordinator) CompleteRemote ¶
func (c *Coordinator) CompleteRemote(ctx context.Context, claim featurestate.RemoteClaim, result featurestate.RemoteCompletion, now time.Time) (featurestate.Record, error)
CompleteRemote delegates lease completion and retains any accepted positive record, including a current positive returned with ErrStaleRemoteClaim.
func (*Coordinator) Load ¶
func (c *Coordinator) Load(ctx context.Context, key featurestate.Key) (featurestate.Record, bool, error)
Load returns a cached positive or loads the current authoritative record. Unknown results are never retained between calls.
func (*Coordinator) Promote ¶
func (c *Coordinator) Promote(ctx context.Context, key featurestate.Key, proposal session.Classification, now time.Time) (featurestate.Record, bool, error)
Promote atomically delegates a first-positive proposal and caches its stable result for later turns.
type CoordinatorConfig ¶
type CoordinatorConfig struct {
// CacheCapacity bounds retained positive records; capacity pressure evicts only local cache entries.
CacheCapacity int
// MaxInflight bounds keyed Load and Promote operations; new keys bypass coordination when full.
MaxInflight int
// IdleTTL expires unused positive cache entries during later cache operations.
IdleTTL time.Duration
// Now supplies cache timestamps and is called before taking the coordinator lock.
Now func() time.Time
}
CoordinatorConfig sets finite bounds for the process-local cache and same-key operation coordination. Zero values select a cache capacity of 4096, an in-flight capacity of 1024, and a 30-minute idle TTL.
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore is an authoritative, bounded in-process store. It does not evict established classifications or remote-attempt history to admit new keys.
func NewMemoryStore ¶
func NewMemoryStore(config MemoryStoreConfig, options ...MemoryStoreOption) (*MemoryStore, error)
NewMemoryStore creates a finite process-local state store. Zero configuration fields use documented bounded defaults; negative or oversized bounds fail.
func (*MemoryStore) ClaimRemote ¶
func (s *MemoryStore) ClaimRemote(ctx context.Context, key featurestate.Key, now time.Time, maxAttempts uint32, leaseTTL time.Duration, retryBackoff time.Duration) (featurestate.RemoteClaim, featurestate.Record, bool, error)
ClaimRemote consumes one finite attempt and publishes its lease before the caller performs network I/O. Backoff is applied at completion, so an abandoned claim becomes eligible immediately when its lease expires.
func (*MemoryStore) CompleteRemote ¶
func (s *MemoryStore) CompleteRemote(ctx context.Context, claim featurestate.RemoteClaim, result featurestate.RemoteCompletion, now time.Time) (featurestate.Record, error)
CompleteRemote completes only the currently held lease. Neutral completions clear the lease and start bounded backoff without writing a negative class.
func (*MemoryStore) Load ¶
func (s *MemoryStore) Load(ctx context.Context, key featurestate.Key) (featurestate.Record, bool, error)
Load returns a record without allocating a missing key. A bounded idle-cleanup slice runs lazily using the injected clock before the map lookup.
func (*MemoryStore) Promote ¶
func (s *MemoryStore) Promote(ctx context.Context, key featurestate.Key, proposal session.Classification, now time.Time) (featurestate.Record, bool, error)
Promote atomically stores the first valid positive classification at the store-owned revision 1. Later proposals cannot rewrite source or evidence.
type MemoryStoreConfig ¶
MemoryStoreConfig places finite process-local bounds on the authoritative store. Idle cleanup applies only to unused unknown records with no remote attempts or active control state; positives and attempted unknowns are pinned.
type MemoryStoreOption ¶
type MemoryStoreOption func(*memoryStoreSettings)
MemoryStoreOption supplies process-owned clocks and lease-token generation. Both callbacks run outside the store mutex.
func WithClock ¶
func WithClock(now func() time.Time) MemoryStoreOption
WithClock injects the clock used only by lazy cleanup during Load. Calls to the clock happen before the store lock is acquired.
func WithLeaseNonceGenerator ¶
func WithLeaseNonceGenerator(nonce func() (string, error)) MemoryStoreOption
WithLeaseNonceGenerator injects a bounded nonce source. The source is called outside the store lock; a per-store sequence makes emitted lease IDs unique.
Source Files