Aegis documentation

#Tasker — every action as a task

The panel never performs a write in the request that asked for it. It validates the form, stores a task, and the tasker daemon executes it. The page returns immediately, the work appears in the task window, and its output stays in the task log afterwards.

That is not an abstraction for its own sake: a vhost render, a mail domain with a DKIM key, a zone rewrite and a database restart all fail in ways that must be reported somewhere the operator can read afterwards. One queue is easier to reason about than a dozen request handlers that each log differently.

#What a task is

A task is one row in database/storage/tasker/tasker.db. It owns:

FieldMeaning
namewhat the panel shows
group_namesection that queued it (web, mail, dns, ftp, database, sys)
typehow it runs: internal, command, script, webhook
targetcallable name, argv JSON, script path or URL
argsJSON parameters
statuspending, running, done, failed, cancelled, interrupted
output / error_outputwhat the action answered, or why it failed
dataJSON the action returned for its caller
retries / max_retriesattempts made and the limit
parent_id / positionthe step tree
resourcewhat is being touched, for reading the queue
actorpanel account that asked
timestampscreated_at, started_at, scheduled_at, completed_at, failed_at

A task with children is a container: it has no work of its own. The children are created with the plan, before anything runs, so the panel can show the steps that are about to happen instead of a list that grows while you watch.

#The four types

TypetargetNotes
internala name registered in app/modules/tasker/registry.pycalls a Python function, keeps validation and rollback
commandan argv list, or a list of argv listsno shell; several lists run in order
scriptan absolute pathargs.argv is passed as arguments
webhookan http(s) URLnon-accepted status is a failure

internal is what the panel uses. A command task exists for maintenance that only a shell command can do, and a webhook task for notifying something outside the host.

#Steps, failure and rollback

Children run in order, in one worker, so two tasks that touch the same resource never interleave. A failing step marks the remaining ones cancelled with not run: the previous step failed, and the container fails with step N failed: ….

A step marked on_failure is part of the plan but not part of the normal run: it is created upfront (and visible), runs only after an earlier step failed, and is recorded as cancelled with not needed: every step succeeded when the task worked. That is how a task that created half a zone before failing can undo it:

python
store.create(    name="create zone example.com",    type="internal",    group="dns",    plan=[        {"name": "write the zone", "type": "internal",         "target": "dns.zone.create", "args": {...}},        {"name": "publish the records", "type": "internal",         "target": "dns.record.add", "args": {...}},        {"name": "delete the zone again", "type": "internal",         "target": "dns.zone.delete", "args": {...}, "on_failure": True},    ],)

A stop requested during the rollback is ignored on purpose: leaving the host half changed is worse than finishing the undo. A rollback step that fails does not stop the others, and its error is reported together with the original one.

#Retries

A failed task is retried only when its result says the failure is retryable (a validation error never is). Retries go back to the queue, not to sleep inside a worker: the row becomes pending again with a future scheduled_at, the worker slot is freed, and the panel shows a queued task rather than a stuck one.

The delay is 5s × attempt, capped at 5 minutes. Nothing is retried more than max_retries times; after that the task fails and stays in the history.

#Cancel and retry from the panel

The floating window offers two buttons per row:

StatusButtonWhat happens
pendingCancelthe row becomes cancelled immediately, its steps too
running (with steps)Stopcancel_requested is set; the daemon stops before the next step and marks the rest as never run
failed, cancelled, interruptedRetrythe same row goes back to pending, its steps reset, the previous attempt stays in the log

A running task without steps cannot be stopped: the call is already in flight and interrupting it would leave the host in an unknown state. The API answers that plainly instead of pretending.

#The window and the bell

Every page carries the same component (js/components/tasker.js):

  • it polls /api/tasker/feed once every 1.2 s, for the window and the bell
  • together;

  • a finished task stays on screen for 15 s, because a 300 ms action would
  • otherwise end between two polls and never be seen;

  • the window is draggable, resizable, minimisable and closable, and remembers
  • its position in localStorage;

  • minimised, the bar names the work (1 task: deleting vhost) instead of
  • showing a bare count, and a click expands it again;

  • the bell counts what arrived since it was last opened.
  • Clicking a row opens the task: status, type, group, actor, attempts, steps, and the log.

    #The task page is live

    Each stored log line and each status change is published on the private Bird topic tasker (see live.md). The task page subscribes and prepends new lines, then reloads once when the task reaches a final status — the steps table, the output block and the Retry button are rendered server-side, and one reload keeps them correct.

    #Command line

    bash
    aegis tasker status              # counts per stateaegis tasker list --limit 20     # recent tasksaegis tasker show 42 --lines 40  # one task with its logaegis tasker run command '["/bin/true"]' --name smokeaegis tasker run internal web.vhost.create --arg vhost_id=3aegis tasker cancel 42           # stop a pending task, or a running containeraegis tasker retry 42            # queue a failed task againaegis tasker daemon              # run the loop in the foreground

    run --wait follows the task in the foreground and exits with its status.

    #Files and supervision

    PathContent
    database/storage/tasker/tasker.dbtasks and their log
    database/migrations/core/taskerschema, one file per change
    <run>/tasker.lockthe lock that keeps a single daemon
    <run>/tasker.pidpid the keeper reads
    <run>/tasker.heartbeatrewritten every tick; a stale one means a hung daemon
    <logs>/tasker.logdaemon output

    The daemon is a keeper service like any other: writes_pid=True, so it publishes its own pid, and a heartbeat the keeper judges. A closed daemon is restarted like any dead service; a hung one (alive pid, stale heartbeat for 90 s) is killed and restarted too. See keeper.md.

    #Housekeeping

  • A step keeps at most 2000 log lines; older ones are dropped.
  • done and cancelled tasks older than 48 hours are purged on a schedule.
  • failed and interrupted rows are not purged: they are what an operator
  • comes back to. Management → Tasker → Clear failed removes them on purpose.

  • On daemon start, rows left running become interrupted — a task cannot be
  • resumed safely, and saying so is honest.

    #Adding an action

  • write the function in app/modules/tasker/actions/<area>.py:
  • python
       @registry.action("mail.alias.add")   def alias_add(context, args) -> ActionResult:       ...       return success("alias added", data={"source": source})
  • import the module in app/modules/tasker/actions/__init__.py;
  • restart the tasker — the daemon imports the action modules once, at start.
  • The function receives ActionContext (config, actor, task_id) and the task's args, and returns success(...), failure(...) or partial(...) from app/helpers/result.py. Raising is allowed: the runner turns the exception into a failed task with the traceback in its error output.