@effect-agent/platform-cloudflare 0.1.0-beta.9 → 0.1.0-beta.91

package/src/internal/message-delivery.ts

@@ -0,0 +1,152 @@
+import { Clock, Context, Deferred, Effect, Layer, Option, Ref, Semaphore, Stream } from "effect";
+import { type ThreadId } from "effect-agent/identifiers";
+import {
+  MessageDeliveryDriver,
+  MessageDeliveryError,
+  MessageDeliveryStore,
+} from "effect-agent/message-delivery";
+import { WakeScheduler } from "effect-agent/wake-scheduler";
+
+import { DurableAlarmError, ThreadMessageDelivery, ThreadMutationGate } from "../Alarm.ts";
+import { ThreadObjectPlacement } from "../CloudflareBindings.ts";
+import { CloudflareDurableRuntimeConfig } from "../CloudflareConfig.ts";
+
+/** Every write prearms its owner; the delivery due index owns its recovery deadline. */
+export const guardedMessageDeliveryStoreLayer = Layer.effect(
+  MessageDeliveryStore,
+  Effect.gen(function* () {
+    const store = yield* MessageDeliveryStore;
+    const mutations = yield* ThreadMutationGate;
+    const wakes = yield* WakeScheduler;
+    const { ownsThread } = yield* ThreadObjectPlacement;
+    // Reconstructed as unknown on every incarnation. The gate prevents a racing read from
+    // caching an empty deadline across a write; SQL remains the recovery authority.
+    const deadline = yield* Ref.make<number | null | undefined>(undefined);
+    const cacheGate = yield* Semaphore.make(1);
+
+    const local = <A, E>(
+      owner: ThreadId | undefined,
+      body: Effect.Effect<A, E>,
+    ): Effect.Effect<A, E | MessageDeliveryError> =>
+      owner === undefined || ownsThread(owner)
+        ? body
+        : Effect.fail(
+            MessageDeliveryError.make({ reason: "validation", operation: "message owner" }),
+          );
+
+    const mutate = <A, E>(body: Effect.Effect<A, E>) =>
+      mutations
+        .withMutation(
+          cacheGate.withPermit(Ref.set(deadline, undefined).pipe(Effect.andThen(body))),
+          // A foreign receipt changing does not make the source ledger actionable. Keep the
+          // prearm and producer gate so eviction and a racing pass cannot lose delivery work.
+          { invalidatesRecovery: false },
+        )
+        .pipe(
+          Effect.catchTag("DurableAlarmError", () =>
+            MessageDeliveryError.make({ reason: "storage", operation: "prearm message delivery" }),
+          ),
+        );
+
+    const nextDeadline = cacheGate.withPermit(
+      Effect.gen(function* () {
+        const cached = yield* Ref.get(deadline);
+
+        if (cached !== undefined) return cached;
+        const current = yield* store.nextDeadline();
+
+        yield* Ref.set(deadline, current);
+
+        return current;
+      }),
+    );
+
+    return MessageDeliveryStore.of({
+      limits: store.limits,
+      maxStoredValueBytes: store.maxStoredValueBytes,
+      insert: (record) =>
+        local(
+          record.key.ownerThreadId,
+          mutate(store.insert(record)).pipe(
+            Effect.tap(() => wakes.notify(record.key.ownerThreadId)),
+          ),
+        ),
+      get: (key) => local(key.ownerThreadId, store.get(key)),
+      list: (request) => local(request.ownerThreadId, store.list(request)),
+      change: (key, change) => local(key.ownerThreadId, mutate(store.change(key, change))),
+      // Only the trusted physical-owner pump omits an owner. All returned keys still
+      // pass placement validation before the driver may dispatch any of the wave.
+      due: (nowMillis, limit, owner) =>
+        local(owner, store.due(nowMillis, limit, owner)).pipe(
+          Effect.filterOrFail(
+            (keys) => keys.every((key) => ownsThread(key.ownerThreadId)),
+            () => MessageDeliveryError.make({ reason: "validation", operation: "message owner" }),
+          ),
+        ),
+      nextDeadline: (owner) =>
+        local(owner, owner === undefined ? nextDeadline : store.nextDeadline(owner)),
+    });
+  }),
+);
+
+/** Message progress shares the native alarm slot without blocking source runtime work. */
+export const threadMessageDeliveryLayer = Layer.effectContext(
+  Effect.gen(function* () {
+    const driver = yield* MessageDeliveryDriver;
+    const store = yield* MessageDeliveryStore;
+    const wakes = yield* WakeScheduler;
+    const config = yield* CloudflareDurableRuntimeConfig;
+
+    const failure = (operation: string) => () =>
+      DurableAlarmError.make({
+        operation,
+        message: "Durable message recovery remains pending",
+      });
+
+    const drain = Effect.gen(function* () {
+      const deadline = yield* store.nextDeadline();
+
+      if (deadline !== null && deadline <= (yield* Clock.currentTimeMillis)) {
+        yield* driver.runDue();
+      }
+    }).pipe(Effect.mapError(failure("drain message delivery")));
+
+    return Context.make(ThreadMessageDelivery, {
+      drain,
+      drainUntil: Effect.fn("ThreadMessageDelivery.drainUntil")(function* (
+        finished: Deferred.Deferred<void>,
+      ) {
+        // One scoped subscription covers every logical lane in this physical owner.
+        // Acquire it before reading durable deadlines; hints remain droppable.
+        const notified = (yield* Stream.toPull(wakes.wakes)).pipe(Effect.catch(() => Effect.never));
+
+        // Always finish one wave; source completion prevents starting subsequent waves.
+        yield* Effect.gen(function* () {
+          yield* drain;
+
+          const deadline = yield* store
+            .nextDeadline()
+            .pipe(Effect.mapError(failure("read message deadline")));
+
+          // The index includes unfinished waves, lease expiry, retry and settlement polls.
+          // Yield at least one millisecond for an already-due deadline instead of spinning.
+          const delay =
+            deadline === null
+              ? config.wakeScanInterval
+              : Math.min(
+                  config.wakeScanInterval,
+                  Math.max(1, deadline - (yield* Clock.currentTimeMillis)),
+                );
+
+          yield* Effect.raceFirst(
+            Deferred.await(finished),
+            Effect.raceFirst(notified, Effect.sleep(delay)),
+          );
+        }).pipe(Effect.repeat({ until: () => Deferred.isDone(finished) }));
+      }, Effect.scoped),
+      pendingDeadline: store
+        .nextDeadline()
+        .pipe(Effect.map(Option.fromNullishOr), Effect.mapError(failure("read message deadline"))),
+    });
+  }),
+);

package/src/internal/prepared-admission.ts

@@ -0,0 +1,116 @@
+import { Effect, Layer } from "effect";
+import { type DurableSubmitAgent } from "effect-agent/durable-agent-runtime";
+import { type AgentId } from "effect-agent/identifiers";
+import { PreparedInputAdmission } from "effect-agent/prepared-input-admission";
+import { PersistedJson } from "effect-agent/records";
+import {
+  type ScheduledEnvelope,
+  ScheduledInputAdmission,
+  ScheduledInputRetryable,
+  ScheduledInputRefused,
+  ScheduleStorageError,
+} from "effect-agent/schedule";
+import { type PreparedInput } from "effect-agent/subscription";
+
+import { CloudflareThreadClient, type ThreadClientError } from "../CloudflareThreadClient.ts";
+
+const passthroughAgent = (agentId: AgentId): DurableSubmitAgent<typeof PersistedJson> => ({
+  definition: { id: agentId, input: PersistedJson },
+});
+
+/** Ordinary prepared admission through one freshly addressed Thread Object call. */
+export const cloudflarePreparedInputAdmissionLayer: Layer.Layer<
+  PreparedInputAdmission,
+  never,
+  CloudflareThreadClient
+> = Layer.effect(
+  PreparedInputAdmission,
+  Effect.gen(function* () {
+    const client = yield* CloudflareThreadClient;
+
+    return PreparedInputAdmission.of({
+      submissionStatus: (receipt) =>
+        client
+          .submissionStatus(receipt)
+          .pipe(Effect.mapError(() => ScheduledInputRetryable.make({ reason: "storage" }))),
+      submit: (envelope) =>
+        client
+          .submit(passthroughAgent(envelope.agentId), envelope.input, {
+            threadId: envelope.threadId,
+            principal: envelope.deliveryPrincipal,
+            idempotencyKey: envelope.admissionKey,
+            ...(envelope.admissionGroup === undefined
+              ? {}
+              : { admissionGroup: envelope.admissionGroup }),
+            ...(envelope.admissionFence === undefined
+              ? {}
+              : { admissionFence: envelope.admissionFence }),
+            ...(envelope.workerAdmission === undefined
+              ? {}
+              : { workerAdmission: envelope.workerAdmission }),
+            ...(envelope.messageAdmission === undefined
+              ? {}
+              : { messageAdmission: envelope.messageAdmission }),
+            definitions: envelope.definitions,
+          })
+          .pipe(
+            Effect.catchTags({
+              AdmissionConflict: () =>
+                ScheduleStorageError.make({ operation: "prepared admission", reason: "corrupt" }),
+              AdmissionLimitExceeded: () => ScheduledInputRetryable.make({ reason: "capacity" }),
+              ThreadClientError: (error: ThreadClientError) =>
+                ScheduledInputRetryable.make({
+                  reason: error.overloaded === true ? "capacity" : "transport",
+                }),
+              HostProtocolError: () => ScheduledInputRetryable.make({ reason: "ambiguous" }),
+              AdmissionPolicyError: (error) =>
+                error.reason === "refused"
+                  ? ScheduledInputRefused.make({ code: error.code })
+                  : ScheduledInputRetryable.make({
+                      reason: error.reason === "occupied" ? "capacity" : "storage",
+                    }),
+              LedgerError: () => ScheduledInputRetryable.make({ reason: "storage" }),
+              ThreadStoreError: () => ScheduledInputRetryable.make({ reason: "storage" }),
+              DurableAlarmError: () => ScheduledInputRetryable.make({ reason: "storage" }),
+              AgentInputError: () =>
+                ScheduleStorageError.make({ operation: "prepared admission", reason: "corrupt" }),
+              DigestError: () =>
+                ScheduleStorageError.make({ operation: "prepared admission", reason: "corrupt" }),
+              ThreadNotMaterialized: () => ScheduledInputRetryable.make({ reason: "storage" }),
+              AppendConflict: () => ScheduledInputRetryable.make({ reason: "ambiguous" }),
+              FenceRejected: () => ScheduledInputRetryable.make({ reason: "ambiguous" }),
+              DurableRuntimeFailpointError: () =>
+                ScheduledInputRetryable.make({ reason: "ambiguous" }),
+            }),
+          ),
+    });
+  }),
+);
+
+const preparedFromSchedule = (envelope: ScheduledEnvelope): PreparedInput => ({
+  schemaVersion: 1,
+  threadId: envelope.threadId,
+  deliveryPrincipal: envelope.deliveryPrincipal,
+  ...(envelope.admissionGroup === undefined ? {} : { admissionGroup: envelope.admissionGroup }),
+  ...(envelope.admissionFence === undefined ? {} : { admissionFence: envelope.admissionFence }),
+  agentId: envelope.agentId,
+  definitions: envelope.definitions,
+  input: envelope.input,
+  inputDigest: envelope.inputDigest,
+  admissionKey: envelope.admissionKey,
+  authorization: envelope.authorization,
+});
+
+/** Compatibility adapter retaining Scheduling's public admission port. */
+export const cloudflareScheduledInputAdmissionLayer: Layer.Layer<
+  ScheduledInputAdmission,
+  never,
+  PreparedInputAdmission
+> = Layer.effect(
+  ScheduledInputAdmission,
+  Effect.map(PreparedInputAdmission, (admission) =>
+    ScheduledInputAdmission.of({
+      submit: (envelope) => admission.submit(preparedFromSchedule(envelope)),
+    }),
+  ),
+);

package/src/internal/progress-wait.ts

@@ -0,0 +1,121 @@
+import { Context, Deferred, Effect, Layer, Ref, type Scope } from "effect";
+
+/** Cancellation tombstones are bounded hints, never durable authority. */
+const MAX_CANCELLATION_TOMBSTONES = 1_024;
+
+type ActiveRegistration = ReadonlySet<Deferred.Deferred<void>>;
+type Registration = ActiveRegistration | "cancelled";
+type Registrations = ReadonlyMap<string, Registration>;
+
+/**
+ * Per-incarnation cancellation registry for long-lived progress RPCs. The public runtime owns
+ * the actual wake registration; this host-only registry lets an interrupted Worker Effect ask
+ * the Object to interrupt its scoped wait before the Worker execution context itself ends.
+ */
+export class ProgressWaitRegistry extends Context.Service<
+  ProgressWaitRegistry,
+  {
+    /** Register a Scope-owned cancellation signal, observing any early cancel tombstone. */
+    readonly subscribe: (
+      waiterId: string,
+    ) => Effect.Effect<Effect.Effect<void>, never, Scope.Scope>;
+    /** Cancel every attempt and retain a bounded tombstone for later transport attempts. */
+    readonly cancel: (waiterId: string) => Effect.Effect<void>;
+  }
+>()("@effect-agent/platform-cloudflare/ProgressWaitRegistry") {
+  static readonly layer: Layer.Layer<ProgressWaitRegistry> = Layer.effect(
+    ProgressWaitRegistry,
+    Effect.gen(function* () {
+      const registrations = yield* Ref.make<Registrations>(new Map());
+
+      const remove = (waiterId: string, deferred: Deferred.Deferred<void>) =>
+        Ref.update(registrations, (current) => {
+          const existing = current.get(waiterId);
+
+          if (existing === undefined || existing === "cancelled" || !existing.has(deferred)) {
+            return current;
+          }
+          const next = new Map(current);
+          const active = new Set(existing);
+
+          active.delete(deferred);
+          if (active.size === 0) {
+            next.delete(waiterId);
+          } else {
+            next.set(waiterId, active);
+          }
+
+          return next;
+        });
+
+      const subscribe = Effect.fn("ProgressWaitRegistry.subscribe")(
+        (waiterId: string): Effect.Effect<Effect.Effect<void>, never, Scope.Scope> =>
+          Effect.gen(function* () {
+            const deferred = yield* Deferred.make<void>();
+
+            yield* Effect.addFinalizer(() => remove(waiterId, deferred));
+
+            const cancelled = yield* Ref.modify(registrations, (current) => {
+              const existing = current.get(waiterId);
+              const next = new Map(current);
+
+              if (existing === "cancelled") {
+                return [true, current] as const;
+              }
+              const active = new Set(existing ?? []);
+
+              active.add(deferred);
+              next.set(waiterId, active);
+
+              return [false, next] as const;
+            });
+
+            return { cancelled, deferred };
+          }).pipe(
+            Effect.map(({ cancelled, deferred }) =>
+              cancelled ? Effect.void : Deferred.await(deferred),
+            ),
+          ),
+      );
+
+      // Updating the registry and completing captured signals form one nonblocking operation;
+      // interruption between them must not strand attempts removed from the active registry.
+      const cancel = Effect.fn("ProgressWaitRegistry.cancel")(function* (waiterId: string) {
+        const waiters = yield* Ref.modify(
+          registrations,
+          (current): readonly [ReadonlyArray<Deferred.Deferred<void>>, Registrations] => {
+            const existing = current.get(waiterId);
+
+            if (existing === "cancelled") return [[], current] as const;
+            const next = new Map(current);
+
+            // A retry may arrive after an active attempt was cancelled. Retain the same
+            // tombstone used for early cancellation, ordered by cancellation time.
+            next.delete(waiterId);
+            next.set(waiterId, "cancelled");
+            let tombstones = 0;
+
+            for (const registration of next.values()) {
+              if (registration === "cancelled") tombstones += 1;
+            }
+            if (tombstones > MAX_CANCELLATION_TOMBSTONES) {
+              for (const [id, registration] of next) {
+                if (registration !== "cancelled") continue;
+                next.delete(id);
+                break;
+              }
+            }
+
+            return [existing === undefined ? [] : [...existing], next] as const;
+          },
+        );
+
+        yield* Effect.forEach(waiters, (waiter) => Deferred.succeed(waiter, undefined), {
+          discard: true,
+        });
+      }, Effect.uninterruptible);
+
+      return ProgressWaitRegistry.of({ subscribe, cancel });
+    }),
+  );
+}

package/src/internal/transport.ts

@@ -0,0 +1,44 @@
+import {
+  ThreadPortTransport,
+  portTransportFailure,
+} from "@effect-agent/storage-cloudflare/port-routing";
+import { Effect, Layer } from "effect";
+
+import { callThreadObject, ThreadObjectNamespace } from "../CloudflareBindings.ts";
+
+/**
+ * `ThreadPortTransport` over native Durable Object JS RPC (decision D-P6-3): one
+ * `portCall(envelope)` on the stub of the Object that owns the addressed Thread
+ * (`namespace.idFromName(threadId)` — the identity rule, plan §1.2). The envelopes are
+ * already Schema-encoded JSON, so the RPC boundary carries only structured-cloneable values;
+ * the protocol module stays transport-agnostic and fetch-with-JSON remains the documented
+ * fallback carrier.
+ *
+ * Every delivery problem — stub construction, RPC rejection, overload, deploy-in-progress —
+ * surfaces as `PortTransportError` (preserving the platform stub's own `retryable` signal
+ * when present) and NEVER as a fabricated answer: on `resolveAdmission` the routing layer
+ * turns exactly this error into `AdmissionIndeterminate` (SUB-031).
+ */
+export const threadPortTransportLayer: Layer.Layer<
+  ThreadPortTransport,
+  never,
+  ThreadObjectNamespace
+> = Layer.effect(ThreadPortTransport)(
+  Effect.gen(function* () {
+    const namespace = yield* ThreadObjectNamespace;
+
+    return ThreadPortTransport.of({
+      call: (threadId, request) =>
+        callThreadObject(
+          threadId,
+          (target) => target.portCall(request),
+          (cause) => portTransportFailure(threadId, cause),
+        ).pipe(
+          Effect.provideService(ThreadObjectNamespace, namespace),
+          Effect.withSpan("CloudflarePortTransport.call", {
+            attributes: { threadId },
+          }),
+        ),
+    });
+  }),
+);