Help us shape the future of Go! Take the 2026 Go Developer Survey

Why Go
- Case Studies
  
  Common problems companies solve with Go
- Use Cases
  
  Stories about how and why companies use Go
- Security
  
  How Go can help keep you secure by default
Learn
Docs
- Effective Go
  
  Tips for writing clear, performant, and idiomatic Go code
- Go User Manual
  
  A complete introduction to building software with Go
- Standard library
  
  Reference documentation for Go's standard library
- Release Notes
  
  Learn what's new in each Go release
- API
  
  Reference documentation for the pkg.go.dev API
Packages
Community
- Recorded Talks
  
  Videos from prior events
- Meetups
  
  Meet other local Go developers
- Conferences
  
  Learn and network with Go developers from around the world
- Go blog
  
  The Go project's official blog.
- Go project
  
  Get help and stay informed from Go
- Get connected

durable

package module

Go to main page

Versions in this module

v1

v1.0.0

Oct 17, 2026

Changes in this version

+ const MaxPayloadBytes

+ var ErrExecutionDeadline = errors.New("execution deadline exceeded")

+ var ErrExecutionExpired = errors.New("execution was removed by retention")

+ var ErrHandlerUnresponsive = errors.New("activity handler did not stop within shutdown grace period")

+ var ErrIncompatibleSchema = errors.New("database schema is incompatible with this binary")

+ var ErrInvalidInput = errors.New("invalid input")

+ var ErrLeaseLost = errors.New("activity lease is no longer valid")

+ var ErrNoActivity = errors.New("no activity is ready")

+ var ErrNotFound = errors.New("execution or step not found")

+ var ErrPayloadTooLarge = errors.New("JSON payload exceeds limit")

+ var ErrResultUnavailable = errors.New("step result is not available")

+ var ErrStartConflict = errors.New("start key already used with different input")

+ var ErrTypeMismatch = errors.New("activity type does not match persisted contract")

+ var ErrUnknownWorkflow = errors.New("workflow definition is not registered")

+ var ErrWorkerBusy = errors.New("worker instance is already running")

+ func Migrate(ctx context.Context, pool *pgxpool.Pool) error

+ func Permanent(err error) error

+ func Register[Input any](registry *Registry, definition Definition[Input]) error

+ func ValidateActivityTransition(from, to ActivityState) error

+ func ValidateAttemptTransition(from, to AttemptState) error

+ func ValidateLeaseTransition(from, to LeaseState) error

+ func ValidateWorkflowTransition(from, to WorkflowState) error

+ type Activity struct

+ AttemptCount int

+ AttemptTimeout time.Duration

+ AvailableAt time.Time

+ CompensatesActivityID *string

+ Compensation *CompensationPlan

+ CompletedAt *time.Time

+ Contract string

+ CreatedAt time.Time

+ ID string

+ Input json.RawMessage

+ InputSchema string

+ Kind ActivityKind

+ LastError string

+ Name string

+ Output json.RawMessage

+ OutputSchema string

+ Position int

+ RetryPolicy RetryPolicy

+ State ActivityState

+ StepKey string

+ UpdatedAt time.Time

+ Version string

+ WorkflowID string

+ type ActivityDefinition struct

+ func DefineActivity[Input, Output any](name string) ActivityDefinition[Input, Output]

+ func (a ActivityDefinition[Input, Output]) Handle(handler func(context.Context, Input) (Output, error)) HandlerRegistration

+ func (a ActivityDefinition[Input, Output]) Result(ctx context.Context, key string) (Output, error)

+ func (a ActivityDefinition[Input, Output]) Step(key string, input Input, options ...StepOption) (ActivitySpec, error)

+ func (a ActivityDefinition[Input, Output]) WithVersion(version, inputSchema, outputSchema string) ActivityDefinition[Input, Output]

+ func (a ActivityDefinition[Input, Output]) WorkflowResult(ctx context.Context, engine *Engine, workflowID string) (Output, error)

+ type ActivityKind string

+ const ActivityCompensation

+ const ActivityForward

+ type ActivityMetadata struct

+ ActivityID string

+ ActivityName string

+ ActivityVersion string

+ AttemptDeadline time.Time

+ AttemptID string

+ AttemptNumber int

+ CompensatesActivityID *string

+ EffectKey string

+ InputSchema string

+ Kind ActivityKind

+ OutputSchema string

+ StepKey string

+ WorkerID string

+ WorkflowID string

+ func Metadata(ctx context.Context) (ActivityMetadata, bool)

+ type ActivitySpec struct

+ Input json.RawMessage

+ InputSchema string

+ Key string

+ Name string

+ OutputSchema string

+ Version string

+ func NewActivity[Input any](name string, input Input, options ...StepOption) (ActivitySpec, error)

+ type ActivityState string

+ const ActivityBlocked

+ const ActivityCancelled

+ const ActivityCompleted

+ const ActivityFailed

+ const ActivityReady

+ const ActivityRunning

+ const ActivityTimedOut

+ const ActivityWaiting

+ type Attempt struct

+ ActivityID string

+ DeadlineAt time.Time

+ EndedAt *time.Time

+ Error string

+ ID string

+ Number int

+ RetryDecision string

+ RetryDueAt *time.Time

+ StartedAt time.Time

+ State AttemptState

+ WorkerID string

+ type AttemptState string

+ const AttemptAbandoned

+ const AttemptCancelled

+ const AttemptCompleted

+ const AttemptFailed

+ const AttemptRunning

+ const AttemptTimedOut

+ type Claim struct

+ ActivityID string

+ ActivityInput json.RawMessage

+ ActivityName string

+ ActivityVersion string

+ AttemptDeadline time.Time

+ AttemptID string

+ AttemptNumber int

+ ClaimedAt time.Time

+ CompensatesActivityID *string

+ InputSchema string

+ Kind ActivityKind

+ LeaseExpiresAt time.Time

+ LeaseID string

+ LeaseToken string

+ OutputSchema string

+ Position int

+ StepKey string

+ WorkerID string

+ WorkflowID string

+ type Clock interface

+ Now func() time.Time

+ type CompensationPlan struct

+ AttemptTimeout time.Duration

+ Contract string

+ Input json.RawMessage

+ InputSchema string

+ Name string

+ OutputSchema string

+ RetryPolicy RetryPolicy

+ Version string

+ type CompensationState string

+ const CompensationCompleted

+ const CompensationFailed

+ const CompensationNone

+ const CompensationRunning

+ type Definition struct

+ InputSchema string

+ Name string

+ Plan func(Input) ([]ActivitySpec, error)

+ Version string

+ func Define[Input any](name string, plan func(Input) ([]ActivitySpec, error)) Definition[Input]

+ func (d Definition[Input]) WithVersion(version, inputSchema string) Definition[Input]

+ type Engine struct

+ func New(pool *pgxpool.Pool, registry *Registry, clock Clock, options ...EngineOption) (*Engine, error)

+ func Open(ctx context.Context, databaseURL string, registry *Registry, clock Clock, ...) (*Engine, error)

+ func (e *Engine) Activities(ctx context.Context, workflowID string) ([]Activity, error)

+ func (e *Engine) Attempts(ctx context.Context, activityID string) ([]Attempt, error)

+ func (e *Engine) Cancel(ctx context.Context, id, actor, reason string) (WorkflowExecution, error)

+ func (e *Engine) CheckSchema(ctx context.Context) error

+ func (e *Engine) ClaimActivity(ctx context.Context, workerID string, leaseDuration time.Duration) (Claim, error)

+ func (e *Engine) Close()

+ func (e *Engine) CompleteActivity(ctx context.Context, claim Claim, output json.RawMessage) error

+ func (e *Engine) FailActivity(ctx context.Context, claim Claim, activityErr error) error

+ func (e *Engine) Heartbeat(ctx context.Context, claim Claim, extension time.Duration) (time.Time, error)

+ func (e *Engine) ListActivities(ctx context.Context, workflowID string, request PageRequest) (Page[Activity], error)

+ func (e *Engine) ListAttempts(ctx context.Context, activityID string, request PageRequest) (Page[Attempt], error)

+ func (e *Engine) ListLeases(ctx context.Context, activityID string, request PageRequest) (Page[Lease], error)

+ func (e *Engine) ListTimeline(ctx context.Context, workflowID string, request PageRequest) (Page[TimelineEvent], error)

+ func (e *Engine) ListWorkflows(ctx context.Context, filter WorkflowFilter, request PageRequest) (Page[WorkflowSummary], error)

+ func (e *Engine) Migrate(ctx context.Context) error

+ func (e *Engine) PurgeTerminal(ctx context.Context, policy RetentionPolicy) (RetentionResult, error)

+ func (e *Engine) RecoverAbandoned(ctx context.Context, limit int) (int, error)

+ func (e *Engine) Timeline(ctx context.Context, workflowID string) ([]TimelineEvent, error)

+ func (e *Engine) Workflow(ctx context.Context, workflowID string) (WorkflowExecution, error)

+ type EngineOption struct

+ func WithObserver(observer Observer) EngineOption

+ type ExecutionExpiredError struct

+ ID string

+ func (e *ExecutionExpiredError) Error() string

+ func (e *ExecutionExpiredError) Unwrap() error

+ type Handler func(context.Context, json.RawMessage) (json.RawMessage, error)

+ type HandlerPanicError struct

+ Value any

+ func (e *HandlerPanicError) Error() string

+ func (e *HandlerPanicError) Unwrap() error

+ type HandlerRegistration struct

+ Handler Handler

+ InputSchema string

+ Name string

+ OutputSchema string

+ Version string

+ func Handle[Input, Output any](name string, handler func(context.Context, Input) (Output, error)) HandlerRegistration

+ type Lease struct

+ AcquiredAt time.Time

+ ActivityID string

+ AttemptID string

+ EndedAt *time.Time

+ ExpiresAt time.Time

+ HeartbeatAt time.Time

+ ID string

+ State LeaseState

+ Token string

+ WorkerID string

+ type LeaseState string

+ const LeaseActive

+ const LeaseExpired

+ const LeaseReleased

+ type ManualClock struct

+ func NewManualClock(now time.Time) *ManualClock

+ func (c *ManualClock) Advance(d time.Duration)

+ func (c *ManualClock) NewTicker(interval time.Duration) Ticker

+ func (c *ManualClock) Now() time.Time

+ type Observation struct

+ ActivityID string

+ At time.Time

+ AttemptID string

+ Duration time.Duration

+ Kind ActivityKind

+ Outcome string

+ ReadyAge time.Duration

+ Reason string

+ StepKey string

+ Type string

+ Version string

+ WorkerID string

+ WorkflowID string

+ type Observer interface

+ Observe func(context.Context, Observation)

+ func SlogObserver(logger *slog.Logger) Observer

+ type ObserverFunc func(context.Context, Observation)

+ func (f ObserverFunc) Observe(ctx context.Context, event Observation)

+ type Page struct

+ Items []T

+ NextCursor string

+ type PageRequest struct

+ Cursor string

+ Limit int

+ Sensitive bool

+ type PendingActivity struct

+ AvailableAt time.Time

+ Kind ActivityKind

+ Name string

+ State ActivityState

+ Version string

+ type Registry struct

+ func NewRegistry() *Registry

+ type RetentionPolicy struct

+ CompletedBefore time.Time

+ Limit int

+ type RetentionResult struct

+ Deleted int

+ ExecutionIDs []string

+ type RetryPolicy struct

+ InitialInterval time.Duration

+ JitterFraction float64

+ MaxAttempts int

+ MaximumInterval time.Duration

+ RetryErrors bool

+ type RuntimeHealth struct

+ ConsecutiveFailures int

+ Healthy bool

+ LastError error

+ LastSuccessAt time.Time

+ Running bool

+ type Scheduler struct

+ func NewScheduler(engine *Engine, pollInterval time.Duration, batchSize int) (*Scheduler, error)

+ func (s *Scheduler) Health() RuntimeHealth

+ func (s *Scheduler) Run(ctx context.Context) error

+ func (s *Scheduler) RunOnce(ctx context.Context) (int, error)

+ type StartOption struct

+ func WithCompensationTimeout(timeout time.Duration) StartOption

+ func WithPredecessor(id string) StartOption

+ func WithStartKey(key string) StartOption

+ func WithWorkflowTimeout(timeout time.Duration) StartOption

+ type StepOption struct

+ func WithAttemptTimeout(timeout time.Duration) StepOption

+ func WithCompensation(cleanup ActivitySpec) StepOption

+ func WithRetry(policy RetryPolicy) StepOption

+ type SystemClock struct

+ func (SystemClock) Now() time.Time

+ type TaskError struct

+ ActivityID string

+ AttemptID string

+ Cause error

+ WorkflowID string

+ func (e *TaskError) Error() string

+ func (e *TaskError) Unwrap() error

+ type Ticker interface

+ Stop func()

+ Ticks func() <-chan time.Time

+ type TickerClock interface

+ NewTicker func(time.Duration) Ticker

+ type TimelineEvent struct

+ ActivityID *string

+ AttemptID *string

+ Details json.RawMessage

+ RecordedAt time.Time

+ Sequence int64

+ Type string

+ WorkflowID string

+ type UnsupportedActivity struct

+ Contract string

+ InputSchema string

+ Name string

+ OutputSchema string

+ ReadyCount int64

+ Version string

+ type Worker struct

+ func NewWorker(engine *Engine, config WorkerConfig, registrations ...HandlerRegistration) (*Worker, error)

+ func (w *Worker) Health() RuntimeHealth

+ func (w *Worker) Run(ctx context.Context) error

+ func (w *Worker) RunOnce(ctx context.Context) (bool, error)

+ func (w *Worker) UnsupportedActivities(ctx context.Context) ([]UnsupportedActivity, error)

+ type WorkerConfig struct

+ DatabaseTimeout time.Duration

+ HeartbeatInterval time.Duration

+ ID string

+ LeaseDuration time.Duration

+ PollInterval time.Duration

+ ShutdownGracePeriod time.Duration

+ type WorkflowExecution struct

+ CancelActor string

+ CancelReason string

+ CancelRequestedAt *time.Time

+ CancelSettledAt *time.Time

+ CompensationDeadlineAt *time.Time

+ CompensationError string

+ CompensationState CompensationState

+ CompensationTimeout time.Duration

+ CompletedAt *time.Time

+ CreatedAt time.Time

+ DeadlineAt time.Time

+ DefinitionName string

+ DefinitionVersion string

+ ID string

+ Input json.RawMessage

+ InputSchema string

+ LastError string

+ OriginalState WorkflowState

+ Output json.RawMessage

+ PreviousExecutionID *string

+ StartKey *string

+ State WorkflowState

+ TerminalReason string

+ Timeout time.Duration

+ UpdatedAt time.Time

+ func Start[Input any](ctx context.Context, engine *Engine, definition Definition[Input], input Input, ...) (WorkflowExecution, error)

+ type WorkflowFilter struct

+ CompensationState CompensationState

+ CreatedBefore *time.Time

+ DefinitionName string

+ DefinitionVersion string

+ ID string

+ State WorkflowState

+ TerminalReason string

+ type WorkflowState string

+ const WorkflowCancelRequested

+ const WorkflowCancelled

+ const WorkflowCompensating

+ const WorkflowCompensationFailed

+ const WorkflowCompleted

+ const WorkflowFailed

+ const WorkflowRunning

+ const WorkflowTimedOut

+ type WorkflowSummary struct

+ Age time.Duration

+ CancelActor string

+ CancelReason string

+ CancelRequestedAt *time.Time

+ CancelSettledAt *time.Time

+ CompensationError string

+ CompensationState CompensationState

+ CompletedAt *time.Time

+ CreatedAt time.Time

+ DeadlineAt time.Time

+ DefinitionName string

+ DefinitionVersion string

+ HasError bool

+ ID string

+ LastError string

+ NextActivity *PendingActivity

+ OriginalState WorkflowState

+ State WorkflowState

+ TerminalReason string

+ UpdatedAt time.Time

v1.0.0-rc.1

Oct 17, 2026