The best way to control Claude Code, Codex and more from any computer or phone

main
ts 369 lines 14.8 KB
Raw
1 import { isScopeEjected } from "alchemy/Http";
2 import type { FunctionListener } from "alchemy/Runtime/Function";
3 import { toSeconds } from "alchemy/Util/Duration";
4 /**
5 * Internal scaffolding for AWS Lambda Durable Functions — NOT exported from
6 * the Lambda service `index.ts`.
7 *
8 * A function created with `DurableConfig` receives every invocation as a
9 * dedicated durable-execution envelope (`DurableExecutionInvocationInput`):
10 * the customer payload rides inside the checkpoint log's EXECUTION operation,
11 * and the handler must speak the checkpoint/replay protocol
12 * (`CheckpointDurableExecution` / `GetDurableExecutionState`) and return a
13 * `SUCCEEDED | FAILED | PENDING` envelope.
14 *
15 * Alchemy owns the Lambda entrypoint, so this protocol is routed exactly like
16 * an event source: {@link isDurableExecutionEvent} is the shape predicate
17 * (the `isSQSEvent` analogue) and {@link makeDurableListener} produces the
18 * `host.listen` listener that drives the orchestrator. The replay engine
19 * itself is AWS's open-source `@aws/durable-execution-sdk-js`
20 * (`withDurableExecution`), wrapped behind the Effect-native `DurableStep`
21 * service — the same posture as the Cloudflare `WorkflowBridge` wrapping the
22 * native `step` object.
23 *
24 * The SDK module is loaded with a dynamic `import()` so it never loads at
25 * plan/deploy time. The `DurableFunction` wrapper merges it into
26 * `build.install` automatically, which both vendors it into the artifact's
27 * `node_modules` and externalizes it from the bundle (install roots are
28 * always external) — plain Functions never resolve it.
29 */
30 import type * as lambda from "aws-lambda";
31 import * as Cause from "effect/Cause";
32 import * as Effect from "effect/Effect";
33 import * as Exit from "effect/Exit";
34 import * as Layer from "effect/Layer";
35 import * as Scope from "effect/Scope";
36 import {
37 DurableExecutionContext,
38 DurableStep,
39 type DurableCallbackOptions,
40 type DurableRetryPolicy,
41 type DurableStepOptions,
42 } from "./Durable.ts";
43 import { HandlerContext, withInvocationDeadline } from "./InvocationDeadline.ts";
44
45 /** Module id of AWS's Durable Execution SDK (an optional peer dependency). */
46 export const DURABLE_SDK_MODULE = "@aws/durable-execution-sdk-js";
47
48 // ---------------------------------------------------------------------------
49 // The durable invocation envelope
50 // ---------------------------------------------------------------------------
51
52 /**
53 * Raw invocation payload delivered to a `DurableConfig`-enabled function.
54 * Mirrors the SDK's `DurableExecutionInvocationInput`.
55 */
56 export interface DurableExecutionInvocationEvent {
57 DurableExecutionArn: string;
58 CheckpointToken: string;
59 UpdatedOperationIds?: string[];
60 InitialExecutionState: {
61 Operations?: {
62 Type?: string;
63 ExecutionDetails?: { InputPayload?: string };
64 }[];
65 NextMarker?: string;
66 };
67 }
68
69 /**
70 * Shape predicate for durable-execution invocations — the durable analogue of
71 * `isSQSEvent`. A durable function's invocations always arrive in this
72 * envelope (the durable execution wraps even the first invocation).
73 */
74 export const isDurableExecutionEvent = (event: any): event is DurableExecutionInvocationEvent =>
75 typeof event === "object" &&
76 event !== null &&
77 typeof event.DurableExecutionArn === "string" &&
78 typeof event.CheckpointToken === "string" &&
79 typeof event.InitialExecutionState === "object" &&
80 event.InitialExecutionState !== null;
81
82 // ---------------------------------------------------------------------------
83 // The alchemy payload envelope (multi-workflow routing)
84 // ---------------------------------------------------------------------------
85
86 /**
87 * Lambda has a single exported handler (unlike workerd's named class
88 * exports), so when several DurableFunctions share one host the start payload
89 * carries a discriminator. Alchemy owns both ends — the `start` client wraps
90 * the params, the listener unwraps them — so user code never sees this.
91 */
92 export interface DurableEnvelope {
93 $alchemy: { workflow: string };
94 params: unknown;
95 }
96
97 export const encodeDurableEnvelope = (workflow: string, params: unknown): string =>
98 JSON.stringify({ $alchemy: { workflow }, params } satisfies DurableEnvelope);
99
100 const asDurableEnvelope = (payload: unknown): DurableEnvelope | undefined =>
101 typeof payload === "object" &&
102 payload !== null &&
103 "$alchemy" in payload &&
104 typeof (payload as DurableEnvelope).$alchemy === "object" &&
105 (payload as DurableEnvelope).$alchemy !== null &&
106 typeof (payload as DurableEnvelope).$alchemy.workflow === "string"
107 ? (payload as DurableEnvelope)
108 : undefined;
109
110 /**
111 * Extract the customer input payload from the checkpoint log's EXECUTION
112 * operation (first page — the EXECUTION operation is always the log's first
113 * entry, so pagination never hides it).
114 */
115 export const readDurableInputPayload = (event: DurableExecutionInvocationEvent): unknown => {
116 const operations = event.InitialExecutionState?.Operations ?? [];
117 const execution = operations.find((op) => op?.Type === "EXECUTION");
118 const raw = execution?.ExecutionDetails?.InputPayload;
119 if (raw === undefined) return undefined;
120 try {
121 return JSON.parse(raw);
122 } catch {
123 return raw;
124 }
125 };
126
127 // ---------------------------------------------------------------------------
128 // Native SDK surface (structural types only — the SDK's own types never leak
129 // into alchemy's public d.ts, keeping the dependency optional)
130 // ---------------------------------------------------------------------------
131
132 interface NativeRetryDecision {
133 shouldRetry: boolean;
134 delay?: { seconds: number };
135 }
136
137 interface NativeStepConfig {
138 retryStrategy?: (error: Error, attemptCount: number) => NativeRetryDecision;
139 semantics?: string;
140 }
141
142 interface NativeDurableContext {
143 lambdaContext: lambda.Context;
144 executionContext: { readonly durableExecutionArn: string };
145 step<T>(
146 name: string,
147 fn: (stepContext: unknown) => Promise<T>,
148 config?: NativeStepConfig,
149 ): Promise<T>;
150 wait(name: string, duration: { seconds: number }): Promise<void>;
151 waitForCallback<T>(
152 name: string,
153 submitter: (callbackId: string, context: unknown) => Promise<void>,
154 config?: {
155 timeout?: { seconds: number };
156 heartbeatTimeout?: { seconds: number };
157 },
158 ): Promise<T>;
159 }
160
161 interface NativeDurableSdk {
162 withDurableExecution: (
163 handler: (event: any, context: NativeDurableContext) => Promise<any>,
164 ) => (event: any, context: lambda.Context) => Promise<any>;
165 }
166
167 /**
168 * Load the Durable Execution SDK. The module id is an install root of every
169 * DurableFunction bundle (the wrapper merges it into `build.install`), so
170 * resolution happens at runtime inside the sandbox — from the artifact's
171 * vendored `node_modules`, otherwise from the managed runtime's bundled
172 * copy.
173 */
174 const loadDurableSdk: Effect.Effect<NativeDurableSdk> = Effect.promise(
175 () => import(DURABLE_SDK_MODULE) as Promise<NativeDurableSdk>,
176 ).pipe(
177 Effect.catchDefect((defect) =>
178 Effect.die(
179 new Error(
180 `Failed to load "${DURABLE_SDK_MODULE}" — install it in the project ` +
181 `that defines the DurableFunction (npm i ${DURABLE_SDK_MODULE}) so ` +
182 `the bundler can vendor it into the artifact.`,
183 { cause: defect },
184 ),
185 ),
186 ),
187 );
188
189 // ---------------------------------------------------------------------------
190 // DurableStep over the native DurableContext
191 // ---------------------------------------------------------------------------
192
193 const toNativeRetryStrategy = (
194 retry: DurableRetryPolicy,
195 ): ((error: Error, attemptCount: number) => NativeRetryDecision) => {
196 const base = toSeconds(retry.delay) ?? 1;
197 const cap = toSeconds(retry.maxDelay);
198 const backoff = retry.backoff ?? "exponential";
199 return (_error, attemptCount) => {
200 if (attemptCount > retry.limit) {
201 return { shouldRetry: false };
202 }
203 const raw =
204 backoff === "constant"
205 ? base
206 : backoff === "linear"
207 ? base * attemptCount
208 : base * 2 ** Math.max(0, attemptCount - 1);
209 const seconds = Math.max(1, Math.ceil(cap ? Math.min(raw, cap) : raw));
210 return { shouldRetry: true, delay: { seconds } };
211 };
212 };
213
214 const toNativeStepConfig = (options: DurableStepOptions<any>): NativeStepConfig | undefined => {
215 if (!options.retry && !options.semantics) return undefined;
216 return {
217 ...(options.retry ? { retryStrategy: toNativeRetryStrategy(options.retry) } : {}),
218 ...(options.semantics
219 ? {
220 semantics:
221 options.semantics === "at-most-once"
222 ? "AT_MOST_ONCE_PER_RETRY"
223 : "AT_LEAST_ONCE_PER_RETRY",
224 }
225 : {}),
226 };
227 };
228
229 const wrapDurableContext = (dctx: NativeDurableContext): DurableStep["Service"] => ({
230 step: <T>(options: DurableStepOptions<T>) =>
231 Effect.tryPromise(() =>
232 dctx.step<T>(
233 options.name,
234 () => Effect.runPromise(options.effect),
235 toNativeStepConfig(options),
236 ),
237 ).pipe(Effect.orDie),
238 wait: (name, duration) =>
239 Effect.tryPromise(() =>
240 dctx.wait(name, { seconds: Math.max(1, toSeconds(duration) ?? 1) }),
241 ).pipe(Effect.orDie),
242 waitForCallback: <T>(options: DurableCallbackOptions) =>
243 Effect.tryPromise(() =>
244 dctx.waitForCallback<T>(
245 options.name,
246 (callbackId) => Effect.runPromise(options.submitter(callbackId)),
247 {
248 ...(options.timeout !== undefined
249 ? { timeout: { seconds: toSeconds(options.timeout)! } }
250 : {}),
251 ...(options.heartbeatTimeout !== undefined
252 ? {
253 heartbeatTimeout: {
254 seconds: toSeconds(options.heartbeatTimeout)!,
255 },
256 }
257 : {}),
258 },
259 ),
260 ).pipe(Effect.orDie),
261 });
262
263 // ---------------------------------------------------------------------------
264 // The listener
265 // ---------------------------------------------------------------------------
266
267 /**
268 * Build the `host.listen` listener that drives one named durable orchestrator.
269 *
270 * The listener recognizes the durable envelope, peeks the alchemy payload
271 * envelope to decline invocations addressed to a different DurableFunction on
272 * the same host, and otherwise hands the raw event to the SDK's
273 * `withDurableExecution` wrapper. The wrapper loads/replays the checkpoint
274 * log and calls back into the Effect body with a fresh per-invocation `Scope`
275 * and the `DurableStep`/`DurableExecutionContext` services.
276 */
277 type WrappedDurableHandler = (event: any, context: lambda.Context) => Promise<any>;
278
279 export const makeDurableListener = (options: {
280 name: string;
281 run: (input: unknown) => Effect.Effect<unknown>;
282 }): Effect.Effect<FunctionListener> =>
283 // `Effect.sync`, NOT `Effect.gen` yielding `loadDurableSdk`: the listener is
284 // CONSTRUCTED when the host resolves `runtimeContext.exports`, which happens
285 // at PLAN/DEPLOY time (`Platform.ts` does `yield* runtimeContext.exports`).
286 // Importing `@aws/durable-execution-sdk-js` there both contradicts the "never
287 // at plan time" contract and stalls the deploy (the SDK's module init
288 // touches the AWS client). Defer the load to the first real invocation and
289 // memoize it.
290 Effect.sync(() => {
291 // Bind the SDK-wrapped handler once, on first invocation, and reuse it.
292 let wrapped: WrappedDurableHandler | undefined;
293 const ensureWrapped: Effect.Effect<WrappedDurableHandler> = Effect.suspend(() =>
294 wrapped !== undefined
295 ? Effect.succeed(wrapped)
296 : loadDurableSdk.pipe(
297 Effect.map((sdk) => {
298 wrapped = sdk.withDurableExecution(async (event, dctx) => {
299 // The SDK extracts the customer payload from the EXECUTION
300 // operation and hands it to us on every (re-)invocation.
301 const envelope = asDurableEnvelope(event);
302 const params = envelope !== undefined ? envelope.params : event;
303
304 // Fresh request scope per durable invocation, matching the
305 // Lambda dispatcher / Worker / Workflow bridges.
306 const scope = Scope.makeUnsafe();
307 const exit = await Effect.runPromiseExit(
308 options.run(params).pipe(
309 Effect.provide(
310 Layer.mergeAll(
311 Layer.succeed(DurableStep, wrapDurableContext(dctx)),
312 Layer.succeed(DurableExecutionContext, {
313 executionArn: dctx.executionContext.durableExecutionArn,
314 }),
315 Layer.succeed(HandlerContext, dctx.lambdaContext),
316 Layer.succeed(Scope.Scope, scope),
317 ),
318 ),
319 ),
320 );
321 if (!isScopeEjected(scope)) {
322 await Scope.close(scope, exit).pipe(
323 Effect.ignoreCause({
324 log: "Warn",
325 message: "Durable invocation scope close failed",
326 }),
327 Effect.runPromise,
328 );
329 }
330 if (Exit.isSuccess(exit)) {
331 return exit.value;
332 }
333 throw Cause.squash(exit.cause);
334 });
335 return wrapped;
336 }),
337 ),
338 );
339
340 // `HandlerContext` is a runtime-only requirement satisfied unconditionally
341 // by the Lambda dispatcher, which provides it (and `Scope`) to every
342 // listener's returned effect. Cast the listener down to the `Req = never`
343 // `FunctionListener` so the requirement never leaks into the host's init
344 // effect — the exact contract `serve`/`makeFunctionHttpHandler` rely on.
345 return ((event: any) => {
346 if (!isDurableExecutionEvent(event)) return;
347 const payload = readDurableInputPayload(event);
348 const envelope = asDurableEnvelope(payload);
349 if (envelope !== undefined && envelope.$alchemy.workflow !== options.name) {
350 // Addressed to another DurableFunction on this host — decline so its
351 // listener picks it up.
352 return;
353 }
354 // Durable invocations are never interrupted at the deadline: the SDK
355 // replays them from checkpoints, and interrupting the wait below would
356 // leave its promise running into the next invocation. The guard still
357 // flushes telemetry before Lambda's hard timeout.
358 return Effect.gen(function* () {
359 const context = yield* HandlerContext;
360 // Lazily load + memoize the SDK on the first real invocation.
361 const run = yield* ensureWrapped;
362 // The SDK owns the checkpoint protocol from here: it replays the log,
363 // runs new work, and returns the SUCCEEDED/FAILED/PENDING envelope
364 // Lambda interprets. A rejection here is a protocol-level failure —
365 // let it surface as an invocation error.
366 return yield* Effect.promise(() => run(event, context));
367 }).pipe(withInvocationDeadline({ interrupt: false }));
368 }) as unknown as FunctionListener;
369 });