# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `jobs` | `id`, `queue`, `kind`, `payload` (JSON), `state`, `attempts`, `run_at`, `leased_until`, `leased_by`, `unique_key`, `last_error`, `created_at`, `finished_at` | | `job_schedules` | `name` (primary key), `kind`, `payload`, `cron`, `last_due_at` (only if `recurring_jobs` is on) | `state` is one of `waiting`, `running`, `done` and `failed`. Indexes: one on `queue`, `state`, `run_at`, `id` for taking jobs, and a unique one on `kind`, `unique_key` where `unique_key` is set and `state` is `waiting` or `running`. ## Taking a job A job can be taken when it is `waiting` and `run_at` has passed, or when it is `running` and `leased_until` has passed. Postgres: ```sql UPDATE jobs SET state = 'running', attempts = attempts + 1, leased_until = $now + interval '1 minute', leased_by = $worker WHERE id IN ( SELECT id FROM jobs WHERE queue = ANY($queues) AND ((state = 'waiting' AND run_at <= $now) OR (state = 'running' AND leased_until < $now)) ORDER BY run_at, id LIMIT $free FOR UPDATE SKIP LOCKED ) RETURNING *; ``` SQLite has one writer at a time, so the same `UPDATE ... WHERE id IN (SELECT ...) RETURNING *` without the last line of the inner query is already safe. Open the database in WAL mode with a busy timeout of 5 seconds. A job taken with `attempts` already at `max_attempts` because its lease ran out is marked failed with the error `worker lost` and not run. ## Finishing a job - Success: set `state` to `done` and `finished_at`. - Failure with attempts left: set `state` to `waiting` and `run_at` to now plus the wait in R3. - Failure with none left, or "do not retry": set `state` to `failed`. - Every one of these updates names the worker in its `WHERE` clause, so a worker that lost its lease cannot overwrite the worker that took over. ## Time Take the time from the database, not from each worker's clock, so workers on machines whose clocks differ agree. Wrap that in one function that tests can replace. ## Recurring jobs Once a minute each worker runs this in one transaction for each schedule: lock the schedule's row, work out the most recent time the cron expression was due, and if that is later than `last_due_at`, add one job and store the time. The lock and the comparison are what make three workers add one job. Support the five cron fields with numbers, `*`, lists, ranges and steps. Names of months and weekdays are not needed. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | ## Who is signed in The spec reaches the app's sign-in through one function, `current_user(request)`. It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session. When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production. ## Named here - In a schedule, when the day of the month and the day of the week are both given, either one matching is enough. Sunday is `0` or `7`. - The two errors are written `time limit exceeded` and `worker lost`. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.