@effect/platform-cloudflare 0.0.0-stage → 4.1.3

package/src/internal/entitySql.ts

@@ -0,0 +1,60 @@
+/**
+ * The entity Durable Object's SQLite exposed to entity handlers as
+ * `DurableObjectSqlClient`.
+ *
+ * A user transaction holds `storage.transaction()` open across Effect
+ * suspensions, and every write on the object's single SQLite connection lands
+ * inside it. Another handler resumed from inside the transaction could save
+ * its reply there and lose it to the user's rollback, so mailbox writes wait
+ * on the same gate as user transactions.
+ *
+ * @internal
+ */
+import type { DurableObjectStorage } from "@cloudflare/workers-types"
+import * as SqliteClient from "@effect/sql-sqlite-do/SqliteClient"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Reactivity from "effect/reactivity/Reactivity"
+import type * as Scope from "effect/Scope"
+import * as Semaphore from "effect/Semaphore"
+import type * as SqlClient from "effect/sql/SqlClient"
+import { DurableObjectSqlClient } from "../CloudflareCluster.ts"
+
+/** @internal */
+export interface EntitySql {
+  /** Builds the client for one handler build, closed with that build's scope. */
+  readonly make: Effect.Effect<Context.Context<DurableObjectSqlClient>, never, Scope.Scope>
+  /** Runs a mailbox write once no user transaction is open. */
+  readonly guard: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+}
+
+const InUserTransaction = Context.Reference<boolean>(
+  "@effect/platform-cloudflare/internal/entitySql/InUserTransaction",
+  { defaultValue: () => false }
+)
+
+/** @internal */
+export const makeEntitySql = (storage: DurableObjectStorage): EntitySql => {
+  const gate = Semaphore.makeUnsafe(1)
+
+  const make = Effect.map(
+    Effect.provideServiceEffect(SqliteClient.make({ storage }), Reactivity.Reactivity, Reactivity.make),
+    (client) => {
+      // Nested transactions reuse the outer storage transaction, so only the
+      // outermost one takes the gate.
+      const withTransaction = client.withTransaction
+      const gated: SqlClient.SqlClient["withTransaction"] = (effect) =>
+        Effect.withFiber((fiber) =>
+          fiber.getRef(InUserTransaction)
+            ? withTransaction(effect)
+            : Semaphore.withPermit(gate, withTransaction(Effect.provideService(effect, InUserTransaction, true)))
+        )
+      return Context.make(DurableObjectSqlClient, Object.assign(client, { withTransaction: gated }))
+    }
+  )
+
+  return {
+    make,
+    guard: (effect) => Semaphore.withPermit(gate, effect)
+  }
+}

package/src/internal/entityStorage.ts

@@ -0,0 +1,168 @@
+/**
+ * Storage glue for the entity Durable Object constructor. The constructor must
+ * stay cheap: open SQLite, ensure the mailbox tables, and re-arm the single
+ * alarm. No user handlers are built here.
+ *
+ * @internal
+ */
+import type { DurableObjectStorage, SqlStorage } from "@cloudflare/workers-types"
+import * as Effect from "effect/Effect"
+import * as Result from "effect/Result"
+
+/** @internal */
+export type EntityAlarm = Pick<DurableObjectStorage, "getAlarm" | "setAlarm">
+
+type DeliverAtRow = {
+  readonly deliver_at: number | null
+}
+
+/**
+ * Runs a synchronous storage effect inside `transactionSync`. A defect throws
+ * out of the callback and rolls the transaction back; a typed failure happens
+ * before any write in the mailbox operations, so it is carried out as a plain
+ * failure.
+ *
+ * @internal
+ */
+export const withTransaction = <A, E>(
+  storage: Pick<DurableObjectStorage, "transactionSync">,
+  effect: Effect.Effect<A, E>
+): Effect.Effect<A, E> =>
+  Effect.suspend(() => {
+    const result = storage.transactionSync(() => Effect.runSync(Effect.result(effect)))
+    return Result.isSuccess(result) ? Effect.succeed(result.success) : Effect.fail(result.failure)
+  })
+
+const ddl = [
+  `CREATE TABLE IF NOT EXISTS cluster_messages (
+    request_id TEXT PRIMARY KEY,
+    message_id TEXT UNIQUE,
+    envelope TEXT NOT NULL,
+    discard INTEGER NOT NULL DEFAULT 0,
+    processed INTEGER NOT NULL DEFAULT 0,
+    last_reply_id TEXT,
+    deliver_at INTEGER,
+    reply_to TEXT
+  )`,
+  `CREATE TABLE IF NOT EXISTS cluster_replies (
+    reply_id TEXT PRIMARY KEY,
+    request_id TEXT NOT NULL,
+    reply TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    sequence INTEGER,
+    acked INTEGER NOT NULL DEFAULT 0,
+    UNIQUE (request_id, sequence)
+  )`,
+  `CREATE INDEX IF NOT EXISTS cluster_messages_deliver_at_idx
+    ON cluster_messages (processed, deliver_at)`,
+  `CREATE INDEX IF NOT EXISTS cluster_replies_unacked_idx
+    ON cluster_replies (request_id) WHERE kind = 'Chunk' AND acked = 0`,
+  // One row: whether the entity wants keep-alive across restarts, and the
+  // encoded name for wakes that arrive without one.
+  `CREATE TABLE IF NOT EXISTS cluster_entity_state (
+    id INTEGER PRIMARY KEY CHECK (id = 0),
+    keep_alive INTEGER NOT NULL DEFAULT 0,
+    name TEXT
+  )`
+]
+
+/** @internal */
+export const ensureEntityStorage = (sql: SqlStorage): void => {
+  for (const statement of ddl) {
+    sql.exec(statement)
+  }
+}
+
+/** @internal */
+export const earliestDeliverAt = (sql: SqlStorage): number | undefined => {
+  const rows = sql.exec<DeliverAtRow>(
+    "SELECT min(deliver_at) AS deliver_at FROM cluster_messages WHERE processed = 0 AND deliver_at IS NOT NULL"
+  ).toArray()
+  return rows[0]?.deliver_at ?? undefined
+}
+
+/** @internal */
+export const armAlarm = (alarm: EntityAlarm, deliverAt: number): Effect.Effect<void> =>
+  Effect.promise(() => alarm.getAlarm()).pipe(
+    Effect.flatMap((current) =>
+      current === null || current > deliverAt
+        ? Effect.promise(() => alarm.setAlarm(deliverAt))
+        : Effect.void
+    )
+  )
+
+type EntityStateRow = {
+  readonly keep_alive: number
+  readonly name: string | null
+}
+
+/** @internal */
+export interface EntityState {
+  readonly keepAlive: boolean
+  readonly name: string | undefined
+}
+
+/** @internal */
+export const loadEntityState = (sql: SqlStorage): EntityState => {
+  const row = sql.exec<EntityStateRow>("SELECT keep_alive, name FROM cluster_entity_state WHERE id = 0").toArray()[0]
+  return { keepAlive: row?.keep_alive === 1, name: row?.name ?? undefined }
+}
+
+/** @internal */
+export const saveKeepAlive = (sql: SqlStorage, enabled: boolean): Effect.Effect<void> =>
+  Effect.sync(() => {
+    sql.exec(
+      `INSERT INTO cluster_entity_state (id, keep_alive) VALUES (0, ?)
+       ON CONFLICT (id) DO UPDATE SET keep_alive = excluded.keep_alive`,
+      enabled ? 1 : 0
+    )
+  })
+
+/** @internal */
+export const rememberEntityName = (sql: SqlStorage, name: string): void => {
+  sql.exec(
+    `INSERT INTO cluster_entity_state (id, name) VALUES (0, ?)
+     ON CONFLICT (id) DO UPDATE SET name = excluded.name`,
+    name
+  )
+}
+
+type UnprocessedRow = {
+  readonly request_id: string
+  readonly deliver_at: number | null
+}
+
+/**
+ * The single alarm time covering every reason to wake this entity: the
+ * earliest due row, `now` for an unprocessed row nothing is running, and a
+ * heartbeat while a row is in flight or keep-alive is wanted. An in-flight row
+ * counts as a heartbeat rather than `now`, so a long handler does not keep
+ * re-firing the alarm.
+ *
+ * @internal
+ */
+export const nextAlarmAt = (
+  sql: SqlStorage,
+  options: {
+    readonly now: number
+    readonly heartbeatMillis: number
+    readonly isRunning: (requestId: string) => boolean
+  }
+): number | undefined => {
+  let next = Infinity
+  let heartbeat = loadEntityState(sql).keepAlive
+  const rows = sql.exec<UnprocessedRow>(
+    "SELECT request_id, deliver_at FROM cluster_messages WHERE processed = 0"
+  ).toArray()
+  for (const row of rows) {
+    if (options.isRunning(row.request_id)) {
+      heartbeat = true
+      continue
+    }
+    next = Math.min(next, row.deliver_at === null ? options.now : Math.max(row.deliver_at, options.now))
+  }
+  if (heartbeat) {
+    next = Math.min(next, options.now + options.heartbeatMillis)
+  }
+  return Number.isFinite(next) ? next : undefined
+}

package/src/internal/entityWire.ts

@@ -0,0 +1,204 @@
+/** @internal */
+import * as EntityAddress from "effect/cluster/EntityAddress"
+import * as EntityId from "effect/cluster/EntityId"
+import * as EntityType from "effect/cluster/EntityType"
+import * as Envelope from "effect/cluster/Envelope"
+import * as Reply from "effect/cluster/Reply"
+import * as ShardId from "effect/cluster/ShardId"
+import type * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Headers from "effect/http/Headers"
+import * as Rpc from "effect/rpc/Rpc"
+import * as RpcSchema from "effect/rpc/RpcSchema"
+import * as Schema from "effect/Schema"
+import type { EntityInvokeResult } from "../CloudflareDurableObjectPrograms.ts"
+import type { EntityRegistration } from "./entityRegistry.ts"
+
+type EncodedRequest = Extract<Envelope.Encoded, { readonly _tag: "Request" }>
+
+/**
+ * The result of a `ClusterEntity.invoke` RPC. Constructed in the Durable
+ * Object as this schema's `Type` (its JSON encoding is the identity) and
+ * decoded once on the Worker side.
+ *
+ * @internal
+ */
+export const InvokeResult = Schema.Union([
+  Schema.Struct({
+    _tag: Schema.Literal("Success"),
+    requestId: Schema.String,
+    replies: Schema.Array(Schema.String)
+  }),
+  Schema.Struct({ _tag: Schema.Literal("MailboxFull") }),
+  Schema.Struct({ _tag: Schema.Literal("EncodedMessageTooLarge") }),
+  Schema.Struct({ _tag: Schema.Literal("AskDeduplicatedToTell") })
+]) satisfies Schema.Codec<EntityInvokeResult>
+
+/** @internal */
+export const decodeInvokeResult = (value: unknown): Effect.Effect<EntityInvokeResult> =>
+  Effect.orDie(Schema.decodeUnknownEffect(InvokeResult)(value))
+
+const EnvelopePeek = Schema.Struct({ tag: Schema.optional(Schema.String) })
+
+/**
+ * Reads the RPC tag out of a stored envelope without decoding the payload,
+ * for rows whose full decode already failed.
+ *
+ * @internal
+ */
+export const peekEnvelopeTag = (envelopeText: string): Effect.Effect<string | undefined> =>
+  Schema.decodeUnknownEffect(EnvelopePeek)(JSON.parse(envelopeText)).pipe(
+    Effect.match({ onFailure: () => undefined, onSuccess: ({ tag }) => tag })
+  )
+
+/** @internal */
+export const runWith = <A>(
+  effect: Effect.Effect<A, any, any>,
+  context: Context.Context<never>
+): Effect.Effect<A> => effect.pipe(Effect.provideContext(context as any), Effect.orDie) as Effect.Effect<A>
+
+// Cached per rpc so the derived AST stays stable and the memoized parser
+// compiler can hit on repeated chunks.
+const chunkValuesCache = new WeakMap<Rpc.AnyWithProps, Schema.Top | undefined>()
+
+const chunkValuesCodec = (rpc: Rpc.AnyWithProps): Schema.Top | undefined => {
+  if (chunkValuesCache.has(rpc)) return chunkValuesCache.get(rpc)
+  const codec = RpcSchema.isStreamSchema(rpc.successSchema)
+    ? Schema.toCodecJson(Schema.NonEmptyArray(rpc.successSchema.success))
+    : undefined
+  chunkValuesCache.set(rpc, codec)
+  return codec
+}
+
+/** @internal */
+export const encodeRequest = (options: {
+  readonly requestId: string
+  readonly address: EntityAddress.EntityAddress
+  readonly tag: string
+  readonly payload: unknown
+  readonly headers: unknown
+  readonly traceId?: string | undefined
+  readonly spanId?: string | undefined
+  readonly sampled?: boolean | undefined
+}): string =>
+  JSON.stringify({
+    _tag: "Request",
+    requestId: options.requestId,
+    address: {
+      shardId: options.address.shardId,
+      entityType: options.address.entityType,
+      entityId: options.address.entityId
+    },
+    tag: options.tag,
+    payload: options.payload,
+    headers: options.headers,
+    ...(options.traceId === undefined ? undefined : {
+      traceId: options.traceId,
+      spanId: options.spanId,
+      sampled: options.sampled
+    })
+  })
+
+/** @internal */
+export const decodeRequest = (
+  registration: EntityRegistration,
+  envelopeText: string
+): Effect.Effect<Envelope.Request.Any> =>
+  runWith(
+    Effect.gen(function*() {
+      const encoded = JSON.parse(envelopeText) as EncodedRequest
+      if (encoded._tag !== "Request" || typeof encoded.requestId !== "string") {
+        return yield* Effect.die("Expected an encoded Request envelope")
+      }
+      const rpc = registration.entity.protocol.requests.get(encoded.tag) as Rpc.AnyWithProps | undefined
+      if (rpc === undefined) return yield* Effect.die(`Unknown entity RPC tag: ${encoded.tag}`)
+      const payload = yield* Schema.decodeUnknownEffect(Schema.toCodecJson(rpc.payloadSchema))(encoded.payload)
+      return Envelope.makeRequest({
+        requestId: encoded.requestId as any,
+        address: EntityAddress.make({
+          shardId: ShardId.make(encoded.address.shardId.group, encoded.address.shardId.id),
+          entityType: EntityType.make(encoded.address.entityType),
+          entityId: EntityId.make(encoded.address.entityId)
+        }),
+        tag: encoded.tag,
+        payload,
+        headers: Headers.fromInput(encoded.headers),
+        ...(encoded.traceId === undefined ? undefined : {
+          traceId: encoded.traceId,
+          spanId: encoded.spanId!,
+          sampled: encoded.sampled!
+        })
+      }) as Envelope.Request.Any
+    }),
+    registration.context
+  )
+
+/** @internal */
+export const encodeReplyFor = (
+  registration: EntityRegistration,
+  rpc: Rpc.AnyWithProps,
+  reply: Reply.Reply<any>
+): Effect.Effect<string> => {
+  if (reply._tag === "WithExit") {
+    return runWith(
+      Effect.map(
+        Schema.encodeUnknownEffect(Schema.toCodecJson(Rpc.exitSchema(rpc)))(reply.exit),
+        (exit) => JSON.stringify({ _tag: "WithExit", requestId: String(reply.requestId), id: String(reply.id), exit })
+      ),
+      registration.context
+    )
+  }
+  const codec = chunkValuesCodec(rpc)
+  if (codec === undefined) {
+    return Effect.die(`Expected a stream RPC: ${rpc._tag}`)
+  }
+  return runWith(
+    Effect.map(
+      Schema.encodeUnknownEffect(codec)(reply.values),
+      (values) =>
+        JSON.stringify({
+          _tag: "Chunk" as const,
+          requestId: String(reply.requestId),
+          id: String(reply.id),
+          sequence: reply.sequence,
+          values
+        })
+    ),
+    registration.context
+  )
+}
+
+/** @internal */
+export const decodeReplyFor = (
+  rpc: Rpc.AnyWithProps,
+  context: Context.Context<never>,
+  replyText: string
+): Effect.Effect<Reply.Reply<any>> => {
+  const encoded = JSON.parse(replyText) as Reply.Encoded
+  if (encoded._tag === "WithExit") {
+    return runWith(
+      Effect.map(
+        Schema.decodeUnknownEffect(Schema.toCodecJson(Rpc.exitSchema(rpc)))(encoded.exit),
+        (exit) => new Reply.WithExit({ requestId: encoded.requestId as any, id: encoded.id as any, exit: exit as any })
+      ),
+      context
+    )
+  }
+  const codec = chunkValuesCodec(rpc)
+  if (codec === undefined) {
+    return Effect.die(`Expected a stream RPC: ${rpc._tag}`)
+  }
+  return runWith(
+    Effect.map(
+      Schema.decodeUnknownEffect(codec)(encoded.values),
+      (values) =>
+        new Reply.Chunk({
+          requestId: encoded.requestId as any,
+          id: encoded.id as any,
+          sequence: encoded.sequence,
+          values: values as any
+        })
+    ),
+    context
+  )
+}

package/src/internal/queueRuntime.ts

@@ -0,0 +1,174 @@
+/**
+ * The durable queue Durable Object runtime. One object holds one named queue:
+ * items live in SQLite, and every lease arms the single alarm at its expiry so
+ * an item whose worker died is redelivered once the watchdog fires. Takers
+ * with no available item wait in memory until an offer, a retry, or a lease
+ * expiry wakes them; a crash or hibernation drops those waiters, whose broken
+ * RPCs are retried from the Worker side. An interrupted taker cancels its wait
+ * by taker id, releasing an item that was already leased to it.
+ *
+ * `take` is idempotent per taker id: a retried take replaces the taker's
+ * waiter, or returns the item still leased to it. Leases are found by owner in
+ * SQLite, so a retry or cancel still finds its item after a restart.
+ *
+ * @internal
+ */
+import type { SqlStorage } from "@cloudflare/workers-types"
+import * as Effect from "effect/Effect"
+import { armAlarm, type EntityAlarm } from "./entityStorage.ts"
+import {
+  completeItem,
+  earliestLeaseExpiry,
+  ensureQueueStorage,
+  expireLeases,
+  extendLease,
+  failItem,
+  leasedItem,
+  leaseNextItem,
+  offerItem,
+  type QueueItem,
+  releaseItem,
+  releaseOwnedItem
+} from "./queueStorage.ts"
+
+/** @internal */
+export interface QueueRuntimeOptions {
+  readonly sql: SqlStorage
+  readonly alarm: EntityAlarm
+  readonly now: () => number
+}
+
+/** @internal */
+export interface QueueRuntime {
+  readonly offer: (
+    id: string,
+    element: string,
+    delayMillis?: number,
+    deduplicate?: "untilExecuted" | "untilRemoved"
+  ) => Promise<void>
+  readonly take: (takerId: string, maxAttempts: number, leaseMillis: number) => Promise<QueueItem>
+  readonly cancelTake: (takerId: string) => Promise<void>
+  readonly complete: (id: string, takerId: string) => Promise<void>
+  readonly fail: (
+    id: string,
+    lastFailure: string,
+    takerId: string,
+    terminal?: boolean,
+    retryDelayMillis?: number
+  ) => Promise<void>
+  readonly release: (id: string, takerId: string) => Promise<void>
+  readonly extend: (id: string, leaseMillis: number, takerId: string) => Promise<void>
+  readonly runAlarm: () => Promise<void>
+}
+
+interface Waiter {
+  readonly takerId: string
+  readonly maxAttempts: number
+  readonly leaseMillis: number
+  resolve: (item: QueueItem) => void
+}
+
+/** @internal */
+export const makeQueueRuntime = (options: QueueRuntimeOptions): QueueRuntime => {
+  const sql = options.sql
+  ensureQueueStorage(sql)
+
+  const waiters: Array<Waiter> = []
+
+  // Waiters differ in maxAttempts, so one waiter finding nothing does not mean
+  // a later one will; every waiter gets its own lease attempt. Leasing stays
+  // fully synchronous so concurrent wake-ups cannot interleave on the waiter
+  // list; only the final alarm arm is asynchronous.
+  const wakeWaiters = Effect.suspend(() => {
+    const now = options.now()
+    let index = 0
+    while (index < waiters.length) {
+      const waiter = waiters[index]
+      const item = leaseNextItem(sql, now, now + waiter.leaseMillis, waiter.maxAttempts, waiter.takerId)
+      if (item === undefined) {
+        index++
+        continue
+      }
+      waiters.splice(index, 1)
+      waiter.resolve(item)
+    }
+    // Include initial visibility deadlines even when no taker is waiting.
+    const earliest = earliestLeaseExpiry(sql)
+    return earliest === undefined ? Effect.void : armAlarm(options.alarm, earliest)
+  })
+
+  const mutateAndWake = (mutate: () => void): Promise<void> =>
+    Effect.runPromise(Effect.suspend(() => {
+      mutate()
+      return wakeWaiters
+    }))
+
+  return {
+    offer: (id, element, delayMillis = 0, deduplicate) =>
+      mutateAndWake(() => {
+        offerItem(sql, id, element, delayMillis > 0 ? options.now() + delayMillis : null, deduplicate)
+      }),
+
+    // The taker joins the waiter list and the shared wake pass leases to it,
+    // so an immediate take and a woken one follow the same code path.
+    take: (takerId, maxAttempts, leaseMillis) => {
+      // A broken take RPC is retried with the same taker id. The retry must
+      // not leave a second waiter that leases an item nobody handles.
+      const leased = leasedItem(sql, takerId, options.now())
+      if (leased !== undefined) return Promise.resolve(leased)
+      const existing = waiters.find((waiter) => waiter.takerId === takerId)
+      const item = new Promise<QueueItem>((resolve) => {
+        if (existing === undefined) {
+          waiters.push({ takerId, maxAttempts, leaseMillis, resolve })
+        } else {
+          existing.resolve = resolve
+        }
+      })
+      return Effect.runPromise(wakeWaiters).then(() => item)
+    },
+
+    cancelTake: (takerId) => {
+      const index = waiters.findIndex((waiter) => waiter.takerId === takerId)
+      if (index >= 0) {
+        waiters.splice(index, 1)
+        return Promise.resolve()
+      }
+      // The cancel can race the delivery; release an item already leased to
+      // the taker instead of stranding it.
+      return mutateAndWake(() => {
+        releaseOwnedItem(sql, takerId, options.now())
+      })
+    },
+
+    complete: (id, takerId) => Promise.resolve(completeItem(sql, id, takerId)),
+
+    fail: (id, lastFailure, takerId, terminal = false, retryDelayMillis = 0) =>
+      mutateAndWake(() => {
+        failItem(
+          sql,
+          id,
+          lastFailure,
+          takerId,
+          terminal,
+          retryDelayMillis > 0 ? options.now() + retryDelayMillis : null
+        )
+      }),
+
+    release: (id, takerId) =>
+      mutateAndWake(() => {
+        releaseItem(sql, id, takerId)
+      }),
+
+    extend: (id, leaseMillis, takerId) => Promise.resolve(extendLease(sql, id, options.now() + leaseMillis, takerId)),
+
+    runAlarm: () =>
+      Effect.runPromise(
+        Effect.gen(function*() {
+          expireLeases(sql, options.now())
+          yield* wakeWaiters
+          const next = earliestLeaseExpiry(sql)
+          if (next !== undefined) yield* armAlarm(options.alarm, next)
+        })
+      )
+  }
+}