alchemy 2.0.0-beta.36 → 2.0.0-beta.37

package/src/Cloudflare/Workers/Worker.ts

@@ -2,6 +2,7 @@ import type * as cf from "@cloudflare/workers-types";
 import cloudflareVite from "@distilled.cloud/cloudflare-vite-plugin";
 import * as workers from "@distilled.cloud/cloudflare/workers";
 import * as zones from "@distilled.cloud/cloudflare/zones";
+import * as Cause from "effect/Cause";
 import * as Context from "effect/Context";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
@@ -12,6 +13,7 @@ import * as Path from "effect/Path";
 import * as Redacted from "effect/Redacted";
 import * as Schedule from "effect/Schedule";
 import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -33,11 +35,16 @@ import {
   type PlatformProps,
   type Rpc,
 } from "../../Platform.ts";
+import { isYieldableEffectLike } from "../../Util/effect.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource, type ResourceBinding } from "../../Resource.ts";
 import * as Serverless from "../../Serverless/index.ts";
 import { Stack } from "../../Stack.ts";
 import type { AiGateway } from "../AiGateway/AiGateway.ts";
+import {
+  isAnalyticsEngineDataset,
+  type AnalyticsEngineDataset,
+} from "../AnalyticsEngine/AnalyticsEngineDataset.ts";
 import {
   isArtifacts as isArtifactsBinding,
   type Artifacts as ArtifactsBinding,
@@ -76,7 +83,14 @@ import {
 import { workersHttpHandler } from "./HttpServer.ts";
 import { LocalWorkerProvider } from "./LocalWorkerProvider.ts";
 import { Request } from "./Request.ts";
-import { makeRpcStub } from "./Rpc.ts";
+import {
+  encodeRpcError,
+  ErrorTag,
+  makeRpcStub,
+  toRpcStream,
+  type RpcErrorEnvelope,
+  type RpcStreamEnvelope,
+} from "./Rpc.ts";
 import { WorkerBundle } from "./WorkerBundle.ts";
 import { createWorkerName } from "./WorkerName.ts";
 
@@ -187,9 +201,11 @@ export type WorkerBindingResource =
   | KVNamespace
   | CloudflareQueue
   | AiGateway
+  | AnalyticsEngineDataset
   | ArtifactsBinding
   | ImagesBinding
   | Hyperdrive
+  | Worker
   | DurableObjectNamespaceLike<any>;
 
 export type WorkerBindings = {
@@ -280,6 +296,12 @@ export interface WorkerProps<
   >;
   exports?: string[];
   bindings?: Bindings;
+  /**
+   * Cron expressions that trigger the Worker's scheduled handler.
+   *
+   * Pass an empty array to remove all Cron Triggers.
+   */
+  crons?: string[];
   /**
    * One or more custom hostnames (e.g. `"app.example.com"`) to bind to this
    * Worker. The Cloudflare Zone is inferred from the hostname — the zone must
@@ -318,6 +340,7 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<
     durableObjectNamespaces: Record<string, string>;
     accountId: string;
     domains: { hostname: string; id: string; zoneId: string }[];
+    crons: string[];
     hash?: {
       assets: string | undefined;
       bundle: string | undefined;
@@ -327,6 +350,7 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<
   {
     bindings?: WorkerBinding[];
     containers?: { className: string }[];
+    crons?: string[];
     hyperdrives?: Record<string, Required<HyperdriveDevOrigin>>;
   },
   Providers
@@ -725,8 +749,11 @@ export const Worker: Platform<
         const bindingEff = props.bindings?.[bindingName] as
           | WorkerBindingResource
           | Effect.Effect<WorkerBindingResource>;
-        const binding = Effect.isEffect(bindingEff)
-          ? yield* bindingEff
+        // Bindings can be passed as a plain resource value, an Effect that
+        // yields a resource, or an effect-class (e.g. a `Cloudflare.Worker`
+        // class). Resolve the yieldable forms before deriving binding metadata.
+        const binding = isYieldableEffectLike(bindingEff)
+          ? ((yield* bindingEff as Effect.Effect<unknown>) as WorkerBindingResource)
           : bindingEff;
 
         const bindingMeta: InputProps<WorkerBinding> | undefined = isAssets(
@@ -747,56 +774,68 @@ export const Worker: Platform<
                   type: "images",
                   name: bindingName,
                 }
-              : isDurableObjectNamespaceLike(binding)
+              : isAnalyticsEngineDataset(binding)
                 ? {
-                    type: "durable_object_namespace",
+                    type: "analytics_engine",
                     name: bindingName,
-                    className: binding.className ?? binding.name,
+                    dataset: binding.dataset,
                   }
-                : binding.Type === "Cloudflare.D1Database"
+                : isDurableObjectNamespaceLike(binding)
                   ? {
-                      type: "d1",
-                      id: binding.databaseId,
+                      type: "durable_object_namespace",
                       name: bindingName,
+                      className: binding.className ?? binding.name,
                     }
-                  : binding.Type === "Cloudflare.R2Bucket"
+                  : binding.Type === "Cloudflare.D1Database"
                     ? {
-                        type: "r2_bucket",
+                        type: "d1",
+                        id: binding.databaseId,
                         name: bindingName,
-                        bucketName: binding.bucketName,
-                        jurisdiction: binding.jurisdiction.pipe(
-                          Output.map((jurisdiction) =>
-                            jurisdiction === "default"
-                              ? undefined
-                              : jurisdiction,
-                          ),
-                        ),
                       }
-                    : binding.Type === "Cloudflare.KVNamespace"
+                    : binding.Type === "Cloudflare.R2Bucket"
                       ? {
-                          type: "kv_namespace",
+                          type: "r2_bucket",
                           name: bindingName,
-                          namespaceId: binding.namespaceId,
+                          bucketName: binding.bucketName,
+                          jurisdiction: binding.jurisdiction.pipe(
+                            Output.map((jurisdiction) =>
+                              jurisdiction === "default"
+                                ? undefined
+                                : jurisdiction,
+                            ),
+                          ),
                         }
-                      : binding.Type === "Cloudflare.Queue"
+                      : binding.Type === "Cloudflare.KVNamespace"
                         ? {
-                            type: "queue",
+                            type: "kv_namespace",
                             name: bindingName,
-                            queueName: binding.queueName,
+                            namespaceId: binding.namespaceId,
                           }
-                        : binding.Type === "Cloudflare.AiGateway"
+                        : binding.Type === "Cloudflare.Queue"
                           ? {
-                              type: "ai",
+                              type: "queue",
                               name: bindingName,
+                              queueName: binding.queueName,
                             }
-                          : binding.Type === "Cloudflare.Hyperdrive"
+                          : binding.Type === "Cloudflare.AiGateway"
                             ? {
-                                type: "hyperdrive",
+                                type: "ai",
                                 name: bindingName,
-                                id: binding.hyperdriveId,
                               }
-                            : // TODO(sam): handle others
-                              undefined;
+                            : binding.Type === "Cloudflare.Hyperdrive"
+                              ? {
+                                  type: "hyperdrive",
+                                  name: bindingName,
+                                  id: binding.hyperdriveId,
+                                }
+                              : isWorker(binding)
+                                ? {
+                                    type: "service",
+                                    name: bindingName,
+                                    service: binding.workerName,
+                                  }
+                                : // TODO(sam): handle others
+                                  undefined;
 
         if (bindingMeta) {
           yield* resource.bind`${bindingName}`({
@@ -812,6 +851,7 @@ export const Worker: Platform<
     const listeners: Effect.Effect<Serverless.FunctionListener>[] = [];
     const exports: Record<string, any> = {};
     const env: Record<string, any> = {};
+    let userShape: Record<string, unknown> | undefined;
 
     const ctx = {
       Type: WorkerTypeId,
@@ -878,7 +918,14 @@ export const Worker: Platform<
         }),
       serve: <Req = never>(
         handler: HttpEffect<Req> | Effect.Effect<HttpEffect<Req>>,
-      ) => ctx.listen(workersHttpHandler(handler)),
+        options?: { shape?: Record<string, unknown> },
+      ) => {
+        // Capture the user's full default-export shape so `exports` can
+        // expose any non-handler methods on it as RPC methods on the
+        // deployed `WorkerEntrypoint` subclass — see `__rpc__` below.
+        if (options?.shape) userShape = options.shape;
+        return ctx.listen(workersHttpHandler(handler));
+      },
       listen: ((
         handler:
           | Serverless.FunctionListener
@@ -898,6 +945,35 @@ export const Worker: Platform<
           concurrency: "unbounded",
         });
         const services = yield* Effect.context();
+
+        // Provide the per-request runtime layer (services + `WorkerExecutionContext`
+        // + a fresh `ExecutionContext`/`Scope`) to a user effect, then run it.
+        // This is the bridge between Cloudflare's request-time callback and
+        // the user's Effect-native handler. Used by both the standard
+        // `handle()` dispatch (fetch/scheduled/…) and the per-RPC dispatchers
+        // below — keeping them on a single layer-provision path.
+        const runUserEffect = <A, E>(
+          eff: Effect.Effect<A, E>,
+          context: cf.ExecutionContext,
+        ): Promise<Exit.Exit<A, E>> => {
+          const scope = Scope.makeUnsafe();
+          return eff
+            .pipe(
+              Effect.provideContext(services),
+              Scope.provide(scope),
+              Effect.provide(Layer.succeed(WorkerExecutionContext, context)),
+              Effect.provide(
+                Layer.succeed(ExecutionContext, { scope, cache: {} }),
+              ),
+              Effect.runPromiseExit,
+            )
+            .finally(() =>
+              context.waitUntil(
+                Effect.runPromise(Scope.close(scope, Exit.void)),
+              ),
+            );
+        };
+
         const handle =
           (type: WorkerEvent["type"]) =>
           (request: any, env: unknown, context: cf.ExecutionContext) => {
@@ -911,36 +987,76 @@ export const Worker: Platform<
             for (const handler of handlers) {
               const eff = handler(event);
               if (Effect.isEffect(eff)) {
-                const scope = Scope.makeUnsafe();
-                return eff
-                  .pipe(
-                    Effect.provideContext(services),
-                    Scope.provide(scope),
-                    Effect.provide(
-                      Layer.succeed(WorkerExecutionContext, context),
-                    ),
-                    Effect.provide(
-                      Layer.succeed(ExecutionContext, {
-                        scope,
-                        cache: {},
-                      }),
-                    ),
-                    Effect.runPromise,
-                  )
-                  .finally(() =>
-                    context.waitUntil(
-                      Effect.runPromise(Scope.close(scope, Exit.void)),
-                    ),
-                  );
+                return runUserEffect(
+                  eff as Effect.Effect<unknown, unknown>,
+                  context,
+                ).then((exit) => {
+                  if (exit._tag === "Success") return exit.value;
+                  throw Cause.squash(exit.cause);
+                });
               }
             }
             return Promise.reject(new Error("No event handler found"));
           };
+
+        // RPC method dispatchers — one per non-handler method on the user's
+        // shape. Each dispatcher is invoked by the WorkerEntrypoint bridge
+        // as `dispatcher(args, ctx)`: `args` are the user-facing call args,
+        // `ctx` is the `this.ctx` that Cloudflare hands the bridge per RPC
+        // request. The dispatcher runs the user effect with the same runtime
+        // layer the fetch path uses, then envelope-encodes the result so
+        // `Effect.fail` round-trips as `RpcErrorEnvelope` and `Stream` as
+        // `RpcStreamEnvelope` (consumers wrap the binding with
+        // `toPromiseApi`/`bindWorker` to decode).
+        const exportedHandlerSet = new Set<string>(ExportedHandlerMethods);
+        const rpcDispatchers: Record<
+          string,
+          (args: unknown[], ctx: cf.ExecutionContext) => Promise<unknown>
+        > = {};
+        if (userShape) {
+          for (const [name, value] of Object.entries(userShape)) {
+            if (exportedHandlerSet.has(name)) continue;
+            if (typeof value !== "function") continue;
+            rpcDispatchers[name] = async (
+              args: unknown[],
+              context: cf.ExecutionContext,
+            ) => {
+              const result = (value as (...a: unknown[]) => unknown)(...args);
+              if (!Effect.isEffect(result)) return result;
+              const exit = await runUserEffect(
+                result as Effect.Effect<unknown, unknown>,
+                context,
+              );
+              if (exit._tag === "Success") {
+                if (Stream.isStream(exit.value)) {
+                  return await Effect.runPromise(
+                    toRpcStream(exit.value) as Effect.Effect<RpcStreamEnvelope>,
+                  );
+                }
+                return exit.value;
+              }
+              const failReason = exit.cause.reasons.find(Cause.isFailReason);
+              if (failReason) {
+                return {
+                  _tag: ErrorTag,
+                  error: encodeRpcError(failReason.error),
+                } satisfies RpcErrorEnvelope;
+              }
+              const dieReason = exit.cause.reasons.find(Cause.isDieReason);
+              throw (
+                dieReason?.defect ??
+                new Error("RPC method failed with an unexpected cause")
+              );
+            };
+          }
+        }
+
         return {
           ...exports,
           default: Object.fromEntries(
             ExportedHandlerMethods.map((method) => [method, handle(method)]),
           ),
+          __rpc__: rpcDispatchers,
         };
       }),
     };
@@ -953,7 +1069,10 @@ export const bindWorker = Effect.fnUntraced(function* <Shape, Req = never>(
     | (Worker & Rpc<Shape>)
     | Effect.Effect<Worker & Rpc<Shape>, never, Req>,
 ) {
-  const worker = Effect.isEffect(workerEff) ? yield* workerEff : workerEff;
+  // Worker classes and regular Effects are both yieldable here.
+  const worker = isYieldableEffectLike(workerEff)
+    ? yield* workerEff as Effect.Effect<Worker & Rpc<Shape>, never, Req>
+    : workerEff;
   const self = yield* Worker;
   yield* self.bind`${worker}`({
     bindings: [
@@ -965,13 +1084,14 @@ export const bindWorker = Effect.fnUntraced(function* <Shape, Req = never>(
     ],
   });
 
-  const workerBinding = WorkerEnvironment.asEffect().pipe(
-    Effect.map((env) => env[worker.LogicalId]),
+  // `bindWorker` runs at *init* phase (both at plantime and at runtime
+  // cold-start). `WorkerEnvironment` only exists at exec phase on the
+  // deployed worker, so we hand `makeRpcStub` an `Effect<stub>` that
+  // resolves the binding lazily on each method call.
+  const stubEff = WorkerEnvironment.asEffect().pipe(
+    Effect.map((env) => (env as Record<string, unknown>)[worker.LogicalId]),
   );
-
-  const fetcher = workerBinding.pipe(Effect.map(fromCloudflareFetcher));
-  // TODO(sam): update makeRpcStub to support lazily evaluating the Effect<Fetcher>
-  return makeRpcStub<Shape>(fetcher);
+  return makeRpcStub<Shape>(stubEff);
 });
 
 export class BindWorkerPolicy extends Binding.Policy<
@@ -1039,6 +1159,12 @@ function getDurableObjectBindings(
   );
 }
 
+export function getCronBindings(
+  bindings: ReadonlyArray<ResourceBinding<Worker["Binding"]>>,
+) {
+  return Array.from(new Set(bindings.flatMap((b) => b.data.crons ?? [])));
+}
+
 function getDurableObjectTagMap(tags: ReadonlyArray<string>) {
   return Object.fromEntries(
     tags.flatMap((tag) => {
@@ -1089,9 +1215,11 @@ export const LiveWorkerProvider = () =>
       const createScriptSubdomain = yield* workers.createScriptSubdomain;
       const deleteScript = yield* workers.deleteScript;
       const getScriptSubdomain = yield* workers.getScriptSubdomain;
+      const getScriptSchedule = yield* workers.getScriptSchedule;
       const getScriptSettings = yield* workers.getScriptScriptAndVersionSetting;
       const getSubdomain = yield* workers.getSubdomain;
       const putScript = yield* workers.putScript;
+      const putScriptSchedule = yield* workers.putScriptSchedule;
       const putDomain = yield* workers.putDomain;
       const listDomains = yield* workers.listDomains;
       const deleteDomain = yield* workers.deleteDomain;
@@ -1139,6 +1267,60 @@ export const LiveWorkerProvider = () =>
               ),
             );
 
+      const normalizeCrons = (crons: string[] | undefined): string[] =>
+        Array.from(new Set(crons ?? []));
+
+      const getWorkerCrons = (scriptName: string) =>
+        getScriptSchedule({
+          accountId,
+          scriptName,
+        }).pipe(
+          Effect.map((response) =>
+            normalizeCrons(response.schedules.map((schedule) => schedule.cron)),
+          ),
+          Effect.catchTag("WorkerNotFound", () => Effect.succeed([])),
+        );
+
+      const reconcileCrons = (
+        scriptName: string,
+        desired: string[],
+        previous: string[],
+        session: ScopedPlanStatusSession,
+      ) =>
+        Effect.gen(function* () {
+          const live = yield* getWorkerCrons(scriptName);
+          const desiredSorted = [...desired].sort();
+          const liveSorted = [...live].sort();
+          const changed =
+            desiredSorted.length !== liveSorted.length ||
+            desiredSorted.some((cron, index) => cron !== liveSorted[index]);
+
+          if (!changed) return live;
+
+          if (desired.length > 0 || previous.length > 0 || live.length > 0) {
+            yield* session.note(
+              `Reconciling Cron Triggers (${desired.length}) ...`,
+            );
+          }
+
+          const result = yield* putScriptSchedule({
+            accountId,
+            scriptName,
+            body: desired.map((cron) => ({ cron })),
+          }).pipe(
+            Effect.retry({
+              while: (error: { _tag?: string }) =>
+                error?._tag === "WorkerNotFound",
+              schedule: Schedule.exponential(200).pipe(
+                Schedule.both(Schedule.recurs(15)),
+              ),
+            }),
+          );
+          return normalizeCrons(
+            result.schedules.map((schedule) => schedule.cron),
+          );
+        });
+
       /**
        * Infer the Cloudflare Zone ID for a given hostname by listing the
        * account's zones and matching the hostname against each zone's name —
@@ -1958,6 +2140,12 @@ export const LiveWorkerProvider = () =>
           desiredDomains,
           previousDomains,
         );
+        const crons = yield* reconcileCrons(
+          name,
+          normalizeCrons([...getCronBindings(bindings), ...(news.crons ?? [])]),
+          output?.crons ?? [],
+          session,
+        );
         return {
           workerId: worker.id ?? name,
           workerName: name,
@@ -1970,6 +2158,7 @@ export const LiveWorkerProvider = () =>
           durableObjectNamespaces,
           accountId,
           domains,
+          crons,
           hash,
         } satisfies Worker["Attributes"];
       });
@@ -2025,7 +2214,13 @@ export const LiveWorkerProvider = () =>
 
       return Worker.Provider.of({
         stables: ["workerId", "workerName"],
-        diff: Effect.fnUntraced(function* ({ id, news, olds, output }) {
+        diff: Effect.fnUntraced(function* ({
+          id,
+          news,
+          olds,
+          output,
+          newBindings,
+        }) {
           if (!isResolved(news)) return undefined;
           if ((output?.accountId ?? accountId) !== accountId) {
             return { action: "replace" };
@@ -2047,7 +2242,23 @@ export const LiveWorkerProvider = () =>
           const domainsChanged =
             newDomains.length !== oldDomains.length ||
             newDomains.some((d, i) => d !== oldDomains[i]);
-          if (domainsChanged || (yield* hasChanged(id, news, output))) {
+          const newCrons = normalizeCrons([
+            ...(Array.isArray(newBindings)
+              ? getCronBindings(
+                  newBindings as ResourceBinding<Worker["Binding"]>[],
+                )
+              : []),
+            ...(news.crons ?? []),
+          ]).sort();
+          const oldCrons = [...(output?.crons ?? [])].sort();
+          const cronsChanged =
+            newCrons.length !== oldCrons.length ||
+            newCrons.some((cron, index) => cron !== oldCrons[index]);
+          if (
+            domainsChanged ||
+            cronsChanged ||
+            (yield* hasChanged(id, news, output))
+          ) {
             return {
               action: "update",
               stables:
@@ -2173,6 +2384,7 @@ export const LiveWorkerProvider = () =>
             durableObjectNamespaces,
             accountId,
             domains: [],
+            crons: [],
           } satisfies Worker["Attributes"];
         }),
         read: Effect.fnUntraced(
@@ -2204,6 +2416,7 @@ export const LiveWorkerProvider = () =>
                 service: workerName,
               }).pipe(Effect.map((r) => r.result ?? [])),
             ]);
+            const crons = yield* getWorkerCrons(workerName);
             yield* Effect.logInfo(
               `Cloudflare Worker read: found ${workerName}`,
             );
@@ -2224,6 +2437,7 @@ export const LiveWorkerProvider = () =>
                   ? [{ id: d.id, hostname: d.hostname, zoneId: d.zoneId }]
                   : [],
               ),
+              crons,
             } satisfies Worker["Attributes"];
 
             // Centralized ownership decision: the engine routes `read`'s

package/src/Cloudflare/Workers/WorkerBundle.ts

@@ -158,11 +158,11 @@ import * as Logger from "effect/Logger";
 import * as Context from "effect/Context";
 import * as Stream from "effect/Stream";
 
-import { env, DurableObject${hasWfClasses ? ", WorkflowEntrypoint" : ""} } from "cloudflare:workers";
+import { env, DurableObject, WorkerEntrypoint${hasWfClasses ? ", WorkflowEntrypoint" : ""} } from "cloudflare:workers";
 import { MinimumLogLevel } from "effect/References";
 import { NodeServices } from "@effect/platform-node";
 import { Stack } from "alchemy/Stack";
-import { WorkerEnvironment, makeDurableObjectBridge${hasWfClasses ? ", makeWorkflowBridge" : ""}, ExportedHandlerMethods } from "alchemy/Cloudflare";
+import { WorkerEnvironment, makeDurableObjectBridge, makeWorkerBridge${hasWfClasses ? ", makeWorkflowBridge" : ""}, ExportedHandlerMethods } from "alchemy/Cloudflare";
 
 import entry from "${importPath}";
 
@@ -223,10 +223,20 @@ let exportsPromise;
 // we cache it synchronously (??=) to guarnatee only one initialization ever happens
 const getExports = () => (exportsPromise ??= Effect.runPromise(exportsEffect))
 const getExport = (name) => getExports().then(exports => exports[name]?.make)
-const worker = () => getExports().then(exports => exports.default)
+const getDefault = () => getExports().then(exports => exports.default)
+const getRpc = () => getExports().then(exports => exports.__rpc__ ?? {})
 
-export default Object.fromEntries(ExportedHandlerMethods.map(
-  method => [method, async (...args) => (await worker())[method](...args)])
+// Bridge the user's default-export shape onto a real \`WorkerEntrypoint\`
+// subclass so Cloudflare service bindings can dispatch both the standard
+// handler methods (fetch, scheduled, …) and any user-defined RPC methods.
+// RPC method results are wire-encoded by \`runtimeContext.exports\`;
+// consumers unwrap them with \`Cloudflare.toPromiseApi(env.X)\` (Promise
+// API) or \`bindWorker(WorkerClass)\` (Effect API).
+export default makeWorkerBridge(
+  WorkerEntrypoint,
+  ExportedHandlerMethods,
+  getDefault,
+  getRpc,
 );
 
 // export class proxy stubs for Durable Objects and Workflows