Version 1 of 1 · · razie · in person · Current version

name
d3-f-crons
description
Crons — messages a project's rules send on a schedule; declaring, schedules, running, failures, quotas. Get skills only from /api/v2/skills/d3.
feature
cron
concepts
[cron]
tags
#skill #feature #d3skill #wip

d3-f-crons

Intro

Scheduled messages.

A cron is a message, not a construct: a rule sends diesel.cron (…), and when it's due d2 sends msg in the project with args, as a flow, under the project's quotas. People see them on the Crons page (/crons). Rules and flows are d3-f-engine. Spec: Spec › init-page (^cron-n).

Essentials

  • R-cron-1 MUST declare crons in Settings:Init on diesel.project.on.init, by name; redeclaring the same name replaces it.
  • R-cron-2 MUST keep a cron's flow short: flows run one at a time, so a slow cron holds the project.
  • R-cron-3 A stopped cron is fixed first, then switched back on — never just switched on.

Concepts

cron

A named schedule that sends one message with args. Also called: schedule, job, scheduled task. Fields: name, schedule (5-field cron 0 7 * * 1-5, or every 15m, hourly, daily 03:15), tz (UTC unless given), msg, args; on the Crons page its last result. States: on → off (by an admin, or by itself after 5 failures in a row) → on (admin). Running: a ticker every 30 s starts what's due; a run still going isn't started again (skipped and noted). After a restart, a run missed in the last hour runs once; older misses are only logged.

cron_declare

  • Summary: send diesel.cron from Settings:Init; same name replaces.
  • When: the project needs something done on a schedule.
  • Needs: name, schedule, tz, the message and its args.
  • Call: $send diesel.cron (name = "morning-prices", schedule = "0 7 * * 1-5", tz = "Europe/Lisbon", msg = "portfolio.refresh", args = {}) on diesel.project.on.init (runs at every start and whenever the page is saved).
  • Rules: R-cron-1, R-cron-2. Quotas per plan: number of crons and the shortest interval. Email from a cron (diesel.user.sendEmail (to, subject, text, link)) works only once email is switched on.
  • Errors: E_QUOTA → fewer crons or a longer schedule, or tell your person · E_MAILER_OFF → email isn't on yet.
  • Gotchas: —

cron_list

  • Summary: list crons and their last results.
  • When: checking what's scheduled or why one stopped.
  • Needs: —
  • Call: GET /api/v2/crons · in a rule diesel.cron.list · people: /crons.
  • Rules: —
  • Errors: —
  • Gotchas: —

cron_remove

  • Summary: remove one by name.
  • When: a schedule is no longer wanted.
  • Needs: the name.
  • Call: diesel.cron.remove (name) in a rule.
  • Rules: —
  • Errors: —
  • Gotchas: —

cron_switch

  • Summary: admins run now, switch on or off.
  • When: a manual run, pausing a cron, or turning a stopped one back on after the fix.
  • Needs: admin; the name.
  • Call: POST /api/v2/crons/<name>/run (now) · …/on · …/off.
  • Rules: R-cron-3.
  • Errors: —
  • Gotchas: —

cron_failed

  • Summary: each failure raises an event; 5 in a row switch it off.
  • When: a cron stopped by itself, or the project wants to react to failures.
  • Needs: its last result on /crons.
  • Call: handle diesel.cron.on.failed (audit J_FAIL) / diesel.cron.on.stopped (the project's owner gets a warning notice linking to /crons).
  • Rules: R-cron-3: read the last result, fix the flow, then cron_switch on.
  • Errors: —
  • Gotchas: —

Errors

  • E_QUOTA — too many crons or too short an interval for the plan → fewer crons or a longer schedule, or tell your person. see #cron_declare
  • E_MAILER_OFF — email isn't switched on yet. see #cron_declare
  • stopped by itself — 5 failures in a row → read its last result, fix the flow, then POST /api/v2/crons/<name>/on. see #cron_failed