Repository navigation
v0.7.0
Upgrading from 0.6.x
- Rewrite every repeating timeout as an
every.timeout :nudge, fire_after: {1, :day}, action: :send_nudge, repeat: truebecomesevery :nudge, {1, :day}, action: :send_nudge. Therepeatoption no longer compiles. - Run
mix ash.codegen add_every_last_fired_columnsand migrate.AshWorkflow.Transformers.AddAttributesnow adds one column perevery, andAshWorkflow.Transformers.AddIndexesa(state, column)index for each, so a resource that declares aneveryfails on insert until the migration runs. - Drop
state_entered_atfrom any action'sacceptlist. It iswritable?: false, and a caller that genuinely needs to set it usesAsh.Changeset.force_change_attribute/3.
Added
-
every, a sibling entity totimeout. 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_reminderor the block form withinterval,action,check_interval,self_scheduled?,last_fired_fieldand a nestedretry. Unliketimeout,everyalways requiresaction, has notransition_toand nofield. It measuresintervalagainst its own nilable:utc_datetime_usecattribute, one perevery, named<step>_<every>_last_fired_atby default or explicitly withlast_fired_field— notstate_entered_at, and notfield, which names an anchor AshWorkflow reads and never writes.AshWorkflow.Changes.RecordEventwrites that column on every fire via its:every_fieldoption, so twoeveryentities on the same step, or aneveryand atimeout, no longer share (and reset) one anchor. A record whose column is stillnil(never fired) measures its interval fromstate_entered_atinstead, 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 andAshWorkflow.Scheduler.Precise.Timelineapply that fallback, as doesAshWorkflow.Calculations.PendingDeadlines.AshWorkflow.Info.everys/2reads the entities off a step.AshWorkflow.Info.recommended_indexes/1covers eachevery's column with the same(state, field)composite index it gives atimeout. -
fire_aton 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 endfires oncenext_check_athas passed, at whatever resolution the selected scheduler polls with.fire_atandfire_afterare mutually exclusive and exactly one of them is required, andfire_atcannot be combined withfield, which is the anchorfire_aftermeasures from.AshWorkflow.Verifiers.ValidateTimeoutPrecisionskips afire_attimeout: it promises no duration, so there is no precision for the scheduler to miss. That replaces thefire_after: {1, :seconds}sentinel the verifier used to coach people towards, which handed it a number that meant nothing.AshWorkflow.Scheduler.Work'sdeadlinemap expresses both shapes, with anilfire_aftermeaning the field holds the instant, andAshWorkflow.Scheduler.due_at/2resolves either to aDateTime.AshWorkflow.Info.workflow_graph/1carriesfire_at, andAshWorkflow.Info.recommended_indexes/1covers afire_atfield with the same(state, field)composite index it gives afield. -
A bound on
everywithuntil.everyfires forever by default;untilstops it after a fixed amount of wall-clock time:every :reminder do interval {2, :days} action :send_review_reminder until {8, :days} enduntilis measured againststate_entered_atdirectly, which anevery's own firing no longer touches (see above).AshWorkflow.Verifiers.ValidateEveryrejects anuntilthat is not strictly longer thaninterval, since anything shorter or equal leaves no room to fire even once. BothAshWorkflow.Scheduler.ObanandAshWorkflow.Scheduler.Precisehonour the bound through the sameWork.matchexpression every other check already goes through, andAshWorkflow.Scheduler.Precise.Timeline's recovery sweep filters on it too. Reaching the bound only stops the firing; compose a second, ordinary timeout with afire_afterequal to the bound for "give up and move on".
Changed
-
Breaking:
state_entered_atis no longer writable through an action.AshWorkflow.Transformers.AddAttributesdeclares itwritable?: false, so it cannot appear in an action'sacceptlist 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 afire_aftertimeout could be pushed out of reach by an unrelated update.AshWorkflow.Changes.RecordEventis unaffected: it writes the attribute withAsh.Changeset.force_change_attribute/3and, on the atomic path, through the mapatomic/3returns, and neither goes throughwritable?. A caller that genuinely needs to set it, such as one backfilling imported records, usesforce_change_attribute/3or the data layer directly. A resource that defines its ownstate_entered_atkeeps whatever it declared, since the transformer is a no-op there. -
Breaking:
timeout'srepeatoption is gone. Useeveryinstead.repeat: truelet a timeout re-fire on its own interval, but it also compiled two combinations that were meaningless:repeat: truewithtransition_to(firing leaves the step, so the repeat never comes round) andrepeat: truewith a customfield(rejected at compile time, since the repeat mechanism resetsstate_entered_at, not the custom field).everyrequiringactionand offering neithertransition_tonorfieldstops both from being representable at all. Changetimeout :name, fire_after: ..., action: ..., repeat: truetoevery :name, interval: ..., action: ....AshWorkflow.Verifiers.ValidateTimeoutFields.validate_no_repeat_with_custom_field/2and its tests are gone along with the option. -
Breaking:
AshWorkflow.Info.workflow_graph/1's:timeoutsentries drop:repeat, and each step's map gains an:everyslist of%{name:, interval:, action:, until:, retry:}maps, mirroring:timeouts.
Fixed
AshWorkflow.Scheduler.due_at/2returnsnilfor a deadline field that is an unloaded calculation, rather than raising on the%Ash.NotLoaded{}struct it read.AshWorkflow.Scheduler.Precise.Timelineloads 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 computingdue_at/2from a record of its own still has to load the calculation first.