Settings

Every cron directory holds a cronhoster-cron-settings.json beside its handler. It sets how many of the cron's runs may be in flight at once and lists the named schedules that fire it. The Crons page walks through writing one; this page is the field-by-field reference.

{
  "cronhoster-cron-setting-maxConcurrent": 1,
  "cronhoster-cron-setting-runs": [
    {
      "cronhoster-cron-setting-run-name": "top",
      "cronhoster-cron-setting-run-month": "*",
      "cronhoster-cron-setting-run-day": "*",
      "cronhoster-cron-setting-run-hour": "*",
      "cronhoster-cron-setting-run-minute": "*",
      "cronhoster-cron-setting-run-second": 0
    },
    {
      "cronhoster-cron-setting-run-name": "half",
      "cronhoster-cron-setting-run-month": "*",
      "cronhoster-cron-setting-run-day": "*",
      "cronhoster-cron-setting-run-hour": "*",
      "cronhoster-cron-setting-run-minute": "*",
      "cronhoster-cron-setting-run-second": 30
    }
  ]
}
A settings file that fires its handler twice a minute, at :00 and :30, one run at a time.

Contents

Two keys: the concurrency ceiling and the list of named schedules.

NameTypeDescription
cronhoster-cron-setting-maxConcurrentintegerHow many of this cron's handlers may run at once. Optional, an integer 1 or more, default 1.
cronhoster-cron-setting-runsarrayA non-empty list of runs. Each run is a named schedule that fires the handler when the clock matches it.

cronhoster-cron-setting-maxConcurrent

How many of this cron's handlers may be running at the same moment. It is optional and defaults to 1, so a cron runs one handler at a time unless you say otherwise. When a run matches while the cron is already at its ceiling, that firing is skipped. It is never queued, so a slow handler drops the ticks it overlaps rather than piling up a backlog. Raise the ceiling for a handler whose runs are safe to overlap.

cronhoster-cron-setting-runs

A non-empty array of run objects. Each run is a named schedule, and the cron fires whenever any of its runs matches the clock. A run carries a name and all five time fields.

NameTypeDescription
cronhoster-cron-setting-run-namestringA label for this schedule, distinct within the cron. It names the run in the logs.
cronhoster-cron-setting-run-monthinteger or "*"Month of the year, 1 to 12, or "*" for any month.
cronhoster-cron-setting-run-dayinteger or "*"Day of the month, 1 to 31, or "*" for any day.
cronhoster-cron-setting-run-hourinteger or "*"Hour of the day, 0 to 23, or "*" for any hour.
cronhoster-cron-setting-run-minuteinteger or "*"Minute of the hour, 0 to 59, or "*" for any minute.
cronhoster-cron-setting-run-secondinteger or "*"Second of the minute, 0 to 59, or "*" for any second.

Every one of the five time fields is required. Each is either an integer in its range or the wildcard string "*". A field left out is an error, because a missing field is ambiguous between a wildcard and a real value, so you always write out all five. Set a field to a number to pin that unit and to "*" to let it float.

The server reads the UTC clock once a second and fires a run when all five of its fields match: a number equals that unit of the current time, and "*" matches any value. Times are UTC. A second the server misses, for example while it is busy, is gone. Missed seconds are not backfilled.

Schedulemonthdayhourminutesecond
Every minute at :30****30
03:00 every day**300
Midday on the 1st of each month*11200
The same field grammar reads as calendar schedules once you fix the units you care about.