mix ash_workflow.gen.deletion adds a deletion workflow to a resource. A deletion is requested, waits a grace period during which it can be restored, then runs a purge action your application fills in. A purge that keeps failing moves to :purge_failed for an operator to retry.
The command
mix ash_workflow.gen.deletion MyApp.Accounts.Account --grace-period 30d
| Option | Default | Effect |
|---|---|---|
--grace-period | required | How long a request waits in :requested before the purge runs. Accepts 30m, 12h, 2d and 2w. A grace period in seconds, such as 10s, needs a scheduler that fires more often than once a minute, such as AshWorkflow.Scheduler.Precise. |
--max-attempts | 3 | How many times the purge runs before the deletion moves to :purge_failed. Must be a positive integer. With 1, the task generates no retry block, and a failed purge moves straight to :purge_failed. |
--module | <Subject>Deletion | Name of the generated deletion resource. |
--domain | the subject's domain | Domain for a subject the task creates. Required only when the subject does not exist. |
--transition-log | true | Also runs mix ash_workflow.gen.transition_log for the deletion resource. Pass --no-transition-log to skip it. |
When the subject does not exist, the task creates it with mix ash.gen.resource, using the data layer of the first ETS or Postgres resource in --domain. When no resource there uses ETS or Postgres, the task stops with an issue and writes nothing. Create the subject resource first, or pass a --domain that has one. Running the task again on the same subject changes nothing.
What it generates
For the command above, the task writes four modules and edits the subject:
MyApp.Accounts.AccountDeletionruns the workflow. It belongs to the account and holdsrequested_at. An identity onsubject_idallows one deletion per account.MyApp.Accounts.AccountDeletion.Changes.Purgeis the:purgeaction's change. It fails every purge as generated.MyApp.Accounts.AccountDeletion.Checks.CanRequestdecides who may request a deletion, request it again and retry a failed purge. It denies everyone as generated.MyApp.Accounts.AccountDeletion.Checks.CanRestoredecides who may restore a deletion. It denies everyone as generated.MyApp.Accounts.Accountgainshas_one :deletionand apending_deletion?calculation. The task adds no change, argument or policy to the subject's actions.
The task deletes nothing itself. Until you fill in Changes.Purge, every purge fails with an error naming that module, so an unfilled deletion moves to :purge_failed rather than to :deleted.
The workflow
stateDiagram-v2
[*] --> requested
requested --> purging: grace period after requested_at
requested --> restored: restore
restored --> requested: request_again
purging --> deleted: purge succeeds
purging --> purge_failed: purge fails max_attempts times
purge_failed --> purging: retry_purge
deleted --> [*]workflow do
step :requested do
transition :restore, to: :restored
timeout :purging, fire_after: {30, :days}, field: :requested_at, transition_to: :purging
end
step :purging do
action :purge
on_success :deleted
on_error :purge_failed
retry do
max_attempts 3
end
end
step :purge_failed do
transition :retry_purge, to: :purging
end
step :restored do
transition :request_again, to: :requested
end
step :deleted, terminal: true
endThe grace period runs from requested_at, which request and request_again both set to the current time. It does not read state_entered_at, so a transition you add that loops back into :requested does not restart it.
:restored is not terminal. The identity allows one deletion per account, so request_again is how a restored account is deleted later. It starts a new grace period.
restore is a plain transition rather than undo. :requested is the first state, so undo has nothing to rewind to, and a restore usually has work of its own to do, such as re-enabling a login.
What your application does next
Request the deletion
Call request/2 wherever a deletion starts, such as a settings page or a support tool:
MyApp.Accounts.AccountDeletion.request(account.id, actor: current_user)CanRequest refuses every request until you change it, as Decide who may act describes. Code that requests a deletion on the application's behalf, such as a data-subject request import, can pass authorize?: false instead. A second request for the same account fails on the :unique_subject identity.
Fill in the purge
The :purge action runs once the grace period has passed. Its generated change, Changes.Purge, adds an error to every purge. Replace its change/3 with the changes that erase or anonymise the subject:
defmodule MyApp.Accounts.AccountDeletion.Changes.Purge do
use Ash.Resource.Change
@impl true
def change(changeset, _opts, _context) do
Ash.Changeset.before_action(changeset, fn changeset ->
MyApp.Accounts.anonymise_account!(changeset.data.subject_id)
changeset
end)
end
endA deletion requested before the purge is filled in moves to :purge_failed once its attempts run out. Call retry_purge/2 on it after deploying the purge.
A purge is retried up to --max-attempts times, and retry_purge runs it again from the start. Write it so that running it twice is safe, such as by checking whether a file is already gone before removing it.
Decide who may act
CanRequest and CanRestore deny everyone, so nobody can call request, request_again, retry_purge or restore until you change them. Replace their match?/3, or replace the authorize_if lines in the deletion's policies with built-in checks:
policies do
policy action(:request) do
authorize_if relates_to_actor_via([:subject, :owner])
end
policy action([:request_again, :retry_purge]) do
authorize_if actor_attribute_equals(:role, :support)
end
policy action(:restore) do
authorize_if relates_to_actor_via([:subject, :owner])
end
endReads stay open by default. AshWorkflow authorizes :read on the deletion resource for every actor. Add a read policy if deletions are private.
Restore
restore/2 moves a deletion in :requested to :restored:
MyApp.Accounts.AccountDeletion.restore(deletion, actor: current_user)A deletion in :purging or :purge_failed cannot be restored, since part of the subject may already be gone.
Handle a failed purge
The task generates no notification. Add a timeout with an action to the :purge_failed step, or an Ash notifier on the deletion resource, to tell an operator. The transition log's :error_path row records the failure. Once the cause is fixed, call retry_purge/2.
Use the outcome
pending_deletion? on the subject is true while its deletion is in :requested, :purging or :purge_failed, and false otherwise, including for a subject with no deletion. Gating a subject action on it is up to you, for example with a policy on the subject:
policy action(:sign_in) do
forbid_if expr(pending_deletion?)
authorize_if always()
endGenerate the migrations
On AshPostgres, run mix ash.codegen add_account_deletion to create the deletion and transition log tables.
Limits
The task records no actor. Nothing in the generated code says who requested or restored a deletion. Add a requested_by relationship, and pass --no-transition-log and run mix ash_workflow.gen.transition_log with --actor, if you need to record it.
The deletion row stays after the purge, so the account's history survives its erasure. If the purge destroys the subject itself, the deletion row still references it. On AshPostgres the generated foreign key then blocks the destroy. The purge cannot clear the reference, because the generated belongs_to :subject sets allow_nil? false. Make the reference nullable and let Postgres clear it on delete, in the deletion resource. On the generated belongs_to :subject, change only allow_nil? to true. Keep the rest of the line as generated. For an integer or string key it also sets attribute_type, and dropping that changes the subject_id column to uuid:
postgres do
table "account_deletions"
repo MyApp.Repo
references do
reference :subject, on_delete: :nilify
end
end
relationships do
belongs_to :subject, MyApp.Accounts.Account, allow_nil?: true, public?: true
endThen run mix ash.codegen again. The foreign key becomes ON DELETE SET NULL, so destroying the account sets the deletion's subject_id to nil and the purge carries on to :deleted.