AshWorkflow.Entities.Every (AshWorkflow v0.12.0)

Copy Markdown View Source

Defines a recurring action entity with its configuration schema.

every is not a timeout: nothing is timing out. It is a recurring action that runs on an interval for as long as a record sits in its step. Firing never leaves the step — there is no transition_to — so every always requires an action.

Storage

AshWorkflow.Transformers.AddAttributes adds one nilable :utc_datetime_usec attribute per every, holding the instant it last fired. Its interval is measured against that column, not against state_entered_at, so two every entities on the same step — and any timeout sharing the step — no longer share one anchor that one firing resets out from under the others.

Named <step>_<every>_last_fired_at by default, or explicitly with last_fired_field:

every :reminder do
  interval {1, :hours}
  action :send_reminder
  last_fired_field :reminder_last_fired_at
end

Not field — AshWorkflow.Entities.Timeout's field names an anchor AshWorkflow reads and never writes. last_fired_field names a column AshWorkflow owns and writes on every fire. Reusing the name would give it two opposite meanings.

A record whose column is still nil has never fired this every, and the interval is then measured from state_entered_at, so the first firing lands one whole interval after the record entered the step rather than on entry. Both the generated Oban trigger and AshWorkflow.Scheduler.Precise.Timeline apply that fallback.

Bounding an every with until

every alone fires forever. until stops it after a fixed amount of wall-clock time since the record entered the step:

every :reminder do
  interval {2, :days}
  action :send_review_reminder
  until {8, :days}
end

until is measured against state_entered_at directly. An every's own firing writes its last_fired_field, not state_entered_at, so state_entered_at stays put for as long as the record occupies the step — nothing moves the anchor until measures against. See AshWorkflow.Verifiers.ValidateEvery for why until must be strictly longer than interval.

Reaching the bound only stops the firing. It does not transition state — compose a second, ordinary timeout with a fire_after equal to the bound for "give up and move on".

Bounding an every with max_fires

max_fires stops it after a number of fires in the current step visit:

every :reminder do
  interval {2, :days}
  action :send_review_reminder
  max_fires 3
end

Spacing fires out with backoff

backoff grows the gap between fires. The first fire still lands one interval after entry. After fire n, the next lands interval plus AshWorkflow.Entities.Retry.delay_ms/2 for attempt n later, so a fixed duration adds the same delay to every later gap and :exponential adds Oban's n^4 + 15 seconds.

Both options add a <step>_<every>_fires integer column holding the fires in the current step visit. A fire recorded before state_entered_at belongs to an earlier visit, so the count restarts on re-entry.

Summary

Functions

The integer attribute counting this every's fires in the current step visit, <step_name>_<every_name>_fires, or nil when the every declares neither max_fires nor backoff and so needs no count.

The gap in milliseconds between fire number fires and the next one.

The attribute this every writes its last-fired instant to, and measures interval against: last_fired_field if given, otherwise <step_name>_<every_name>_last_fired_at.

The instant this every is next due, given the record's last-fired instant, its fire count and its state_entered_at.

Types

duration_unit()

@type duration_unit() :: AshWorkflow.Duration.unit()

t()

@type t() :: %AshWorkflow.Entities.Every{
  __spark_metadata__: term(),
  action: atom(),
  backoff: AshWorkflow.Entities.Retry.backoff() | nil,
  check_interval: String.t() | nil,
  emits: [AshWorkflow.Entities.Emit.t()],
  interval: {pos_integer(), duration_unit()},
  last_fired_field: atom() | nil,
  max_fires: pos_integer() | nil,
  name: atom(),
  retry: AshWorkflow.Entities.Retry.t() | nil,
  self_scheduled?: boolean(),
  until: AshWorkflow.Duration.t() | nil
}

Functions

attribute_schema()

fires_field(step_name, every)

@spec fires_field(atom(), t()) :: atom() | nil

The integer attribute counting this every's fires in the current step visit, <step_name>_<every_name>_fires, or nil when the every declares neither max_fires nor backoff and so needs no count.

gap_ms(interval, backoff, fires)

The gap in milliseconds between fire number fires and the next one.

fires of 0 is the gap from step entry to the first fire, which is interval whatever the backoff.

last_fired_field(step_name, every)

@spec last_fired_field(atom(), t()) :: atom()

The attribute this every writes its last-fired instant to, and measures interval against: last_fired_field if given, otherwise <step_name>_<every_name>_last_fired_at.

next_due_at(interval, backoff, last_fired_at, fires, state_entered_at)

The instant this every is next due, given the record's last-fired instant, its fire count and its state_entered_at.

A nil last fire measures interval from state_entered_at. A last fire from an earlier step visit counts as zero fires in this one.

validate_duration(value)