alchemy 2.0.0-beta.22 → 2.0.0-beta.24

package/src/Cloudflare/Workers/DurableObjectNamespace.ts

@@ -301,6 +301,51 @@ export class DurableObjectNamespaceScope extends Context.Service<
  * };
  * ```
  *
+ * @section Returning Streams from RPC
+ * RPC methods can return an Effect `Stream` and the caller will see
+ * the chunks as they're produced. Combine with `Stream.schedule` to
+ * pace emission, or with `Stream.fromQueue` to bridge an inbound
+ * subscription.
+ *
+ * @example Streaming sequential numbers
+ * ```typescript
+ * import * as Schedule from "effect/Schedule";
+ * import * as Stream from "effect/Stream";
+ *
+ * return {
+ *   tick: (n: number) =>
+ *     Stream.iterate(0, (i) => i + 1).pipe(
+ *       Stream.take(n),
+ *       Stream.schedule(Schedule.spaced("100 millis")),
+ *     ),
+ * };
+ * ```
+ *
+ * @example Forwarding the stream as a chunked HTTP response
+ * ```typescript
+ * // in a Worker fetch handler
+ * const counter = counters.getByName("tick");
+ * const stream = counter.tick(5).pipe(
+ *   Stream.map((i) => `${i}\n`),
+ *   Stream.encodeText,
+ * );
+ * return HttpServerResponse.stream(stream, {
+ *   headers: { "content-type": "text/plain" },
+ * });
+ * ```
+ *
+ * @section Worker → DO HTTP forwarding
+ * In addition to RPC methods, the typed stub exposes a `fetch`
+ * method that forwards an `HttpServerRequest` straight to the DO.
+ * The DO's own `fetch` Effect produces the response — useful for
+ * WebSocket upgrades and other request-shaped interactions.
+ *
+ * @example Forwarding an HTTP request to a DO
+ * ```typescript
+ * const room = rooms.getByName(roomId);
+ * return yield* room.fetch(request);
+ * ```
+ *
  * @section Accessing Instance State
  * Each Durable Object instance has its own transactional key-value
  * storage via `Cloudflare.DurableObjectState`. Use `storage.get` and
@@ -356,14 +401,66 @@ export class DurableObjectNamespaceScope extends Context.Service<
  * ```
  *
  * @example Recovering sessions after hibernation
+ * Place the rehydration loop **inside the inner `Effect.gen`** so
+ * it runs every time the DO instance is reconstructed (including
+ * after Cloudflare wakes the DO from hibernation).
+ *
  * ```typescript
- * const state = yield* Cloudflare.DurableObjectState;
- * const sockets = yield* state.getWebSockets();
+ * return Effect.gen(function* () {
+ *   const state = yield* Cloudflare.DurableObjectState;
+ *   const sessions = new Map<string, Cloudflare.DurableWebSocket>();
+ *
+ *   // Rehydrate the in-memory session map after hibernation.
+ *   for (const socket of yield* state.getWebSockets()) {
+ *     const data = socket.deserializeAttachment<{ id: string }>();
+ *     if (data) sessions.set(data.id, socket);
+ *   }
  *
- * for (const socket of sockets) {
- *   const data = socket.deserializeAttachment<{ id: string }>();
- *   // re-populate your session map
- * }
+ *   return {
+ *     fetch: Effect.gen(function* () {
+ *       const [response, socket] = yield* Cloudflare.upgrade();
+ *       const id = crypto.randomUUID();
+ *       socket.serializeAttachment({ id });
+ *       sessions.set(id, socket);
+ *       return response;
+ *     }),
+ *     webSocketMessage: Effect.fnUntraced(function* (socket, message) {
+ *       const text =
+ *         typeof message === "string" ? message : new TextDecoder().decode(message);
+ *       for (const peer of sessions.values()) {
+ *         yield* peer.send(text);
+ *       }
+ *     }),
+ *   };
+ * });
+ * ```
+ *
+ * @section Scheduled Alarms
+ * Each Durable Object can have a single alarm timestamp. Alchemy
+ * layers a small SQLite-backed scheduler on top via
+ * `Cloudflare.scheduleEvent` and `Cloudflare.processScheduledEvents`,
+ * so you can register many named events with arbitrary payloads and
+ * fire them from a single `alarm` handler.
+ *
+ * @example Scheduling and processing events
+ * ```typescript
+ * // schedule from a request or message handler
+ * yield* Cloudflare.scheduleEvent(
+ *   "reminder-1",
+ *   new Date(Date.now() + 60_000),
+ *   { message: "your meeting starts in a minute" },
+ * );
+ *
+ * return {
+ *   alarm: () =>
+ *     Effect.gen(function* () {
+ *       const fired = yield* Cloudflare.processScheduledEvents;
+ *       for (const event of fired) {
+ *         const payload = event.payload as { message: string };
+ *         // dispatch / broadcast / persist...
+ *       }
+ *     }),
+ * };
  * ```
  *
  * @section Using from a Worker

package/src/Cloudflare/Workers/LocalWorkerProvider.ts

@@ -0,0 +1,93 @@
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Provider from "../../Provider.ts";
+import type { ResourceBinding } from "../../Resource.ts";
+import { Stack } from "../../Stack.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import { Sidecar } from "../Local/Sidecar.ts";
+import { getCompatibility } from "./Compatibility.ts";
+import { Worker, type WorkerBinding, type WorkerProps } from "./Worker.ts";
+import { createWorkerName } from "./WorkerName.ts";
+
+export const LocalWorkerProvider = () =>
+  Provider.effect(
+    Worker,
+    Effect.gen(function* () {
+      const { accountId } = yield* CloudflareEnvironment;
+      const stack = yield* Stack;
+      const sidecar = yield* Sidecar;
+
+      const run = Effect.fn(function* (
+        id: string,
+        props: WorkerProps,
+        bindings: ResourceBinding<Worker["Binding"]>[],
+      ) {
+        const name = yield* createWorkerName(id, props.name);
+        const workerBindings: WorkerBinding[] = [];
+        const durableObjectNamespaces: Record<string, string> = {};
+        for (const { sid, data } of bindings) {
+          for (const binding of data.bindings ?? []) {
+            workerBindings.push(binding);
+            if (binding.type === "durable_object_namespace") {
+              durableObjectNamespaces[binding.name] = sid;
+            }
+          }
+        }
+        for (const [key, value] of Object.entries(props.env ?? {})) {
+          if (Redacted.isRedacted(value)) {
+            workerBindings.push({
+              type: "secret_text",
+              name: key,
+              text: Redacted.value(value),
+            });
+          } else {
+            workerBindings.push({
+              type: "plain_text",
+              name: key,
+              text: value,
+            });
+          }
+        }
+        const result = yield* sidecar.serve({
+          id,
+          name,
+          main: props.main,
+          compatibility: getCompatibility(props),
+          entry: props.isExternal
+            ? {
+                kind: "external",
+              }
+            : {
+                kind: "effect",
+                exports: (props.exports ?? {}) as any,
+              },
+          stack: { name: stack.name, stage: stack.stage },
+          bindings: workerBindings,
+          durableObjectNamespaces: Object.entries(durableObjectNamespaces).map(
+            ([className, namespaceId]) => ({
+              className,
+              uniqueKey: namespaceId,
+              sql: true,
+            }),
+          ),
+        });
+        return {
+          workerId: name,
+          workerName: name,
+          logpush: undefined,
+          url: result.address,
+          tags: [],
+          durableObjectNamespaces,
+          domains: [],
+          accountId,
+        } satisfies Worker["Attributes"];
+      });
+
+      return {
+        diff: () => Effect.succeed({ action: "update" }),
+        create: ({ id, news, bindings }) => run(id, news, bindings),
+        update: ({ id, news, bindings }) => run(id, news, bindings),
+        delete: ({ output }) => sidecar.stop(output.workerName),
+      };
+    }),
+  );

package/src/Cloudflare/Workers/Worker.ts

@@ -22,6 +22,8 @@ import { pathToFileURL } from "node:url";
 import type * as rolldown from "rolldown";
 import Sonda from "sonda/rolldown";
 import type * as vite from "vite";
+import { AdoptPolicy } from "../../AdoptPolicy.ts";
+import { AlchemyContext } from "../../AlchemyContext.ts";
 import * as Artifacts from "../../Artifacts.ts";
 import * as Binding from "../../Binding.ts";
 import {
@@ -53,6 +55,7 @@ import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import { D1Database } from "../D1/D1Database.ts";
 import { fromCloudflareFetcher } from "../Fetcher.ts";
 import type { KVNamespace } from "../KV/KVNamespace.ts";
+import { SidecarLive } from "../Local/Sidecar.ts";
 import { CloudflareLogs } from "../Logs.ts";
 import type { Providers } from "../Providers.ts";
 import type { Queue as CloudflareQueue } from "../Queue/Queue.ts";
@@ -72,6 +75,7 @@ import {
   type DurableObjectNamespaceLike,
 } from "./DurableObjectNamespace.ts";
 import { workersHttpHandler } from "./HttpServer.ts";
+import { LocalWorkerProvider } from "./LocalWorkerProvider.ts";
 import { Request } from "./Request.ts";
 import { makeRpcStub } from "./Rpc.ts";
 import { isWorkflowExport } from "./Workflow.ts";
@@ -966,7 +970,30 @@ function getDurableObjectTagMap(tags: ReadonlyArray<string>) {
   );
 }
 
+const selectLayer = <
+  LayerLive extends Layer.Layer<any, any, any>,
+  LayerDev extends Layer.Layer<any, any, any>,
+>(input: {
+  live: () => LayerLive;
+  dev: () => LayerDev;
+}): Layer.Layer<
+  Layer.Success<LayerLive | LayerDev>,
+  Layer.Error<LayerLive | LayerDev>,
+  Layer.Services<LayerLive | LayerDev> | AlchemyContext
+> =>
+  Layer.unwrap(
+    AlchemyContext.useSync((context) =>
+      context.dev ? input.dev() : input.live(),
+    ),
+  );
+
 export const WorkerProvider = () =>
+  selectLayer({
+    live: LiveWorkerProvider,
+    dev: () => Layer.provide(LocalWorkerProvider(), SidecarLive),
+  });
+
+export const LiveWorkerProvider = () =>
   Provider.effect(
     Worker,
     Effect.gen(function* () {
@@ -1094,27 +1121,83 @@ export const WorkerProvider = () =>
 
           if (desired.length === 0) return [];
 
+          const adoptEnabled = yield* Effect.serviceOption(AdoptPolicy).pipe(
+            Effect.map(Option.getOrElse(() => false)),
+          );
+
           const zoneCache = new Map<string, string>();
+
+          /**
+           * Attach `hostname` to `scriptName`, recovering from a "hostname
+           * already in use" conflict when adoption is enabled.
+           *
+           * The Cloudflare API rejects a `PUT /workers/domains` whose
+           * hostname is already registered (even when the existing entry
+           * points at the same Worker, which is exactly what happens
+           * after a state-store wipe). The SDK surfaces this as the
+           * unmatched `UnknownCloudflareError` channel because there's
+           * no dedicated error tag for it. With adoption opted-in we
+           * list domains for the hostname; if the existing entry
+           * already targets *this* Worker we adopt it in place. We
+           * never transfer a hostname off another Worker — that would
+           * silently re-route someone else's traffic.
+           */
+          const attachDomain = Effect.fnUntraced(function* (hostname: string) {
+            const zoneId = yield* inferZoneIdForHostname(hostname, zoneCache);
+            return yield* putDomain({
+              accountId,
+              hostname,
+              service: scriptName,
+              zoneId,
+            }).pipe(
+              Effect.map((res) => ({
+                hostname,
+                id: res.id ?? "",
+                zoneId: res.zoneId ?? zoneId,
+              })),
+              Effect.catchTag("UnknownCloudflareError", (err) =>
+                adoptEnabled && /already in use/i.test(err.message)
+                  ? adoptDomainIfSameService(hostname, zoneId, err)
+                  : Effect.fail(err),
+              ),
+            );
+          });
+
+          const adoptDomainIfSameService = Effect.fnUntraced(function* (
+            hostname: string,
+            zoneId: string,
+            originalError: { message: string },
+          ) {
+            const existing = yield* listDomains({
+              accountId,
+              hostname,
+            }).pipe(
+              Effect.map((r) =>
+                (r.result ?? []).find((d) => d.hostname === hostname),
+              ),
+            );
+            if (existing?.id && existing.service === scriptName) {
+              return {
+                hostname,
+                id: existing.id,
+                zoneId: existing.zoneId ?? zoneId,
+              };
+            }
+            // The hostname exists but on a different Worker. Refuse to
+            // hijack it; surface a more actionable message than the raw
+            // Cloudflare error.
+            return yield* Effect.die(
+              new Error(
+                `Cannot attach hostname '${hostname}' to Worker '${scriptName}': ` +
+                  `it is already attached to Worker '${existing?.service ?? "<unknown>"}'. ` +
+                  `Detach it from that Worker first, or pick a different hostname. ` +
+                  `(Cloudflare reported: ${originalError.message})`,
+              ),
+            );
+          });
+
           const applied = yield* Effect.all(
-            desired.map((hostname) =>
-              Effect.gen(function* () {
-                const zoneId = yield* inferZoneIdForHostname(
-                  hostname,
-                  zoneCache,
-                );
-                const res = yield* putDomain({
-                  accountId,
-                  hostname,
-                  service: scriptName,
-                  zoneId,
-                });
-                return {
-                  hostname,
-                  id: res.id ?? "",
-                  zoneId: res.zoneId ?? zoneId,
-                };
-              }),
-            ),
+            desired.map(attachDomain),
             { concurrency: "unbounded" },
           );
           return applied;

package/src/Cloudflare/Workers/WorkerBundle.ts

@@ -0,0 +1,234 @@
+import cloudflareRolldown from "@distilled.cloud/cloudflare-rolldown-plugin";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import { flow } from "effect/Function";
+import type * as Path from "effect/Path";
+import * as Stream from "effect/Stream";
+import type * as rolldown from "rolldown";
+import * as Artifacts from "../../Artifacts.ts";
+import * as Bundle from "../../Bundle/Bundle.ts";
+import { findCwdForBundle } from "../../Bundle/TempRoot.ts";
+import { Self } from "../../Self.ts";
+import {
+  isDurableObjectExport,
+  type DurableObjectExport,
+} from "./DurableObjectNamespace.ts";
+import { isWorkflowExport, type WorkflowExport } from "./Workflow.ts";
+
+export interface WorkerBundleOptions {
+  id: string;
+  main: string;
+  compatibility: {
+    date: string;
+    flags: string[];
+  };
+  entry:
+    | {
+        kind: "external";
+      }
+    | {
+        kind: "effect";
+        exports: Record<string, DurableObjectExport | WorkflowExport>;
+      };
+  stack: { name: string; stage: string };
+}
+
+export const WorkerBundle = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const context = yield* Effect.context<FileSystem.FileSystem | Path.Path>();
+  const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
+
+  const makeOptions = Effect.fnUntraced(function* (
+    options: WorkerBundleOptions,
+  ) {
+    const realMain = yield* fs.realPath(options.main).pipe(
+      Effect.mapError(
+        (cause) =>
+          new Bundle.BundleError({
+            message: `Failed to find real path for bundle: ${options.main}`,
+            cause,
+          }),
+      ),
+    );
+    const inputOptions: rolldown.InputOptions = {
+      input: realMain,
+      cwd: yield* findCwdForBundle(realMain).pipe(
+        Effect.mapError(
+          (cause) =>
+            new Bundle.BundleError({
+              message: `Failed to find cwd for bundle: ${realMain}`,
+              cause,
+            }),
+        ),
+        Effect.provide(context),
+      ),
+      plugins: [
+        cloudflareRolldown({
+          compatibilityDate: options.compatibility.date,
+          compatibilityFlags: options.compatibility.flags,
+        }),
+        options.entry.kind === "effect"
+          ? virtualEntryPlugin(
+              makeEffectVirtualEntry(options.entry.exports, options.stack),
+            )
+          : undefined,
+      ],
+      checks: {
+        // Suppress unresolved import warnings for unrelated AWS packages
+        unresolvedImport: false,
+      },
+    };
+    const outputOptions: rolldown.OutputOptions = {
+      format: "esm",
+      sourcemap: "hidden",
+      minify: true,
+      keepNames: true,
+      dir: `.alchemy/bundles/${options.id}`,
+    };
+    return { inputOptions, outputOptions };
+  });
+
+  return {
+    build: flow(
+      makeOptions,
+      Effect.flatMap((resolved) =>
+        Bundle.build(resolved.inputOptions, resolved.outputOptions),
+      ),
+      Artifacts.cached("build"),
+    ),
+    watch: flow(
+      makeOptions,
+      Stream.fromEffect,
+      Stream.flatMap((resolved) =>
+        Bundle.watch(resolved.inputOptions, resolved.outputOptions),
+      ),
+    ),
+  };
+});
+
+const makeEffectVirtualEntry = (
+  exports: Record<string, DurableObjectExport | WorkflowExport>,
+  stack: { name: string; stage: string },
+) => {
+  const durableObjectClasses: string[] = [];
+  const workflowClasses: string[] = [];
+  for (const [className, entry] of Object.entries(exports)) {
+    if (isDurableObjectExport(entry)) {
+      durableObjectClasses.push(className);
+    } else if (isWorkflowExport(entry)) {
+      workflowClasses.push(className);
+    }
+  }
+  return (importPath: string) => `import * as Config from "effect/Config";
+  import * as ConfigProvider from "effect/ConfigProvider";
+  import * as Console from "effect/Console";
+  import * as Effect from "effect/Effect";
+  import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+  import * as Layer from "effect/Layer";
+  import * as Logger from "effect/Logger";
+  import * as Context from "effect/Context";
+  import * as Stream from "effect/Stream";
+  
+  import { env, DurableObject${workflowClasses.length > 0 ? ", WorkflowEntrypoint" : ""} } from "cloudflare:workers";
+  import { MinimumLogLevel } from "effect/References";
+  import { NodeServices } from "@effect/platform-node";
+  import { Stack } from "alchemy/Stack";
+  import { WorkerEnvironment, makeDurableObjectBridge${workflowClasses.length > 0 ? ", makeWorkflowBridge" : ""}, ExportedHandlerMethods } from "alchemy/Cloudflare";
+  
+  import entry from "${importPath}";
+  
+  const tag = Context.Service("${Self.key}")
+  const layer =
+  typeof entry?.build === "function"
+  ? entry
+  : Layer.effect(tag, typeof entry?.asEffect === "function" ? entry.asEffect() : entry);
+  
+  const platform = Layer.mergeAll(
+  NodeServices.layer,
+  FetchHttpClient.layer,
+  // TODO(sam): wire this up to telemetry more directly
+  Logger.layer([Logger.consolePretty()]),
+  );
+  
+  const stack = Layer.succeed(
+  Stack,
+  {
+  name: "${stack.name}",
+  stage: "${stack.stage}",
+  bindings: {},
+  resources: {}
+  }
+  );
+  
+  const exportsEffect = tag.asEffect().pipe(
+  Effect.flatMap(func => func.ExecutionContext.exports),
+  Effect.map(exports => exports),
+  Effect.provide(
+  layer.pipe(
+  Layer.provideMerge(stack),
+  // TODO(sam): additional credentials?
+  Layer.provideMerge(platform),
+  Layer.provideMerge(
+  Layer.succeed(
+    ConfigProvider.ConfigProvider,
+    ConfigProvider.orElse(
+      ConfigProvider.fromUnknown({ ALCHEMY_PHASE: "runtime" }),
+      ConfigProvider.fromUnknown(env),
+    ),
+  )
+  ),
+  Layer.provideMerge(
+  Layer.succeed(
+    WorkerEnvironment,
+    env,
+  )
+  ),
+  Layer.provideMerge(
+  Layer.succeed(
+    MinimumLogLevel,
+    env.DEBUG ? "Debug" : "Info",
+  )
+  ),
+  )
+  ),
+  Effect.scoped
+  );
+  
+  // TODO(sam): we could kick this off during module init, but any I/O will break deploy
+  // let exportsPromise = Effect.runPromise(exportsEffect);
+  
+  // for now, we delay initializing the worker until the first request
+  let exportsPromise;
+  
+  // don't initialize the workerEffect during module init because Cloudflare does not allow I/O during module init
+  // 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)
+  
+  export default Object.fromEntries(ExportedHandlerMethods.map(
+  method => [method, async (...args) => (await worker())[method](...args)])
+  ) satisfies Required<cf.ExportedHandler>;
+  
+  // export class proxy stubs for Durable Objects and Workflows
+  ${[
+    ...(durableObjectClasses.length > 0
+      ? [
+          "const DurableObjectBridge = makeDurableObjectBridge(DurableObject, getExport);",
+          ...durableObjectClasses.map(
+            (id) =>
+              `export class ${id} extends DurableObjectBridge("${id}") {}`,
+          ),
+        ]
+      : []),
+    ...(workflowClasses.length > 0
+      ? [
+          "const WorkflowBridgeFn = makeWorkflowBridge(WorkflowEntrypoint, getExport);",
+          ...workflowClasses.map(
+            (id) => `export class ${id} extends WorkflowBridgeFn("${id}") {}`,
+          ),
+        ]
+      : []),
+  ].join("\n")}
+  `;
+};

package/src/Cloudflare/Workers/WorkerName.ts

@@ -0,0 +1,10 @@
+import * as Effect from "effect/Effect";
+import { createPhysicalName } from "../../PhysicalName.ts";
+
+export const createWorkerName = (id: string, name: string | undefined) =>
+  name
+    ? Effect.succeed(name)
+    : createPhysicalName({
+        id,
+        maxLength: 54,
+      }).pipe(Effect.map((name) => name.toLowerCase()));