async

package
v3.1.1 Latest Latest
Warning

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

Go to latest
Published: May 21, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package async provides supported contrib worker runner contracts for durable async jobs.

The package includes a bounded runner, low-cardinality metric hooks, safe failure-message helpers, and a job-kind handler mux for sharing one durable queue across multiple worker concerns without routing on unbounded payload data.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrInvalidJobKind reports a missing or unsafe async job kind.
	ErrInvalidJobKind = errors.New("invalid async job kind")
	// ErrHandlerNotFound reports a missing async handler registration.
	ErrHandlerNotFound = errors.New("async handler not found")
)

Functions

func SafeFailureMessage

func SafeFailureMessage(err error) string

SafeFailureMessage bounds failure messages before durable storage.

func SafeLabel

func SafeLabel(value string) string

SafeLabel returns a bounded label for metrics and logs.

Types

type Config

type Config struct {
	Store        Store
	Handler      Handler
	Logger       ports.Logger
	Metrics      MetricsRecorder
	BatchSize    int
	Concurrency  int
	PollInterval time.Duration
}

Config configures a Runner.

type Event

type Event struct {
	Kind    string
	Outcome string
}

Event captures low-cardinality worker observations.

type Handler

type Handler interface {
	Handle(ctx context.Context, job Job) error
}

Handler executes one leased job.

type HandlerFunc

type HandlerFunc func(context.Context, Job) error

HandlerFunc adapts a function to Handler.

func (HandlerFunc) Handle

func (f HandlerFunc) Handle(ctx context.Context, job Job) error

Handle executes a job.

type HandlerMux

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

HandlerMux dispatches jobs to handlers by sanitized low-cardinality kind.

func NewHandlerMux

func NewHandlerMux(routes ...HandlerRoute) (*HandlerMux, error)

NewHandlerMux constructs a mux and registers the supplied routes.

func (*HandlerMux) Handle

func (m *HandlerMux) Handle(ctx context.Context, job Job) error

Handle dispatches job to the registered handler for job.Kind.

func (*HandlerMux) Kinds

func (m *HandlerMux) Kinds() []string

Kinds returns registered job kinds in sorted order.

func (*HandlerMux) Register

func (m *HandlerMux) Register(kind string, handler Handler) error

Register adds or replaces a handler for kind.

type HandlerRoute

type HandlerRoute struct {
	Kind    string
	Handler Handler
}

HandlerRoute registers a handler for a low-cardinality job kind.

type Job

type Job struct {
	ID       string
	Kind     string
	TenantID string
	Payload  []byte
	Attempts int
}

Job is leased from a durable async queue or outbox.

type MetricsRecorder

type MetricsRecorder interface {
	ObserveAsyncJob(ctx context.Context, event Event)
}

MetricsRecorder records worker outcomes.

type MetricsRecorderFunc

type MetricsRecorderFunc func(context.Context, Event)

MetricsRecorderFunc adapts a function to MetricsRecorder.

func (MetricsRecorderFunc) ObserveAsyncJob

func (f MetricsRecorderFunc) ObserveAsyncJob(ctx context.Context, event Event)

ObserveAsyncJob records an async job event.

type Runner

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

Runner leases and executes async jobs until the context is canceled.

func New

func New(cfg Config) (*Runner, error)

New constructs a Runner with safe defaults.

func (*Runner) Run

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

Run starts the worker loop and blocks until ctx is canceled and in-flight jobs finish.

type Store

type Store interface {
	Lease(ctx context.Context, limit int) ([]Job, error)
	Complete(ctx context.Context, id string) error
	Fail(ctx context.Context, id string, message string) error
}

Store leases jobs and records their final outcome.

Directories

Path Synopsis
Package asynctest contains reusable async store contract tests.
Package asynctest contains reusable async store contract tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL