availability

package
v1.2.1 Latest Latest
Warning

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

 Go to latest Published: Sep 11, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

Documentation

Overview

Package availability owns runtime state for exact provider offerings.

Index

Constants

View Source 
const (
	// DefaultSharedTTL bounds how long a replica's health record outlives
	// its last transition. A dead replica's record expires on its own.
	DefaultSharedTTL = time.Minute
	// DefaultSharedRefreshInterval bounds the peer read cost. A tracker
	// reads peer state at most once per interval.
	DefaultSharedRefreshInterval = 5 * time.Second
)

Variables

View Source 
var (
	// ErrInvalidOffering reports an incomplete offering identity.
	ErrInvalidOffering = errors.New("provider offering identity is incomplete")
	// ErrInvalidConfig reports an invalid availability policy.
	ErrInvalidConfig = errors.New("availability configuration is invalid")
)
View Source 
var ErrInvalidSharedStore = errors.New("shared availability store is required")

ErrInvalidSharedStore reports a missing distributed store.

Functions

func NewInstanceID added in v1.2.0 

func NewInstanceID() string

NewInstanceID returns a random replica identity for shared health records.

Types

type Clock 

type Clock interface {
	Now() time.Time
}

Clock supplies deterministic availability time.

type Config 

type Config struct {
	FailureThreshold int
	OpenDuration     time.Duration
}

Config defines the offering circuit policy.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns the production availability policy.

type KVStore added in v1.2.0 

type KVStore interface {
	SetWithTTL(ctx context.Context, key string, value []byte, ttl time.Duration) error
	ScanWithPrefix(ctx context.Context, prefix string, limit int) ([]string, error)
	BatchGet(ctx context.Context, keys []string) (map[string][]byte, error)
}

KVStore is the storage subset that shared health state uses. The deployment's distributed key-value store satisfies it. A tracker without one stays process-local.

type Offering 

type Offering struct {
	ProviderID      string
	ProviderModelID string
}

Offering identifies one provider model endpoint.

func OfferingFromRoute 

func OfferingFromRoute(route routing.Route) Offering

OfferingFromRoute converts a planned route to runtime identity.

type Publisher 

type Publisher interface {
	PublishAvailability(Snapshot) error
}

Publisher receives immutable availability state for derived projections.

type Record 

type Record struct {
	Offering           Offering
	State              State
	FailureKind        failure.Kind
	ConsecutiveFailure int
	OpenUntil          time.Time
}

Record is one immutable offering state record.

type SharedConfig added in v1.2.0 

type SharedConfig struct {
	// InstanceID names this replica's record. An empty value draws a
	// random identity.
	InstanceID string
	// TTL is the record lifetime in the shared store.
	TTL time.Duration
	// RefreshInterval is the shortest gap between two peer reads.
	RefreshInterval time.Duration
}

SharedConfig bounds the distributed health exchange.

type Snapshot 

type Snapshot struct {
	Revision uint64
	Records  []Record
}

Snapshot is one immutable availability generation.

type State 

type State string

State identifies one offering's runtime availability state. 

const (
	// StateHealthy admits normal attempts for an offering.
	StateHealthy State = "healthy"
	// StateOpen rejects attempts until the open interval expires.
	StateOpen State = "open"
	// StateHalfOpen admits one recovery probe.
	StateHalfOpen State = "half_open"
	// StateUnavailable rejects attempts until an explicit reset.
	StateUnavailable State = "unavailable"
)

type Tracker 

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

Tracker owns all offering state transitions and half-open probe admission.

func New 

func New(config Config, clock Clock, publisher Publisher) (*Tracker, error)

New creates one offering-level availability owner.

func (*Tracker) Acquire 

func (t *Tracker) Acquire(route routing.Route) bool

Acquire admits one attempt. A half-open offering admits one probe at a time.

func (*Tracker) LastPublishError 

func (t *Tracker) LastPublishError() error

LastPublishError returns the latest derived-projection or shared-store publication error.

func (*Tracker) RecordFailure 

func (t *Tracker) RecordFailure(route routing.Route, providerFailure *failure.Failure, _ time.Duration)

RecordFailure applies one normalized failure to the offering state machine.

func (*Tracker) RecordSuccess 

func (t *Tracker) RecordSuccess(route routing.Route, _ time.Duration)

RecordSuccess closes the offering circuit and clears failure evidence.

func (*Tracker) Refresh 

func (t *Tracker) Refresh(ctx context.Context)

Refresh makes expired open offerings eligible for one half-open probe and merges peer state when a shared store is configured.

func (*Tracker) Release added in v1.0.2 

func (t *Tracker) Release(route routing.Route)

Release ends a prior half-open admission without recording a provider outcome. Credential selection uses it when no provider request ran.

func (*Tracker) Reset 

func (t *Tracker) Reset(offering Offering) error

Reset makes one offering healthy. Catalog activation or an operator action can use it.

func (*Tracker) Snapshot 

func (t *Tracker) Snapshot() Snapshot

Snapshot returns a caller-owned immutable state generation.

func (*Tracker) UseSharedStore added in v1.2.0 

func (t *Tracker) UseSharedStore(store KVStore, config SharedConfig) error

UseSharedStore turns on distributed health publication. The tracker writes its state under its own instance key on every transition and merges peer state during Refresh. Local state wins recency conflicts.

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.