Chris Arderne
3e7964e7fa
## Summary Adds execution-window product surfaces for both declarative and imperative schedules. - Declarative schedules can set `window` through `schedules.task()`, with support for whole-minute, hour, and percentage values. - Imperative schedules can create, update, clear, and inspect windows through the API and dashboard. - Schedule API responses preserve `nextRun` as the nominal CRON time and expose `nextRunEffectiveAt` as the stable assigned time. - The dashboard displays configured windows alongside assigned upcoming-run times. - Deploy output summarizes declarative schedules and suggests adding a wider window when the default 60-second placement range is used. ## Design Window validation remains authoritative on the server and ensures each window is compatible with the schedule cadence. Omitting a window uses the default 60-second range, while explicit zero-duration windows remain supported. Deployment summaries are derived from the deployment's stored task metadata, so they reflect the declarations associated with that deployment.
@internal/schedule-engine
The @internal/schedule-engine package encapsulates all scheduling logic for Trigger.dev, providing a clean API boundary for managing scheduled tasks and their execution.
Architecture
The ScheduleEngine follows the same pattern as the RunEngine, providing:
- Centralized Schedule Management: All schedule-related operations go through the ScheduleEngine
- Redis Worker Integration: Built-in Redis-based distributed task scheduling
- Distributed Execution: Prevents thundering herd issues by distributing executions across time windows
- Comprehensive Testing: Built-in utilities for testing schedule behavior
Key Components
ScheduleEngine Class
The main interface for all schedule operations:
import { ScheduleEngine } from "@internal/schedule-engine";
const engine = new ScheduleEngine({
prisma,
redis: {
/* Redis configuration */
},
worker: {
/* Worker configuration */
},
distributionWindow: { seconds: 30 }, // Optional: default 30s
});
// Register next schedule instance
await engine.registerNextTaskScheduleInstance({ instanceId });
// Upsert a schedule
await engine.upsertTaskSchedule({
projectId,
schedule: {
taskIdentifier: "my-task",
cron: "0 */5 * * *",
timezone: "UTC",
environments: ["env-1", "env-2"],
},
});
Distributed Scheduling
The engine includes built-in distributed scheduling to prevent all scheduled tasks from executing at exactly the same moment:
import { calculateDistributedExecutionTime } from "@internal/schedule-engine";
const exactTime = new Date("2024-01-01T12:00:00Z");
const distributedTime = calculateDistributedExecutionTime(exactTime, 30); // 30-second window
Schedule Calculation
High-performance CRON schedule calculation with optimization for old timestamps:
import {
calculateNextScheduledTimestampFromNow,
nextScheduledTimestamps,
} from "@internal/schedule-engine";
const nextRun = calculateNextScheduledTimestampFromNow("0 */5 * * *", "UTC");
const upcoming = nextScheduledTimestamps("0 */5 * * *", "UTC", nextRun, 5);
Integration with Webapp
The ScheduleEngine should be the API boundary between the webapp and schedule logic. Services in the webapp should call into the ScheduleEngine rather than implementing schedule logic directly.
Migration Path
Currently, the webapp uses individual services like:
RegisterNextTaskScheduleInstanceServiceTriggerScheduledTaskService- Schedule calculation utilities
These should be replaced with ScheduleEngine method calls:
// Old approach
const service = new RegisterNextTaskScheduleInstanceService(tx);
await service.call(instanceId);
// New approach
await scheduleEngine.registerNextTaskScheduleInstance({ instanceId });
Configuration
The ScheduleEngine expects these configuration options:
prisma: PrismaClient instanceredis: Redis connection configurationworker: Worker configuration (concurrency, polling intervals)distributionWindow: Optional time window for distributed executiontracer: Optional OpenTelemetry tracermeter: Optional OpenTelemetry meter
Testing
The package includes comprehensive test utilities and examples. See the test directory for usage examples.