Scheduling

Active contributors: alex, david, yichaoyang

Purpose

Schedules let users run a workflow on a calendar (cron expression, intervals, calendar specs) without writing the orchestration logic themselves. The server tracks scheduled invocations, retries, catch-up, and overlap policies on behalf of the user.

Two implementations

The codebase currently has two parallel implementations:

• Classic (service/worker/scheduler/) — a system workflow under the Internal Worker. Each schedule is a workflow execution.
• CHASM (chasm/lib/scheduler/) — a CHASM Library that lives directly in History. The migration target.

The CHASM version is the future; both ship today and are toggleable via dynamic config. The CHASM Library is one of the cleanest examples of a non-trivial ASM and a recommended template for new state machines.

Source map

Surface	File / package
Public proto	temporal.api.schedule.v1.* (in [go.temporal.io/api])
Frontend handler	Schedule RPCs are routed through OperatorService; see service/frontend/operator_handler.go
Classic system workflow	service/worker/scheduler/
CHASM Library	chasm/lib/scheduler/
Schedule migration	tests/schedule_migration_test.go
Architecture doc	docs/architecture/schedules.md

How it works

graph TD
    User[User: CreateSchedule] --> FE[Frontend OperatorService]
    FE --> CHASM[chasm/lib/scheduler Library]
    CHASM --> Engine[CHASM Engine in History]
    Engine -->|timer task| Trigger[Schedule fires]
    Trigger --> StartWF[StartWorkflow on user task queue]
    Engine -->|update state| Persist[(persistence)]

Schedule policies (overlap, catch-up window, jitter, calendar) are implemented as part of the scheduler Component's transition logic. The tests in tests/schedule_test.go (110KB) and tests/schedule_migration_test.go (45KB) are the most authoritative reference for behaviour.

Migration

Schedules are migrated from the classic to the CHASM implementation by a dedicated workflow in service/worker/migration/. For an operator, migration is transparent: schedules continue firing while their state moves under the new engine.

Entry points for modification

• Adding a schedule policy option: edit the public proto in temporalio/api, regen, and implement the new behaviour in both chasm/lib/scheduler/ and service/worker/scheduler/ (or only the CHASM side if migration is complete for that field).
• Tuning schedule firing timing: dynamic-config keys prefixed scheduler.* in common/dynamicconfig/constants.go.

Related pages

• CHASM — the framework the new scheduler builds on.
• Internal Worker — host of the classic implementation.
• docs/architecture/schedules.md