longrun

type AllPermanent ¶ added in v0.5.0

type AllPermanent struct{}

AllPermanent treats every error as permanent.

func (AllPermanent) IsTransient(error) bool

type AttemptTracker ¶ added in v0.5.0

type AttemptTracker interface {
	// OnFailure returns the 0-based attempt index to use for backoff calculation
	// and whether the task is allowed to retry.
	//
	// Example with maxRetries=3:
	//   1st call: attempt=0, ok=true
	//   2nd call: attempt=1, ok=true
	//   3rd call: attempt=2, ok=true
	//   4th call: attempt=3, ok=false (budget exhausted)
	OnFailure() (attempt int, ok bool)
	// Reset sets the attempt counter back to zero (e.g. after healthy progress).
	Reset()
}

AttemptTracker tracks retry attempts and decides whether more retries are allowed.

func ResolveAttemptTracker(maxRetries int) AttemptTracker

UnlimitedRetries (-1) → unlimited retries.
0 (zero-value)        → DefaultMaxRetries (3).
>0                    → exact limit.

type BackoffConfig ¶ added in v0.5.0

type BackoffConfig struct {
	Initial    time.Duration
	Max        time.Duration
	Multiplier float64
	// MaxRetries limits consecutive retry attempts.
	//   0 (zero-value) → DefaultMaxRetries (3).
	//  -1 (UnlimitedRetries) → no limit.
	//  >0 → exact limit.
	MaxRetries int
}

BackoffConfig controls exponential backoff between retry attempts.

func DefaultBackoff() BackoffConfig

type ErrorClassifier ¶ added in v0.5.0

type ErrorClassifier interface {
	IsTransient(err error) bool
}

ErrorClassifier decides whether an error is transient (retryable).

func ResolveErrorClassifier(transientErrors []error) ErrorClassifier

type LimitedAttempts ¶ added in v0.5.0

type LimitedAttempts struct {
	MaxRetries int
	// contains filtered or unexported fields
}

LimitedAttempts stops retrying after MaxRetries consecutive failures.

func NewLimitedAttempts(maxRetries int) *LimitedAttempts

func (l *LimitedAttempts) OnFailure() (int, bool)

func (l *LimitedAttempts) Reset()

type NeverRestart ¶ added in v0.5.0

type NeverRestart struct{}

NeverRestart stops the task after any completion (success or failure).

func (NeverRestart) ShouldRestart(error) bool

type RestartOnFailure ¶ added in v0.5.0

type RestartOnFailure struct{}

RestartOnFailure restarts only when the task returned a non-nil error.

func (RestartOnFailure) ShouldRestart(err error) bool

type RestartPolicy ¶ added in v0.5.0

type RestartPolicy int

RestartPolicy determines when a task should be restarted after completion.

const (
	Never     RestartPolicy = iota // do not restart (default)
	OnFailure                      // restart only on failure
)

type RestartStrategy ¶ added in v0.5.0

type RestartStrategy interface {
	ShouldRestart(err error) bool
}

RestartStrategy decides whether the task loop should restart.

func ResolveRestartStrategy(p RestartPolicy) RestartStrategy

type Runner ¶

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

Runner orchestrates N tasks. When any task returns a permanent error the runner cancels all remaining tasks and performs graceful shutdown.

func NewRunner(opts RunnerOptions) *Runner

func (r *Runner) Add(task *Task)

func (r *Runner) Wait(ctx context.Context) error

type RunnerOptions ¶ added in v0.5.0

type RunnerOptions struct {
	ShutdownTimeout time.Duration // default 30s
	Logger          *slog.Logger  // nil = slog.Default()
}

RunnerOptions configures a Runner.

type ShutdownFunc ¶ added in v0.5.0

type ShutdownFunc func(ctx context.Context) error

ShutdownFunc is called during graceful shutdown.

type Task ¶ added in v0.5.0

type Task struct {
	Name     string
	Work     WorkFunc
	Shutdown ShutdownFunc
	Options  TaskOptions
	// contains filtered or unexported fields
}

Task is a self-contained unit of work with interval, retry and backoff support. It can be used standalone (via Wait) or managed by a Runner.

Task is NOT safe for concurrent use — call Wait from a single goroutine. Runner handles this automatically (one goroutine per task).

func NewTask(name string, work WorkFunc, opts TaskOptions) *Task

func (t *Task) Wait(ctx context.Context) error

type TaskOptions ¶ added in v0.5.0

type TaskOptions struct {
	Interval        time.Duration // 0 = one-shot
	SkipInitialRun  bool          // default false = run immediately
	Restart         RestartPolicy // default Never
	Backoff         BackoffConfig
	Timeout         time.Duration // per-invocation, 0 = none
	TransientErrors []error       // whitelist; empty = all errors are permanent
	Logger          *slog.Logger  // nil = slog.Default()
}

TaskOptions configures the behaviour of a Task.

The two axes — Interval and Restart — form a simple state machine:

Interval=0  + Restart=Never     → one-shot: run once, stop.
Interval=0  + Restart=OnFailure → one-shot with retries: retry transient errors, stop on success or permanent error.
Interval>0  + Restart=Never     → periodic: ticker loop, stop on first error.
Interval>0  + Restart=OnFailure → periodic with retries: ticker loop, restart loop on transient errors.

By default all errors are permanent — a single failure stops the task. To enable retries, set Restart to OnFailure and list the errors that should be retried in TransientErrors (whitelist). Only errors matching via errors.Is are considered transient; everything else remains permanent and stops the task immediately.

type UnlimitedAttempts ¶ added in v0.5.0

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

UnlimitedAttempts never exhausts the retry budget.

func NewUnlimitedAttempts() *UnlimitedAttempts

func (u *UnlimitedAttempts) OnFailure() (int, bool)

func (u *UnlimitedAttempts) Reset()

type WhitelistClassifier ¶ added in v0.5.0

type WhitelistClassifier struct {
	Errors []error
}

WhitelistClassifier treats only listed errors (matched via errors.Is) as transient. All other errors are considered permanent.

func NewWhitelistClassifier(errs ...error) WhitelistClassifier

func (w WhitelistClassifier) IsTransient(err error) bool

type WorkFunc ¶ added in v0.5.0

type WorkFunc func(ctx context.Context) error

WorkFunc is the function that performs the actual work of a task.