@effect/platform-cloudflare 0.0.0-stage → 4.1.3

package/src/CloudflareWorkflowEngine.ts

@@ -0,0 +1,220 @@
+/**
+ * Runs durable workflows on the dedicated workflow Durable Object class.
+ *
+ * On this path one workflow execution is one Durable Object: the engine
+ * encodes `(workflowName, executionId)` into a Durable Object name with the
+ * same length-prefix scheme as entities and resolves the object through the
+ * workflow namespace binding. Execution state, activity results keyed
+ * `${name}/${attempt}`, durable deferred exits, and the clock due table all
+ * live on the object's SQLite storage behind its single alarm.
+ *
+ * Every `DurableClock` is durable on this engine: the in-memory short-sleep
+ * path is disabled, so even sub-minute sleeps persist a due row and arm the
+ * alarm.
+ *
+ * @stability experimental
+ * @since 4.1.3
+ */
+import { Clock } from "effect/Clock"
+import * as Context from "effect/Context"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import * as Schedule from "effect/Schedule"
+import * as Workflow from "effect/workflow/Workflow"
+import * as WorkflowEngine from "effect/workflow/WorkflowEngine"
+import { encodeName } from "./internal/clusterName.ts"
+import { callDurableObject } from "./internal/transport.ts"
+import {
+  CurrentExecutionHandle,
+  registerWorkflow,
+  unregisterWorkflow,
+  type WorkflowRegistration,
+  type WorkflowStub
+} from "./internal/workflowRegistry.ts"
+import { InterruptSignalName } from "./internal/workflowRuntime.ts"
+import { decodeExit, decodeResult, encodeExit, encodePayload } from "./internal/workflowWire.ts"
+
+/**
+ * The workflow Durable Object namespace binding the engine is built from.
+ *
+ * @stability experimental
+ * @category layers
+ * @since 4.1.3
+ */
+export interface LayerOptions {
+  readonly workflowNamespace: DurableObjectNamespace
+}
+
+const retryPolicy = Schedule.min([
+  Schedule.exponential(200, 1.5),
+  Schedule.spaced("1 minute")
+])
+
+/**
+ * Creates the `WorkflowEngine` service backed by the workflow Durable Object
+ * namespace binding.
+ *
+ * **Details**
+ *
+ * Inside a workflow Durable Object the engine operates on the local execution
+ * handle, so activities and deferred reads never leave the object. Everywhere
+ * else it resolves the target execution's object with `getByName` and drives
+ * it over the same-Worker binding.
+ *
+ * @stability experimental
+ * @category constructors
+ * @since 4.1.3
+ */
+export const make = Effect.fnUntraced(function*(options: LayerOptions) {
+  const clock = yield* Clock
+
+  // Inside a run the execution's own handle avoids a self-RPC; every other
+  // target resolves to its Durable Object stub through the namespace binding.
+  //
+  // As in `ClusterWorkflowEngine`, a transport failure is retried on an
+  // exponential schedule capped at one minute and only then becomes a defect:
+  // every call here is idempotent by key, and a permanently unreachable object
+  // stalls the caller instead of failing a workflow for good. The object never
+  // rejects for application reasons, so a child's own defect arrives as its
+  // stored `Complete` result and is never retried.
+  const callExecution = <A>(
+    workflowName: string,
+    executionId: string,
+    call: (stub: WorkflowStub) => Promise<A>
+  ): Effect.Effect<A> =>
+    Effect.flatMap(Effect.serviceOption(CurrentExecutionHandle), (handle) => {
+      if (Option.isSome(handle) && handle.value.executionId === executionId) {
+        const local = handle.value as WorkflowStub
+        return Effect.promise(() => call(local))
+      }
+      const name = encodeName(workflowName, executionId)
+      return callDurableObject({
+        resolve: () => options.workflowNamespace.getByName(name) as unknown as WorkflowStub,
+        call,
+        retry: retryPolicy
+      }).pipe(Effect.orDie)
+    })
+
+  const localHandle = Effect.fnUntraced(function*(operation: string) {
+    const instance = yield* WorkflowEngine.WorkflowInstance
+    const handle = yield* Effect.serviceOption(CurrentExecutionHandle)
+    if (Option.isNone(handle)) {
+      return yield* Effect.die(
+        `CloudflareWorkflowEngine: ${operation} is only available inside a workflow Durable Object execution`
+      )
+    }
+    return { instance, handle: handle.value } as const
+  })
+
+  return WorkflowEngine.makeUnsafe({
+    register: Effect.fnUntraced(function*(workflow, execute) {
+      const context = yield* Effect.context<never>()
+      const registration: WorkflowRegistration = { workflow, execute, context }
+      if (!registerWorkflow(workflow._tag, registration)) return
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          unregisterWorkflow(workflow._tag, registration)
+        })
+      )
+    }),
+
+    execute: Effect.fnUntraced(function*(workflow, opts) {
+      const context = yield* Effect.context<never>()
+      const payload = yield* encodePayload(workflow, opts.payload, context)
+      // A detached child keeps no parent, so neither its completion nor a
+      // failed run wakes the parent.
+      const parent = opts.parent === undefined || opts.detached
+        ? undefined
+        : { workflowName: opts.parent.workflow._tag, executionId: opts.parent.executionId }
+      const text = yield* callExecution(
+        workflow._tag,
+        opts.executionId,
+        (stub) => stub.run(payload, { discard: opts.discard, parent })
+      )
+      if (opts.discard) return undefined
+      return yield* decodeResult(workflow, text, context)
+    }) as WorkflowEngine.Encoded["execute"],
+
+    poll: Effect.fnUntraced(function*(workflow, executionId) {
+      const context = yield* Effect.context<never>()
+      const text = yield* callExecution(workflow._tag, executionId, (stub) => stub.poll())
+      if (text === undefined) return Option.none()
+      return Option.some(yield* decodeResult(workflow, text, context))
+    }),
+
+    interrupt: (workflow, executionId) => callExecution(workflow._tag, executionId, (stub) => stub.interrupt()),
+
+    interruptUnsafe: (workflow, executionId) =>
+      callExecution(workflow._tag, executionId, (stub) => stub.interruptUnsafe()),
+
+    resume: (workflow, executionId) => callExecution(workflow._tag, executionId, (stub) => stub.resume()),
+
+    activityExecute: Effect.fnUntraced(function*(activity, attempt) {
+      const { handle, instance } = yield* localHandle("Activity execution")
+      const key = `${activity.name}/${attempt}`
+      const stored = handle.loadActivity(key)
+      if (stored !== undefined) {
+        return new Workflow.Complete({ exit: yield* decodeExit(stored, Context.empty()) })
+      }
+      // A pending interrupt replays only to rebuild compensations, so it must
+      // not start new activities. Suspending lets the run apply the interrupt.
+      if (!instance.interrupted && handle.loadDeferred(InterruptSignalName) !== undefined) {
+        instance.suspended = true
+        return new Workflow.Suspended({})
+      }
+      const activityInstance = WorkflowEngine.WorkflowInstance.initial(instance.workflow, instance.executionId)
+      activityInstance.interrupted = instance.interrupted
+      const result = yield* activity.executeEncoded.pipe(
+        Workflow.intoResult,
+        Effect.provideService(WorkflowEngine.WorkflowInstance, activityInstance)
+      )
+      if (result._tag === "Complete") {
+        handle.saveActivity(key, yield* encodeExit(result.exit, Context.empty()))
+      }
+      return result
+    }),
+
+    deferredResult: Effect.fnUntraced(function*(deferred) {
+      const { handle } = yield* localHandle("DurableDeferred reads")
+      const stored = handle.loadDeferred(deferred.name)
+      if (stored === undefined) return Option.none()
+      return Option.some(yield* decodeExit(stored, Context.empty()))
+    }),
+
+    deferredDone: Effect.fnUntraced(function*({ deferredName, executionId, exit, workflowName }) {
+      const text = yield* encodeExit(exit, Context.empty())
+      const handle = yield* Effect.serviceOption(CurrentExecutionHandle)
+      if (Option.isSome(handle) && handle.value.executionId === executionId) {
+        return yield* handle.value.completeOwnDeferred(deferredName, text)
+      }
+      yield* callExecution(workflowName, executionId, (stub) => stub.deferredDone(deferredName, text))
+    }),
+
+    scheduleClock: Effect.fnUntraced(function*(workflow, opts) {
+      const wakeUp = clock.currentTimeMillisUnsafe() + Math.ceil(Duration.toMillis(opts.clock.duration))
+      yield* callExecution(
+        workflow._tag,
+        opts.executionId,
+        (stub) => stub.scheduleClock(opts.clock.name, opts.clock.deferred.name, wakeUp)
+      )
+    })
+  })
+})
+
+/**
+ * Layer that provides the `WorkflowEngine` backed by the workflow Durable
+ * Object namespace binding.
+ *
+ * **Details**
+ *
+ * `CloudflareCluster.layer` already includes this layer; use it directly only
+ * when the workflow engine is needed without the rest of the cluster.
+ *
+ * @stability experimental
+ * @category layers
+ * @since 4.1.3
+ */
+export const layer = (options: LayerOptions): Layer.Layer<WorkflowEngine.WorkflowEngine> =>
+  Layer.effect(WorkflowEngine.WorkflowEngine)(make(options))

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @since 4.1.3
+ */
+
+// The index stays free of the optional `alchemy` peer dependency, so the
+// Alchemy integration is exposed only through its own entrypoint:
+// `@effect/platform-cloudflare/AlchemyCloudflareCluster`.
+// @barrel(Cloudflare*.ts): Auto-generated exports. Do not edit manually.
+
+/**
+ * @stability experimental
+ * @since 4.1.3
+ */
+export * as CloudflareCluster from "./CloudflareCluster.ts"
+
+/**
+ * @stability experimental
+ * @since 4.1.3
+ */
+export * as CloudflareDurableObjectPrograms from "./CloudflareDurableObjectPrograms.ts"
+
+/**
+ * @stability experimental
+ * @since 4.1.3
+ */
+export * as CloudflareDurableObjects from "./CloudflareDurableObjects.ts"
+
+/**
+ * @stability experimental
+ * @since 4.1.3
+ */
+export * as CloudflarePersistedQueue from "./CloudflarePersistedQueue.ts"
+
+/**
+ * @stability experimental
+ * @since 4.1.3
+ */
+export * as CloudflareWorkflowEngine from "./CloudflareWorkflowEngine.ts"

package/src/internal/alchemyCluster.ts

@@ -0,0 +1,120 @@
+/**
+ * The alchemy-free half of `AlchemyCloudflareCluster.make`: building the
+ * cluster handle from resolved namespace bindings. Kept separate so it can be
+ * exercised without importing `alchemy`, whose runtime must match the
+ * published `effect` release rather than this workspace.
+ *
+ * @internal
+ */
+import type * as Entity from "effect/cluster/Entity"
+import * as Context from "effect/Context"
+import type * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Scope from "effect/Scope"
+import * as CloudflareCluster from "../CloudflareCluster.ts"
+import type { SingletonWakeResult } from "../CloudflareDurableObjectPrograms.ts"
+import type { Cluster } from "./cluster.ts"
+import { boundedRetry, callDurableObject } from "./transport.ts"
+
+interface SingletonStub {
+  // An object still on an older deploy resolves `undefined` on success.
+  readonly wake: () => Promise<SingletonWakeResult | undefined>
+}
+
+/** @internal */
+export interface ClusterHandleOptions {
+  readonly entities: ReadonlyArray<Entity.Entity<any, any>>
+  readonly layer: Layer.Layer<never, any, any>
+  readonly env: Record<string, unknown>
+  readonly keepAliveHeartbeat?: Duration.Input | undefined
+}
+
+/** @internal */
+export const makeClusterHandle = Effect.fnUntraced(function*(options: ClusterHandleOptions) {
+  const entityNamespace = options.env.ClusterEntity as DurableObjectNamespace
+  const workflowNamespace = options.env.ClusterWorkflow as DurableObjectNamespace
+  const queueNamespace = options.env.ClusterDurableQueue as DurableObjectNamespace
+  const singletonNamespace = options.env.ClusterSingleton as DurableObjectNamespace
+
+  // The isolate-lifetime scope. workerd has no isolate-teardown hook, so it
+  // is never closed; the built services live for the isolate, exactly like
+  // the Wrangler path's `setInitializer` build.
+  const scope = Scope.makeUnsafe()
+  const context = yield* Layer.buildWithScope(
+    options.layer.pipe(
+      Layer.provideMerge(CloudflareCluster.layer({
+        entities: options.entities,
+        entityNamespace,
+        workflowNamespace,
+        queueNamespace,
+        singletonNamespace,
+        keepAliveHeartbeat: options.keepAliveHeartbeat
+      }))
+    ),
+    scope
+  ).pipe(
+    // Drop the build's memo map so a Layer the user provides inside a
+    // handler builds per event instead of sharing one instance pinned to
+    // the first request's IoContext.
+    Effect.map(Context.omit(Layer.CurrentMemoMap))
+  )
+
+  const handle: Cluster<never> = {
+    provide: (effect) => Effect.provideContext(effect, context),
+    // Only a transport failure rejects `wake()`, so retrying never reruns a
+    // failed singleton. A failed run still fails the Cron Trigger.
+    wake: (name) => () =>
+      callDurableObject({
+        resolve: () => singletonNamespace.getByName(`Singleton/${name}`) as unknown as SingletonStub,
+        call: (stub) => stub.wake(),
+        retry: boundedRetry
+      }).pipe(
+        Effect.orDie,
+        Effect.flatMap((result) =>
+          result?._tag === "Failure"
+            ? Effect.die(new Error(`Singleton "${name}" failed: ${result.message}`))
+            : Effect.void
+        )
+      ),
+    entityNamespace,
+    workflowNamespace,
+    queueNamespace,
+    singletonNamespace,
+    context
+  }
+  return handle
+})
+
+/**
+ * The plan-time handle: the deploy-machine evaluation only discovers the
+ * Durable Object declarations, and nothing returned from the Worker init
+ * program runs outside the deployed isolate.
+ *
+ * @internal
+ */
+export const inertClusterHandle = (): Cluster<never> => ({
+  provide: (effect) => effect,
+  wake: () => () => Effect.void,
+  get entityNamespace() {
+    return planTimeOnly("entityNamespace")
+  },
+  get workflowNamespace() {
+    return planTimeOnly("workflowNamespace")
+  },
+  get queueNamespace() {
+    return planTimeOnly("queueNamespace")
+  },
+  get singletonNamespace() {
+    return planTimeOnly("singletonNamespace")
+  },
+  get context() {
+    return planTimeOnly("context")
+  }
+})
+
+const planTimeOnly = (field: string): never => {
+  throw new Error(
+    `AlchemyCloudflareCluster: '${field}' is only available at runtime, not during plan evaluation`
+  )
+}

package/src/internal/boundedMap.ts

@@ -0,0 +1,15 @@
+/** @internal */
+
+/**
+ * Inserts refreshing the key's recency, then evicts the oldest entry once the
+ * map exceeds `capacity`.
+ *
+ * @internal
+ */
+export const setWithEviction = <K, V>(map: Map<K, V>, key: K, value: V, capacity: number): void => {
+  map.delete(key)
+  map.set(key, value)
+  if (map.size <= capacity) return
+  const oldest = map.keys().next().value
+  if (oldest !== undefined) map.delete(oldest)
+}

package/src/internal/cluster.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared cluster handle types without the Alchemy dependency graph.
+ *
+ * @since 4.1.3
+ */
+import type * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+
+/**
+ * The handle returned by `AlchemyCloudflareCluster.make`.
+ *
+ * **Gotchas**
+ *
+ * Namespace bindings and `context` are available only in the deployed runtime.
+ * Reading them during plan evaluation throws a diagnostic; `provide` and
+ * `wake` remain inert during planning.
+ *
+ * @category models
+ * @since 4.1.3
+ */
+export interface Cluster<in R = never> {
+  /**
+   * Attaches the built cluster context to a user Effect, for the Worker's
+   * `fetch` handler and other entrypoints. Only provides the already-built
+   * Context; it does not open a new Scope.
+   */
+  readonly provide: <A, E, R2>(effect: Effect.Effect<A, E, R2>) => Effect.Effect<A, E, Exclude<R2, R>>
+  /**
+   * A handler that wakes the named singleton, for `Cloudflare.Workers.cron`.
+   * The name is the singleton name without the `Singleton/` prefix, and the
+   * returned handler is already context-provided. A `ClusterCron` fires only
+   * once its seed singleton is woken; get its name from
+   * `CloudflareCluster.clusterCronSingletonName`.
+   */
+  readonly wake: (name: string) => () => Effect.Effect<void>
+  /**
+   * The native namespace binding of the cluster entity class.
+   */
+  readonly entityNamespace: DurableObjectNamespace
+  /**
+   * The native namespace binding of the workflow class.
+   */
+  readonly workflowNamespace: DurableObjectNamespace
+  /**
+   * The native namespace binding of the durable queue class.
+   */
+  readonly queueNamespace: DurableObjectNamespace
+  /**
+   * The native namespace binding of the singleton class.
+   */
+  readonly singletonNamespace: DurableObjectNamespace
+  /**
+   * The Context built from the cluster layer and the user layer into the
+   * isolate-lifetime Scope.
+   */
+  readonly context: Context.Context<R>
+}

package/src/internal/clusterName.ts

@@ -0,0 +1,19 @@
+import type { ClusterName } from "../CloudflareCluster.ts"
+
+/** @internal */
+export const encodeName = (type: string, id: string): string => `${type.length}:${type}${id}`
+
+const lengthPrefix = /^([1-9]\d*):/
+
+/** @internal */
+export const decodeName = (name: string): ClusterName | undefined => {
+  const match = lengthPrefix.exec(name)
+  if (match === null) return undefined
+  const typeLength = Number(match[1])
+  const payload = name.slice(match[0].length)
+  if (typeLength > payload.length) return undefined
+  return {
+    type: payload.slice(0, typeLength),
+    id: payload.slice(typeLength)
+  }
+}

package/src/internal/entityKeepAlive.ts

@@ -0,0 +1,121 @@
+/**
+ * Keep-alive for one entity Durable Object, in three separate pieces of
+ * state:
+ *
+ * - `wanted` mirrors the persisted `keep_alive` flag that a restart restores.
+ * - `hold` is the fiber running the self `hold()` RPC while one is in flight.
+ * - The holder count belongs to the current handler build only. Persisting it
+ *   would break on restart: an `EntityResource` re-acquired by the rebuild
+ *   adds a holder on top of the stored count, which then never returns to 0.
+ *
+ * @internal
+ */
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import type * as Fiber from "effect/Fiber"
+import * as Latch from "effect/Latch"
+import * as Schedule from "effect/Schedule"
+
+/** @internal */
+export interface EntityKeepAlive {
+  /** The `Entity.keepAlive` handler. */
+  readonly update: (enabled: boolean) => Effect.Effect<void>
+  /** The body of the self `hold()` RPC; resolves once the hold is released. */
+  readonly await: Effect.Effect<void>
+  /** Forgets the holders of a closed handler build. The hold stays. */
+  readonly resetHolders: () => void
+  /** Starts the self hold when keep-alive is wanted and none is in flight. */
+  readonly restore: () => void
+}
+
+/** @internal */
+export interface EntityKeepAliveOptions {
+  /** Starts the self `hold()` RPC; the promise settles when the hold ends. */
+  readonly startHold: () => Promise<void>
+  /** The persisted flag, read when the Durable Object starts. */
+  readonly wanted: boolean
+  /**
+   * Persists each requested flag in a forked fiber. The hold is released only
+   * after a successful `false` write while keep-alive is still unwanted.
+   */
+  readonly persist: (wanted: boolean) => Effect.Effect<void>
+  /** Upper bound of the retry delay after a failed hold RPC. */
+  readonly retryCapMillis: () => number
+}
+
+/** @internal */
+export const makeEntityKeepAlive = (options: EntityKeepAliveOptions): EntityKeepAlive => {
+  const latch = Latch.makeUnsafe(true)
+  let holders = 0
+  let wanted = options.wanted
+  let hold: Fiber.Fiber<void, unknown> | undefined
+
+  // A safeguard only: production probes never saw a rejected hold.
+  const runHold = Effect.tryPromise(() => options.startHold()).pipe(
+    Effect.tapError((error) => Effect.logWarning("Entity keep-alive hold failed, retrying", error)),
+    Effect.retry(
+      Schedule.exponential(100).pipe(
+        Schedule.modifyDelay(({ duration }) =>
+          Effect.succeed(Duration.min(duration, Duration.millis(options.retryCapMillis())))
+        ),
+        Schedule.jittered
+      )
+    )
+  )
+
+  const restore = () => {
+    if (!wanted || hold !== undefined) return
+    latch.closeUnsafe()
+    const fiber = Effect.runFork(runHold)
+    hold = fiber
+    fiber.addObserver(() => {
+      if (hold === fiber) hold = undefined
+    })
+  }
+
+  const release = () => {
+    if (hold === undefined) return
+    hold.interruptUnsafe()
+    hold = undefined
+    latch.openUnsafe()
+  }
+
+  const setWanted = (next: boolean) => {
+    if (wanted === next) return
+    wanted = next
+    // Mailbox writes wait for an open user transaction, so writing inline
+    // would deadlock `Entity.keepAlive` called inside `withTransaction`.
+    Effect.runFork(
+      Effect.suspend(() => options.persist(next)).pipe(
+        Effect.andThen(Effect.sync(() => {
+          if (!next && !wanted) release()
+        })),
+        Effect.catchCause((cause) => Effect.logError("Entity keep-alive persistence failed", cause))
+      )
+    )
+  }
+
+  const update = (enabled: boolean): Effect.Effect<void> =>
+    Effect.sync(() => {
+      if (enabled) {
+        holders++
+        setWanted(true)
+        // Also restarts a hold that ended without a release.
+        restore()
+        return
+      }
+      // With no holders in memory the flag may still be set: a fresh object
+      // after a restart has count 0 while its stored row says 1.
+      if (holders > 0) holders--
+      if (holders === 0) setWanted(false)
+    })
+
+  return {
+    update,
+    await: latch.await,
+    resetHolders: () => {
+      holders = 0
+    },
+    restore
+  }
+}