/** @effect-diagnostics anyUnknownInErrorContext:off */
/**
* INTERNAL — the shared skeleton for `alchemy dev` AWS providers that deploy
* into the floci emulator and keep a long-lived watch loop hot-swapping the
* resource on file change ([Lambda FlociFunctionProvider](../Lambda/FlociFunctionProvider.ts),
* [ECS FlociTaskProvider](../ECS/FlociTaskProvider.ts),
* [ECS FlociServiceProvider](../ECS/FlociServiceProvider.ts)).
*
* What the helper owns (identically for every consumer):
*
* - **RPC-sidecar hosting** via {@link RpcProvider.effect} with the shared
* AWS provider group ([Local.ts](./Local.ts)), so the provider and its
* watch fibers survive exec-process hot reloads during `alchemy dev`.
* - **Live-provider delegation** — builds the caller's LIVE provider layer
* inside the floci override context ({@link flociServices} + optional
* caller-supplied extra service layers) and wraps every lifecycle method
* with {@link withProviderContext}, so the exact same reconcile/read/
* delete/list logic runs against the emulator gateway with the dummy
* account.
* - **The instanceId-guarded watch registry** — one watch fiber per logical
* id; a config change interrupts and restarts it; a create-first
* replacement's old-generation delete cannot kill the successor's watcher.
* - **The dev diff policy** — the diff NEVER bundles or builds:
* resource-specific replacement rules run first (spec `replaceOn`), a
* fresh session with state rows but no registered watcher forces an
* `update` (converges the emulator and restarts the watcher), and
* structurally-equal props (spec `normalizeProps`) are a `noop` because
* content-only changes are the watch loop's job.
* - **Serialized reconciles** — engine reconciles, watcher-triggered
* re-reconciles ({@link DevWatchContext.rerunReconcile}), and deletes are
* serialized per logical id, so a rebuild-and-swap never interleaves with
* an engine-driven converge.
*/
import { diffBindings, havePropsChanged, isResolved, stripEffects } from "alchemy/Diff";
import { canonicalHash } from "alchemy/Local/LocalProvider";
import * as RpcProvider from "alchemy/Local/RpcProvider";
import type { Platform } from "alchemy/Platform";
import type { ProviderService } from "alchemy/Provider";
import type { ResourceBinding, ResourceClassLike, ResourceLike } from "alchemy/Resource";
import { moduleExtension } from "alchemy/Util/Node";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
import * as Layer from "effect/Layer";
import * as Scope from "effect/Scope";
import * as Semaphore from "effect/Semaphore";
import { flociServices } from "./FlociServices.ts";
import { withProviderContext } from "./ProviderContext.ts";
/**
* The AWS provider group module ([Local.ts](./Local.ts)) — every
* {@link makeDevWatchProvider} consumer passes this so all floci dev
* providers are served from the same group by the dev sidecar.
*/
export const flociProvidersUrl = () =>
import.meta.resolve(`./Local${moduleExtension(import.meta.url)}`, import.meta.url);
/** A diff decision produced by {@link DevWatchSpec.replaceOn}. */
export interface DevReplaceDecision {
readonly action: "replace";
readonly deleteFirst?: boolean;
}
/**
* The context handed to {@link DevWatchSpec.startWatch}. Runs inside the
* sidecar with the floci override services provided.
*/
export interface DevWatchContext<Props, Attrs> {
readonly id: string;
readonly instanceId: string;
/** The resolved props of the reconcile that started this watcher. */
readonly news: Props;
/** Attributes at watch start. */
readonly attrs: Attrs;
/** The freshest attributes (updated by {@link rerunReconcile}). */
readonly currentAttrs: Effect.Effect<Attrs>;
/**
* Re-runs the wrapped LIVE reconcile with the latest engine input
* (props/bindings) and the current attributes as `output`, records and
* returns the fresh attributes. Serialized with engine reconciles/deletes
* on the same logical id.
*/
readonly rerunReconcile: Effect.Effect<Attrs, unknown>;
/**
* {@link rerunReconcile}, gated on a staleness check that runs INSIDE the
* per-id lock against the freshest attributes. A trigger can fire while an
* engine reconcile for the same id holds the lock; by the time the lock
* frees, that reconcile may already have published exactly the content the
* trigger saw, and re-running would register a redundant revision and reap
* the one the engine just recorded. A check made before waiting on the
* lock cannot see that. Returns the current attributes untouched when
* `isStale` resolves `false`.
*/
readonly rerunReconcileIfStale: (
isStale: (current: Attrs) => Effect.Effect<boolean, unknown, any>,
) => Effect.Effect<Attrs, unknown>;
}
/**
* The per-resource contract for {@link makeDevWatchProvider}: everything the
* shared skeleton cannot know about the resource.
*/
export interface DevWatchSpec<Props, Attrs> {
/**
* The LIVE provider layer (e.g. `() => FunctionProvider()`). Built inside
* the floci override context and endpoint-wrapped, exactly like the plain
* `flociDual` resources.
*/
readonly liveProvider: () => Layer.Layer<any, any, any>;
/**
* Extra service layers built alongside {@link flociServices} inside the
* override context (e.g. Lambda's fresh `AssetsLive`, whose cached bucket
* lookup must resolve against the emulator and never share a cache with
* the live arm's instance).
*/
readonly services?: Layer.Layer<any, any, any>;
/**
* The restart surface of the watch loop: everything that changes WHAT the
* watcher builds or WHERE it publishes. Plain, canonically-hashable data
* only — closures degrade to stable placeholders under
* {@link canonicalHash}. `news` arrives {@link stripEffects}-stripped.
*/
readonly watchConfigOf: (news: Props, attrs: Attrs) => unknown;
/**
* Transform the resolved props before EVERY delegated reconcile —
* engine-driven and watcher-driven alike — inside the per-id lock, with
* the floci override services provided. This is where a provider swaps a
* build-here artifact form for a build-locally one (e.g. the MicroVM dev
* provider docker-builds the image on the HOST and hands the live
* reconcile a `codeArtifact: { uri: "docker://…" }` instead of `main`/
* `context`, so the emulator never zips, uploads, or builds anything).
* The untransformed props stay in the watch registry, so restarts and
* watch-config comparisons see the user's real inputs.
*/
readonly transformReconcileNews?: (input: {
id: string;
news: Props;
}) => Effect.Effect<Props, unknown, any>;
/**
* Called after EVERY successful reconcile — engine-driven (a prop
* change, a fresh session's converge) and watcher-driven
* ({@link DevWatchContext.rerunReconcile}) alike — inside the per-id
* lock, with the floci override services provided. This is where a
* provider makes the emulator's RUNNING state follow the new revision
* (e.g. ECS restarting tasks): the watch trigger only fires for FILE
* changes, so restart logic that lives only in the watch loop silently
* skips prop-driven updates (an inline dockerfile edit, a new env var)
* and running tasks keep serving the old revision until the next source
* edit.
*
* `previous` is the attrs before this reconcile — `undefined` on a
* greenfield create.
*/
readonly onReconciled?: (input: {
id: string;
news: Props;
previous: Attrs | undefined;
attrs: Attrs;
}) => Effect.Effect<void, unknown, any>;
/**
* Runs alongside every reconcile (watcher-driven and engine-driven) and is
* interrupted when it returns. For work the live reconcile waits on but
* cannot do itself, e.g. stopping tasks the emulator keeps on an old
* revision while the reconcile waits for the new one to stabilize.
*/
readonly whileReconciling?: (input: {
id: string;
news: Props;
previous: Attrs | undefined;
}) => Effect.Effect<void, unknown, any>;
/**
* Resource-specific replacement rules, mirroring the LIVE diff's cheap
* checks (never bundling/building). Checked before the generic dev policy.
*/
readonly replaceOn?: (input: {
id: string;
olds: Props;
news: Props;
output: Attrs;
}) => Effect.Effect<DevReplaceDecision | undefined, never, any>;
/**
* Normalization applied to both sides before the structural code-only
* `noop` equivalence check (e.g. Lambda resolves layer references to ARNs).
* @default identity
*/
readonly normalizeProps?: (props: Props) => unknown;
/**
* Pin `precreate`'s news to a stub-compatible shape (Lambda pins the
* handler-affecting props to the 503 stub's own single-module shape).
* Only consulted when the live provider implements `precreate`.
*/
readonly transformPrecreateNews?: (news: Props) => Props;
/**
* The watch loop, forked (detached, in the provider scope) after every
* successful reconcile that changes the watch config. Runs with the floci
* override services provided; failures are logged, never propagated. A
* spec with nothing to watch for a given props shape simply returns.
*/
readonly startWatch: (ctx: DevWatchContext<Props, Attrs>) => Effect.Effect<void, any, any>;
}
interface WatchEntry {
readonly instanceId: string;
readonly configHash: string;
fiber: Fiber.Fiber<void, never> | undefined;
/** The latest engine reconcile input (news/bindings/…) for re-runs. */
lastInput: any;
/** The freshest attributes. */
attrs: any;
}
/**
* Build an RPC-sidecar-hosted `alchemy dev` provider that delegates its
* lifecycle to the LIVE provider inside the floci override context and owns
* a per-resource watch loop. See the module doc for the exact split between
* the shared skeleton and the {@link DevWatchSpec}.
*/
export const makeDevWatchProvider = <
R extends ResourceLike,
Props = R["Props"],
Attrs = R["Attributes"],
>(
cls: ResourceClassLike<R> | Platform<R, any, any, any, any, any>,
providersUrl: string,
spec: DevWatchSpec<Props, Attrs>,
) =>
RpcProvider.effect(
cls,
providersUrl,
Effect.gen(function* () {
const scope = yield* Effect.scope;
const ambient = yield* Effect.context<never>();
// The floci override context (emulator endpoint, dummy credentials,
// account 000000000000) plus any caller-supplied extra services.
const overrides = yield* Layer.buildWithScope(
Layer.mergeAll(flociServices(), spec.services ?? Layer.empty).pipe(
Layer.provide(Layer.succeedContext(ambient)),
) as Layer.Layer<any, any, never>,
scope,
).pipe(Effect.orDie);
const services = Layer.succeedContext(Context.merge(ambient, overrides)) as Layer.Layer<
any,
never,
never
>;
// The live provider machinery, every lifecycle method endpoint-wrapped
// to the emulator — same F1 combinator the plain `flociDual` resources
// use, applied to a provider instance we build ourselves.
const liveCtx = yield* Layer.buildWithScope(
spec.liveProvider().pipe(Layer.provide(services)) as unknown as Layer.Layer<
any,
any,
never
>,
scope,
).pipe(Effect.orDie);
const live = liveCtx.mapUnsafe.get(cls.Type) as ProviderService<R>;
const wrapped = withProviderContext(live, services);
// Sidecar-process watch registry, keyed by logical id. `instanceId`
// guards a create-first replacement's old-generation delete against
// killing the successor's watcher.
const watches = new Map<string, WatchEntry>();
// Per-id serialization: engine reconciles, watcher re-reconciles, and
// deletes never interleave for the same logical resource.
const locks = new Map<string, Semaphore.Semaphore>();
const withLock = (id: string) => {
let lock = locks.get(id);
if (lock === undefined) {
lock = Semaphore.makeUnsafe(1);
locks.set(id, lock);
}
return <A, E, Req>(effect: Effect.Effect<A, E, Req>) =>
Semaphore.withPermits(lock, 1)(effect);
};
// Plan-status callbacks don't cross the RPC boundary (functions
// serialize to `null`) — the live machinery calls `session.note`, so
// substitute a log-backed session when the wire stripped it.
const withSafeSession = (input: any) =>
typeof input?.session?.note === "function"
? input
: {
...input,
session: {
...input?.session,
note: (note: string) => Effect.logDebug(note),
},
};
// Run `spec.whileReconciling` beside a reconcile; interrupted when it returns.
const alongsideReconcile = <A, E, Req>(
input: { id: string; news: Props; previous: Attrs | undefined },
reconcile: Effect.Effect<A, E, Req>,
): Effect.Effect<A, E, Req> =>
spec.whileReconciling === undefined
? reconcile
: Effect.scoped(
Effect.gen(function* () {
yield* spec.whileReconciling!(input).pipe(
Effect.provide(services),
Effect.catchCause((cause) =>
Effect.logWarning(`reconcile side task failed`, cause),
),
Effect.forkScoped,
);
return yield* reconcile;
}),
);
const ensureWatch = Effect.fn(function* (input: any, attrs: any) {
const strippedNews = stripEffects(input.news);
const configHash = yield* canonicalHash(
spec.watchConfigOf(strippedNews as Props, attrs as Attrs),
);
const existing = watches.get(input.id);
if (
existing !== undefined &&
existing.configHash === configHash &&
existing.instanceId === input.instanceId
) {
// Same watcher keeps running — just refresh the re-run input.
existing.lastInput = input;
existing.attrs = attrs;
return;
}
if (existing?.fiber !== undefined) {
yield* Fiber.interrupt(existing.fiber);
}
const entry: WatchEntry = {
instanceId: input.instanceId,
configHash,
fiber: undefined,
lastInput: input,
attrs,
};
watches.set(input.id, entry);
// One watcher-driven reconcile, UNLOCKED: callers take the per-id lock.
const rerun = Effect.gen(function* () {
const previous = entry.attrs as Attrs | undefined;
const rerunNews =
spec.transformReconcileNews !== undefined
? yield* spec
.transformReconcileNews({
id: input.id,
news: stripEffects(entry.lastInput.news) as Props,
})
.pipe(Effect.provide(services))
: entry.lastInput.news;
const fresh = yield* alongsideReconcile(
{
id: input.id,
news: stripEffects(entry.lastInput.news) as Props,
previous,
},
wrapped.reconcile(
withSafeSession({
...entry.lastInput,
news: rerunNews,
olds: entry.lastInput.news,
output: entry.attrs,
}) as any,
),
);
entry.attrs = fresh;
if (spec.onReconciled !== undefined) {
yield* spec
.onReconciled({
id: input.id,
news: stripEffects(entry.lastInput.news) as Props,
previous,
attrs: fresh as Attrs,
})
.pipe(Effect.provide(services));
}
return fresh as Attrs;
});
const ctx: DevWatchContext<Props, Attrs> = {
id: input.id,
instanceId: input.instanceId,
news: strippedNews as Props,
attrs: attrs as Attrs,
currentAttrs: Effect.sync(() => entry.attrs as Attrs),
rerunReconcile: withLock(input.id)(rerun) as Effect.Effect<Attrs, unknown>,
rerunReconcileIfStale: (isStale) =>
withLock(input.id)(
Effect.gen(function* () {
const current = entry.attrs as Attrs;
if (!(yield* isStale(current).pipe(Effect.provide(services)))) return current;
return yield* rerun;
}),
) as Effect.Effect<Attrs, unknown>,
};
const fiber = yield* spec.startWatch(ctx).pipe(
Effect.provide(services),
Effect.catchCause((cause) => Effect.logWarning(`watch loop exited`, cause)),
Effect.forkDetach,
Scope.provide(scope),
);
entry.fiber = fiber as Fiber.Fiber<void, never>;
});
const stopWatch = Effect.fn(function* (id: string, instanceId: string) {
const existing = watches.get(id);
if (existing !== undefined && existing.instanceId === instanceId) {
watches.delete(id);
if (existing.fiber !== undefined) {
yield* Fiber.interrupt(existing.fiber);
}
}
});
const normalize = (props: Props | undefined): object | undefined =>
props === undefined ? undefined : ((spec.normalizeProps?.(props) ?? props) as object);
const provider: any = {
// read / precreate / list / tail / logs / stables delegate to the
// endpoint-wrapped live provider (spreading the Proxy materializes
// each member through the wrapping `get`).
...(wrapped as any),
diff: Effect.fn(function* ({
id,
olds,
news: rawNews,
output,
oldBindings = [],
newBindings = [],
}: {
id: string;
olds: Props;
news: Props;
output: Attrs | undefined;
oldBindings?: ResourceBinding[];
newBindings?: ResourceBinding[];
}) {
// Runtime props (an Effect-native Function's handler, a Layer)
// arrive as Effects, which `isResolved` classifies as unresolved.
// They are irrelevant to the dev diff, so strip them BEFORE the
// resolved check — otherwise this diff bails to the engine default
// (`havePropsChanged` → noop) and the "fresh session with a state
// row but no watcher" branch below never runs: `alchemy dev`
// resumed over an existing stage would start no watch loop and
// hot reload would silently be dead.
const news = stripEffects(rawNews);
if (!isResolved(news)) return;
if (!output) return undefined;
if (spec.replaceOn !== undefined) {
const decision = yield* spec.replaceOn({ id, olds, news, output });
if (decision !== undefined) return decision;
}
// A fresh dev session has state rows but no running watcher (and
// possibly a wiped emulator) — force a reconcile to converge floci
// and (re)start the watch loop. A DEAD watcher (its loop exited or
// was interrupted) counts as none: nothing is handling content
// changes for this id anymore.
const entry = watches.get(id);
if (
entry === undefined ||
(entry.fiber !== undefined && entry.fiber.pollUnsafe() !== undefined)
) {
return { action: "update" as const };
}
// The watcher may have swapped content SINCE state was last
// persisted (its rerunReconcile updates the emulator and the
// sidecar's in-memory attrs, not the state store). If the
// persisted attrs drifted from the watcher's current attrs, plan
// an update — the content-addressed reconcile is cheap, the
// engine persists the fresh attrs, and downstream consumers
// (stack outputs, Actions keyed on `code.hash`) see the swap
// instead of replaying stale state forever.
const persistedHash = yield* canonicalHash(output as object);
const watcherHash = yield* canonicalHash(entry.attrs as object);
if (persistedHash !== watcherHash) {
return { action: "update" as const };
}
// Binding data (env vars, policy statements) is applied by
// reconcile, not the watch loop. An explicit `noop` is final — the
// engine does not re-check bindings after it — so a binding-only
// change must plan an update here.
if (diffBindings(oldBindings, newBindings).some((b) => b.action !== "noop")) {
return { action: "update" as const };
}
if (!havePropsChanged(normalize(olds), normalize(news)!)) {
// Content-only changes are the watch loop's job — the dev diff
// never bundles or builds.
return { action: "noop" as const };
}
return { action: "update" as const };
}),
reconcile: Effect.fn(function* (input: any) {
return yield* withLock(input.id)(
Effect.gen(function* () {
const previous = (input.output ?? watches.get(input.id)?.attrs) as Attrs | undefined;
const reconcileNews =
spec.transformReconcileNews !== undefined
? yield* spec
.transformReconcileNews({
id: input.id,
news: stripEffects(input.news) as Props,
})
.pipe(Effect.provide(services))
: input.news;
const attrs = yield* alongsideReconcile(
{ id: input.id, news: stripEffects(input.news) as Props, previous },
wrapped.reconcile(withSafeSession({ ...input, news: reconcileNews }) as any),
);
yield* ensureWatch(input, attrs);
if (spec.onReconciled !== undefined) {
yield* spec
.onReconciled({
id: input.id,
news: stripEffects(input.news) as Props,
previous,
attrs: attrs as Attrs,
})
.pipe(Effect.provide(services));
}
return attrs;
}),
);
}),
delete: Effect.fn(function* (input: any) {
yield* stopWatch(input.id, input.instanceId);
yield* withLock(input.id)(wrapped.delete(withSafeSession(input) as any));
}),
};
if (typeof (live as any).precreate === "function") {
provider.precreate = (input: any) =>
(wrapped as any).precreate(
withSafeSession({
...input,
news:
spec.transformPrecreateNews !== undefined
? spec.transformPrecreateNews(input.news)
: input.news,
}),
);
}
return provider;
}),
);