Documentation
¶
Overview ¶
Package redis is the Redis driver of workflow.Client, on go-redis v9: every run, schedule, lease and idempotency key is a Redis key, so a restart or a dead worker loses nothing, and any number of clients on any number of machines share one Redis.
rdb := goredis.NewClient(&goredis.Options{Addr: "localhost:6379"})
c, _ := redis.New(rdb, redis.WithPrefix("myapp"))
_ = c.Register(wf)
_ = c.Start(ctx) // nothing runs before this; cancel ctx to stop
The package is named redis like go-redis itself, so import one of the two under another name (goredis above).
Capabilities ¶
Declared, each proven by the workflowtest conformance suite against a real Redis: CapDurable, CapDelayedStart, CapDurableSleep, CapWaitForEvent, CapIdempotencyKey, CapConcurrencyKey (every strategy) and CapKeyFIFO, CapRateLimit (sliding windows), CapCron, CapCancel, CapRunFinished, CapRetryJitter and CapRetryDelay (delays computed in Go by workflow.RetryPolicy.Next; WithJitterSource pins the draws), CapQueue and CapQueueOverride, CapJobRetry, CapRetryUntil, CapRetryMaxErrors, CapDiscard, CapDiscardExhausted (RetryPolicy.DiscardOnExhaust) and CapRunStates (StatusRetrying with the next attempt, StatusDiscarded), CapSnooze, CapHeartbeat, CapRunTimeout, CapTenant, CapNodeIdentity, CapResult, CapDueQuery, CapMisfireSkip, CapMisfireFireOnce, CapMisfireFireAll, CapCronZone, CapCronSeconds, CapScheduleActive, CapScheduleKeep, CapTickTime, CapScheduleWhen, CapScheduleWindow, CapTickEvents, CapSchedulePause, CapRunQuery, CapLabelPrefix, CapRetryRun, CapDeleteRun, CapCancelAll, CapPauseWorkflow, CapPauseQueue, CapChain, CapDrain, CapDrainReport, CapScheduleList, CapScheduleTrigger, CapScheduleHistory, CapOverlapSkip, CapEnqueueOnly, CapErrorHistory, CapShutdownRequeue, CapForceRun and CapWorkerScale (QueueLoads and SetWorkers over the WithQueues list; each ready set has a companion scored by when its runs became claimable, so a queue's oldest wait is one read; measured with 3,000 runs, no throughput cost). The client also implements the interfaces that need no capability: RunRescheduler, StepCanceller, HealthChecker, LifecycleNotifier and PayloadLimiter (512 MiB, the largest value Redis stores; WithPayloadLimit lowers it).
Not declared, so Start, Enqueue or Schedule refuse what needs them with an UnsupportedError instead of ignoring it: closures (a closure cannot be stored) and CapQueueLimitGlobal (a non-zero QueueConfig.Limit is refused at Start: a run is claimed whole, so a cluster-wide count of a queue's in-flight step attempts is not kept; Workers is the per-client cap). Concurrency, rate and wait keys are Go functions (workflow.KeyFunc); Start refuses an expression key (KeyExpr). QueueConfig.Weight orders queues of equal priority by a weighted draw (workflow.PickWeighted on the jitter source).
How work moves ¶
- Enqueue writes a run hash ({prefix}:run:<id>) and puts its ID in the ready set of its queue and workflow ({prefix}:ready:<queue>/<workflow>, ordered by priority, then by ID, which starts with the creation time), or in the due set ({prefix}:due, by due time) for a RunAt in the future. A run of a workflow with a concurrency or rate policy, or of a workflow the enqueuing client did not register (an enqueue-only client, a chained job, a schedule fired elsewhere), first waits in {prefix}:pending:<workflow>: the dispatcher of a client that registered the workflow evaluates its queue and keys in Go and admits it in one script against the stored concurrency buckets (the runs holding a slot until they end) and rate windows (sliding: no span of Per holds more than Limit starts), so the limits hold across every client. An idempotency key is a field of {prefix}:idem checked and set in the same script, so two clients racing on one key make one run; the key is released when the run ends. A published message wakes idle workers at once.
- A run is claimed whole. The claim script moves due runs to their ready sets, hands back runs whose lease expired, then takes the best ready run of the workflows this client registered, and records the claim token and the lease end ({prefix}:leases). The holder renews the lease every third of WithLease. A client claims only workflows it registered, and with WithQueues only the queues it serves, the higher QueueConfig.Priority first; a run is claimed whole, so QueueConfig.Workers caps the runs of a queue one client executes at once. A pause ({prefix}:paused: everything, a workflow or a queue) is checked by the claim and by the holder between rounds, so every client obeys it and it survives a restart.
- The holder runs every step whose parents are done, in parallel, round by round, and records each attempt's outcome in the run hash. Every write the holder makes compares its token with the run's owner, so a holder whose lease expired and whose run another client took over writes nothing: each step outcome is recorded once per lease. A step whose result was lost with its worker runs again (at least once).
- A retry with a backoff, or a sleep step, hands the run back to the due set at the time it is ready again; the run reads StatusQueued (StatusWaiting for a sleep) meanwhile and holds no worker. Retries follow workflow.EffectiveRetriesFor and RetryPolicy.Next with the step's stored counts, so Until and MaxErrors hold across restarts.
- A wait step looks for a kept signal of its name and key sent since the run was enqueued (signals are numbered; a run takes only those above the number current at its enqueue) and otherwise registers in {prefix}:waiters:<name>\n<key> and hands the run back until its deadline (StatusWaiting, holding no worker). Signal keeps the signal and resolves every registered wait on its name and key, one per run, in one script, and makes those runs ready. A wait past its deadline fails its step (OnFailure runs). Kept signals are dropped once no unfinished run may take them.
- A step that fails for good runs OnFailure once with its input (under the lease, so a crash reruns it: at least once), then the run is failed. A step returning workflow.Discard ends the run StatusDiscarded, without retries or OnFailure. Retry re-opens a failed run from its failed step, admitted again under its workflow's policies.
- A run's chain (Job.Chain and the edits its steps made with PrependToChain and AppendToChain, applied only when the attempt succeeds) is stored with the run; the script that ends the run succeeded creates the next job's run, so no crash loses a link.
- Every script that ends a run records it in {prefix}:ended:<workflow>. A client with OnRunFinished observers claims ends of its workflows under a lease, calls the observers and then removes the entry: at least once, on one client, including ends that happened while no client was running.
- A run whose lease expires more than WithMaxReclaims times in a row (default 5) with no step finishing in between fails with ErrAbandoned, so a step that kills every worker it lands on cannot loop through the fleet.
- Stopping a client (cancelling the Start ctx, or Drain once its ctx ends) hands every run it holds back at once, without counting the cut-off attempts (CapShutdownRequeue): the next worker runs them with the same StepInfo.Attempt. DrainWithReport lists those attempts with the disposition workflow.DrainRequeued. A crashed client hands back nothing; its runs are claimed again once their leases expire.
- Cancel, ForceComplete and ForceFail end the run in one script and publish a stop message; the holder cancels its steps (the context cause is workflow.ErrCancelled or workflow.ErrForced) and its later writes are fenced off.
- Schedules ({prefix}:sched:<id>, next fire times in {prefix}:scheds) fire on any client that registered their workflow (its ScheduleWhen is code only such a client has), except a WithoutScheduler worker node; WithSchedulerOnly makes a node that fires schedules and runs no worker. Windows, ScheduleWhen and pauses are decided per tick on the firing client and reported to OnTick observers (TickFired, TickSkipped with its reason, TickMisfired), once, by the client that moved the schedule. A tick is fired by a script that moves the schedule's last catch-up time from the value the firing client read and creates the tick's runs in the same step, so a tick runs once across any number of clients. The default misfire policy fires the newest missed tick once; a workflow.Misfire fires what Misfire.Due picks. Under OverlapSkip a tick, or a TriggerSchedule, starts nothing while the run of the schedule's last fire is unfinished, decided in the same script. Fired runs carry workflow.FiredLabels.
- Client.Schedule with a Name is an upsert by (Workflow, Name); an unchanged expression, zone and misfire policy keep the next fire time, so an app can declare its schedules at every boot. Workflow.Cron entries are schedules with the stable IDs "cron:<workflow>:<index>".
- Runs walks an index of runs by enqueue time ({prefix}:runs) and filters in Go. A finished run's key expires after WithRetention (24 hours by default; Redis measures it, so it is wall time), and the index drops it when it is next read.
Time ¶
Due times, sleeps, backoff, step timeouts and cron fires are on WithClock (the default is the real clock); leases and polling are on WithLeaseClock, because a lease is about a worker being alive. Both are read in Go and passed to the scripts, so clients must keep their clocks close: a client whose clock runs ahead claims due work early. Rate windows are measured on WithClock; Redis expires an idle window's key after twice its Per plus a minute of wall time.
Deployment notes ¶
- Every key of a prefix carries the hash tag {prefix}, so on a Redis Cluster one prefix lives in one slot: correct, but one prefix does not spread over several shards. Proven on a single Redis node only.
- Use a Redis that does not evict keys (maxmemory-policy noeviction): an evicted run or lease key is lost work, not a cache miss.
- Durability is Redis's: with AOF every second a crash of Redis itself can lose up to a second of enqueues and state changes.
- Run ends wait in {prefix}:ended:<workflow> until a client with an OnRunFinished observer delivers them, or until their run expires (WithRetention); with retention off and no observer anywhere, that index grows with every run, as the run index does.
- Every started client reports in to {prefix}:nodes every third of WithLease; Nodes lists those seen within three leases (a crashed node drops out after that). WithNodeID names the node.
- A run past Workflow.RunTimeout (measured from admission, or from RunAt for a delayed run) is failed with workflow.ErrRunTimeout by its holder, or made ready by the dispatcher when no client holds it so a worker fails it; a run held back by a pause times out on resume.
- UniqueStore (Client.UniqueStore or NewUniqueStore) keeps the locks of the middleware package's Unique and UniqueWith in Redis, shared by every process, with the holder's run for UniqueConfig.States and ReturnExisting; a lock's ttl is a Redis expiry (wall time).
- JournalStore (workflow.JournalStore, step memoisation: a hash per run, optional expiry), BucketStore (workflow.BucketStore, leaky buckets: the drain and the take are one script, on the caller's clock) and DebounceStore (middleware.DebounceStore: Swap is one script) keep state other processes share; each has a constructor (NewJournalStore, NewBucketStore, NewDebounceStore) and a Client method over the client's prefix.
- WithEnqueueOnly makes a client for web nodes that enqueue and never run work; Register is optional there.
Index ¶
- Variables
- type BucketStore
- type Client
- func (c *Client) BucketStore() *BucketStore
- func (c *Client) Cancel(ctx context.Context, ref workflow.RunRef) error
- func (c *Client) CancelAll(ctx context.Context, q workflow.RunQuery) (int, error)
- func (c *Client) CancelStep(ctx context.Context, ref workflow.RunRef, step string) error
- func (c *Client) Capabilities() workflow.Caps
- func (c *Client) DebounceStore() *DebounceStore
- func (c *Client) Delete(ctx context.Context, ref workflow.RunRef) error
- func (c *Client) Done() <-chan struct{}
- func (c *Client) Drain(ctx context.Context) error
- func (c *Client) DrainWithReport(ctx context.Context) (workflow.DrainReport, error)
- func (c *Client) Enqueue(ctx context.Context, job workflow.Job) (workflow.RunRef, error)
- func (c *Client) ForceComplete(ctx context.Context, ref workflow.RunRef) error
- func (c *Client) ForceFail(ctx context.Context, ref workflow.RunRef, reason string) error
- func (c *Client) Health(ctx context.Context) workflow.HealthReport
- func (c *Client) JournalStore() *JournalStore
- func (c *Client) Nodes(ctx context.Context) ([]workflow.NodeInfo, error)
- func (c *Client) OnLifecycle(fn workflow.LifecycleFunc) error
- func (c *Client) OnRunFinished(fn workflow.RunFinishedFunc) error
- func (c *Client) OnTick(fn workflow.TickObserver) error
- func (c *Client) Pause(ctx context.Context, t workflow.PauseTarget) error
- func (c *Client) PauseSchedule(ctx context.Context, t workflow.ScheduleTarget) error
- func (c *Client) Paused(ctx context.Context) ([]workflow.PauseTarget, error)
- func (c *Client) PayloadLimit() int
- func (c *Client) QueueLoads(ctx context.Context) ([]workflow.QueueLoad, error)
- func (c *Client) Register(wf workflow.Workflow) error
- func (c *Client) Reschedule(ctx context.Context, ref workflow.RunRef, at time.Time) (workflow.RunRef, error)
- func (c *Client) Result(ctx context.Context, ref workflow.RunRef) ([]byte, error)
- func (c *Client) Resume(ctx context.Context, t workflow.PauseTarget) error
- func (c *Client) ResumeSchedule(ctx context.Context, t workflow.ScheduleTarget) error
- func (c *Client) Retry(ctx context.Context, ref workflow.RunRef) (workflow.RunRef, error)
- func (c *Client) Runs(ctx context.Context, q workflow.RunQuery) (workflow.RunPage, error)
- func (c *Client) Schedule(ctx context.Context, s workflow.Schedule) (workflow.ScheduleID, error)
- func (c *Client) Schedules(ctx context.Context) ([]workflow.ScheduleInfo, error)
- func (c *Client) SetWorkers(_ context.Context, queue string, n int) error
- func (c *Client) Signal(ctx context.Context, ev workflow.Event) error
- func (c *Client) Start(ctx context.Context) error
- func (c *Client) Status(ctx context.Context, ref workflow.RunRef) (workflow.Status, error)
- func (c *Client) Stop()
- func (c *Client) TriggerSchedule(ctx context.Context, id workflow.ScheduleID) (workflow.RunRef, error)
- func (c *Client) UniqueStore() *UniqueStore
- func (c *Client) Unschedule(ctx context.Context, id workflow.ScheduleID) error
- type DebounceStore
- type JournalStore
- type Option
- func WithClock(clk clock.Clock) Option
- func WithCronParser(p cron.Parser) Option
- func WithEnqueueOnly() Option
- func WithErrorHistory(n int) Option
- func WithIDFunc(f func() string) Option
- func WithJitterSource(rnd func() float64) Option
- func WithLease(d time.Duration) Option
- func WithLeaseClock(clk clock.Clock) Option
- func WithLogger(l *slog.Logger) Option
- func WithMaxReclaims(n int) Option
- func WithMiddleware(mw ...workflow.Middleware) Option
- func WithNodeID(id string) Option
- func WithPayloadLimit(n int) Option
- func WithPollInterval(d time.Duration) Option
- func WithPrefix(p string) Option
- func WithQueues(qs ...workflow.QueueConfig) Option
- func WithRetention(d time.Duration) Option
- func WithSchedulerOnly() Option
- func WithWorkers(n int) Option
- func WithoutScheduler() Option
- type UniqueStore
- func (u *UniqueStore) Acquire(ctx context.Context, key, owner string, ttl time.Duration) (bool, error)
- func (u *UniqueStore) Holder(ctx context.Context, key string) (string, workflow.RunRef, bool, error)
- func (u *UniqueStore) Release(ctx context.Context, key, owner string) error
- func (u *UniqueStore) SetHolder(ctx context.Context, key, owner string, ref workflow.RunRef) error
Constants ¶
This section is empty.
Variables ¶
var ErrAbandoned = errors.New("redis: run abandoned by its workers")
ErrAbandoned is the error of a run whose lease expired more than WithMaxReclaims times in a row: every worker that took it died (or lost Redis) before a step finished.
Functions ¶
This section is empty.
Types ¶
type BucketStore ¶
type BucketStore struct {
// contains filtered or unexported fields
}
BucketStore is a workflow.BucketStore in Redis: one hash per bucket key ({prefix}:bucket:<key>: its level and when it was last set), so every worker calling one upstream draws from one bucket. Take drains the level by the leak since then and admits or refuses the cost in one script, from the now the caller passes (never Redis's clock), so a fake clock drives it. Times are stored in microseconds, which a Lua number holds exactly. An idle bucket's key expires once it would have drained to empty, plus a minute.
func NewBucketStore ¶
func NewBucketStore(rdb goredis.UniversalClient, prefix string) (*BucketStore, error)
NewBucketStore returns a BucketStore over rdb under prefix.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the Redis driver of workflow.Client. Build it with New, Register workflows, then Start.
func New ¶
func New(rdb goredis.UniversalClient, opts ...Option) (*Client, error)
New returns an unstarted client over rdb. It never touches Redis until Start.
func (*Client) BucketStore ¶
func (c *Client) BucketStore() *BucketStore
BucketStore returns a BucketStore over this client's Redis and prefix.
func (*Client) Cancel ¶
Cancel stops an unfinished run: a delayed or queued one never starts, a running one has its step's context cancelled on the client that holds it (told through a published message). Finished runs are left alone.
func (*Client) CancelAll ¶
CancelAll cancels every run matching q in the statuses workflow.CancelStatuses picks (by default the runs not yet started), each exactly as Cancel would, and returns how many it cancelled. A run that moved to another status meanwhile is left alone. See workflow.BulkCanceller.
func (*Client) CancelStep ¶
CancelStep withdraws one step of a run (workflow.StepCanceller): a running attempt's ctx is cancelled with cause workflow.ErrStepCancelled on the client that holds the run, and what the handler returns decides (an output: the step succeeded; an error: it fails for good); a step in its backoff, snooze, wait or sleep fails for good at once, with an error matching workflow.ErrStepCancelled. A step not started or ended is ErrWrongState; an unknown run or step ErrNotFound.
func (*Client) Capabilities ¶
Capabilities returns what this driver does; see the package doc.
func (*Client) DebounceStore ¶
func (c *Client) DebounceStore() *DebounceStore
DebounceStore returns a DebounceStore over this client's Redis and prefix.
func (*Client) Delete ¶
Delete forgets a terminal run: Status then returns ErrNotFound and Runs no longer lists it.
func (*Client) Done ¶
func (c *Client) Done() <-chan struct{}
Done is closed once the client has fully stopped.
func (*Client) Drain ¶
Drain stops claiming runs, waits until the runs being executed finish or ctx ends, then stops the client as cancelling the Start ctx would. Runs still executing when ctx ends are handed back, so another client resumes them; the cut-off attempt is not charged an attempt (CapShutdownRequeue). See workflow.Drainer. It is DrainWithReport without the report.
func (*Client) DrainWithReport ¶
DrainWithReport is Drain that also returns what the drain finished and cut off (workflow.ReportingDrainer). A cut-off attempt is one whose handler was still running when ctx ended; its disposition is DrainRequeued. The report is fixed before the client's context is cancelled, and a second call returns the first call's report.
func (*Client) Enqueue ¶
Enqueue writes a run, ready now or at job.RunAt. With an idempotency key held by an unfinished run of the same workflow it writes nothing and returns that run's RunRef; the check and the write are one script, so two clients racing on one key make one run.
func (*Client) ForceComplete ¶
ForceComplete ends an unfinished or failed run as succeeded, from outside: steps still executing are cancelled with cause workflow.ErrForced and their results ignored, and the idempotency key is released. A succeeded or cancelled run is ErrWrongState.
func (*Client) ForceFail ¶
ForceFail ends an unfinished run as failed with workflow.ForcedFailure(reason) as its error: no retry, and OnFailure does not run. A finished run is ErrWrongState.
func (*Client) Health ¶
func (c *Client) Health(ctx context.Context) workflow.HealthReport
Health reports the client live unless it stopped, and ready while it is started (an enqueue-only client: always) and Redis answers a PING within ctx's deadline (workflow.HealthChecker).
func (*Client) JournalStore ¶
func (c *Client) JournalStore() *JournalStore
JournalStore returns a JournalStore over this client's Redis and prefix with no expiry.
func (*Client) Nodes ¶
Nodes lists the nodes of the prefix seen within three leases, by ID, and drops older entries (workflow.NodeLister).
func (*Client) OnLifecycle ¶
func (c *Client) OnLifecycle(fn workflow.LifecycleFunc) error
OnLifecycle registers fn to observe the lifecycle of the runs this process touches (workflow.LifecycleNotifier): best-effort and local, delivered in order on one goroutine; an event that finds the buffer of lifecycleBuffer full is dropped and logged.
func (*Client) OnRunFinished ¶
func (c *Client) OnRunFinished(fn workflow.RunFinishedFunc) error
OnRunFinished registers fn to observe run ends (workflow.RunNotifier), with the guaranteed delivery CapRunFinished promises. It returns workflow.ErrAlreadyStarted after Start.
func (*Client) OnTick ¶
func (c *Client) OnTick(fn workflow.TickObserver) error
OnTick registers fn to observe every tick this client fires, skips or drops (workflow.TickNotifier): TickFired with the run, TickSkipped for a tick a window, ScheduleWhen, a schedule pause or OverlapSkip held back, TickMisfired for ticks a late wake dropped, and TickFired with Manual for a TriggerSchedule. Each tick is reported by the one client whose script moved the schedule, after it ran; a crash in between loses the report. Register before Start.
func (*Client) Pause ¶
Pause holds the runs t names: no step attempt of them is claimed until Resume; attempts already executing finish. See workflow.Pauser.
func (*Client) PauseSchedule ¶
PauseSchedule stops a schedule, or every schedule (All, including ones made later), from firing until ResumeSchedule: its due ticks are reported TickSkipped with TickReasonPaused and never fire, not even on resume. The pause is stored, so every client obeys it. An unknown ID is ErrNotFound (workflow.SchedulePauser).
func (*Client) Paused ¶
Paused lists the targets in force: All first, then workflows, then queues, each by name.
func (*Client) PayloadLimit ¶
PayloadLimit is the largest payload Enqueue accepts (workflow.PayloadLimiter).
func (*Client) QueueLoads ¶
QueueLoads returns the load of every queue this client was configured with (WithQueues), sorted by name: the runs of its workflows ready on the queue, how long the oldest has waited, its worker cap here and its runs executing here (workflow.WorkerScaler). A client given no queues reports none.
func (*Client) Register ¶
Register validates wf and stores it. Cron expressions are parsed here so a typo fails now, not at the first fire.
func (*Client) Reschedule ¶
func (c *Client) Reschedule(ctx context.Context, ref workflow.RunRef, at time.Time) (workflow.RunRef, error)
Reschedule moves a delayed run that has not started to at (now when at is zero or past), keeping its RunRef (workflow.RunRescheduler).
func (*Client) Result ¶
Result returns a succeeded run's output: its one final step's output, or a JSON object of every final step's output (workflow.RunOutput). A run that has not succeeded is ErrWrongState (workflow.ResultReader).
func (*Client) Resume ¶
Resume removes the pause on t; Resume(PauseAll()) removes every pause. Resuming a target that is not paused is a no-op.
func (*Client) ResumeSchedule ¶
ResumeSchedule lets a paused schedule fire again from its next tick; with All it clears every schedule pause.
func (*Client) Retry ¶
Retry re-opens a failed run from the step that failed: steps that succeeded keep their outputs, the failed step and every step it held back start again with fresh attempt counts. The run keeps its RunRef, is admitted again under its workflow's policies, takes its idempotency key again (ErrDuplicate when another unfinished run holds it) and is reported again to run-finished observers when it ends. See workflow.RunRetrier.
func (*Client) Runs ¶
Runs lists runs newest enqueue first (ties by RunID, descending), across every client of the prefix. It walks the enqueue-time index and filters in Go with RunQuery.Match, so a narrow filter over a long history reads more than it returns; finished runs leave the index when Delete or retention removes them.
func (*Client) Schedule ¶
Schedule writes a recurring trigger. With a Name it is an upsert by (Workflow, Name): the same ScheduleID on every client and boot, and an unchanged expression, zone and misfire policy keep their next fire time. Any client of the prefix may fire it; the fire is a compare-and-set on the schedule's last catch-up time, so each tick runs once.
func (*Client) Schedules ¶
Schedules lists every schedule of the prefix, declared and made at run time, sorted by Workflow, then Name, then ID, with Last filled from the schedule's stored last fire and its run's current status ("" once the run is gone).
func (*Client) SetWorkers ¶
SetWorkers sets how many runs of queue this client executes at once, from its next claim; running runs are not interrupted. n below one wraps ErrInvalid; a queue not given to WithQueues wraps ErrNotFound.
func (*Client) Signal ¶
Signal keeps ev and resumes every run waiting on its name and key: each such run takes it once, and a run that reaches a matching wait step later takes it then, provided the run was enqueued before the signal was sent. A signal nobody waits for is kept until no unfinished run may take it, and is not an error.
func (*Client) Start ¶
Start checks every workflow against Capabilities, writes the declared cron schedules, subscribes to wake-up messages and starts the workers and the dispatcher. It does not block; cancelling ctx stops the client, handing its running runs back so another client resumes them.
func (*Client) Stop ¶
func (c *Client) Stop()
Stop cancels the client and waits until it has stopped. Safe to call more than once and before Start.
func (*Client) TriggerSchedule ¶
func (c *Client) TriggerSchedule(ctx context.Context, id workflow.ScheduleID) (workflow.RunRef, error)
TriggerSchedule enqueues one run of schedule id now, with its input and labels plus workflow.TriggeredLabels, and records it as the schedule's last fire; the next cron fire is unchanged. Under OverlapSkip it enqueues nothing while the schedule's last run is unfinished and returns an error matching workflow.ErrOverlap; the check and the enqueue are one script.
func (*Client) UniqueStore ¶
func (c *Client) UniqueStore() *UniqueStore
UniqueStore returns a UniqueStore over this client's Redis and prefix.
func (*Client) Unschedule ¶
Unschedule removes a schedule. An empty id is a no-op.
type DebounceStore ¶
type DebounceStore struct {
// contains filtered or unexported fields
}
DebounceStore is a middleware.DebounceStore in Redis: one hash per debounce key ({prefix}:debounce:<key>: the burst's first enqueue, its run time and its pending run), so a key enqueued from several processes is debounced once. Swap is one script, so of two processes swapping at once each gets back a different previous burst. A burst's key expires an hour of wall time after its RunAt (at least an hour after the swap), when its run has long started and nothing can cancel it any more.
func NewDebounceStore ¶
func NewDebounceStore(rdb goredis.UniversalClient, prefix string) (*DebounceStore, error)
NewDebounceStore returns a DebounceStore over rdb under prefix.
func (*DebounceStore) Get ¶
func (d *DebounceStore) Get(ctx context.Context, key string) (middleware.DebounceBurst, bool, error)
Get returns key's burst, or found false when there is none.
func (*DebounceStore) Swap ¶
func (d *DebounceStore) Swap(ctx context.Context, key string, b middleware.DebounceBurst) (middleware.DebounceBurst, bool, error)
Swap stores b as key's burst and returns the burst it replaced.
type JournalStore ¶
type JournalStore struct {
// contains filtered or unexported fields
}
JournalStore is a workflow.JournalStore in Redis: one hash per run ({prefix}:journal:<run>, a field per memo key), so a step's memoised results survive a crash and are seen by whichever worker resumes the run. With a TTL each Save also sets the hash to expire that long (wall time, measured by Redis) after its last write, a safety net for runs whose Forget never comes; zero keeps entries until Forget.
func NewJournalStore ¶
func NewJournalStore(rdb goredis.UniversalClient, prefix string, ttl time.Duration) (*JournalStore, error)
NewJournalStore returns a JournalStore over rdb under prefix, whose entries expire ttl after a run's last Save (zero: never).
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithClock ¶
WithClock sets the time source of every due time: delayed starts, sleeps, retry backoff, step timeouts and cron fires. The default is clock.Real; tests pass clock.NewFake.
func WithCronParser ¶
WithCronParser sets the cron dialect. Every client of one prefix must use the same parser, since any of them may fire any schedule. The default is cron.Parse.
func WithEnqueueOnly ¶
func WithEnqueueOnly() Option
WithEnqueueOnly makes an enqueue-only client, for a node that adds work but never runs it (a web server beside a separate worker fleet): Enqueue, Status, Cancel, Signal, Runs, Delete and the run forcers work without Start, Register is optional, and Start returns nil and starts nothing (no worker, no scheduler, no subscription). A job for a workflow this client registered gets that workflow's checks (its idempotency policy); a job for one it did not is checked by workflow.CheckJob only, and runs once a worker client that registers it claims it.
func WithErrorHistory ¶
WithErrorHistory sets how many failed attempts RunInfo.Errors keeps per run, newest kept (workflow.DefaultErrorHistory by default). Zero or less turns the history off.
func WithIDFunc ¶
WithIDFunc sets how run IDs are made. IDs must be unique across every client of the prefix and may not contain ':' or '{'. The default is the creation time in milliseconds (13 hex digits, so IDs sort by time and equal-priority runs start oldest first) followed by 16 random hex digits. A function that returns IDs in another order changes only the order of equal-priority runs.
func WithJitterSource ¶
WithJitterSource sets the random source of retry jitter, a function returning values in [0, 1). Tests pin it; the default is math/rand.
func WithLease ¶
WithLease sets how long a claimed run stays claimed without renewal (renewed every third of it). Values of zero or less are ignored.
func WithLeaseClock ¶
WithLeaseClock sets the clock leases and polling are measured on. It is separate from WithClock because a lease is about a worker being alive, which is wall time: a test that moves a fake scheduling clock by an hour must not make every running step look abandoned. The default is clock.Real.
func WithLogger ¶
WithLogger sets where background errors go (a failed renewal, a run that could not be handed back). The default discards them.
func WithMaxReclaims ¶
WithMaxReclaims sets how many lease expiries in a row a run survives before it fails with ErrAbandoned. Negative values are ignored.
func WithMiddleware ¶
func WithMiddleware(mw ...workflow.Middleware) Option
WithMiddleware wraps every step handler and OnFailure handler, outermost first.
func WithNodeID ¶
WithNodeID sets this client's node identity: StepInfo.Node, AttemptError.Node, RunInfo.AttemptedBy and its NodeInfo. The default is workflow.DefaultNodeID (host name and process ID).
func WithPayloadLimit ¶
WithPayloadLimit refuses, at Enqueue, a job whose payload (or a chained job's) is larger than n bytes, with a *workflow.PayloadTooLargeError. The default and the ceiling is the 512 MiB Redis stores in one value.
func WithPollInterval ¶
WithPollInterval sets how often an idle worker looks for work without a wake-up message. Values of zero or less are ignored.
func WithPrefix ¶
WithPrefix sets the key prefix (default "wf"). Clients that share a prefix share every run and schedule; give each app or test its own. Keys look like {prefix}:run:<id>.
func WithQueues ¶
func WithQueues(qs ...workflow.QueueConfig) Option
WithQueues makes this client serve only the named queues, each with its worker cap and priority (workflow.QueueConfig): runs of other queues wait for a client that serves them, which is how separate worker processes per queue are deployed. A run is claimed whole, so Workers caps how many runs of the queue this client executes at once (each may run parallel steps), within WithWorkers. Without it a client serves every queue from one pool. Start refuses an invalid list.
func WithRetention ¶
WithRetention sets how long a finished run stays readable before Redis expires its key (measured by Redis, so wall time). Zero keeps finished runs until Delete; negative values are ignored.
func WithSchedulerOnly ¶
func WithSchedulerOnly() Option
WithSchedulerOnly makes a scheduler node: Start runs no worker, only the dispatcher, which fires schedules and admits pending runs for the worker nodes (workflow.NodeScheduler).
func WithWorkers ¶
WithWorkers sets how many runs this client executes at once. Values below 1 are ignored.
func WithoutScheduler ¶
func WithoutScheduler() Option
WithoutScheduler makes a worker node: it runs workers and admits pending runs but fires no schedule (workflow.NodeWorker), so a separate scheduler node (WithSchedulerOnly) fires them. Declared Workflow.Cron entries are still written at Start.
type UniqueStore ¶
type UniqueStore struct {
// contains filtered or unexported fields
}
UniqueStore keeps the locks of the middleware package's Unique, UniqueUntilFinished and UniqueWith in Redis, so every process that enqueues shares them: it implements middleware.UniqueStore and middleware.UniqueHolders (the holder's run, for UniqueConfig.States and ReturnExisting). Each lock is the hash {prefix}:uniq:<key> (its owner and run) with a Redis expiry of its ttl, so a lock's ttl is wall time measured by Redis, and a lock nobody releases disappears on its own. Acquire, Release and SetHolder are each one script, so two processes racing on one key get one lock.
func NewUniqueStore ¶
func NewUniqueStore(rdb goredis.UniversalClient, prefix string) (*UniqueStore, error)
NewUniqueStore returns a UniqueStore over rdb whose keys start with prefix (WithPrefix's rules; a Client of the same prefix shares the hash tag, so on a Redis Cluster the locks live beside its runs).
func (*UniqueStore) Acquire ¶
func (u *UniqueStore) Acquire(ctx context.Context, key, owner string, ttl time.Duration) (bool, error)
Acquire takes key for owner for ttl and reports true, or reports false while another holder has it.
func (*UniqueStore) Holder ¶
func (u *UniqueStore) Holder(ctx context.Context, key string) (string, workflow.RunRef, bool, error)
Holder reports the owner and run of a held key whose run was recorded.