alchemy 2.0.0-beta.40 → 2.0.0-beta.41

package/src/Cloudflare/Workers/WorkerRuntimeContext.ts

@@ -0,0 +1,164 @@
+import type * as cf from "@cloudflare/workers-types";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
+import type { HttpEffect } from "../../Http.ts";
+import * as Output from "../../Output.ts";
+import type * as Serverless from "../../Serverless/index.ts";
+import { makeRequestHandler } from "./HttpServer.ts";
+import {
+  ExportedHandlerMethods,
+  WorkerEnvironment,
+  WorkerTypeId,
+  type WorkerEvent,
+} from "./Worker.ts";
+
+export interface WorkerRuntimeContext extends Serverless.FunctionContext {
+  export(name: string, value: any): Effect.Effect<void>;
+  shape: () => Record<string, any>;
+}
+
+export const makeWorkerRuntimeContext = (id: string): WorkerRuntimeContext => {
+  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,
+    id,
+    env,
+    shape: () => userShape!,
+    get: (key: string) =>
+      Effect.serviceOption(WorkerEnvironment).pipe(
+        Effect.map(Option.getOrUndefined),
+        Effect.flatMap((env) =>
+          env
+            ? Effect.succeed(env[key])
+            : Effect.die("WorkerEnvironment not found"),
+        ),
+        Effect.flatMap((value) =>
+          value
+            ? Effect.succeed(value)
+            : Effect.die(`Environment variable '${key}' not found`),
+        ),
+        Effect.map((json) => {
+          try {
+            const value = JSON.parse(json);
+            // The `set` path serializes Redacted values as
+            // `{_tag: "Redacted", value: ...}`. After JSON.parse the
+            // result is a plain object — `Redacted.isRedacted` would
+            // always return `false` on it — so detect the marker shape
+            // and rebuild the Redacted wrapper. Plain values pass
+            // through unchanged.
+            if (
+              value !== null &&
+              typeof value === "object" &&
+              (value as { _tag?: unknown })._tag === "Redacted" &&
+              "value" in (value as object)
+            ) {
+              return Redacted.make((value as { value: unknown }).value);
+            }
+            return value;
+          } catch {
+            return json;
+          }
+        }),
+      ) as any,
+    set: (id: string, output: Output.Output) =>
+      Effect.sync(() => {
+        const key = id.replaceAll(/[^a-zA-Z0-9]/g, "_");
+        // Preserve `Redacted`-ness across the Output → env → Cloudflare
+        // binding boundary so the put-worker loop can deploy secrets via
+        // `secret_text` instead of leaking them as `plain_text`. The JSON
+        // payload still carries the `{_tag: "Redacted", …}` marker so the
+        // runtime `get` accessor can rebuild the wrapper after Cloudflare
+        // hands the binding back as a plain string.
+        env[key] = output.pipe(
+          Output.map((value) =>
+            Redacted.isRedacted(value)
+              ? Redacted.make(
+                  JSON.stringify({
+                    _tag: "Redacted",
+                    value: Redacted.value(value),
+                  }),
+                )
+              : JSON.stringify(value),
+          ),
+        );
+        return key;
+      }),
+    serve: <Req = never>(
+      handler: HttpEffect<Req> | Effect.Effect<HttpEffect<Req>>,
+      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(makeRequestHandler(handler));
+    },
+    listen: ((
+      handler:
+        | Serverless.FunctionListener
+        | Effect.Effect<Serverless.FunctionListener>,
+    ) =>
+      Effect.sync(() =>
+        Effect.isEffect(handler)
+          ? listeners.push(handler)
+          : listeners.push(Effect.succeed(handler)),
+      )) as any as Serverless.FunctionContext["listen"],
+    export: (name: string, value: any) =>
+      Effect.sync(() => {
+        exports[name] = value;
+      }),
+    exports: Effect.gen(function* () {
+      const handlers = yield* Effect.all(listeners, {
+        concurrency: "unbounded",
+      });
+      const services = yield* Effect.context();
+
+      const dispatch =
+        (type: WorkerEvent["type"]) =>
+        (request: any, env: unknown, context: cf.ExecutionContext) => {
+          const event: WorkerEvent = {
+            kind: "Cloudflare.Workers.WorkerEvent",
+            type,
+            input: request,
+            env,
+            context,
+          };
+          for (const handler of handlers) {
+            const eff = handler(event);
+            if (Effect.isEffect(eff)) {
+              return [eff, services];
+            }
+          }
+          return [
+            Effect.die(
+              new Error(`No event handler found for event type '${type}'`),
+            ),
+            services,
+          ];
+        };
+
+      // 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).
+
+      return {
+        ...exports,
+        default: Object.fromEntries(
+          ExportedHandlerMethods.map((method) => [method, dispatch(method)]),
+        ),
+      };
+    }),
+  };
+  return ctx;
+};

package/src/Cloudflare/Workers/WorkflowBridge.ts

@@ -0,0 +1,92 @@
+import * as Effect from "effect/Effect";
+import {
+  WorkflowEvent as WorkflowEventService,
+  type WorkflowExport,
+  type WorkflowImpl,
+  WorkflowStep,
+} from "./Workflow.ts";
+import { getWorkerExport } from "./WorkerBridge.ts";
+
+/**
+ * Create a WorkflowBridge class that extends `WorkflowEntrypoint` and
+ * delegates the `run(event, step)` call to the Effect-native workflow body
+ * registered via `worker.export(...)`.
+ *
+ * The bridge provides `WorkflowEvent` and `WorkflowStep` as Effect
+ * services so the user writes `yield* WorkflowEvent` and `yield* task(...)`
+ * instead of receiving callback parameters.
+ */
+export const makeWorkflowBridge =
+  (
+    WorkflowEntrypoint: abstract new (
+      ctx: unknown,
+      env: unknown,
+    ) => { run(event: any, step: any): Promise<unknown> },
+    {
+      entrypoint,
+      stack,
+    }: {
+      entrypoint: Effect.Effect<Record<string, any>>;
+      stack: { name: string; stage: string };
+    },
+  ) =>
+  (className: string) =>
+    class WorkflowBridge extends WorkflowEntrypoint {
+      readonly fn: Promise<WorkflowImpl<unknown, unknown>>;
+
+      constructor(ctx: unknown, env: unknown) {
+        super(ctx, env);
+
+        const { globalContext, exported } = getWorkerExport<WorkflowExport>({
+          entrypoint,
+          stack,
+          exportName: className,
+        });
+
+        this.fn = exported.pipe(
+          Effect.flatMap((wf) => wf.make(env)),
+          Effect.provide(globalContext),
+          Effect.runPromise,
+        ) as Promise<WorkflowImpl<unknown, unknown>>;
+      }
+
+      async run(event: any, step: any): Promise<unknown> {
+        const fn = await this.fn;
+        return Effect.runPromise(
+          fn(event.payload).pipe(
+            Effect.provideService(
+              WorkflowEventService,
+              wrapWorkflowEvent(event),
+            ),
+            Effect.provideService(WorkflowStep, wrapWorkflowStep(step)),
+          ) as Effect.Effect<unknown>,
+        );
+      }
+    };
+
+const wrapWorkflowEvent = (
+  event: any,
+): { payload: unknown; timestamp: Date; instanceId: string } => ({
+  payload: event.payload,
+  timestamp:
+    event.timestamp instanceof Date
+      ? event.timestamp
+      : new Date(event.timestamp),
+  instanceId: event.instanceId ?? "",
+});
+
+const wrapWorkflowStep = (step: any): WorkflowStep["Service"] => ({
+  do: <T>(name: string, effect: Effect.Effect<T>): Effect.Effect<T> =>
+    Effect.tryPromise(
+      () => step.do(name, () => Effect.runPromise(effect)) as Promise<T>,
+    ),
+  sleep: (name: string, duration: string | number): Effect.Effect<void> =>
+    Effect.tryPromise(() => step.sleep(name, duration)),
+  sleepUntil: (name: string, timestamp: Date | number): Effect.Effect<void> =>
+    Effect.tryPromise(() =>
+      step.sleepUntil(
+        name,
+        timestamp instanceof Date ? timestamp.toISOString() : timestamp,
+      ),
+    ),
+});

package/src/Cloudflare/Workers/index.ts

@@ -1,6 +1,7 @@
 export * from "./Assets.ts";
 export * from "./ConfigProvider.ts";
 export * from "./CronEventSource.ts";
+export * from "./DurableObjectBridge.ts";
 export * from "./DurableObjectNamespace.ts";
 export * from "./DurableObjectState.ts";
 export * from "./DurableObjectStorage.ts";
@@ -14,4 +15,7 @@ export * from "./Rpc.ts";
 export * from "./ScheduledEvents.ts";
 export * from "./WebSocket.ts";
 export * from "./Worker.ts";
+export * from "./WorkerBinding.ts";
+export * from "./WorkerBridge.ts";
 export * from "./Workflow.ts";
+export * from "./WorkflowBridge.ts";

package/src/Cloudflare/index.ts

@@ -1,11 +1,12 @@
-export * from "./ApiToken/index.ts";
-export * from "./Artifacts/index.ts";
 export * from "./AiGateway/index.ts";
 export * from "./AnalyticsEngine/index.ts";
+export * from "./ApiToken/index.ts";
+export * from "./Artifacts/index.ts";
 export * from "./CloudflareEnvironment.ts";
 export * from "./Container/index.ts";
 export * from "./D1/index.ts";
 export * from "./EdgeSession.ts";
+export * from "./Fetcher.ts";
 export * from "./Email/index.ts";
 export * from "./Hyperdrive/index.ts";
 export * from "./Images/index.ts";
@@ -19,3 +20,4 @@ export * from "./Tunnel/index.ts";
 export * from "./VpcService/index.ts";
 export * from "./Website/index.ts";
 export * from "./Workers/index.ts";
+export * from "./Workers/RpcAsync.ts";

package/src/Neon/Project.ts

@@ -6,11 +6,12 @@ import {
   getProjectOperation,
   listProjectBranchDatabases,
   listProjectBranches,
-  type ListProjectsOutput,
   listProjects,
+  type ListProjectsOutput,
   createProject as sdkCreateProject,
   updateProject,
 } from "@distilled.cloud/neon";
+import * as Console from "effect/Console";
 import * as Data from "effect/Data";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
@@ -586,6 +587,7 @@ export const ProjectProvider = () =>
         }),
         delete: Effect.fn(function* ({ output }) {
           yield* deleteProject({ project_id: output.projectId }).pipe(
+            Effect.tapError(Console.log),
             Effect.catchTag("NotFound", () => Effect.void),
           );
         }),

package/src/Platform.ts

@@ -7,10 +7,12 @@ import type { Scope } from "effect/Scope";
 import type { HttpClient } from "effect/unstable/http/HttpClient";
 import { SingleShotGen } from "effect/Utils";
 import type { PolicyLike } from "./Binding.ts";
+import type { ExecutionContext } from "./ExecutionContext.ts";
 import type { HttpEffect } from "./Http.ts";
 import type { InputProps } from "./Input.ts";
 import type { Provider, ProviderCollectionLike } from "./Provider.ts";
 import { Resource, type ResourceLike } from "./Resource.ts";
+import type { Rpc } from "./Rpc.ts";
 import { RuntimeContext, type BaseRuntimeContext } from "./RuntimeContext.ts";
 import { Self } from "./Self.ts";
 import type { Stack, StackServices } from "./Stack.ts";
@@ -35,13 +37,10 @@ export type Main<InitServices = never> = void | {
       >;
 };
 
-export type Rpc<Shape> = {
-  "~alchemy/rpc": Shape;
-};
-
 // services provided to the Resource
 export type PlatformServices =
   | RuntimeContext
+  | ExecutionContext
   | HttpClient
   | PolicyLike
   | Provider<any>

package/src/Rpc.ts

@@ -0,0 +1,25 @@
+import type * as Effect from "effect/Effect";
+
+export type Rpc<Shape> = {
+  "~alchemy/rpc": Shape;
+};
+
+/**
+ * Recover the user's RPC `Shape` from any of the forms a caller might pass
+ * to {@link toPromiseApi}:
+ *
+ *   - the Worker class value's type, e.g. `typeof Backend`, which extends
+ *     `Effect.Effect<Worker & Rpc<Shape>, …>`
+ *   - the unwrapped `Worker & Rpc<Shape>` type
+ *   - a bare `Shape` (when the caller types it explicitly)
+ */
+export declare namespace Rpc {
+  export type Shape<W> =
+    W extends Effect.Effect<infer R, any, any>
+      ? R extends Rpc<infer Shape>
+        ? Shape
+        : R
+      : W extends Rpc<infer Shape>
+        ? Shape
+        : W;
+}

package/src/RuntimeContext.ts

@@ -16,6 +16,7 @@ export interface BaseRuntimeContext {
     handler: HttpEffect<Req>,
     options?: { shape?: Record<string, unknown> },
   ): Effect.Effect<void, never, Req>;
+  shape?: () => Record<string, unknown>;
 }
 
 export interface RuntimeContext<

package/src/Sidecar/RpcHandler.ts

@@ -129,6 +129,21 @@ export const serializeRpcHandlers = <T extends RpcHandlers>(
     ]),
   ) as SerializedRpcHandlers<T>;
 
+const encodeRedacted = (value: unknown): unknown => {
+  if (Redacted.isRedacted(value)) {
+    return { _tag: "Redacted", value: Redacted.value(value) };
+  }
+  if (Array.isArray(value)) {
+    return value.map(encodeRedacted);
+  }
+  if (value && typeof value === "object" && !("toJSON" in value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => [key, encodeRedacted(child)]),
+    );
+  }
+  return value;
+};
+
 const deserializeRpcHandler =
   <Args extends Array<any>, Success, Error>(
     handler: SerializedRpcHandler<Args, Success, Error>,
@@ -137,15 +152,9 @@ const deserializeRpcHandler =
   (...args) =>
     Effect.promise(async () => {
       try {
-        const serializedArgs = JSON.stringify(args, (_, value) => {
-          if (Redacted.isRedacted(value)) {
-            return {
-              _tag: "Redacted",
-              value: Redacted.value(value),
-            };
-          }
-          return value;
-        }) as SerializedArgs<Args>;
+        const serializedArgs = JSON.stringify(
+          encodeRedacted(args),
+        ) as SerializedArgs<Args>;
         return await handler(serializedArgs);
       } catch (error) {
         console.error("Error calling handler", error);

package/src/State/HttpStateApi.ts

@@ -174,6 +174,17 @@ export const SetStackOutput = HttpApiEndpoint.put(
   },
 );
 
+/**
+ * Version of the State Store wire / behavioural contract.
+ *
+ * Bump this whenever the wire format or runtime behaviour of an HTTP
+ * state-store changes in a way that an older deployed copy can no
+ * longer satisfy. Clients query `/version` on the deployed worker and
+ * compare against this constant; a mismatch (or 404) triggers a
+ * forced redeploy via the bootstrap flow.
+ */
+export const STATE_STORE_VERSION = 5 as const;
+
 /** Response shape for the unauthenticated `/version` probe. */
 export const VersionResponse = Schema.Struct({
   version: Schema.Number,

package/src/State/HttpStateStore.ts

@@ -9,8 +9,8 @@ import { StateApi } from "./HttpStateApi.ts";
 import type { ReplacedResourceState, ResourceState } from "./ResourceState.ts";
 import {
   StateStoreError,
-  type StateService,
   type PersistedState,
+  type StateService,
 } from "./State.ts";
 import { encodeState, reviveStateRecursive } from "./StateEncoding.ts";
 
@@ -59,6 +59,11 @@ export const makeHttpStateStore = ({
 
     const service: StateService = {
       id,
+      getVersion: () =>
+        apiClient.version.getVersion().pipe(
+          Effect.map((v) => v.version),
+          mapStateStoreError,
+        ),
       listStacks: () =>
         state.listStacks().pipe(
           Effect.map((stacks) => [...stacks]),
@@ -196,8 +201,8 @@ const retryTransient = <A, Err, Req>(eff: Effect.Effect<A, Err, Req>) =>
 /** Collapse any client failure into a {@link StateStoreError}. */
 const mapStateStoreError = <A, E, R>(eff: Effect.Effect<A, E, R>) =>
   eff.pipe(
-    Effect.tapError(Effect.log),
     retryTransient,
+    Effect.tapError(Effect.log),
     Effect.catch((e: E) =>
       Effect.fail(
         new StateStoreError({

package/src/State/InMemoryState.ts

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import { recordStateStoreInit } from "../Telemetry/Metrics.ts";
+import { STATE_STORE_VERSION } from "./HttpStateApi.ts";
 import type { ResourceState } from "./ResourceState.ts";
 import { State, type PersistedState } from "./State.ts";
 
@@ -28,6 +29,7 @@ export const InMemoryService = (
 ) =>
   State.of({
     id: "inmemory",
+    getVersion: () => Effect.succeed(STATE_STORE_VERSION),
     listStacks: () => Effect.succeed(Array.from(Object.keys(state))),
     listStages: (stack: string) =>
       Effect.succeed(

package/src/State/LocalState.ts

@@ -5,6 +5,7 @@ import * as Path from "effect/Path";
 import type { PlatformError } from "effect/PlatformError";
 import { decodeFqn, encodeFqn } from "../FQN.ts";
 import { recordStateStoreInit } from "../Telemetry/Metrics.ts";
+import { STATE_STORE_VERSION } from "./HttpStateApi.ts";
 import { State, StateStoreError, type StateService } from "./State.ts";
 import { encodeState, reviveState } from "./StateEncoding.ts";
 
@@ -60,6 +61,7 @@ export const makeLocalState = () =>
 
     const state: StateService = {
       id: "local",
+      getVersion: () => Effect.succeed(STATE_STORE_VERSION),
       listStacks: () =>
         fs.readDirectory(stateDir).pipe(
           recover,

package/src/State/State.ts

@@ -45,6 +45,14 @@ export interface StateService {
    * stable, kebab-case slug.
    */
   readonly id: string;
+  /**
+   * Wire / behavioural contract version of this state-store
+   * implementation. For local / in-process stores this is the
+   * `STATE_STORE_VERSION` the CLI was built against; for HTTP-backed
+   * stores it is the version reported by the deployed `/version`
+   * probe.
+   */
+  getVersion(): Effect.Effect<number, StateStoreError, never>;
   listStacks(): Effect.Effect<readonly string[], StateStoreError, never>;
   listStages(
     stack: string,

package/src/State/StateEncoding.ts

@@ -19,7 +19,14 @@ export const REDACTED_MARKER = "__redacted__";
  * - Plain objects and arrays are walked structurally.
  */
 export const encodeState = (value: unknown): unknown => {
-  if (value === null || value === undefined) return value;
+  if (
+    value === null ||
+    value === undefined ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  )
+    return value;
   if (Redacted.isRedacted(value)) {
     return {
       [REDACTED_MARKER]: encodeState(Redacted.value(value)),

package/src/index.ts

@@ -1,3 +1,9 @@
+export {
+  Action,
+  isAction,
+  type Action as ActionInstance,
+  type ActionLike,
+} from "./Action.ts";
 export * as AdoptPolicy from "./AdoptPolicy.ts";
 export * from "./AlchemyContext.ts";
 export * from "./Apply.ts";
@@ -23,12 +29,6 @@ export * from "./Random.ts";
 export * from "./Ref.ts";
 export * as RemovalPolicy from "./RemovalPolicy.ts";
 export * from "./Resource.ts";
-export {
-  Action,
-  isAction,
-  type ActionLike,
-  type Action as ActionInstance,
-} from "./Action.ts";
 export * as Schema from "./Schema.ts";
 export { Secret } from "./Secret.ts";
 export * as Server from "./Server/index.ts";
@@ -48,6 +48,7 @@ export { Cli } from "./Cli/Cli.ts";
 export type * from "./Platform.ts";
 export { Platform } from "./Platform.ts";
 export type { ProviderCollectionLike } from "./Provider.ts";
+export type * from "./Rpc.ts";
 export {
   RuntimeContext,
   type BaseRuntimeContext,