@swirls/looms 0.3.0 → 0.5.0

package/dist/schedule/effects.js

@@ -0,0 +1,244 @@
+import { Clock, Data, Effect, Schema } from 'effect';
+import { DEFAULT_DEFINITION_VERSION, RunLauncherTag } from '@swirls/looms/core';
+import { ScheduleMisfireSchema, ScheduleOverlapSchema, } from './definitions.js';
+import { ScheduleDefinitionsTag } from './definitions-store.js';
+import { scheduleModule } from './scope.js';
+import { MISFIRE_GRACE_MS, ScheduleSpecSchema, nextFireAt } from './specs.js';
+const NullableFinite = Schema.NullOr(Schema.Finite);
+const NullableJson = Schema.NullOr(Schema.Json);
+const PlanInputSchema = Schema.Struct({
+    spec: ScheduleSpecSchema,
+    generation: Schema.Finite,
+    fireCount: Schema.Finite,
+    startAt: NullableFinite,
+    endAt: NullableFinite,
+    maxFires: NullableFinite,
+    misfire: ScheduleMisfireSchema,
+});
+const FireInputSchema = Schema.Struct({
+    definitionName: Schema.String,
+    definitionVersion: Schema.String,
+    spec: ScheduleSpecSchema,
+    generation: Schema.Finite,
+    at: Schema.Finite,
+    nextAt: NullableFinite,
+    misfire: ScheduleMisfireSchema,
+    overlap: ScheduleOverlapSchema,
+    storedInput: NullableJson,
+    fireCount: Schema.Finite,
+    startAt: NullableFinite,
+    endAt: NullableFinite,
+    maxFires: NullableFinite,
+    lastFiredRunId: Schema.NullOr(Schema.String),
+    manual: Schema.Boolean,
+    triggerId: Schema.optional(Schema.String),
+});
+const RETRY = { maxAttempts: 5, backoffMs: 1_000, maxBackoffMs: 60_000 };
+class ScheduleEffectError extends Data.TaggedError('ScheduleEffectError') {
+}
+export const planEffect = scheduleModule.effect({
+    type: 'schedule.plan',
+    input: PlanInputSchema,
+    retry: RETRY,
+    execute: (input, ctx) => Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+        const nextAt = planNextAt(input, now);
+        return [
+            {
+                type: 'schedule.planned',
+                payload: { nextAt, generation: input.generation, spec: input.spec },
+                threadId: ctx.threadId,
+            },
+        ];
+    }),
+});
+export const fireEffect = scheduleModule.effect({
+    type: 'schedule.fire',
+    input: FireInputSchema,
+    retry: RETRY,
+    execute: (input, ctx) => Effect.gen(function* () {
+        const definitions = yield* ScheduleDefinitionsTag;
+        const launcher = yield* RunLauncherTag;
+        const now = yield* Clock.currentTimeMillis;
+        const definition = yield* definitions.resolve(input.definitionName, input.definitionVersion);
+        if (!definition) {
+            return yield* new ScheduleEffectError({
+                message: `Unknown schedule definition "${input.definitionName}@${input.definitionVersion}"`,
+            });
+        }
+        if (!input.manual && input.misfire === 'skip' && now > input.at + MISFIRE_GRACE_MS) {
+            return skipped(ctx.threadId, input, input.at, 'misfire', scheduledNext(input, now, now));
+        }
+        const fireCtx = {
+            at: input.manual ? now : input.at,
+            input: input.storedInput,
+            runId: ctx.runId,
+            manual: input.manual,
+        };
+        const gate = yield* resolveBeforeFire(definition, fireCtx);
+        if (gate !== 'fire') {
+            return skipped(ctx.threadId, input, fireCtx.at, gate.skip, input.manual ? input.nextAt : scheduledNext(input, input.at, now));
+        }
+        if (input.overlap === 'skip' && input.lastFiredRunId) {
+            const previous = yield* launcher.status(input.lastFiredRunId);
+            if (previous &&
+                previous.status !== 'completed' &&
+                previous.status !== 'failed' &&
+                previous.status !== 'cancelled') {
+                return skipped(ctx.threadId, input, fireCtx.at, 'overlap', input.manual ? input.nextAt : scheduledNext(input, input.at, now));
+            }
+        }
+        const produced = yield* resolveFireInput(definition, fireCtx);
+        const targetRunId = input.manual && input.triggerId
+            ? `${ctx.runId}:manual:${input.triggerId}`
+            : `${ctx.runId}:fire:${input.at}`;
+        yield* launcher.launch({
+            runId: targetRunId,
+            kind: definition.target.kind,
+            definitionName: definition.target.name,
+            definitionVersion: definition.target.version ?? DEFAULT_DEFINITION_VERSION,
+            input: produced,
+            idempotencyKey: targetRunId,
+        });
+        const nextFireCount = input.fireCount + 1;
+        const nextAt = input.manual
+            ? input.maxFires !== null && nextFireCount >= input.maxFires
+                ? null
+                : input.nextAt
+            : scheduledNext(input, input.at, now, nextFireCount);
+        const payload = {
+            at: fireCtx.at,
+            runId: targetRunId,
+            nextAt,
+            generation: input.generation,
+            manual: input.manual,
+        };
+        return [
+            {
+                type: 'schedule.fired',
+                payload: input.triggerId === undefined ? payload : { ...payload, triggerId: input.triggerId },
+                threadId: ctx.threadId,
+            },
+        ];
+    }),
+});
+export function planInputOf(state) {
+    return {
+        spec: state.spec,
+        generation: state.generation,
+        fireCount: state.fireCount,
+        startAt: state.startAt,
+        endAt: state.endAt,
+        maxFires: state.maxFires,
+        misfire: state.misfire,
+    };
+}
+export function fireInputOf(state, at, manual, triggerId) {
+    const input = {
+        definitionName: state.definitionName,
+        definitionVersion: state.definitionVersion,
+        spec: state.spec,
+        generation: state.generation,
+        at,
+        nextAt: state.nextAt,
+        misfire: state.misfire,
+        overlap: state.overlap,
+        storedInput: state.input,
+        fireCount: state.fireCount,
+        startAt: state.startAt,
+        endAt: state.endAt,
+        maxFires: state.maxFires,
+        lastFiredRunId: state.lastFiredRunId,
+        manual,
+    };
+    if (triggerId === undefined) {
+        return input;
+    }
+    return { ...input, triggerId };
+}
+function planNextAt(input, now) {
+    if (input.maxFires !== null && input.fireCount >= input.maxFires) {
+        return null;
+    }
+    const spec = input.spec;
+    let next;
+    if (spec.type === 'once') {
+        if (input.startAt !== null && spec.at < input.startAt) {
+            next = null;
+        }
+        else if (spec.at > now || input.misfire === 'fire-once') {
+            next = spec.at;
+        }
+        else {
+            next = null;
+        }
+    }
+    else {
+        const notBefore = input.startAt !== null ? Math.max(now, input.startAt) : now;
+        next = nextFireAt(spec, notBefore - 1);
+        if (next !== null && next < notBefore) {
+            next = nextFireAt(spec, notBefore);
+        }
+    }
+    return withinEndAt(next, input.endAt);
+}
+function scheduledNext(input, after, now, firesAfter = input.fireCount) {
+    if (input.maxFires !== null && firesAfter >= input.maxFires) {
+        return null;
+    }
+    const floor = input.startAt !== null ? Math.max(now, input.startAt) : now;
+    let next = nextFireAt(input.spec, after);
+    if (next !== null && next <= floor) {
+        next = nextFireAt(input.spec, floor);
+    }
+    return withinEndAt(next, input.endAt);
+}
+function withinEndAt(next, endAt) {
+    if (next !== null && endAt !== null && next > endAt) {
+        return null;
+    }
+    return next;
+}
+function skipped(threadId, input, at, reason, nextAt) {
+    const payload = {
+        at,
+        reason,
+        nextAt,
+        generation: input.generation,
+        manual: input.manual,
+        triggerId: input.triggerId,
+    };
+    return [
+        {
+            type: 'schedule.skipped',
+            payload,
+            threadId,
+        },
+    ];
+}
+function resolveBeforeFire(definition, ctx) {
+    const decide = definition.beforeFire;
+    if (!decide) {
+        return Effect.succeed('fire');
+    }
+    return Effect.tryPromise({
+        try: () => Promise.resolve(decide(ctx)),
+        catch: (cause) => new ScheduleEffectError({
+            message: cause instanceof Error ? cause.message : 'beforeFire failed',
+            cause,
+        }),
+    });
+}
+function resolveFireInput(definition, ctx) {
+    const produce = definition.fireInput;
+    if (!produce) {
+        return Effect.succeed(ctx.input);
+    }
+    return Effect.tryPromise({
+        try: () => Promise.resolve(produce(ctx)),
+        catch: (cause) => new ScheduleEffectError({
+            message: cause instanceof Error ? cause.message : 'schedule input failed',
+            cause,
+        }),
+    });
+}

package/dist/schedule/ensure.d.ts

@@ -0,0 +1,55 @@
+import { Schema } from 'effect';
+import { type EventInput, type JsonValue, type LaunchRunArgs, type RunState } from '@swirls/looms/core';
+import type { ScheduleDefinition } from './definitions';
+import { type ScheduleSpec } from './specs';
+declare const ScheduleSnapshotSchema: Schema.Struct<{
+    readonly spec: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"cron">;
+        readonly expr: Schema.String;
+        readonly tz: Schema.optional<Schema.String>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"every">;
+        readonly everyMs: Schema.Finite;
+        readonly anchor: Schema.optional<Schema.Finite>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"once">;
+        readonly at: Schema.Finite;
+    }>]>>;
+    readonly input: Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly endAt: Schema.NullOr<Schema.Finite>;
+    readonly maxFires: Schema.NullOr<Schema.Finite>;
+    readonly paused: Schema.Boolean;
+    readonly retired: Schema.Boolean;
+    readonly generation: Schema.Finite;
+    readonly definitionName: Schema.String;
+    readonly definitionVersion: Schema.String;
+}>;
+export type ScheduleSnapshot = Schema.Schema.Type<typeof ScheduleSnapshotSchema>;
+/**
+ * The three operations a deploy reconciler needs. `createLooms` already has them.
+ * On Cloudflare, use `durableObjectScheduleHost`.
+ */
+export interface ScheduleHost {
+    startRun(args: LaunchRunArgs): Promise<{
+        readonly runId: string;
+    }>;
+    signal(runId: string, events: ReadonlyArray<EventInput>): Promise<RunState>;
+    getRun(runId: string): Promise<RunState>;
+}
+export interface ScheduleEnsureConfig {
+    readonly spec?: ScheduleSpec;
+    readonly input?: JsonValue | null;
+    readonly startAt?: number | null;
+    readonly endAt?: number | null;
+    readonly maxFires?: number | null;
+}
+export type ScheduleEnsureResult = 'started' | 'updated' | 'resumed' | 'unchanged';
+/**
+ * Start a schedule, or bring an existing one in line with `config`.
+ * A retired schedule is resumed in place. A cancelled, completed, or failed one throws:
+ * those run ids cannot be reused.
+ */
+export declare function ensureSchedule(host: ScheduleHost, definition: ScheduleDefinition, runId: string, config?: ScheduleEnsureConfig): Promise<ScheduleEnsureResult>;
+/** The schedule thread's config, or null when the run has not started. */
+export declare function readSchedule(state: RunState): ScheduleSnapshot | null;
+export {};

package/dist/schedule/ensure.js

@@ -0,0 +1,109 @@
+import { Option, Schema } from 'effect';
+import { stringifyJson, } from '@swirls/looms/core';
+import { resume, update } from './signals.js';
+import { ScheduleSpecSchema } from './specs.js';
+const ScheduleSnapshotSchema = Schema.Struct({
+    spec: Schema.NullOr(ScheduleSpecSchema),
+    input: Schema.NullOr(Schema.Json),
+    endAt: Schema.NullOr(Schema.Finite),
+    maxFires: Schema.NullOr(Schema.Finite),
+    paused: Schema.Boolean,
+    retired: Schema.Boolean,
+    generation: Schema.Finite,
+    definitionName: Schema.String,
+    definitionVersion: Schema.String,
+});
+const decodeSnapshot = Schema.decodeUnknownOption(ScheduleSnapshotSchema);
+/**
+ * Start a schedule, or bring an existing one in line with `config`.
+ * A retired schedule is resumed in place. A cancelled, completed, or failed one throws:
+ * those run ids cannot be reused.
+ */
+export function ensureSchedule(host, definition, runId, config = {}) {
+    return host.getRun(runId).then((state) => {
+        const current = readSchedule(state);
+        if (!current) {
+            return host
+                .startRun({
+                runId,
+                kind: definition.kind,
+                definitionName: definition.name,
+                definitionVersion: definition.version,
+                input: startInput(config),
+            })
+                .then(() => 'started');
+        }
+        if (state.status !== 'running') {
+            throw new Error(`Schedule "${runId}" is ${state.status}; cancelled schedules need a new runId`);
+        }
+        const desired = {
+            spec: config.spec ?? definition.spec,
+            input: config.input ?? null,
+            endAt: config.endAt ?? null,
+            maxFires: config.maxFires ?? null,
+            definitionName: definition.name,
+            definitionVersion: definition.version,
+        };
+        const changed = stringifyJson(current.spec) !== stringifyJson(desired.spec) ||
+            stringifyJson(current.input) !== stringifyJson(desired.input) ||
+            current.endAt !== desired.endAt ||
+            current.maxFires !== desired.maxFires ||
+            current.definitionName !== desired.definitionName ||
+            current.definitionVersion !== desired.definitionVersion;
+        const events = [];
+        if (changed) {
+            events.push(update({
+                spec: desired.spec,
+                input: desired.input,
+                endAt: desired.endAt,
+                maxFires: desired.maxFires,
+                definitionName: desired.definitionName,
+                definitionVersion: desired.definitionVersion,
+            }));
+        }
+        if (current.paused || current.retired) {
+            events.push(resume());
+        }
+        if (events.length === 0) {
+            return 'unchanged';
+        }
+        return host
+            .signal(runId, events)
+            .then(() => (changed ? 'updated' : 'resumed'));
+    });
+}
+/** The schedule thread's config, or null when the run has not started. */
+export function readSchedule(state) {
+    const threadId = state.rootThreadId;
+    if (!threadId) {
+        return null;
+    }
+    const thread = state.threads[threadId];
+    if (!thread) {
+        return null;
+    }
+    const decoded = decodeSnapshot(thread.state);
+    if (Option.isNone(decoded)) {
+        throw new Error(`Schedule "${state.runId}" state is unreadable`);
+    }
+    return decoded.value;
+}
+function startInput(config) {
+    const input = {};
+    if (config.spec !== undefined) {
+        input.spec = config.spec;
+    }
+    if (config.input !== undefined) {
+        input.input = config.input;
+    }
+    if (config.startAt !== undefined) {
+        input.startAt = config.startAt;
+    }
+    if (config.endAt !== undefined) {
+        input.endAt = config.endAt;
+    }
+    if (config.maxFires !== undefined) {
+        input.maxFires = config.maxFires;
+    }
+    return input;
+}

package/dist/schedule/events.d.ts

@@ -0,0 +1,116 @@
+import { Schema } from 'effect';
+export declare const SchedulePlannedPayloadSchema: Schema.Struct<{
+    readonly nextAt: Schema.NullOr<Schema.Finite>;
+    readonly generation: Schema.Finite;
+    readonly spec: Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"cron">;
+        readonly expr: Schema.String;
+        readonly tz: Schema.optional<Schema.String>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"every">;
+        readonly everyMs: Schema.Finite;
+        readonly anchor: Schema.optional<Schema.Finite>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"once">;
+        readonly at: Schema.Finite;
+    }>]>;
+}>;
+export declare const ScheduleFiredPayloadSchema: Schema.Struct<{
+    readonly at: Schema.Finite;
+    readonly runId: Schema.String;
+    readonly nextAt: Schema.NullOr<Schema.Finite>;
+    readonly generation: Schema.Finite;
+    readonly manual: Schema.Boolean;
+    readonly triggerId: Schema.optional<Schema.String>;
+}>;
+export declare const ScheduleSkippedPayloadSchema: Schema.Struct<{
+    readonly at: Schema.Finite;
+    readonly reason: Schema.String;
+    readonly nextAt: Schema.NullOr<Schema.Finite>;
+    readonly generation: Schema.Finite;
+    readonly manual: Schema.Boolean;
+    readonly triggerId: Schema.optional<Schema.String>;
+}>;
+export declare const ScheduleUpdatedPayloadSchema: Schema.Struct<{
+    readonly spec: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"cron">;
+        readonly expr: Schema.String;
+        readonly tz: Schema.optional<Schema.String>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"every">;
+        readonly everyMs: Schema.Finite;
+        readonly anchor: Schema.optional<Schema.Finite>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"once">;
+        readonly at: Schema.Finite;
+    }>]>>;
+    readonly input: Schema.optional<Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly endAt: Schema.optional<Schema.NullOr<Schema.Finite>>;
+    readonly maxFires: Schema.optional<Schema.NullOr<Schema.Finite>>;
+    readonly definitionName: Schema.optional<Schema.String>;
+    readonly definitionVersion: Schema.optional<Schema.String>;
+}>;
+export declare const ScheduleEmptyPayloadSchema: Schema.Struct<{}>;
+export declare const ScheduleRejectedPayloadSchema: Schema.Struct<{
+    readonly reason: Schema.String;
+}>;
+export declare const scheduleCatalog: import("@swirls/looms/core").EventCatalog<"schedule", {
+    planned: Schema.Struct<{
+        readonly nextAt: Schema.NullOr<Schema.Finite>;
+        readonly generation: Schema.Finite;
+        readonly spec: Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"cron">;
+            readonly expr: Schema.String;
+            readonly tz: Schema.optional<Schema.String>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"every">;
+            readonly everyMs: Schema.Finite;
+            readonly anchor: Schema.optional<Schema.Finite>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"once">;
+            readonly at: Schema.Finite;
+        }>]>;
+    }>;
+    fired: Schema.Struct<{
+        readonly at: Schema.Finite;
+        readonly runId: Schema.String;
+        readonly nextAt: Schema.NullOr<Schema.Finite>;
+        readonly generation: Schema.Finite;
+        readonly manual: Schema.Boolean;
+        readonly triggerId: Schema.optional<Schema.String>;
+    }>;
+    skipped: Schema.Struct<{
+        readonly at: Schema.Finite;
+        readonly reason: Schema.String;
+        readonly nextAt: Schema.NullOr<Schema.Finite>;
+        readonly generation: Schema.Finite;
+        readonly manual: Schema.Boolean;
+        readonly triggerId: Schema.optional<Schema.String>;
+    }>;
+    updated: Schema.Struct<{
+        readonly spec: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"cron">;
+            readonly expr: Schema.String;
+            readonly tz: Schema.optional<Schema.String>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"every">;
+            readonly everyMs: Schema.Finite;
+            readonly anchor: Schema.optional<Schema.Finite>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"once">;
+            readonly at: Schema.Finite;
+        }>]>>;
+        readonly input: Schema.optional<Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly endAt: Schema.optional<Schema.NullOr<Schema.Finite>>;
+        readonly maxFires: Schema.optional<Schema.NullOr<Schema.Finite>>;
+        readonly definitionName: Schema.optional<Schema.String>;
+        readonly definitionVersion: Schema.optional<Schema.String>;
+    }>;
+    paused: Schema.Struct<{}>;
+    resumed: Schema.Struct<{}>;
+    retired: Schema.Struct<{}>;
+    triggered: Schema.Struct<{}>;
+    rejected: Schema.Struct<{
+        readonly reason: Schema.String;
+    }>;
+}>;

package/dist/schedule/events.js

@@ -0,0 +1,49 @@
+import { Schema } from 'effect';
+import { defineEventCatalog } from '@swirls/looms/core';
+import { ScheduleSpecSchema } from './specs.js';
+const GenerationSchema = Schema.Finite;
+const NextAtSchema = Schema.NullOr(Schema.Finite);
+export const SchedulePlannedPayloadSchema = Schema.Struct({
+    nextAt: NextAtSchema,
+    generation: GenerationSchema,
+    spec: ScheduleSpecSchema,
+});
+export const ScheduleFiredPayloadSchema = Schema.Struct({
+    at: Schema.Finite,
+    runId: Schema.String,
+    nextAt: NextAtSchema,
+    generation: GenerationSchema,
+    manual: Schema.Boolean,
+    triggerId: Schema.optional(Schema.String),
+});
+export const ScheduleSkippedPayloadSchema = Schema.Struct({
+    at: Schema.Finite,
+    reason: Schema.String,
+    nextAt: NextAtSchema,
+    generation: GenerationSchema,
+    manual: Schema.Boolean,
+    triggerId: Schema.optional(Schema.String),
+});
+export const ScheduleUpdatedPayloadSchema = Schema.Struct({
+    spec: Schema.optional(ScheduleSpecSchema),
+    input: Schema.optional(Schema.NullOr(Schema.Json)),
+    endAt: Schema.optional(Schema.NullOr(Schema.Finite)),
+    maxFires: Schema.optional(Schema.NullOr(Schema.Finite)),
+    definitionName: Schema.optional(Schema.String),
+    definitionVersion: Schema.optional(Schema.String),
+});
+export const ScheduleEmptyPayloadSchema = Schema.Struct({});
+export const ScheduleRejectedPayloadSchema = Schema.Struct({
+    reason: Schema.String,
+});
+export const scheduleCatalog = defineEventCatalog('schedule', {
+    planned: SchedulePlannedPayloadSchema,
+    fired: ScheduleFiredPayloadSchema,
+    skipped: ScheduleSkippedPayloadSchema,
+    updated: ScheduleUpdatedPayloadSchema,
+    paused: ScheduleEmptyPayloadSchema,
+    resumed: ScheduleEmptyPayloadSchema,
+    retired: ScheduleEmptyPayloadSchema,
+    triggered: ScheduleEmptyPayloadSchema,
+    rejected: ScheduleRejectedPayloadSchema,
+});

package/dist/schedule/index.d.ts

@@ -0,0 +1,11 @@
+export * from './definitions';
+export * from './definitions-store';
+export * from './effects';
+export * from './ensure';
+export * from './events';
+export * from './module';
+export * from './projections';
+export * from './scope';
+export * from './signals';
+export * from './specs';
+export * from './threads';

package/dist/schedule/index.js

@@ -0,0 +1,11 @@
+export * from './definitions.js';
+export * from './definitions-store.js';
+export * from './effects.js';
+export * from './ensure.js';
+export * from './events.js';
+export * from './module.js';
+export * from './projections.js';
+export * from './scope.js';
+export * from './signals.js';
+export * from './specs.js';
+export * from './threads.js';