Schedules

Send a message into a queue on a cron, evaluated in an IANA time zone, from gigadrive.yaml, the console or the API.

A schedule sends the same message into a queue on a cron, so recurring work such as a daily digest or an hourly sync needs no scheduler of your own. The queue's consumer then processes each tick like any other message, with the same retries and dead letters.

Declare a schedule

Schedules in gigadrive.yaml belong to their queue. Each deployment brings the queue's declared schedules up to date and removes declared schedules you deleted from the file.

services:
  queues:
    digests:
      consumer: /api/queues/digests
      schedules:
        weekday-digest:
          cron: '0 8 * * MON-FRI'
          timezone: Europe/Berlin
          body: { kind: weekday }
        nightly-cleanup:
          cron: '@daily'
          body: { kind: cleanup }

A body that is not a string is sent as JSON, and a string body as plain text unless you set contentType. A declared name that matches a schedule made in the console or the API takes it over, so removing it from the file later removes it; other schedules made in the console or the API are left alone by deployments.

Create one from code

import { queue } from '@gigadrive/sdk';

const digests = queue<{ kind: string }>('digests');

await digests.schedule('weekday-digest', {
  cron: '0 8 * * MON-FRI',
  timezone: 'Europe/Berlin',
  payload: { kind: 'weekday' },
});

schedule creates the schedule, or updates it when the name exists. Inside a deployed Function, queue() needs no configuration: it authenticates with the Function's own credential, described in OIDC federation.

In the console, open the queue, select the Schedules tab, then Create schedule. The same tab shows each schedule's next and last run, disables one with its switch, and sends one now with Run now.

Cron syntax

Five fields: minute, hour, day of month, month and day of week. Each accepts *, numbers, ranges (1-5), lists (1,15) and steps (*/10). Months and weekdays also accept names such as JAN or MON, and 7 means Sunday as well as 0. When both day fields are restricted, a day matches either one, as in standard cron.

Macro	Same as
`@hourly`	`0 * * * *`
`@daily`, `@midnight`	`0 0 * * *`
`@weekly`	`0 0 * * 0`
`@monthly`	`0 0 1 * *`
`@yearly`, `@annually`	`0 0 1 1 *`

Time zones and daylight saving

timezone takes an IANA name such as Europe/Berlin or America/New_York and defaults to UTC. The cron is evaluated in local time, so 0 8 * * * stays at 08:00 across a daylight saving change. A local time that does not exist on the spring-forward day is skipped, and one that occurs twice in autumn runs once.

Each tick runs once

A tick fires within about 15 seconds of its time. Every tick carries a deduplication key built from the schedule and the tick time, so a tick is sent at most once even if the platform retries. A tick that was missed while the schedule was disabled is not caught up.

A send that fails, such as one refused by a full backlog, is recorded as the schedule's last error and retried for the same tick until the next tick is due. The first retry comes 30 seconds later, and the delay doubles with each retry up to one hour. A tick that still fails by then is skipped. A validation error, a queue that no longer exists, or an exceeded plan quota skips the tick at once, since retrying cannot fix it.

Headers on each tick

Every message a schedule sends carries x-schedule-name, the schedule's name, and x-schedule-time, the tick's time in ISO 8601 UTC. A schedule's own headers follow the rules for message headers, may not set those two names, and are limited to 30.

Limits

Schedules count per environment: 10 on Starter, 250 on Pro, and no limit on Enterprise. Each tick is one message, priced like any other send.