@flowdular/sdk 0.2.4 → 0.3.0

package/modules/automations/src/domain/cron.ts

@@ -0,0 +1,366 @@
+/**
+ * Five field cron with no seconds: minute, hour, day of month, month, day of
+ * week. Each field is `*`, a number, a range `a-b`, any of those with a step
+ * `/n`, or a comma separated list of them. Three letter month and weekday
+ * names are accepted and normalized to numbers. A next run is a wall clock
+ * time in the workspace zone, resolved to one UTC instant through Intl.
+ */
+export const MAX_CRON_LENGTH = 100;
+const MAX_FIELD_ITEMS = 32;
+/* Four years covers 29 February, so an expression with no match inside the
+   window has none at all and is refused where it is saved. */
+const MAX_SEARCH_DAYS = 1_500;
+const DAY_MS = 86_400_000;
+
+export class InvalidCronError extends Error {
+	constructor(detail: string) {
+		super(`Cron expression is invalid: ${detail}`);
+		this.name = 'InvalidCronError';
+	}
+}
+
+export interface CronFields {
+	readonly minutes: readonly number[];
+	readonly hours: readonly number[];
+	readonly daysOfMonth: readonly number[];
+	readonly months: readonly number[];
+	/** 0 is Sunday; 7 is accepted on input and stored as 0. */
+	readonly daysOfWeek: readonly number[];
+	/* Vixie rule: with both day fields restricted a slot matches either one, so
+	   `0 0 13 * 5` is the 13th and every Friday, not only Friday the 13th. A
+	   field that starts with a star is unrestricted, step or not, so a stepped
+	   day of month keeps the intersection. */
+	readonly dayUnion: boolean;
+}
+
+const MONTH_NAMES = [
+	'jan',
+	'feb',
+	'mar',
+	'apr',
+	'may',
+	'jun',
+	'jul',
+	'aug',
+	'sep',
+	'oct',
+	'nov',
+	'dec',
+];
+
+const WEEKDAY_NAMES = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+
+interface FieldSpec {
+	readonly name: string;
+	readonly min: number;
+	readonly max: number;
+	readonly names?: readonly string[];
+}
+
+const SPECS: readonly FieldSpec[] = [
+	{ name: 'minute', min: 0, max: 59 },
+	{ name: 'hour', min: 0, max: 23 },
+	{ name: 'day of month', min: 1, max: 31 },
+	{ name: 'month', min: 1, max: 12, names: MONTH_NAMES },
+	{ name: 'day of week', min: 0, max: 7, names: WEEKDAY_NAMES },
+];
+
+function fieldValue(raw: string, spec: FieldSpec): number {
+	const named = spec.names?.indexOf(raw) ?? -1;
+	if (named >= 0) return named + spec.min;
+	if (!/^\d{1,2}$/.test(raw)) {
+		throw new InvalidCronError(`${spec.name} has an unsupported value`);
+	}
+	const value = Number(raw);
+	if (value < spec.min || value > spec.max) {
+		throw new InvalidCronError(
+			`${spec.name} must be between ${spec.min} and ${spec.max}`,
+		);
+	}
+	return value;
+}
+
+function parseField(raw: string, spec: FieldSpec): readonly number[] {
+	const items = raw.split(',');
+	if (items.length > MAX_FIELD_ITEMS) {
+		throw new InvalidCronError(`${spec.name} lists too many values`);
+	}
+	const values = new Set<number>();
+	for (const item of items) {
+		const parts = item.split('/');
+		if (parts.length > 2 || parts[0] === '') {
+			throw new InvalidCronError(`${spec.name} has an unsupported value`);
+		}
+		const stepped = parts.length === 2;
+		const step = stepped ? Number(parts[1]) : 1;
+		if (
+			stepped &&
+			(!/^\d{1,2}$/.test(parts[1]!) ||
+				step < 1 ||
+				step > spec.max - spec.min + 1)
+		) {
+			throw new InvalidCronError(`${spec.name} has an unsupported step`);
+		}
+		let from: number;
+		let to: number;
+		if (parts[0] === '*') {
+			from = spec.min;
+			to = spec.max;
+		} else {
+			const bounds = parts[0]!.split('-');
+			if (bounds.length > 2) {
+				throw new InvalidCronError(`${spec.name} has an unsupported range`);
+			}
+			from = fieldValue(bounds[0]!, spec);
+			if (bounds.length === 1) {
+				/* A single value with a step would silently mean `value to max`. */
+				if (stepped) {
+					throw new InvalidCronError(
+						`${spec.name} needs a range or * before a step`,
+					);
+				}
+				to = from;
+			} else {
+				to = fieldValue(bounds[1]!, spec);
+				if (to < from) {
+					throw new InvalidCronError(`${spec.name} range runs backwards`);
+				}
+			}
+		}
+		for (let value = from; value <= to; value += step) values.add(value);
+	}
+	return [...values].sort((left, right) => left - right);
+}
+
+export function parseCron(expression: string): CronFields {
+	if (expression.length > MAX_CRON_LENGTH) {
+		throw new InvalidCronError('it is too long');
+	}
+	const fields = expression.trim().toLowerCase().split(/\s+/);
+	if (fields.length !== 5 || fields[0] === '') {
+		throw new InvalidCronError('it needs five fields');
+	}
+	const parsed = fields.map((field, index) => parseField(field, SPECS[index]!));
+	/* Sunday is both 0 and 7 on input; the matcher only ever sees 0. */
+	const daysOfWeek = [
+		...new Set(parsed[4]!.map((day) => (day === 7 ? 0 : day))),
+	].sort((left, right) => left - right);
+	return {
+		minutes: parsed[0]!,
+		hours: parsed[1]!,
+		daysOfMonth: parsed[2]!,
+		months: parsed[3]!,
+		daysOfWeek,
+		dayUnion: !fields[2]!.startsWith('*') && !fields[4]!.startsWith('*'),
+	};
+}
+
+/** One canonical spelling: lower case, single spaces, no surrounding space. */
+export function normalizeCron(expression: string): string {
+	parseCron(expression);
+	return expression.trim().toLowerCase().split(/\s+/).join(' ');
+}
+
+interface WallTime {
+	year: number;
+	month: number;
+	day: number;
+	hour: number;
+	minute: number;
+}
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+function formatterFor(timeZone: string): Intl.DateTimeFormat {
+	const cached = formatters.get(timeZone);
+	if (cached) return cached;
+	const created = new Intl.DateTimeFormat('en-US', {
+		timeZone,
+		hourCycle: 'h23',
+		year: 'numeric',
+		month: '2-digit',
+		day: '2-digit',
+		hour: '2-digit',
+		minute: '2-digit',
+		second: '2-digit',
+	});
+	/* Bounded: a deployment holds a handful of workspace zones, and the cap
+	   keeps a long-lived process from carrying every zone it ever saw. */
+	if (formatters.size >= 32) formatters.clear();
+	formatters.set(timeZone, created);
+	return created;
+}
+
+function partsOf(
+	instant: number,
+	timeZone: string,
+): WallTime & { second: number } {
+	const parts = formatterFor(timeZone).formatToParts(new Date(instant));
+	const read = (type: string): number =>
+		Number(parts.find((part) => part.type === type)?.value ?? '0');
+	return {
+		year: read('year'),
+		month: read('month'),
+		day: read('day'),
+		hour: read('hour'),
+		minute: read('minute'),
+		second: read('second'),
+	};
+}
+
+function asUtc(wall: WallTime, second = 0): number {
+	return Date.UTC(
+		wall.year,
+		wall.month - 1,
+		wall.day,
+		wall.hour,
+		wall.minute,
+		second,
+	);
+}
+
+function offsetAt(instant: number, timeZone: string): number {
+	const parts = partsOf(instant, timeZone);
+	return asUtc(parts, parts.second) - Math.floor(instant / 1_000) * 1_000;
+}
+
+/**
+ * The UTC instant of a wall clock time, or null when the zone skips it because
+ * clocks moved forward. A wall time that occurs twice resolves to the first of
+ * the two, so a slot in a repeated hour fires once.
+ */
+export function instantOf(wall: WallTime, timeZone: string): number | null {
+	const wallMs = asUtc(wall);
+	/* The offsets a day either side bracket any transition near this wall time,
+	   so both readings of an ambiguous hour are candidates and a wall time the
+	   zone skipped produces none that verifies. */
+	const before = wallMs - offsetAt(wallMs - DAY_MS, timeZone);
+	const after = wallMs - offsetAt(wallMs + DAY_MS, timeZone);
+	let resolved: number | null = null;
+	for (const candidate of before === after ? [before] : [before, after]) {
+		if (resolved !== null && candidate >= resolved) continue;
+		const parts = partsOf(candidate, timeZone);
+		if (
+			parts.year === wall.year &&
+			parts.month === wall.month &&
+			parts.day === wall.day &&
+			parts.hour === wall.hour &&
+			parts.minute === wall.minute
+		) {
+			resolved = candidate;
+		}
+	}
+	return resolved;
+}
+
+function daysInMonth(year: number, month: number): number {
+	return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+function weekdayOf(wall: WallTime): number {
+	return new Date(Date.UTC(wall.year, wall.month - 1, wall.day)).getUTCDay();
+}
+
+function dayMatches(fields: CronFields, wall: WallTime): boolean {
+	const byDate = fields.daysOfMonth.includes(wall.day);
+	const byWeekday = fields.daysOfWeek.includes(weekdayOf(wall));
+	return fields.dayUnion ? byDate || byWeekday : byDate && byWeekday;
+}
+
+function nextMonth(wall: WallTime): void {
+	wall.month += 1;
+	if (wall.month > 12) {
+		wall.month = 1;
+		wall.year += 1;
+	}
+	wall.day = 1;
+	wall.hour = 0;
+	wall.minute = 0;
+}
+
+function nextDay(wall: WallTime): void {
+	wall.day += 1;
+	wall.hour = 0;
+	wall.minute = 0;
+	if (wall.day > daysInMonth(wall.year, wall.month)) {
+		wall.day = 1;
+		wall.month += 1;
+		if (wall.month > 12) {
+			wall.month = 1;
+			wall.year += 1;
+		}
+	}
+}
+
+function nextHour(wall: WallTime): void {
+	if (wall.hour >= 23) {
+		nextDay(wall);
+		return;
+	}
+	wall.hour += 1;
+	wall.minute = 0;
+}
+
+function nextMinute(wall: WallTime): void {
+	wall.minute += 1;
+	if (wall.minute > 59) {
+		wall.minute = 0;
+		nextHour(wall);
+	}
+}
+
+/**
+ * The first slot strictly after `after`, as a UTC instant. The search walks the
+ * workspace wall clock, so the daily hour stays the same across a daylight
+ * saving change; Intl is consulted only to convert the match it found. Returns
+ * null for an expression no real date matches, such as 30 February.
+ */
+export function nextCronSlot(
+	fields: CronFields,
+	after: number,
+	timeZone: string,
+): number | null {
+	const start = partsOf(after, timeZone);
+	const wall: WallTime = {
+		year: start.year,
+		month: start.month,
+		day: start.day,
+		hour: start.hour,
+		minute: start.minute,
+	};
+	nextMinute(wall);
+	let days = 0;
+	while (days <= MAX_SEARCH_DAYS) {
+		if (!fields.months.includes(wall.month)) {
+			days += daysInMonth(wall.year, wall.month) - wall.day + 1;
+			nextMonth(wall);
+			continue;
+		}
+		if (!dayMatches(fields, wall)) {
+			days += 1;
+			nextDay(wall);
+			continue;
+		}
+		if (!fields.hours.includes(wall.hour)) {
+			const previousDay = wall.day;
+			nextHour(wall);
+			if (wall.day !== previousDay) days += 1;
+			continue;
+		}
+		if (!fields.minutes.includes(wall.minute)) {
+			const previousDay = wall.day;
+			nextMinute(wall);
+			if (wall.day !== previousDay) days += 1;
+			continue;
+		}
+		const instant = instantOf(wall, timeZone);
+		/* A wall time the zone skipped has no instant, and one inside a repeated
+		   hour can resolve behind `after`; both move on to the next candidate so
+		   a slot is never fired twice and never replayed. */
+		if (instant !== null && instant > after) return instant;
+		const previousDay = wall.day;
+		nextMinute(wall);
+		if (wall.day !== previousDay) days += 1;
+	}
+	return null;
+}

package/modules/automations/src/domain/time-zone.ts

@@ -0,0 +1,61 @@
+import { TENANT_TIME_ZONE_SETTING } from '@flowdular/sdk/contracts';
+import {
+	ModuleSettingsError,
+	type ModuleSettingsRuntime,
+} from '@flowdular/sdk/kernel';
+
+/* Declared and owned by system.core as a shared tenant setting. automations
+   reads it through the settings runtime, never through system.core storage, and
+   addresses it by the id, key and fallback the shared contract names. */
+export const TENANT_TIME_ZONE_MODULE_ID = TENANT_TIME_ZONE_SETTING.moduleId;
+export const TENANT_TIME_ZONE_KEY = TENANT_TIME_ZONE_SETTING.key;
+export const DEFAULT_TIME_ZONE = TENANT_TIME_ZONE_SETTING.defaultValue;
+
+/* Spellings this runtime accepted, lower-cased so every spelling of a zone
+   shares one entry, and capped like the formatter cache in cron.ts so a
+   long-lived process cannot carry every value it was ever handed. */
+const MAX_SUPPORTED_ZONES = 32;
+const supported = new Set<string>([DEFAULT_TIME_ZONE.toLowerCase()]);
+
+function isSupported(value: string): boolean {
+	const spelling = value.toLowerCase();
+	if (supported.has(spelling)) return true;
+	try {
+		new Intl.DateTimeFormat('en-US', { timeZone: value });
+	} catch {
+		return false;
+	}
+	if (supported.size >= MAX_SUPPORTED_ZONES) supported.clear();
+	supported.add(spelling);
+	return true;
+}
+
+/**
+ * The workspace zone a cron slot is computed in. A workspace that set nothing,
+ * a deployment without system.core, and a stored name this runtime does not
+ * know all resolve to UTC, because the scheduler must keep firing either way.
+ */
+export function tenantTimeZone(
+	settings: ModuleSettingsRuntime,
+	tenantId: string,
+): string {
+	let stored: string;
+	try {
+		stored = settings.get<string>(
+			tenantId,
+			TENANT_TIME_ZONE_MODULE_ID,
+			TENANT_TIME_ZONE_KEY,
+		);
+	} catch (error) {
+		/* Absent system.core is a deployment shape; an unprimed workspace is a
+		   caller defect and stays loud. */
+		if (
+			error instanceof ModuleSettingsError &&
+			error.code === 'SETTINGS_NOT_DECLARED'
+		) {
+			return DEFAULT_TIME_ZONE;
+		}
+		throw error;
+	}
+	return isSupported(stored) ? stored : DEFAULT_TIME_ZONE;
+}

package/modules/automations/src/platform.ts

@@ -15,8 +15,16 @@ import {
 	AUTOMATION_TARGETS_CAPABILITY,
 	createAutomationExecutionCapability,
 	createAutomationTargetRegistry,
+	createAutomationWorkflowActionTools,
+	registerWorkflowAutomationTarget,
 } from './server/index.ts';
 import { registerScheduleVariableSource } from './domain/variables.ts';
+import {
+	tenantTimeZone,
+	TENANT_TIME_ZONE_KEY,
+	TENANT_TIME_ZONE_MODULE_ID,
+} from './domain/time-zone.ts';
+import { automationsDataClasses } from './services/data-classes.ts';
 import {
 	automationsModuleSettingsFromEnvironment,
 	automationsSchedulerPollMs,
@@ -27,6 +35,7 @@ export function createServerComposition(
 ): PlatformServerComposition {
 	const targets = createAutomationTargetRegistry();
 	context.capabilities.register(AUTOMATION_TARGETS_CAPABILITY, targets);
+	registerWorkflowAutomationTarget(targets, context.capabilities);
 	const runQueue = () => {
 		const queue = context.capabilities.get<AgentRunQueue>(
 			AGENT_RUN_QUEUE_CAPABILITY,
@@ -53,21 +62,46 @@ export function createServerComposition(
 					: 'preview',
 		schedulerPollMs: () =>
 			automationsSchedulerPollMs(context.settings, context.environment),
+		timeZone: (tenantId) => tenantTimeZone(context.settings, tenantId),
+		primeTenant: (tenantId) => context.settings.prime(tenantId),
 		variables: registerScheduleVariableSource(
 			platformVariableRegistry(context.capabilities),
 			runQueue,
 		),
 		targets,
 	});
-	context.capabilities.register(
-		AUTOMATION_EXECUTION_CAPABILITY,
-		createAutomationExecutionCapability(() => runtime.scheduleService()),
+	const execution = createAutomationExecutionCapability(() =>
+		runtime.scheduleService(),
+	);
+	context.capabilities.register(AUTOMATION_EXECUTION_CAPABILITY, execution);
+	context.agentTools.register(
+		createAutomationWorkflowActionTools(() => execution),
+	);
+	/* The export runs here, on this module's own leases and under its own tenant
+	   transaction; the platform only holds the declaration. */
+	context.dataClasses.declare(
+		automationsDataClasses(() => runtime.repository()),
 	);
+	/* The workspace zone is the real signal for when a cron slot lands, so a
+	   change to it moves the pending slots of that workspace at once instead of
+	   waiting for each schedule to fire in the zone it no longer uses. */
+	const stopWatchingTimeZone = context.settings.onChange((change) => {
+		if (
+			change.moduleId !== TENANT_TIME_ZONE_MODULE_ID ||
+			change.key !== TENANT_TIME_ZONE_KEY
+		) {
+			return;
+		}
+		runtime.retimeSchedules(change.tenantId);
+	});
 	return {
 		routes: createAutomationsRoutes(context.auth, runtime),
 		settings: automationsModuleSettingsFromEnvironment(context.environment),
 		start: () => runtime.start(),
 		stop: () => runtime.quiesce(),
-		dispose: () => runtime.dispose(),
+		dispose: async () => {
+			stopWatchingTimeZone();
+			await runtime.dispose();
+		},
 	};
 }

package/modules/automations/src/server/index.ts

@@ -37,3 +37,14 @@ export {
 	automationsModuleSettingsFromEnvironment,
 	automationsSchedulerPollMs,
 } from '../settings.ts';
+export {
+	createWorkflowAutomationTargetAdapter,
+	registerWorkflowAutomationTarget,
+	WorkflowAutomationTargetError,
+} from './workflow-target.ts';
+export {
+	AUTOMATION_SCHEDULE_ACTION_ID,
+	createAutomationWorkflowActionTools,
+	WORKFLOW_DISPATCHABLE_TARGET_KINDS,
+	WorkflowAutomationActionError,
+} from './workflow-tools.ts';

package/modules/automations/src/server/runtime.ts

@@ -9,6 +9,7 @@ import {
 } from '@flowdular/sdk/database';
 import type { PlatformVariableRegistry } from '@flowdular/sdk/kernel';
 import type { AgentRunQueue } from '@flowdular/sdk/modules/agents/server';
+import type { JobRunner } from '@flowdular/sdk/server';
 import {
 	createAutomationTargetRegistry,
 	type AutomationTargetRegistry,
@@ -18,6 +19,7 @@ import type {
 	AutomationAuditVerification,
 } from '../domain/types.ts';
 import type { AutomationsRepository } from '../services/repository.ts';
+import { createAutomationScheduleRunner } from '../services/schedule-runner.ts';
 import { AutomationScheduleService } from '../services/schedule-service.ts';
 import {
 	secretVaultFromEnvironment,
@@ -40,6 +42,10 @@ export interface AutomationsRuntimeOptions {
 	readonly workspaceRoot?: string;
 	readonly secretVault?: SecretVault;
 	readonly schedulerPollMs?: number | (() => number);
+	/** Reads the workspace zone a cron slot is computed in, live per call. */
+	readonly timeZone?: (tenantId: string) => string;
+	/** Loads a workspace's settings before the scheduler reads its zone. */
+	readonly primeTenant?: (tenantId: string) => Promise<void>;
 	readonly repository?: AutomationsRepository;
 	readonly variables?: PlatformVariableRegistry;
 	readonly targets?: AutomationTargetRegistry;
@@ -53,6 +59,14 @@ export interface AutomationsRuntime {
 		limit: number,
 	): Promise<readonly AutomationAuditEvent[]>;
 	verifyAudit(tenantId: string): Promise<AutomationAuditVerification>;
+	/** Opens the repository, for the data class operations the module owns. */
+	repository(): Promise<AutomationsRepository>;
+	/**
+	 * Re-times this workspace's pending cron slots after its zone changed. The
+	 * work is queued behind the previous one and drained by `quiesce`, so the
+	 * settings write that triggered it never waits for the database.
+	 */
+	retimeSchedules(tenantId: string): void;
 	start(): void;
 	stop(): void;
 	quiesce(): Promise<void>;
@@ -130,8 +144,8 @@ export function createAutomationsRuntime(
 	const targets = options.targets ?? createAutomationTargetRegistry();
 	let schedules: AutomationScheduleService | undefined;
 	let triggers: AutomationTriggerService | undefined;
-	let poll: ReturnType<typeof setInterval> | undefined;
-	let tickInFlight: Promise<void> | undefined;
+	let jobs: JobRunner | undefined;
+	let retimeInFlight: Promise<void> = Promise.resolve();
 	const resolutionController = new AbortController();
 	let disposed = false;
 	const scheduleService = async () =>
@@ -142,6 +156,8 @@ export function createAutomationsRuntime(
 			resolutionController.signal,
 			options.variables,
 			targets,
+			options.timeZone,
+			options.primeTenant,
 		));
 	const triggerService = async () =>
 		(triggers ??= new AutomationTriggerService(
@@ -152,30 +168,42 @@ export function createAutomationsRuntime(
 			undefined,
 			targets,
 		));
-	const tick = () => {
-		if (disposed || tickInFlight) return;
-		const pending = scheduleService()
-			.then((service) => service.tick())
+	/* The platform runner owns the loop: the interval and its unref, the guard
+	   against overlapping passes, the bound on claims, the isolation of one
+	   schedule from the next and the drain. This module keeps its cross-tenant
+	   poll, the re-read under the workspace and the slot advance. The interval is
+	   a live setting read when the loop starts, so the runner is built there
+	   rather than while the composition is assembled. */
+	const runner = (): JobRunner =>
+		(jobs ??= createAutomationScheduleRunner({
+			repository: repositoryInstance,
+			service: scheduleService,
+			intervalMs:
+				typeof options.schedulerPollMs === 'function'
+					? options.schedulerPollMs()
+					: (options.schedulerPollMs ?? 30_000),
+		}));
+	const retimeSchedules = (tenantId: string) => {
+		if (disposed) return;
+		retimeInFlight = retimeInFlight
+			.then(() => scheduleService())
+			.then((service) => service.retime(tenantId))
 			.then(() => undefined)
 			.catch((error: unknown) => {
 				console.error(
-					'[automations] scheduler tick failed:',
+					'[automations] schedule re-timing failed:',
 					error instanceof Error ? error.message : error,
 				);
-			})
-			.finally(() => {
-				if (tickInFlight === pending) tickInFlight = undefined;
 			});
-		tickInFlight = pending;
 	};
 	const stop = () => {
-		if (poll) clearInterval(poll);
-		poll = undefined;
+		jobs?.stop();
 	};
 	const quiesce = async () => {
 		stop();
 		resolutionController.abort('automations-runtime-stopped');
-		await tickInFlight;
+		await jobs?.quiesce();
+		await retimeInFlight;
 	};
 	return {
 		scheduleService,
@@ -187,16 +215,11 @@ export function createAutomationsRuntime(
 			),
 		verifyAudit: async (tenantId) =>
 			(await repositoryInstance()).verifyAuditChain(tenantId),
+		repository: repositoryInstance,
+		retimeSchedules,
 		start() {
 			if (disposed) return;
-			if (poll) return;
-			tick();
-			const pollMs =
-				typeof options.schedulerPollMs === 'function'
-					? options.schedulerPollMs()
-					: (options.schedulerPollMs ?? 30_000);
-			poll = setInterval(tick, pollMs);
-			poll.unref?.();
+			runner().start();
 		},
 		stop,
 		quiesce,
@@ -204,6 +227,7 @@ export function createAutomationsRuntime(
 			if (disposed) return;
 			disposed = true;
 			await quiesce();
+			await jobs?.dispose();
 			/* An open still in flight would assign its leases after this read, so
 			   settle it first; a failed open must not surface as an unhandled
 			   rejection during teardown. */