taskx

type DeliveryFailureMode ¶

type DeliveryFailureMode string

DeliveryFailureMode controls what the runtime does when the application callback returns an error.

const (
	DeliveryFailureConstant DeliveryFailureMode = "constant"
	DeliveryFailureDrop     DeliveryFailureMode = "drop"
)

type DeliveryFailurePolicy ¶

type DeliveryFailurePolicy struct {
	Mode       DeliveryFailureMode
	MaxRetries *uint32
	Interval   time.Duration
}

DeliveryFailurePolicy is deliberately smaller than the local RetryPolicy. It governs delivery from the runtime to the application, not retries inside a business handler.

func (p DeliveryFailurePolicy) Validate() error

type Event ¶

type Event struct {
	Kind        EventKind
	JobName     string
	RunID       string
	ScheduledAt time.Time
	Timestamp   time.Time
	Attempt     int
	MaxAttempts int
	Duration    time.Duration
	Reason      string
	Err         error
}

Event is emitted for observability adapters.

type EventHandler ¶

type EventHandler func(context.Context, TriggerEvent) error

EventHandler handles one durable runtime trigger.

type EventKind ¶

type EventKind string

EventKind identifies scheduler lifecycle and execution events.

const (
	EventScheduled EventKind = "scheduled"
	EventStarted   EventKind = "started"
	EventRetrying  EventKind = "retrying"
	EventSucceeded EventKind = "succeeded"
	EventFailed    EventKind = "failed"
	EventSkipped   EventKind = "skipped"
)

type Handler ¶

type Handler func(context.Context) error

Handler is a unit of background work. Implementations must be idempotent because retries and failover can result in at-least-once execution.

type Job ¶

type Job struct {
	Name         string
	Schedule     Schedule
	Handler      Handler
	RunOnStart   bool
	AllowOverlap bool
	Timeout      time.Duration
	Retry        RetryPolicy
	Lease        LeaseOptions
}

Job describes a scheduled background task.

type Lease ¶

type Lease interface {
	Renew(ctx context.Context, ttl time.Duration) error
	Release(ctx context.Context) error
}

Lease is an owned distributed lock. Renew and Release must verify ownership.

type LeaseOptions ¶

type LeaseOptions struct {
	Enabled       bool
	Key           string
	TTL           time.Duration
	RenewInterval time.Duration
}

LeaseOptions enables cross-instance singleton execution.

type Locker ¶

type Locker interface {
	TryAcquire(ctx context.Context, key string, ttl time.Duration) (lease Lease, acquired bool, err error)
}

Locker coordinates a job run across service replicas.

type ManagedJob ¶

type ManagedJob struct {
	Name          string
	Schedule      string
	DueTime       string
	Repeats       *uint32
	TTL           string
	Data          []byte
	DataTypeURL   string
	Overwrite     bool
	FailurePolicy *DeliveryFailurePolicy
}

ManagedJob is a durable job definition stored by an external task runtime. Schedule uses Kernel's canonical scheduler expression format:

• @every 5m
• @hourly, @daily, @weekly, @monthly, @yearly
• six-field cron: seconds minutes hours day-of-month month day-of-week

DueTime and TTL accept RFC3339 timestamps or Go duration strings. At least one of Schedule or DueTime must be set.

func (j ManagedJob) Validate() error

type Observer ¶

type Observer interface {
	Observe(context.Context, Event)
}

Observer receives task execution events. Implementations must be non-blocking or perform their own buffering.

type ObserverFunc ¶

type ObserverFunc func(context.Context, Event)

ObserverFunc adapts a function to Observer.

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

type Option ¶

type Option func(*Scheduler)

Option configures Scheduler.

func WithLocker(locker Locker) Option

func WithNow(now func() time.Time) Option

func WithObserver(observer Observer) Option

type PrometheusObserver ¶

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

PrometheusObserver exports bounded-cardinality task execution metrics.

func NewPrometheusObserver(reg prometheus.Registerer) (*PrometheusObserver, error)

func (o *PrometheusObserver) Observe(_ context.Context, event Event)

type RedisLocker ¶

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

RedisLocker implements distributed leases with SET NX and ownership-checked Lua scripts. The scripts use one key and are safe for Redis Cluster slots.

func NewRedisLocker(client redis.UniversalClient, prefix string) *RedisLocker

func (l *RedisLocker) TryAcquire(ctx context.Context, key string, ttl time.Duration) (Lease, bool, error)

type RetryPolicy ¶

type RetryPolicy struct {
	MaxAttempts    int
	InitialBackoff time.Duration
	MaxBackoff     time.Duration
	Multiplier     float64
}

RetryPolicy controls retries for one scheduled run. MaxAttempts includes the first attempt. Zero values disable retries.

type Runtime ¶

type Runtime interface {
	Schedule(context.Context, ManagedJob) error
	Get(context.Context, string) (ManagedJob, error)
	Delete(context.Context, string) error
	RegisterHandler(string, EventHandler) error
}

Runtime is the provider-neutral contract for a durable task runtime.

A Runtime owns the schedule definition and dispatches trigger events back to one application replica. Implementations are expected to provide at-least-once delivery, therefore handlers must remain idempotent.

type Schedule ¶

type Schedule interface {
	Next(after time.Time) time.Time
}

Schedule calculates the first execution strictly after the supplied time. Returning the zero time means that the schedule has completed.

func At(at time.Time) Schedule

func Every(interval time.Duration) Schedule

func ScheduleFunc(fn func(time.Time) time.Time) Schedule

type Scheduler ¶

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

Scheduler owns registered jobs and their lifecycle.

func NewScheduler(opts ...Option) *Scheduler

func (s *Scheduler) Register(job Job) error

func (s *Scheduler) Shutdown(ctx context.Context) error

func (s *Scheduler) Start(parent context.Context) error

func (s *Scheduler) Trigger(ctx context.Context, name string) error

type TriggerEvent ¶

type TriggerEvent struct {
	Name string
	Data []byte
}

TriggerEvent is delivered by a Runtime when a managed job becomes due.