This page was generated from the source of RoboHub. Edit the source, not this page.
Scheduler
Recurring maintenance and deferred actions — chores — for a host application:
a water change every week, a filter rinse after 720 hours of running, a check at
a set time. The module registers its pages and API on the host's router
(/scheduler, /api/scheduler/...); it has no port of its own. Aquarium and
energy include it.
How an application uses it
Include the module and add it to deps. It brings i18n, settings,
notifications, forms and inventory.
The application:
- defines
host_shell(req, title, body, scripts): the module's pages render
content only, and their CSS travels with the content; - seeds its chores at startup with
scheduler_presets(text)(below); - calls
scheduler_usage_tick()from its background work, after
inventory_runtime_tick(), if chores follow an item's runtime; - calls
scheduler_complete_title(title, note)when what it records is the
chore itself — a water change logged is the water-change chore done; - adds the module's settings tab:
scheduler_settings_formand
scheduler_settings_save, combined throughhost_settings_tabs/form/save
(see appshell/index).
scheduler_status(chore, now) and scheduler_links_text(chore) let an
application show a chore's state and what it is tied to on its own pages.
Schedules
| Kind | When it is due |
|---|---|
interval | Every N hours (interval_hours; a day when none is given) |
cron | A five-field cron expression (minute, hour, day of month, month, day of week) in the machine's local time: *, 5, 1-5, 1,3,5, */15, 10-50/20. As in cron, when both day fields are restricted a day matching either is taken; day of week 7 is Sunday |
one_time | A date and time |
usage | After N hours of use (usage_hours), typed in, posted to POST /api/scheduler/chores/{id}/usage, or counted from an inventory item's runtime |
A chore is due when its time comes and overdue once its grace period
(grace_hours) has passed. Completing it records the note and computes the next
due time at once. Snoozing moves the visible due time without changing the
schedule.
Tied to the inventory
A chore can name inventory items by handle. runtime_of: filter-main makes a
usage chore count the item's switch runtime instead of hours typed in; only
runtime gained since the chore was tied to the item counts. consumes:
filter-pads with consumes_qty: 1 takes that much off the shelf each time the
chore is done, recorded as a stock movement for the chore (chore#<id>).
Presets
scheduler_presets(text) seeds the chores from the text of the application's
presets/schedule.yml. Each chore under chores: has a title and a kind,
and may have value (the cron expression or the date), interval_hours,
usage_hours, grace_hours, priority, runtime_of, consumes and
consumes_qty:
chores:
water-change:
title: Water change 30 %
kind: interval
interval_hours: 168
rinse-filter:
title: Rinse filter media
kind: usage
usage_hours: 720
runtime_of: filter-main
consumes: filter-pads
consumes_qty: 1
A chore is added once, by its title; after that it is the person's.
API
The JSON API under /api/scheduler/chores lists chores with their status and
due time, creates one, and completes, snoozes (in hours) or adds usage hours to
one by id. The routes are listed in the reference below.
Settings
Kept in the application's settings store (see settings/index):
| Key | Default | What it is |
|---|---|---|
scheduler.grace_hours | 12 | The grace period a new chore starts with |
scheduler.priority | normal | The priority a new chore starts with |
Data it keeps
In the application's database, <workspace>/data/app.db (or
RHO_SCHEDULER_DB), from the module's own db/schema.sql, which rho-sql
generates into every application that depends on the module:
| Table | What it holds |
|---|---|
chores | Each chore: its schedule, next due time, grace, priority, and what it is tied to in the inventory (runtime_of, the runtime already counted, consumes) |
chore_completions | Each completion, with the note a person left |
Additions and completions are written to the application log under the
scheduler subject; a changed chore is written to the journal.
Reference
Generated from the module's manifest and sources when this site was built.
Exports — what an application may call (provides.exports, imported as robohub.scheduler):
scheduler_statusscheduler_links_textscheduler_usage_tickscheduler_presetsscheduler_complete_titlescheduler_settings_formscheduler_settings_save
Routes — registered on the host application's router:
| Method | Path | Handler |
|---|---|---|
| GET | /scheduler | scheduler_page |
| POST | /scheduler/chores/add | scheduler_chores_add |
| POST | /scheduler/chores/complete | scheduler_chores_complete |
| POST | /scheduler/chores/snooze | scheduler_chores_snooze |
| POST | /scheduler/chores/usage | scheduler_chores_usage |
| GET | /scheduler/chores/edit | scheduler_chore_edit_page |
| POST | /scheduler/chores/edit | scheduler_chore_edit_save |
| POST | /scheduler/chores/delete | scheduler_chore_delete |
| GET | /api/scheduler/chores | scheduler_api_list |
| POST | /api/scheduler/chores | scheduler_api_add |
| POST | /api/scheduler/chores/{id}/complete | scheduler_api_complete |
| POST | /api/scheduler/chores/{id}/snooze | scheduler_api_snooze |
| POST | /api/scheduler/chores/{id}/usage | scheduler_api_usage |
Host hooks — functions the application must define, because this module calls them:
host_shell
Release history
[0.1.0] - 2026-11-02
The scheduler module. Interval, cron, one-time and usage-based chores; due and overdue states with a grace period; completion notes and next-due recalculation; snoozing; and a JSON chores API under /api/scheduler/chores. Tables live in the host application's main SQL database.
[0.1.1] - 2026-11-03
The scheduler page carries the same full application menu as the dashboard.
[0.1.2] - 2026-11-08
English/Romanian navigation and page copy, forms-engine add-chore flow with CSRF, and scheduler defaults moved to parent settings.
[0.1.3] - 2026-11-09
Pages render content through the host shell, so the host application owns the header, footer and menu. The scheduler CSS moved into templates/parts/style.html with the content. Chore additions and completions are written to the host application log.
[0.1.4] - 2026-11-12
The module declares the runtime functions it calls rather than relying on helpers the including application defines. Its smoke test signs in with a keeper ticket and sends the form token the module checks.
[0.1.5] - 2026-11-13
The module declares its tables and statements in its own sql: block, and rho-sql 0.2 generates them into each application that depends on it, so an application no longer repeats them. The smoke test runs in the aquarium's own repository.
[0.2.0] - 2026-11-13
A chore can be tied to the inventory: runtime_of names an item whose switch runtime (counted by inventory 0.2) drives a usage chore through scheduler_usage_tick(), and consumes names an item and a quantity that completing the chore takes off the shelf, recorded as a stock movement for that chore. An application seeds its chores from its presets (scheduler_presets); a seeded chore is added once and is the person's after that. scheduler_complete_title(title, note) completes a chore by its title, for an application whose own record is the chore (a water change logged).
[0.2.1] - 2026-11-13
The clock is read from the process (rho_now_s, rho 0.6.0) instead of from date written to a file and read back, which a request and the background loop could truncate under each other: entries dated 1970 and modes that expired at once. A date a person typed is one argument of date -d, run without a shell (rho_exec_capture), and its answer is returned rather than read from a shared file.
[0.2.2] - 2026-11-13
Cron is read as cron: *, numbers, ranges, lists and steps in all five fields (*/15 * * * *, 30 9 * * 1-5, 0 8 * * 7), day of week 7 as Sunday, and a day of the month or of the week matching when both are restricted, in local time with the offset of each moment. Before, */15 was never due and every weekday range was Saturday. A cron that names no time is refused. The API's add says whether the chore was kept, and why not, instead of always answering 201.
[0.2.3] - 2026-11-14
Trimming, URL escapes, form fields and decimals come from the toolchain (rho 0.7.0: str_trim, str_url_encode/str_url_decode, form_field, milli_*) rather than this module's own copy, the same on both backends. Needs rho 0.7.0. A quantity reads a decimal comma and a sign; a negative one is 0.
[0.2.4] - 2026-11-14
Cron is read in src/cron.rho, apart from the chores, and has unit tests of its own (tests/scheduler_test.rho): fields, lists, ranges and steps, the next time in local time in any time zone, and expressions that name no time. Nothing it does changed.
[0.2.5] - 2026-11-14
The route handlers are scheduler_chores_add, scheduler_chores_complete and so on, and the helpers and constants carry the prefix too (ignore_string is scheduler_ignore_string); unprefixed, they were in every including application's namespace.
[0.2.6] - 2026-11-14
Its data is kept where app_workspace() says (rho 0.8.0) — the application's workspace, else ~/.rho/apps/<app> — so two applications started by hand no longer share this module's records. It declares the i18n module it uses. Needs rho 0.8.0.
[0.2.7] - 2026-11-14
A chore can be edited — its schedule, what it uses, its priority — and deleted with its history, from its row; renaming one does not move when it is due. The row's forms carry the form token and are translated, and a change returns to the page by GET.
[0.2.8] - 2026-11-14
Its settings form is its own (scheduler_settings_form, scheduler_settings_save), shown by an application as one of its settings tabs.
[0.3.0] - 2026-11-14
It lists what other code may use (provides.exports, imported as robohub.scheduler). An application that includes it still reaches everything, and a build (rho 0.8.3) names each call to a function outside the list. The list is what the applications and modules of the ecosystem call; anything else is the module's own and may change without notice.