execution

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.
	Key string
	// Unavailable reports a candidate skipped without a try because Health
	// reported it unavailable until Until.
	Unavailable 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 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
	// Key returns a candidate's health key: the instance it runs on. It is
	// required with Health.
	Key func(C) string
	// 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 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
}