sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workers/ CronEventSource.ts

import type * as cf from "@cloudflare/workers-types";
import * as Namespace from "alchemy/Namespace";
import type { FunctionContext } from "alchemy/Runtime/Function";
import { RuntimeContext } from "alchemy/RuntimeContext";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import { isWorkerEvent, Worker } from "./Worker.ts";

/**
 * Subscribe to Cloudflare Cron Triggers with an Effect handler.
 *
 * A single call wires both pieces of a scheduled Worker:
 *
 * - **Deploy-time**: attaches the cron expression to the host Worker's
 *   Cron Triggers.
 * - **Runtime**: registers a `scheduled` listener that runs your Effect on
 *   each fire. The handler receives Cloudflare's `ScheduledController`,
 *   which has three members:
 *   - `controller.scheduledTime` — the fire time in milliseconds since the
 *     Unix epoch.
 *   - `controller.cron` — the cron expression that fired.
 *   - `controller.noRetry()` — opts the invocation out of Cloudflare's
 *     retry-on-failure. Only meaningful when the scheduled invocation can
 *     actually fail — see the failure & retry section below.
 *
 *   Each member has its own section below with an Effect example first and
 *   an async example second.
 *
 * Requires `CronEventSourceLive` provided on the Worker's Effect.
 *
 * **Failure & retry semantics**: a failing handler won't crash the Worker —
 * the event source catches the failure and moves on. That also means
 * Cloudflare never observes a failed invocation, so its platform-level
 * retry (and `controller.noRetry()`) never comes into play here. Express
 * retry declaratively with `Effect.retry` inside the handler, and log or
 * report errors if you need visibility into failed runs. In async Workers
 * the opposite holds: a `scheduled` handler that throws (or rejects) marks
 * the invocation failed and Cloudflare may retry it — call
 * `controller.noRetry()` before rethrowing to suppress that.
 *
 * Async (non-Effect) Workers don't use `cron` — they attach schedules with
 * the Worker's `crons` prop and export their own `scheduled` handler from
 * the entry module (each section below includes the async variant). Pass
 * `crons: []` to remove all Cron Triggers from a Worker.
 *
 *
 * ### Declare a schedule
 * **Example:** Effect-native Worker (recommended)
 * ```typescript
 * import * as Cloudflare from "@alchemy.run/cloudflare";
 * import * as Effect from "effect/Effect";
 * import * as HttpServerResponse from "effect/http/HttpServerResponse";
 *
 * export default Cloudflare.Worker(
 *   "Worker",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     yield* Cloudflare.Workers.cron("0 12 * * *", () =>
 *       Effect.log("cron fired"),
 *     );
 *
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("ok")),
 *     };
 *   }).pipe(Effect.provide(Cloudflare.Workers.CronEventSourceLive)),
 * );
 * ```
 *
 * **Example:** Async Worker — `crons` prop + exported `scheduled` handler
 * ```typescript
 * // alchemy.run.ts — attach the cron expressions at deploy time
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   crons: ["0 12 * * *"],
 * });
 *
 * // src/worker.ts — the entry module handles the fires itself
 * export default {
 *   async scheduled(controller: ScheduledController) {
 *     console.log("cron fired");
 *   },
 * };
 * ```
 *
 * ### `controller.scheduledTime` — the fire time
 * **Example:** Effect: record each fire on a Durable Object
 * ```typescript
 * export default class Worker extends Cloudflare.Worker<Worker>()(
 *   "Worker",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const counters = yield* CronCounter;
 *
 *     yield* Cloudflare.Workers.cron("0 * * * *", (controller) =>
 *       counters.getByName("default").record(controller.scheduledTime),
 *     );
 *
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const { times } = yield* counters.getByName("default").snapshot();
 *         return yield* HttpServerResponse.json({ times });
 *       }),
 *     };
 *   }).pipe(Effect.provide(Cloudflare.Workers.CronEventSourceLive)),
 * ) {}
 * ```
 *
 * **Example:** Async: use the fire time as an idempotency key
 * ```typescript
 * // scheduledTime is the time the fire was *scheduled* for (not when it
 * // ran), so it is stable across retries of the same fire — a natural
 * // idempotency key for at-most-once side effects.
 * export default {
 *   async scheduled(controller: ScheduledController, env: WorkerEnv) {
 *     const key = `run:${controller.scheduledTime}`;
 *     if (await env.RUNS.get(key)) return;
 *     await syncFeeds();
 *     await env.RUNS.put(key, "done");
 *   },
 * };
 * ```
 *
 * ### `controller.cron` — dispatch multiple schedules
 * **Example:** Effect: one handler per expression
 * ```typescript
 * // Each handler only runs for fires of its own expression — the listener
 * // checks controller.cron, so a midnight fire never runs the hourly handler.
 * yield* Cloudflare.Workers.cron("0 * * * *", () => syncFeeds);
 * yield* Cloudflare.Workers.cron("0 0 * * *", () => purgeExpired);
 * ```
 *
 * **Example:** Async: switch on `controller.cron`
 * ```typescript
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   crons: ["0 * * * *", "0 0 * * *"],
 * });
 *
 * // src/worker.ts — one scheduled handler receives every fire
 * export default {
 *   async scheduled(controller: ScheduledController) {
 *     switch (controller.cron) {
 *       case "0 * * * *":
 *         await syncFeeds();
 *         break;
 *       case "0 0 * * *":
 *         await purgeExpired();
 *         break;
 *     }
 *   },
 * };
 * ```
 *
 * ### `controller.noRetry()` — failure & retry control
 * **Example:** Effect: bound retries with `Effect.retry`
 * ```typescript
 * import * as Schedule from "effect/Schedule";
 *
 * // The event source reports the invocation as successful even when the
 * // handler fails, so Cloudflare's platform retry rarely engages for Effect
 * // handlers — Effect.retry is the primary retry control. Calling
 * // controller.noRetry() once retries are exhausted defensively covers
 * // anything that can still mark the invocation failed (e.g. a failing
 * // waitUntil task).
 * yield* Cloudflare.Workers.cron("0 * * * *", (controller) =>
 *   syncFeeds.pipe(
 *     Effect.retry({ schedule: Schedule.exponential("1 second"), times: 3 }),
 *     Effect.tapError((error) =>
 *       Effect.logError("syncFeeds failed permanently", error).pipe(
 *         Effect.andThen(Effect.sync(() => controller.noRetry())),
 *       ),
 *     ),
 *   ),
 * );
 * ```
 *
 * **Example:** Async: suppress retry for permanent failures
 * ```typescript
 * // src/worker.ts — a thrown error marks the invocation failed and
 * // Cloudflare may retry it; noRetry() opts this fire out of that.
 * export default {
 *   async scheduled(controller: ScheduledController) {
 *     try {
 *       await syncFeeds();
 *     } catch (error) {
 *       if (isPermanentFailure(error)) {
 *         controller.noRetry();
 *       }
 *       throw error; // still recorded as a failed invocation
 *     }
 *   },
 * };
 * ```
 *
 * @see https://developers.cloudflare.com/workers/configuration/cron-triggers/
 *
 * @binding
 * @product Workers
 * @category Workers & Compute
 */
export const cron = <Req = never>(
  expression: string,
  process: (controller: cf.ScheduledController) => Effect.Effect<void, unknown, Req>,
): Effect.Effect<void, never, CronEventSource | Exclude<Req, RuntimeContext>> =>
  CronEventSource.use((source) => source(expression, process));

export type CronEventSourceService = <Req = never>(
  expression: string,
  process: (controller: cf.ScheduledController) => Effect.Effect<void, unknown, Req>,
) => Effect.Effect<void, never, Exclude<Req, RuntimeContext>>;

export class CronEventSource extends Context.Service<CronEventSource, CronEventSourceService>()(
  "Cloudflare.Workers.CronEventSource",
) {}

export const CronEventSourceLive = Layer.effect(
  CronEventSource,
  Effect.gen(function* () {
    const host = yield* Worker;
    return Effect.fn(function* <Req>(
      expression: string,
      process: (controller: cf.ScheduledController) => Effect.Effect<void, unknown, Req>,
    ) {
      // Deploy-time: attach the cron expression to the host Worker. Skipped once
      // running inside the deployed Worker (the global guard), where the only
      // work is registering the runtime scheduled handler below. Namespaced
      // under the host so logical identity matches the previous Binding.Policy.
      if (!globalThis.__ALCHEMY_RUNTIME__) {
        yield* Namespace.push(
          host.LogicalId,
          host.bind(`Cron(${expression})`, {
            crons: [expression],
          }),
        );
      }

      const ctx = (yield* RuntimeContext) as unknown as FunctionContext;
      yield* ctx.listen<void, Req>((event) => {
        if (!isWorkerEvent(event) || event.type !== "scheduled") return;

        const controller = event.input as cf.ScheduledController;
        if (controller.cron !== expression) return;

        return process(controller).pipe(Effect.ignoreCause);
      });
    }) as CronEventSourceService;
  }),
);