Skip to content

v0.7.0

Choose a tag to compare

@github-actions github-actions released this 22 Sep 16:42
· 344 commits to main since this release
Immutable release. Only release title and notes can be modified.
f6bac53

Upgrading from 0.6.x

  • Rewrite every repeating timeout as an every. timeout :nudge, fire_after: {1, :day}, action: :send_nudge, repeat: true becomes every :nudge, {1, :day}, action: :send_nudge. The repeat option no longer compiles.
  • Run mix ash.codegen add_every_last_fired_columns and migrate. AshWorkflow.Transformers.AddAttributes now adds one column per every, and AshWorkflow.Transformers.AddIndexes a (state, column) index for each, so a resource that declares an every fails on insert until the migration runs.
  • Drop state_entered_at from any action's accept list. It is writable?: false, and a caller that genuinely needs to set it uses Ash.Changeset.force_change_attribute/3.

Added

  • every, a sibling entity to timeout. Declares a recurring action that runs on an interval for as long as a record sits in its step: every :nudge, {1, :day}, action: :send_reminder or the block form with interval, action, check_interval, self_scheduled?, last_fired_field and a nested retry. Unlike timeout, every always requires action, has no transition_to and no field. It measures interval against its own nilable :utc_datetime_usec attribute, one per every, named <step>_<every>_last_fired_at by default or explicitly with last_fired_field — not state_entered_at, and not field, which names an anchor AshWorkflow reads and never writes. AshWorkflow.Changes.RecordEvent writes that column on every fire via its :every_field option, so two every entities on the same step, or an every and a timeout, no longer share (and reset) one anchor. A record whose column is still nil (never fired) measures its interval from state_entered_at instead, so the first firing lands one whole interval after the record entered the step and an existing table needs no backfill. Both the generated Oban trigger and AshWorkflow.Scheduler.Precise.Timeline apply that fallback, as does AshWorkflow.Calculations.PendingDeadlines. AshWorkflow.Info.everys/2 reads the entities off a step. AshWorkflow.Info.recommended_indexes/1 covers each every's column with the same (state, field) composite index it gives a timeout.

  • fire_at on a timeout. Names a datetime attribute or expression calculation that already holds the deadline instant, rather than an anchor to measure an offset from: timeout :dormant do fire_at :next_check_at; transition_to :dormant_review end fires once next_check_at has passed, at whatever resolution the selected scheduler polls with. fire_at and fire_after are mutually exclusive and exactly one of them is required, and fire_at cannot be combined with field, which is the anchor fire_after measures from. AshWorkflow.Verifiers.ValidateTimeoutPrecision skips a fire_at timeout: it promises no duration, so there is no precision for the scheduler to miss. That replaces the fire_after: {1, :seconds} sentinel the verifier used to coach people towards, which handed it a number that meant nothing. AshWorkflow.Scheduler.Work's deadline map expresses both shapes, with a nil fire_after meaning the field holds the instant, and AshWorkflow.Scheduler.due_at/2 resolves either to a DateTime. AshWorkflow.Info.workflow_graph/1 carries fire_at, and AshWorkflow.Info.recommended_indexes/1 covers a fire_at field with the same (state, field) composite index it gives a field.

  • A bound on every with until. every fires forever by default; until stops it after a fixed amount of wall-clock time:

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

    until is measured against state_entered_at directly, which an every's own firing no longer touches (see above). AshWorkflow.Verifiers.ValidateEvery rejects an until that is not strictly longer than interval, since anything shorter or equal leaves no room to fire even once. Both AshWorkflow.Scheduler.Oban and AshWorkflow.Scheduler.Precise honour the bound through the same Work.match expression every other check already goes through, and AshWorkflow.Scheduler.Precise.Timeline's recovery sweep filters on it too. Reaching the bound only stops the firing; compose a second, ordinary timeout with a fire_after equal to the bound for "give up and move on".

Changed

  • Breaking: state_entered_at is no longer writable through an action. AshWorkflow.Transformers.AddAttributes declares it writable?: false, so it cannot appear in an action's accept list and is rejected as action input. Every deadline on a step measures from this attribute, so a write from outside moved all of them at once, and a fire_after timeout could be pushed out of reach by an unrelated update. AshWorkflow.Changes.RecordEvent is unaffected: it writes the attribute with Ash.Changeset.force_change_attribute/3 and, on the atomic path, through the map atomic/3 returns, and neither goes through writable?. A caller that genuinely needs to set it, such as one backfilling imported records, uses force_change_attribute/3 or the data layer directly. A resource that defines its own state_entered_at keeps whatever it declared, since the transformer is a no-op there.

  • Breaking: timeout's repeat option is gone. Use every instead. repeat: true let a timeout re-fire on its own interval, but it also compiled two combinations that were meaningless: repeat: true with transition_to (firing leaves the step, so the repeat never comes round) and repeat: true with a custom field (rejected at compile time, since the repeat mechanism resets state_entered_at, not the custom field). every requiring action and offering neither transition_to nor field stops both from being representable at all. Change timeout :name, fire_after: ..., action: ..., repeat: true to every :name, interval: ..., action: .... AshWorkflow.Verifiers.ValidateTimeoutFields.validate_no_repeat_with_custom_field/2 and its tests are gone along with the option.

  • Breaking: AshWorkflow.Info.workflow_graph/1's :timeouts entries drop :repeat, and each step's map gains an :everys list of %{name:, interval:, action:, until:, retry:} maps, mirroring :timeouts.

Fixed

  • AshWorkflow.Scheduler.due_at/2 returns nil for a deadline field that is an unloaded calculation, rather than raising on the %Ash.NotLoaded{} struct it read. AshWorkflow.Scheduler.Precise.Timeline loads a calculation deadline field with the records it sweeps and re-reads before firing, so it arms the timer from a value rather than from nothing. That is the #70 failure mode under the Precise scheduler; a caller computing due_at/2 from a record of its own still has to load the calculation first.