@effect/platform-cloudflare 0.0.0-stage → 4.1.3

package/src/internal/queueStorage.ts

@@ -0,0 +1,255 @@
+/**
+ * Storage glue for the durable queue Durable Object. The constructor must stay
+ * cheap: open SQLite, ensure the queue table, and re-arm the single alarm from
+ * the earliest pending lease expiry or initial visibility deadline.
+ *
+ * Completed rows are retained (not deleted) so custom-id deduplication
+ * survives completion, matching the SQL-backed store. A failed item moves to
+ * the back of the queue, so a poisoned item cannot hot-loop the head while
+ * still being retried ahead of items offered after its failure.
+ *
+ * `completed` holds the row state: 0 while pending, processing, or waiting to
+ * retry, 1 once completed, and 2 once its final attempt failed. An
+ * `"untilExecuted"` offer replaces a row in state 1 or 2.
+ *
+ * Each lease records its taker in `lease_owner` and the taker's
+ * `max_attempts`. Settling or extending a lease only applies while that taker
+ * still owns the row, so a taker whose lease expired cannot settle work another
+ * taker now holds or a row an `"untilExecuted"` offer re-created.
+ *
+ * Leasing a row counts an attempt, so a taker that crashes still consumes one.
+ * An expired lease keeps its owner until another taker leases the row; if it
+ * used the row's last attempt the row moves to the failed state (2). A release
+ * refunds the attempt. A recorded failure or release clears the owner, so a
+ * retried `fail` or `release` cannot settle the same attempt twice.
+ * A recorded failure that leaves the row pending stores its retry delay in
+ * `lease_until` with no owner, the same delayed visibility an offer uses.
+ * Lookups by taker go through `lease_owner`, so a retried take or a cancel
+ * finds its row after the object restarts.
+ *
+ * @internal
+ */
+import type { SqlStorage } from "@cloudflare/workers-types"
+import type { DurableQueueItem } from "../CloudflareDurableObjectPrograms.ts"
+
+const ddl = [
+  `CREATE TABLE IF NOT EXISTS queue_items (
+    id TEXT PRIMARY KEY,
+    element TEXT NOT NULL,
+    position INTEGER NOT NULL,
+    attempts INTEGER NOT NULL DEFAULT 0,
+    completed INTEGER NOT NULL DEFAULT 0,
+    lease_until INTEGER,
+    lease_owner TEXT,
+    max_attempts INTEGER,
+    last_failure TEXT
+  )`,
+  `CREATE INDEX IF NOT EXISTS queue_items_take_idx
+    ON queue_items (completed, position)`,
+  `CREATE INDEX IF NOT EXISTS queue_items_lease_idx
+    ON queue_items (lease_until)`,
+  // MAX(position) in offerItem/failItem needs a bare position index; the
+  // (completed, position) index cannot serve it and completed rows are
+  // retained forever for dedup.
+  `CREATE INDEX IF NOT EXISTS queue_items_position_idx
+    ON queue_items (position)`,
+  // A retried take and a cancel look the taker's row up by owner.
+  `CREATE INDEX IF NOT EXISTS queue_items_owner_idx
+    ON queue_items (lease_owner)`
+]
+
+/** @internal */
+export const ensureQueueStorage = (sql: SqlStorage): void => {
+  for (const statement of ddl) {
+    sql.exec(statement)
+  }
+}
+
+/** @internal */
+export type QueueItem = DurableQueueItem
+
+type QueueItemRow = {
+  readonly id: string
+  readonly element: string
+  readonly attempts: number
+}
+
+type LeaseExpiryRow = {
+  readonly lease_until: number | null
+}
+
+/** @internal */
+export const offerItem = (
+  sql: SqlStorage,
+  id: string,
+  element: string,
+  visibleAt: number | null,
+  deduplicate?: "untilExecuted" | "untilRemoved" | undefined
+): void => {
+  if (deduplicate === "untilExecuted") {
+    // A completed or failed row releases the id. Deleting it lets the insert
+    // below store the offer as new work after every existing row. Both
+    // statements run synchronously, so no other offer can interleave.
+    sql.exec("DELETE FROM queue_items WHERE id = ? AND completed <> 0", id)
+  }
+  // Reuse lease_until for initial visibility; INSERT OR IGNORE preserves the
+  // original deadline and payload when an id is offered again.
+  sql.exec(
+    `INSERT OR IGNORE INTO queue_items (id, element, position, lease_until)
+     VALUES (?, ?, (SELECT IFNULL(MAX(position), 0) + 1 FROM queue_items), ?)`,
+    id,
+    element,
+    visibleAt
+  )
+}
+
+/**
+ * Leases the next available item and counts the attempt. The returned
+ * `attempts` is the number of earlier attempts, not counting this one.
+ *
+ * @internal
+ */
+export const leaseNextItem = (
+  sql: SqlStorage,
+  now: number,
+  leaseUntil: number,
+  maxAttempts: number,
+  owner: string
+): QueueItem | undefined => {
+  const row = sql.exec<QueueItemRow>(
+    `SELECT id, element, attempts FROM queue_items
+     WHERE completed = 0 AND attempts < ? AND (lease_until IS NULL OR lease_until <= ?)
+     ORDER BY position ASC LIMIT 1`,
+    maxAttempts,
+    now
+  ).toArray()[0]
+  if (row === undefined) return undefined
+  sql.exec(
+    `UPDATE queue_items SET attempts = attempts + 1, lease_until = ?, lease_owner = ?, max_attempts = ?
+     WHERE id = ?`,
+    leaseUntil,
+    owner,
+    maxAttempts,
+    row.id
+  )
+  return row
+}
+
+/**
+ * The item still leased to `owner` under a live lease, so a retried take can
+ * return it. `attempts` counts earlier attempts, as `leaseNextItem` returns.
+ *
+ * @internal
+ */
+export const leasedItem = (sql: SqlStorage, owner: string, now: number): QueueItem | undefined =>
+  sql.exec<QueueItemRow>(
+    `SELECT id, element, attempts - 1 AS attempts FROM queue_items
+     WHERE lease_owner = ? AND completed = 0 AND lease_until > ?
+     LIMIT 1`,
+    owner,
+    now
+  ).toArray()[0]
+
+/** @internal */
+export const completeItem = (sql: SqlStorage, id: string, owner: string): void => {
+  sql.exec("UPDATE queue_items SET completed = 1, lease_until = NULL WHERE id = ? AND lease_owner = ?", id, owner)
+}
+
+/**
+ * Records a failed attempt, which the lease already counted. When the attempt
+ * reaches the `max_attempts` stored with the lease, or the failure is
+ * `terminal`, the row moves to the failed state (2). A row that is already
+ * completed is left alone, even when the caller was its last owner.
+ * A row that stays pending is hidden until `visibleAt` (null for no delay).
+ * Clearing `lease_owner` makes a replayed call a no-op until the next lease
+ * assigns a new owner.
+ *
+ * @internal
+ */
+export const failItem = (
+  sql: SqlStorage,
+  id: string,
+  lastFailure: string,
+  owner: string,
+  terminal: boolean,
+  visibleAt: number | null
+): void => {
+  const failed = "? OR attempts >= max_attempts"
+  sql.exec(
+    `UPDATE queue_items
+     SET lease_until = CASE WHEN ${failed} THEN NULL ELSE ? END, lease_owner = NULL, last_failure = ?,
+         completed = CASE WHEN ${failed} THEN 2 ELSE 0 END,
+         position = (SELECT IFNULL(MAX(position), 0) + 1 FROM queue_items)
+     WHERE id = ? AND lease_owner = ? AND completed = 0`,
+    terminal ? 1 : 0,
+    visibleAt,
+    lastFailure,
+    terminal ? 1 : 0,
+    id,
+    owner
+  )
+}
+
+/**
+ * Returns the item to the queue and refunds the attempt its lease counted.
+ *
+ * @internal
+ */
+export const releaseItem = (sql: SqlStorage, id: string, owner: string): void => {
+  sql.exec(
+    `UPDATE queue_items SET attempts = attempts - 1, lease_until = NULL, lease_owner = NULL
+     WHERE id = ? AND lease_owner = ? AND completed = 0`,
+    id,
+    owner
+  )
+}
+
+/**
+ * Releases the item `owner` holds under a live lease, as `releaseItem` does.
+ * An expired lease can still carry the same owner until its alarm runs; it
+ * keeps its spent attempt so it can fail on its own.
+ *
+ * @internal
+ */
+export const releaseOwnedItem = (sql: SqlStorage, owner: string, now: number): void => {
+  sql.exec(
+    `UPDATE queue_items SET attempts = attempts - 1, lease_until = NULL, lease_owner = NULL
+     WHERE lease_owner = ? AND completed = 0 AND lease_until > ?`,
+    owner,
+    now
+  )
+}
+
+/** @internal */
+export const extendLease = (sql: SqlStorage, id: string, leaseUntil: number, owner: string): void => {
+  sql.exec(
+    "UPDATE queue_items SET lease_until = ? WHERE id = ? AND lease_owner = ? AND lease_until IS NOT NULL",
+    leaseUntil,
+    id,
+    owner
+  )
+}
+
+/**
+ * Expires due leases and initial visibility deadlines. A lease that used the
+ * row's last attempt moves the row to the failed state (2).
+ *
+ * @internal
+ */
+export const expireLeases = (sql: SqlStorage, now: number): void => {
+  sql.exec(
+    `UPDATE queue_items
+     SET lease_until = NULL,
+         completed = CASE WHEN lease_owner IS NOT NULL AND attempts >= max_attempts THEN 2 ELSE 0 END
+     WHERE lease_until IS NOT NULL AND lease_until <= ? AND completed = 0`,
+    now
+  )
+}
+
+/** @internal */
+export const earliestLeaseExpiry = (sql: SqlStorage): number | undefined => {
+  const row = sql.exec<LeaseExpiryRow>(
+    "SELECT min(lease_until) AS lease_until FROM queue_items WHERE lease_until IS NOT NULL"
+  ).toArray()[0]
+  return row?.lease_until ?? undefined
+}

package/src/internal/registry.ts

@@ -0,0 +1,31 @@
+/**
+ * A module-level registration map shared between the Worker layer and the
+ * Durable Object instances of the same isolate. Unregistering only removes
+ * the exact registration that was added, so a finalizer racing a re-register
+ * cannot drop the replacement.
+ *
+ * @internal
+ */
+
+/** @internal */
+export interface Registry<A> {
+  readonly get: (key: string) => A | undefined
+  readonly register: (key: string, value: A) => boolean
+  readonly unregister: (key: string, value: A) => void
+}
+
+/** @internal */
+export const makeRegistry = <A>(): Registry<A> => {
+  const registrations = new Map<string, A>()
+  return {
+    get: (key) => registrations.get(key),
+    register: (key, value) => {
+      if (registrations.has(key)) return false
+      registrations.set(key, value)
+      return true
+    },
+    unregister: (key, value) => {
+      if (registrations.get(key) === value) registrations.delete(key)
+    }
+  }
+}

package/src/internal/singletonRegistry.ts

@@ -0,0 +1,21 @@
+/** @internal */
+import type * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import { makeRegistry } from "./registry.ts"
+
+/** @internal */
+export interface SingletonRegistration {
+  readonly run: Effect.Effect<void, unknown, never>
+  readonly context: Context.Context<never>
+}
+
+const registry = makeRegistry<SingletonRegistration>()
+
+/** @internal */
+export const getSingletonRegistration: (name: string) => SingletonRegistration | undefined = registry.get
+
+/** @internal */
+export const registerSingleton: (name: string, registration: SingletonRegistration) => boolean = registry.register
+
+/** @internal */
+export const unregisterSingleton: (name: string, registration: SingletonRegistration) => void = registry.unregister

package/src/internal/singletonRuntime.ts

@@ -0,0 +1,88 @@
+/**
+ * Runs one singleton effect for each Worker Cron Trigger wake. Concurrent
+ * duplicate wakes are ignored while the accepted wake is still running; once
+ * it returns, the object has no live work and Cloudflare may hibernate it.
+ *
+ * While a wake runs, a watchdog alarm stays armed in the future. If it fires
+ * mid-run it is re-armed, so losing the isolate never leaves the pending wake
+ * without an alarm to resume it.
+ *
+ * @internal
+ */
+import type { DurableObjectStorage, SqlStorage } from "@cloudflare/workers-types"
+import * as Effect from "effect/Effect"
+import { armAlarm } from "./entityStorage.ts"
+import {
+  beginSingletonWake,
+  completeSingletonWake,
+  ensureSingletonStorage,
+  loadSingletonState
+} from "./singletonStorage.ts"
+
+/**
+ * How far ahead the watchdog alarm is armed while a wake is running.
+ */
+const watchdogMillis = 60_000
+
+/** @internal */
+export interface SingletonRuntimeOptions {
+  readonly sql: SqlStorage
+  readonly alarm: Pick<DurableObjectStorage, "deleteAlarm" | "getAlarm" | "setAlarm">
+  readonly now: () => number
+  readonly run: Effect.Effect<void, unknown>
+}
+
+/** @internal */
+export interface SingletonRuntime {
+  readonly wake: () => Promise<void>
+  readonly runAlarm: () => Promise<void>
+}
+
+/** @internal */
+export const makeSingletonRuntime = (options: SingletonRuntimeOptions): SingletonRuntime => {
+  ensureSingletonStorage(options.sql)
+  let inFlight: Promise<void> | undefined
+
+  const armWatchdog = (): Effect.Effect<void> =>
+    Effect.suspend(() => armAlarm(options.alarm, options.now() + watchdogMillis))
+
+  const runPending = (arm: boolean): Promise<void> => {
+    const run = options.run.pipe(
+      Effect.ensuring(
+        Effect.promise(() => options.alarm.deleteAlarm()).pipe(
+          Effect.ensuring(Effect.sync(() => completeSingletonWake(options.sql)))
+        )
+      )
+    )
+    const operation = Effect.runPromise(arm ? Effect.andThen(armWatchdog(), run) : run)
+    inFlight = operation
+    void operation.then(
+      () => {
+        inFlight = undefined
+      },
+      () => {
+        inFlight = undefined
+      }
+    )
+    return operation
+  }
+
+  return {
+    wake: () => {
+      if (inFlight !== undefined) return Promise.resolve()
+      const pending = loadSingletonState(options.sql).wakeAt
+      if (pending !== undefined) return runPending(false)
+      const now = options.now()
+      if (!beginSingletonWake(options.sql, now)) return Promise.resolve()
+      return runPending(true)
+    },
+
+    // Cloudflare consumes the alarm before invoking this handler, so an alarm
+    // that fires during a run must arm the next watchdog before returning.
+    runAlarm: () => {
+      if (loadSingletonState(options.sql).wakeAt === undefined) return Promise.resolve()
+      if (inFlight !== undefined) return Effect.runPromise(armWatchdog())
+      return runPending(false)
+    }
+  }
+}

package/src/internal/singletonStorage.ts

@@ -0,0 +1,64 @@
+/**
+ * Storage glue for the singleton Durable Object. A pending row is a watchdog:
+ * a normal wake clears it after the effect returns, while an isolate crash
+ * leaves it for the constructor to re-arm on the next alarm wake.
+ *
+ * @internal
+ */
+import type { SqlStorage } from "@cloudflare/workers-types"
+
+const ddl = `CREATE TABLE IF NOT EXISTS singleton_state (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  name TEXT,
+  wake_at INTEGER
+)`
+
+/** @internal */
+export const ensureSingletonStorage = (sql: SqlStorage): void => {
+  sql.exec(ddl)
+}
+
+/** @internal */
+export interface SingletonState {
+  readonly name: string | undefined
+  readonly wakeAt: number | undefined
+}
+
+type SingletonStateRow = {
+  readonly name: string | null
+  readonly wake_at: number | null
+}
+
+/** @internal */
+export const loadSingletonState = (sql: SqlStorage): SingletonState => {
+  const row = sql.exec<SingletonStateRow>("SELECT name, wake_at FROM singleton_state WHERE id = 1").toArray()[0]
+  return {
+    name: row?.name ?? undefined,
+    wakeAt: row?.wake_at ?? undefined
+  }
+}
+
+/** @internal */
+export const rememberSingletonName = (sql: SqlStorage, name: string): void => {
+  sql.exec(
+    `INSERT INTO singleton_state (id, name) VALUES (1, ?)
+     ON CONFLICT(id) DO UPDATE SET name = excluded.name`,
+    name
+  )
+}
+
+/** @internal */
+export const beginSingletonWake = (sql: SqlStorage, wakeAt: number): boolean => {
+  if (loadSingletonState(sql).wakeAt !== undefined) return false
+  sql.exec(
+    `INSERT INTO singleton_state (id, wake_at) VALUES (1, ?)
+     ON CONFLICT(id) DO UPDATE SET wake_at = excluded.wake_at`,
+    wakeAt
+  )
+  return true
+}
+
+/** @internal */
+export const completeSingletonWake = (sql: SqlStorage): void => {
+  sql.exec("UPDATE singleton_state SET wake_at = NULL WHERE id = 1")
+}

package/src/internal/transport.ts

@@ -0,0 +1,67 @@
+/** @internal */
+import { PersistenceError } from "effect/cluster/ClusterError"
+import * as Effect from "effect/Effect"
+import * as Schedule from "effect/Schedule"
+
+/**
+ * The flags Cloudflare sets on the Error a failed Durable Object call rejects
+ * with.
+ *
+ * @internal
+ */
+export interface TransportErrorFlags {
+  readonly retryable?: boolean | undefined
+  readonly overloaded?: boolean | undefined
+  readonly remote?: boolean | undefined
+}
+
+/**
+ * Whether a failed Durable Object call may be retried. Cloudflare marks
+ * transient failures `retryable`, and an `overloaded` object must not be
+ * retried, as retrying only adds load.
+ *
+ * @internal
+ */
+export const isRetryable = (error: PersistenceError): boolean => {
+  const cause = error.cause as TransportErrorFlags | null | undefined
+  return typeof cause === "object" && cause !== null && cause.retryable === true && cause.overloaded !== true
+}
+
+/**
+ * The bounded retry policy for idempotent calls outside a workflow: a few
+ * quick attempts, then the caller sees the typed error.
+ *
+ * @internal
+ */
+export const boundedRetry: Schedule.Schedule<unknown> = Schedule.max([
+  Schedule.exponential(100, 2),
+  Schedule.recurs(4)
+])
+
+/**
+ * Makes one Worker-to-Durable Object stub call.
+ *
+ * **Details**
+ *
+ * A rejection becomes a `PersistenceError` whose `cause` is the rejected
+ * value, so Cloudflare's `retryable`, `overloaded` and `remote` flags stay
+ * readable. Each attempt resolves a fresh stub with `resolve`, because
+ * Cloudflare advises against reusing a stub after it throws. With `retry`, the
+ * call is retried on that schedule while the error is retryable; only pass it
+ * for idempotent calls.
+ *
+ * @internal
+ */
+export const callDurableObject = <Stub, A>(options: {
+  readonly resolve: () => Stub
+  readonly call: (stub: Stub) => Promise<A>
+  readonly retry?: Schedule.Schedule<unknown, PersistenceError> | undefined
+}): Effect.Effect<A, PersistenceError> => {
+  const attempt = Effect.tryPromise({
+    try: () => options.call(options.resolve()),
+    catch: (cause) => new PersistenceError({ cause })
+  })
+  return options.retry === undefined
+    ? attempt
+    : Effect.retry(attempt, { schedule: options.retry, while: isRetryable })
+}

package/src/internal/workflowRegistry.ts

@@ -0,0 +1,78 @@
+/**
+ * Module-level workflow state shared between the Worker layer and the workflow
+ * Durable Object instances of the same isolate. Registrations are recorded at
+ * Worker init; a running execution provides its own handle through
+ * `CurrentExecutionHandle` so engine operations inside the run hit local
+ * SQLite instead of a self-RPC.
+ *
+ * @internal
+ */
+import * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import type * as Workflow from "effect/workflow/Workflow"
+import * as WorkflowEngine from "effect/workflow/WorkflowEngine"
+import type { ClusterWorkflowRunOptions, ClusterWorkflowWakeMode } from "../CloudflareDurableObjectPrograms.ts"
+import { makeRegistry } from "./registry.ts"
+
+/** @internal */
+export interface WorkflowRegistration {
+  readonly workflow: Workflow.Any
+  readonly execute: (
+    payload: object,
+    executionId: string
+  ) => Effect.Effect<unknown, unknown, WorkflowEngine.WorkflowInstance | WorkflowEngine.WorkflowEngine>
+  readonly context: Context.Context<never>
+}
+
+const registry = makeRegistry<WorkflowRegistration>()
+
+/** @internal */
+export const getWorkflowRegistration: (name: string) => WorkflowRegistration | undefined = registry.get
+
+/** @internal */
+export const registerWorkflow: (name: string, registration: WorkflowRegistration) => boolean = registry.register
+
+/** @internal */
+export const unregisterWorkflow: (name: string, registration: WorkflowRegistration) => void = registry.unregister
+
+/** @internal */
+export type WorkflowRunOptions = ClusterWorkflowRunOptions
+
+/**
+ * The transport shared by workflow Durable Object stubs and same-isolate
+ * execution handles. All payloads are JSON text.
+ *
+ * @internal
+ */
+export interface WorkflowStub {
+  readonly run: (payload: string, options: WorkflowRunOptions) => Promise<string>
+  readonly poll: () => Promise<string | undefined>
+  readonly resume: (mode?: ClusterWorkflowWakeMode) => Promise<void>
+  readonly interrupt: () => Promise<void>
+  readonly interruptUnsafe: () => Promise<void>
+  readonly deferredDone: (name: string, exit: string) => Promise<void>
+  readonly scheduleClock: (name: string, deferredName: string, wakeUp: number) => Promise<void>
+}
+
+/** @internal */
+export interface WorkflowExecutionHandle extends WorkflowStub {
+  readonly executionId: string
+  readonly loadActivity: (key: string) => string | undefined
+  readonly saveActivity: (key: string, exit: string) => void
+  readonly loadDeferred: (name: string) => string | undefined
+  /** Completes a deferred of this execution from inside its own run. */
+  readonly completeOwnDeferred: (name: string, exit: string) => Effect.Effect<void>
+}
+
+/**
+ * The handle of the workflow execution currently running in this fiber,
+ * provided by the workflow Durable Object runtime around each run attempt.
+ *
+ * @internal
+ */
+export class CurrentExecutionHandle extends Context.Service<CurrentExecutionHandle, WorkflowExecutionHandle>()(
+  "@effect/platform-cloudflare/CloudflareWorkflowEngine/CurrentExecutionHandle"
+) {}
+
+/** @internal */
+export const deferredState = WorkflowEngine.makeDeferredState()