execution

type Admission interface {
	// Admit reports whether key may be tried now, taking its share of any
	// limit when it may, and when it may not, until when; the zero time
	// when it cannot tell.
	Admit(key string) (admitted bool, until time.Time)
}

type AfterOutputError struct {
	// Err is the stream's own error, for errors.Is and errors.As.
	Err error
}

type Attempt[C any] struct {
	// Candidate is the candidate the entry describes.
	Candidate C
	// Key is the candidate's health key, when the execution tracks health
	// or admits candidates.
	Key string
	// Unavailable reports a candidate skipped without a try because Health
	// reported it unavailable until Until, and Unadmitted one the
	// Admission refused until Until.
	Unavailable bool
	Unadmitted  bool
	Until       time.Time
	// Tries counts the tries, repeats included.
	Tries int
	// Err is the last try's error: nil when the candidate served or was
	// skipped.
	Err error
	// Classification is Err's routing metadata, Class names its kind, and
	// Disposition is what it permitted. A terminal disposition ended the
	// execution.
	Classification core.ProviderErrorClassification
	Class          core.ProviderErrorClass
	Disposition    core.Disposition
	// Duration spans the tries and the waits between them.
	Duration time.Duration
}

type CircuitOpenError struct {
	// Key is the instance's health key.
	Key string
	// Until is when the instance becomes available, and RetryAfter is how
	// long after the error that is. Both are zero when Health gave no time.
	Until      time.Time
	RetryAfter time.Duration
}

type Effect int

type Executor[C any] struct {
	// Health skips the candidates it reports unavailable and records the
	// outcome of every candidate tried. Nil tracks nothing.
	Health Health
	// Admission, when set, decides whether a candidate Health admits may
	// be tried now, as a client-side rate limiter keyed by instance does.
	// A candidate it refuses is skipped without a try, as one Health
	// reports unavailable is.
	Admission Admission
	// Key returns a candidate's health key: the instance it runs on. It is
	// required with Health or Admission.
	Key func(C) string
	// CredentialFailover moves on to the next candidate when one's
	// credential is rejected, a failure of class auth or forbidden, rather
	// than ending the execution, for candidates that hold different
	// credentials. The rejection counts against no instance: Health
	// records an answer, as it records any other refusal.
	CredentialFailover bool
	// Retry repeats a candidate that fails with a retryable disposition
	// before moving on. The zero value never repeats one.
	Retry Retry
	// Now returns the current time, for durations in the trace and the
	// RetryAfter of an UnavailableError, so it should agree with Health's
	// clock. Nil uses time.Now.
	Now func() time.Time
	// Sleep waits d before a repeat, or returns ctx's error once ctx ends.
	// Nil waits on a timer.
	Sleep func(ctx context.Context, d time.Duration) error
}

type Failure struct {
	// Key is the key that failed.
	Key string
	// Class is the failure's Observation.Class.
	Class string
	// Streak is the length of the streak, this failure included, and
	// ClassFailures the number of its failures of Class.
	Streak        int
	ClassFailures int
}

type Health interface {
	// Available reports whether key may be tried now and, when it may not,
	// until when.
	Available(key string) (available bool, until time.Time)
	// Record reports the outcome of one operation on key: nil is a success.
	Record(key string, err error)
}

type HealthOptions struct {
	// Policy returns the policy of one key, so keys can differ and follow
	// settings as they change. Nil gives every key DefaultFailureThreshold
	// and DefaultOpenDuration.
	Policy func(key string) HealthPolicy
	// Observe decides what an operation's error says about health. Nil uses
	// Observe.
	Observe func(error) Observation
	// Now returns the current time. Nil uses time.Now.
	Now func() time.Time
}

type HealthPolicy struct {
	// FailureThreshold is the streak of consecutive circuit failures that
	// opens the circuit. Zero or less disables circuit breaking: failures
	// are not counted and the circuit never opens.
	FailureThreshold int
	// OpenDuration is how long an open circuit refuses requests.
	OpenDuration time.Duration
	// Backoff, when set, replaces OpenDuration for each failure at or past
	// the threshold, so the open time can grow with the streak or depend on
	// the failure's class. It runs under the tracker's lock and must be a
	// pure function of its argument.
	Backoff func(Failure) time.Duration
	// FailureWindow forgets a streak whose last failure is older than the
	// window, so the next failure starts a new streak. Zero never forgets.
	FailureWindow time.Duration
	// IgnoreRetryAfter keeps RetryAfter from starting cooldowns, for a
	// product whose failover predates them.
	IgnoreRetryAfter bool
}

type HealthState struct {
	// Streak counts consecutive circuit failures, and ClassFailures counts
	// them by Observation.Class.
	Streak        int
	ClassFailures map[string]int
	// LastFailure is when the streak last grew.
	LastFailure time.Time
	// OpenUntil is when the circuit stops refusing requests. Once it has
	// passed with the streak still at the threshold, the circuit is
	// half-open.
	OpenUntil time.Time
	// CooldownUntil is when the latest RetryAfter cooldown ends.
	CooldownUntil time.Time
}

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

type Observation struct {
	// Effect is what the outcome does to the instance's key.
	Effect Effect
	// Class names the kind of a failure, for a Backoff that treats kinds
	// differently, such as billing failures. The empty class is a kind too.
	Class string
	// RetryAfter is how long the upstream asked callers to wait. A positive
	// value starts a cooldown, which only a later RetryAfter can extend,
	// unless the policy ignores RetryAfter.
	RetryAfter time.Duration
}

type Policy struct {
	// Retry repeats a try whose error Classify reads as retryable, up to
	// Retry.Attempts tries of one operation, waiting Retry.Delay between
	// them. ExponentialBackoff is the gateway's Delay.
	Retry Retry
	// Health is the instance's circuit, under the key Resilient is given.
	// While it reports the key unavailable, every operation is refused
	// with a *CircuitOpenError and nothing is sent. It records the outcome
	// of each operation's last try, so an operation whose repeats all fail
	// counts once. Nil guards nothing.
	Health Health
	// Classify reads a try's error: whether it may repeat, whether it
	// counts against the circuit, and how long the upstream asked callers
	// to wait. Retry.Delay and Health read the error as Classify does. Nil
	// uses core.ClassifyError.
	Classify func(error) core.ProviderErrorClassification
	// Repeatable reports whether a request may be sent more than once; one
	// it refuses is tried once, whatever Retry says. Nil uses
	// RepeatableRequest.
	Repeatable func(core.Request) bool
	// Now returns the current time, for a CircuitOpenError's RetryAfter,
	// so it should agree with Health's clock. Nil uses time.Now.
	Now func() time.Time
	// Sleep waits d before a repeat, or returns ctx's error once ctx ends.
	// Nil waits on a timer.
	Sleep func(ctx context.Context, d time.Duration) error
}

type Result[C, R any] struct {
	// Value is what the serving candidate returned, and Candidate is that
	// candidate. Both are zero when no candidate served.
	Value     R
	Candidate C
	// Attempts is the trace: an entry for each candidate reached, in order.
	Attempts []Attempt[C]
}

type Retry struct {
	// Attempts is how many times one candidate may be tried, the first try
	// included. Below two, a candidate is tried once.
	Attempts int
	// Delay returns how long to wait before trying again, given how many
	// tries have failed and the last one's error. A product that honours
	// Retry-After waits at least core.ClassifyError(err).RetryAfter. Nil
	// tries again at once.
	Delay func(failed int, err error) time.Duration
}

type UnavailableError struct {
	// Until is the earliest time a candidate becomes available, and
	// RetryAfter is how long after the error that is. Both are zero when
	// Health gave no time.
	Until      time.Time
	RetryAfter time.Duration
}