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

main
ts 546 lines 22.8 KB
Raw
1 /** @effect-diagnostics anyUnknownInErrorContext:off */
2
3 /**
4 * INTERNAL — the shared skeleton for `alchemy dev` AWS providers that deploy
5 * into the floci emulator and keep a long-lived watch loop hot-swapping the
6 * resource on file change ([Lambda FlociFunctionProvider](../Lambda/FlociFunctionProvider.ts),
7 * [ECS FlociTaskProvider](../ECS/FlociTaskProvider.ts),
8 * [ECS FlociServiceProvider](../ECS/FlociServiceProvider.ts)).
9 *
10 * What the helper owns (identically for every consumer):
11 *
12 * - **RPC-sidecar hosting** via {@link RpcProvider.effect} with the shared
13 * AWS provider group ([Local.ts](./Local.ts)), so the provider and its
14 * watch fibers survive exec-process hot reloads during `alchemy dev`.
15 * - **Live-provider delegation** — builds the caller's LIVE provider layer
16 * inside the floci override context ({@link flociServices} + optional
17 * caller-supplied extra service layers) and wraps every lifecycle method
18 * with {@link withProviderContext}, so the exact same reconcile/read/
19 * delete/list logic runs against the emulator gateway with the dummy
20 * account.
21 * - **The instanceId-guarded watch registry** — one watch fiber per logical
22 * id; a config change interrupts and restarts it; a create-first
23 * replacement's old-generation delete cannot kill the successor's watcher.
24 * - **The dev diff policy** — the diff NEVER bundles or builds:
25 * resource-specific replacement rules run first (spec `replaceOn`), a
26 * fresh session with state rows but no registered watcher forces an
27 * `update` (converges the emulator and restarts the watcher), and
28 * structurally-equal props (spec `normalizeProps`) are a `noop` because
29 * content-only changes are the watch loop's job.
30 * - **Serialized reconciles** — engine reconciles, watcher-triggered
31 * re-reconciles ({@link DevWatchContext.rerunReconcile}), and deletes are
32 * serialized per logical id, so a rebuild-and-swap never interleaves with
33 * an engine-driven converge.
34 */
35
36 import { diffBindings, havePropsChanged, isResolved, stripEffects } from "alchemy/Diff";
37 import { canonicalHash } from "alchemy/Local/LocalProvider";
38 import * as RpcProvider from "alchemy/Local/RpcProvider";
39 import type { Platform } from "alchemy/Platform";
40 import type { ProviderService } from "alchemy/Provider";
41 import type { ResourceBinding, ResourceClassLike, ResourceLike } from "alchemy/Resource";
42 import { moduleExtension } from "alchemy/Util/Node";
43 import * as Context from "effect/Context";
44 import * as Effect from "effect/Effect";
45 import * as Fiber from "effect/Fiber";
46 import * as Layer from "effect/Layer";
47 import * as Scope from "effect/Scope";
48 import * as Semaphore from "effect/Semaphore";
49 import { flociServices } from "./FlociServices.ts";
50 import { withProviderContext } from "./ProviderContext.ts";
51
52 /**
53 * The AWS provider group module ([Local.ts](./Local.ts)) — every
54 * {@link makeDevWatchProvider} consumer passes this so all floci dev
55 * providers are served from the same group by the dev sidecar.
56 */
57 export const flociProvidersUrl = () =>
58 import.meta.resolve(`./Local${moduleExtension(import.meta.url)}`, import.meta.url);
59
60 /** A diff decision produced by {@link DevWatchSpec.replaceOn}. */
61 export interface DevReplaceDecision {
62 readonly action: "replace";
63 readonly deleteFirst?: boolean;
64 }
65
66 /**
67 * The context handed to {@link DevWatchSpec.startWatch}. Runs inside the
68 * sidecar with the floci override services provided.
69 */
70 export interface DevWatchContext<Props, Attrs> {
71 readonly id: string;
72 readonly instanceId: string;
73 /** The resolved props of the reconcile that started this watcher. */
74 readonly news: Props;
75 /** Attributes at watch start. */
76 readonly attrs: Attrs;
77 /** The freshest attributes (updated by {@link rerunReconcile}). */
78 readonly currentAttrs: Effect.Effect<Attrs>;
79 /**
80 * Re-runs the wrapped LIVE reconcile with the latest engine input
81 * (props/bindings) and the current attributes as `output`, records and
82 * returns the fresh attributes. Serialized with engine reconciles/deletes
83 * on the same logical id.
84 */
85 readonly rerunReconcile: Effect.Effect<Attrs, unknown>;
86 /**
87 * {@link rerunReconcile}, gated on a staleness check that runs INSIDE the
88 * per-id lock against the freshest attributes. A trigger can fire while an
89 * engine reconcile for the same id holds the lock; by the time the lock
90 * frees, that reconcile may already have published exactly the content the
91 * trigger saw, and re-running would register a redundant revision and reap
92 * the one the engine just recorded. A check made before waiting on the
93 * lock cannot see that. Returns the current attributes untouched when
94 * `isStale` resolves `false`.
95 */
96 readonly rerunReconcileIfStale: (
97 isStale: (current: Attrs) => Effect.Effect<boolean, unknown, any>,
98 ) => Effect.Effect<Attrs, unknown>;
99 }
100
101 /**
102 * The per-resource contract for {@link makeDevWatchProvider}: everything the
103 * shared skeleton cannot know about the resource.
104 */
105 export interface DevWatchSpec<Props, Attrs> {
106 /**
107 * The LIVE provider layer (e.g. `() => FunctionProvider()`). Built inside
108 * the floci override context and endpoint-wrapped, exactly like the plain
109 * `flociDual` resources.
110 */
111 readonly liveProvider: () => Layer.Layer<any, any, any>;
112 /**
113 * Extra service layers built alongside {@link flociServices} inside the
114 * override context (e.g. Lambda's fresh `AssetsLive`, whose cached bucket
115 * lookup must resolve against the emulator and never share a cache with
116 * the live arm's instance).
117 */
118 readonly services?: Layer.Layer<any, any, any>;
119 /**
120 * The restart surface of the watch loop: everything that changes WHAT the
121 * watcher builds or WHERE it publishes. Plain, canonically-hashable data
122 * only — closures degrade to stable placeholders under
123 * {@link canonicalHash}. `news` arrives {@link stripEffects}-stripped.
124 */
125 readonly watchConfigOf: (news: Props, attrs: Attrs) => unknown;
126 /**
127 * Transform the resolved props before EVERY delegated reconcile —
128 * engine-driven and watcher-driven alike — inside the per-id lock, with
129 * the floci override services provided. This is where a provider swaps a
130 * build-here artifact form for a build-locally one (e.g. the MicroVM dev
131 * provider docker-builds the image on the HOST and hands the live
132 * reconcile a `codeArtifact: { uri: "docker://…" }` instead of `main`/
133 * `context`, so the emulator never zips, uploads, or builds anything).
134 * The untransformed props stay in the watch registry, so restarts and
135 * watch-config comparisons see the user's real inputs.
136 */
137 readonly transformReconcileNews?: (input: {
138 id: string;
139 news: Props;
140 }) => Effect.Effect<Props, unknown, any>;
141 /**
142 * Called after EVERY successful reconcile — engine-driven (a prop
143 * change, a fresh session's converge) and watcher-driven
144 * ({@link DevWatchContext.rerunReconcile}) alike — inside the per-id
145 * lock, with the floci override services provided. This is where a
146 * provider makes the emulator's RUNNING state follow the new revision
147 * (e.g. ECS restarting tasks): the watch trigger only fires for FILE
148 * changes, so restart logic that lives only in the watch loop silently
149 * skips prop-driven updates (an inline dockerfile edit, a new env var)
150 * and running tasks keep serving the old revision until the next source
151 * edit.
152 *
153 * `previous` is the attrs before this reconcile — `undefined` on a
154 * greenfield create.
155 */
156 readonly onReconciled?: (input: {
157 id: string;
158 news: Props;
159 previous: Attrs | undefined;
160 attrs: Attrs;
161 }) => Effect.Effect<void, unknown, any>;
162 /**
163 * Runs alongside every reconcile (watcher-driven and engine-driven) and is
164 * interrupted when it returns. For work the live reconcile waits on but
165 * cannot do itself, e.g. stopping tasks the emulator keeps on an old
166 * revision while the reconcile waits for the new one to stabilize.
167 */
168 readonly whileReconciling?: (input: {
169 id: string;
170 news: Props;
171 previous: Attrs | undefined;
172 }) => Effect.Effect<void, unknown, any>;
173 /**
174 * Resource-specific replacement rules, mirroring the LIVE diff's cheap
175 * checks (never bundling/building). Checked before the generic dev policy.
176 */
177 readonly replaceOn?: (input: {
178 id: string;
179 olds: Props;
180 news: Props;
181 output: Attrs;
182 }) => Effect.Effect<DevReplaceDecision | undefined, never, any>;
183 /**
184 * Normalization applied to both sides before the structural code-only
185 * `noop` equivalence check (e.g. Lambda resolves layer references to ARNs).
186 * @default identity
187 */
188 readonly normalizeProps?: (props: Props) => unknown;
189 /**
190 * Pin `precreate`'s news to a stub-compatible shape (Lambda pins the
191 * handler-affecting props to the 503 stub's own single-module shape).
192 * Only consulted when the live provider implements `precreate`.
193 */
194 readonly transformPrecreateNews?: (news: Props) => Props;
195 /**
196 * The watch loop, forked (detached, in the provider scope) after every
197 * successful reconcile that changes the watch config. Runs with the floci
198 * override services provided; failures are logged, never propagated. A
199 * spec with nothing to watch for a given props shape simply returns.
200 */
201 readonly startWatch: (ctx: DevWatchContext<Props, Attrs>) => Effect.Effect<void, any, any>;
202 }
203
204 interface WatchEntry {
205 readonly instanceId: string;
206 readonly configHash: string;
207 fiber: Fiber.Fiber<void, never> | undefined;
208 /** The latest engine reconcile input (news/bindings/…) for re-runs. */
209 lastInput: any;
210 /** The freshest attributes. */
211 attrs: any;
212 }
213
214 /**
215 * Build an RPC-sidecar-hosted `alchemy dev` provider that delegates its
216 * lifecycle to the LIVE provider inside the floci override context and owns
217 * a per-resource watch loop. See the module doc for the exact split between
218 * the shared skeleton and the {@link DevWatchSpec}.
219 */
220 export const makeDevWatchProvider = <
221 R extends ResourceLike,
222 Props = R["Props"],
223 Attrs = R["Attributes"],
224 >(
225 cls: ResourceClassLike<R> | Platform<R, any, any, any, any, any>,
226 providersUrl: string,
227 spec: DevWatchSpec<Props, Attrs>,
228 ) =>
229 RpcProvider.effect(
230 cls,
231 providersUrl,
232 Effect.gen(function* () {
233 const scope = yield* Effect.scope;
234 const ambient = yield* Effect.context<never>();
235
236 // The floci override context (emulator endpoint, dummy credentials,
237 // account 000000000000) plus any caller-supplied extra services.
238 const overrides = yield* Layer.buildWithScope(
239 Layer.mergeAll(flociServices(), spec.services ?? Layer.empty).pipe(
240 Layer.provide(Layer.succeedContext(ambient)),
241 ) as Layer.Layer<any, any, never>,
242 scope,
243 ).pipe(Effect.orDie);
244 const services = Layer.succeedContext(Context.merge(ambient, overrides)) as Layer.Layer<
245 any,
246 never,
247 never
248 >;
249
250 // The live provider machinery, every lifecycle method endpoint-wrapped
251 // to the emulator — same F1 combinator the plain `flociDual` resources
252 // use, applied to a provider instance we build ourselves.
253 const liveCtx = yield* Layer.buildWithScope(
254 spec.liveProvider().pipe(Layer.provide(services)) as unknown as Layer.Layer<
255 any,
256 any,
257 never
258 >,
259 scope,
260 ).pipe(Effect.orDie);
261 const live = liveCtx.mapUnsafe.get(cls.Type) as ProviderService<R>;
262 const wrapped = withProviderContext(live, services);
263
264 // Sidecar-process watch registry, keyed by logical id. `instanceId`
265 // guards a create-first replacement's old-generation delete against
266 // killing the successor's watcher.
267 const watches = new Map<string, WatchEntry>();
268
269 // Per-id serialization: engine reconciles, watcher re-reconciles, and
270 // deletes never interleave for the same logical resource.
271 const locks = new Map<string, Semaphore.Semaphore>();
272 const withLock = (id: string) => {
273 let lock = locks.get(id);
274 if (lock === undefined) {
275 lock = Semaphore.makeUnsafe(1);
276 locks.set(id, lock);
277 }
278 return <A, E, Req>(effect: Effect.Effect<A, E, Req>) =>
279 Semaphore.withPermits(lock, 1)(effect);
280 };
281
282 // Plan-status callbacks don't cross the RPC boundary (functions
283 // serialize to `null`) — the live machinery calls `session.note`, so
284 // substitute a log-backed session when the wire stripped it.
285 const withSafeSession = (input: any) =>
286 typeof input?.session?.note === "function"
287 ? input
288 : {
289 ...input,
290 session: {
291 ...input?.session,
292 note: (note: string) => Effect.logDebug(note),
293 },
294 };
295
296 // Run `spec.whileReconciling` beside a reconcile; interrupted when it returns.
297 const alongsideReconcile = <A, E, Req>(
298 input: { id: string; news: Props; previous: Attrs | undefined },
299 reconcile: Effect.Effect<A, E, Req>,
300 ): Effect.Effect<A, E, Req> =>
301 spec.whileReconciling === undefined
302 ? reconcile
303 : Effect.scoped(
304 Effect.gen(function* () {
305 yield* spec.whileReconciling!(input).pipe(
306 Effect.provide(services),
307 Effect.catchCause((cause) =>
308 Effect.logWarning(`reconcile side task failed`, cause),
309 ),
310 Effect.forkScoped,
311 );
312 return yield* reconcile;
313 }),
314 );
315
316 const ensureWatch = Effect.fn(function* (input: any, attrs: any) {
317 const strippedNews = stripEffects(input.news);
318 const configHash = yield* canonicalHash(
319 spec.watchConfigOf(strippedNews as Props, attrs as Attrs),
320 );
321 const existing = watches.get(input.id);
322 if (
323 existing !== undefined &&
324 existing.configHash === configHash &&
325 existing.instanceId === input.instanceId
326 ) {
327 // Same watcher keeps running — just refresh the re-run input.
328 existing.lastInput = input;
329 existing.attrs = attrs;
330 return;
331 }
332 if (existing?.fiber !== undefined) {
333 yield* Fiber.interrupt(existing.fiber);
334 }
335 const entry: WatchEntry = {
336 instanceId: input.instanceId,
337 configHash,
338 fiber: undefined,
339 lastInput: input,
340 attrs,
341 };
342 watches.set(input.id, entry);
343 // One watcher-driven reconcile, UNLOCKED: callers take the per-id lock.
344 const rerun = Effect.gen(function* () {
345 const previous = entry.attrs as Attrs | undefined;
346 const rerunNews =
347 spec.transformReconcileNews !== undefined
348 ? yield* spec
349 .transformReconcileNews({
350 id: input.id,
351 news: stripEffects(entry.lastInput.news) as Props,
352 })
353 .pipe(Effect.provide(services))
354 : entry.lastInput.news;
355 const fresh = yield* alongsideReconcile(
356 {
357 id: input.id,
358 news: stripEffects(entry.lastInput.news) as Props,
359 previous,
360 },
361 wrapped.reconcile(
362 withSafeSession({
363 ...entry.lastInput,
364 news: rerunNews,
365 olds: entry.lastInput.news,
366 output: entry.attrs,
367 }) as any,
368 ),
369 );
370 entry.attrs = fresh;
371 if (spec.onReconciled !== undefined) {
372 yield* spec
373 .onReconciled({
374 id: input.id,
375 news: stripEffects(entry.lastInput.news) as Props,
376 previous,
377 attrs: fresh as Attrs,
378 })
379 .pipe(Effect.provide(services));
380 }
381 return fresh as Attrs;
382 });
383 const ctx: DevWatchContext<Props, Attrs> = {
384 id: input.id,
385 instanceId: input.instanceId,
386 news: strippedNews as Props,
387 attrs: attrs as Attrs,
388 currentAttrs: Effect.sync(() => entry.attrs as Attrs),
389 rerunReconcile: withLock(input.id)(rerun) as Effect.Effect<Attrs, unknown>,
390 rerunReconcileIfStale: (isStale) =>
391 withLock(input.id)(
392 Effect.gen(function* () {
393 const current = entry.attrs as Attrs;
394 if (!(yield* isStale(current).pipe(Effect.provide(services)))) return current;
395 return yield* rerun;
396 }),
397 ) as Effect.Effect<Attrs, unknown>,
398 };
399 const fiber = yield* spec.startWatch(ctx).pipe(
400 Effect.provide(services),
401 Effect.catchCause((cause) => Effect.logWarning(`watch loop exited`, cause)),
402 Effect.forkDetach,
403 Scope.provide(scope),
404 );
405 entry.fiber = fiber as Fiber.Fiber<void, never>;
406 });
407
408 const stopWatch = Effect.fn(function* (id: string, instanceId: string) {
409 const existing = watches.get(id);
410 if (existing !== undefined && existing.instanceId === instanceId) {
411 watches.delete(id);
412 if (existing.fiber !== undefined) {
413 yield* Fiber.interrupt(existing.fiber);
414 }
415 }
416 });
417
418 const normalize = (props: Props | undefined): object | undefined =>
419 props === undefined ? undefined : ((spec.normalizeProps?.(props) ?? props) as object);
420
421 const provider: any = {
422 // read / precreate / list / tail / logs / stables delegate to the
423 // endpoint-wrapped live provider (spreading the Proxy materializes
424 // each member through the wrapping `get`).
425 ...(wrapped as any),
426 diff: Effect.fn(function* ({
427 id,
428 olds,
429 news: rawNews,
430 output,
431 oldBindings = [],
432 newBindings = [],
433 }: {
434 id: string;
435 olds: Props;
436 news: Props;
437 output: Attrs | undefined;
438 oldBindings?: ResourceBinding[];
439 newBindings?: ResourceBinding[];
440 }) {
441 // Runtime props (an Effect-native Function's handler, a Layer)
442 // arrive as Effects, which `isResolved` classifies as unresolved.
443 // They are irrelevant to the dev diff, so strip them BEFORE the
444 // resolved check — otherwise this diff bails to the engine default
445 // (`havePropsChanged` → noop) and the "fresh session with a state
446 // row but no watcher" branch below never runs: `alchemy dev`
447 // resumed over an existing stage would start no watch loop and
448 // hot reload would silently be dead.
449 const news = stripEffects(rawNews);
450 if (!isResolved(news)) return;
451 if (!output) return undefined;
452 if (spec.replaceOn !== undefined) {
453 const decision = yield* spec.replaceOn({ id, olds, news, output });
454 if (decision !== undefined) return decision;
455 }
456 // A fresh dev session has state rows but no running watcher (and
457 // possibly a wiped emulator) — force a reconcile to converge floci
458 // and (re)start the watch loop. A DEAD watcher (its loop exited or
459 // was interrupted) counts as none: nothing is handling content
460 // changes for this id anymore.
461 const entry = watches.get(id);
462 if (
463 entry === undefined ||
464 (entry.fiber !== undefined && entry.fiber.pollUnsafe() !== undefined)
465 ) {
466 return { action: "update" as const };
467 }
468 // The watcher may have swapped content SINCE state was last
469 // persisted (its rerunReconcile updates the emulator and the
470 // sidecar's in-memory attrs, not the state store). If the
471 // persisted attrs drifted from the watcher's current attrs, plan
472 // an update — the content-addressed reconcile is cheap, the
473 // engine persists the fresh attrs, and downstream consumers
474 // (stack outputs, Actions keyed on `code.hash`) see the swap
475 // instead of replaying stale state forever.
476 const persistedHash = yield* canonicalHash(output as object);
477 const watcherHash = yield* canonicalHash(entry.attrs as object);
478 if (persistedHash !== watcherHash) {
479 return { action: "update" as const };
480 }
481 // Binding data (env vars, policy statements) is applied by
482 // reconcile, not the watch loop. An explicit `noop` is final — the
483 // engine does not re-check bindings after it — so a binding-only
484 // change must plan an update here.
485 if (diffBindings(oldBindings, newBindings).some((b) => b.action !== "noop")) {
486 return { action: "update" as const };
487 }
488 if (!havePropsChanged(normalize(olds), normalize(news)!)) {
489 // Content-only changes are the watch loop's job — the dev diff
490 // never bundles or builds.
491 return { action: "noop" as const };
492 }
493 return { action: "update" as const };
494 }),
495 reconcile: Effect.fn(function* (input: any) {
496 return yield* withLock(input.id)(
497 Effect.gen(function* () {
498 const previous = (input.output ?? watches.get(input.id)?.attrs) as Attrs | undefined;
499 const reconcileNews =
500 spec.transformReconcileNews !== undefined
501 ? yield* spec
502 .transformReconcileNews({
503 id: input.id,
504 news: stripEffects(input.news) as Props,
505 })
506 .pipe(Effect.provide(services))
507 : input.news;
508 const attrs = yield* alongsideReconcile(
509 { id: input.id, news: stripEffects(input.news) as Props, previous },
510 wrapped.reconcile(withSafeSession({ ...input, news: reconcileNews }) as any),
511 );
512 yield* ensureWatch(input, attrs);
513 if (spec.onReconciled !== undefined) {
514 yield* spec
515 .onReconciled({
516 id: input.id,
517 news: stripEffects(input.news) as Props,
518 previous,
519 attrs: attrs as Attrs,
520 })
521 .pipe(Effect.provide(services));
522 }
523 return attrs;
524 }),
525 );
526 }),
527 delete: Effect.fn(function* (input: any) {
528 yield* stopWatch(input.id, input.instanceId);
529 yield* withLock(input.id)(wrapped.delete(withSafeSession(input) as any));
530 }),
531 };
532 if (typeof (live as any).precreate === "function") {
533 provider.precreate = (input: any) =>
534 (wrapped as any).precreate(
535 withSafeSession({
536 ...input,
537 news:
538 spec.transformPrecreateNews !== undefined
539 ? spec.transformPrecreateNews(input.news)
540 : input.news,
541 }),
542 );
543 }
544 return provider;
545 }),
546 );