sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Local/ LocalProvider.ts

/** @effect-diagnostics anyUnknownInErrorContext:off */

import * as Clock from "effect/Clock";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Fiber from "effect/Fiber";
import * as Redacted from "effect/Redacted";
import * as Scope from "effect/Scope";
import * as Semaphore from "effect/Semaphore";
import { isResolved, stripEffects, type Diff } from "../Diff.ts";
import type { Platform } from "../Platform.ts";
import type { ProviderService } from "../Provider.ts";
import type { ScopedPlanStatusSession } from "../Report.ts";
import type { ResourceBinding, ResourceClassLike, ResourceLike } from "../Resource.ts";
import { LogAnnotation } from "../Util/LogAnnotation.ts";
import { sha256 } from "../Util/sha256.ts";
import * as RpcProvider from "./RpcProvider.ts";

/**
 * # LocalProvider — the standard shape of a long-running local provider
 *
 * A local provider's "physical resource" is a running process (a spawned
 * dev server, a workerd instance) that lives in the dev sidecar and is
 * invisible to the state store: a state row can say `created` while the
 * process is dead (the previous dev session ended), and a redundant
 * reconcile can arrive while the process is healthy. Every local provider
 * therefore needs the same machinery:
 *
 * - an **instance registry** answering "is something running for this
 *   resource right now?",
 * - a **config comparison** answering "was it started with the config I'm
 *   being asked for?",
 * - restart/teardown choreography that keeps the process alive across
 *   deploys (scopes forked from the provider root scope) and kills it on
 *   change or delete.
 *
 * {@link make} generates `diff` / `reconcile` / `delete` / `list` from that
 * machinery; the provider author writes {@link LocalProviderSpec.start}
 * (how to boot one instance) and optionally
 * {@link LocalProviderSpec.resolveConfig} (what the restart-relevant config
 * is) and {@link LocalProviderSpec.stop} (cleanup that outlives instance
 * scopes).
 *
 * The produced layer wraps {@link RpcProvider.effect}, so during
 * `alchemy dev` the provider (and its registry of running processes) lives
 * in the sidecar process and survives user-code hot reloads.
 */

/** Inputs common to every generated lifecycle call. */
export interface LocalProviderInput<R extends ResourceLike> {
  id: string;
  fqn: string;
  instanceId: string;
  news: R["Props"];
  bindings: ResourceBinding<R["Binding"]>[];
}

export interface StartContext<R extends ResourceLike, Config> extends LocalProviderInput<R> {
  /**
   * The value produced by {@link LocalProviderSpec.resolveConfig} for this
   * reconcile — the same value whose canonical hash decided that a
   * (re)start was needed, so "what changed?" and "what starts?" can never
   * drift.
   */
  config: Config;
  session: ScopedPlanStatusSession;
  /**
   * Removes this instance from the running registry (a no-op if it has
   * already been replaced), so the next `diff` reports `update` and the
   * next reconcile boots a fresh instance. Fork this after the process's
   * exit — e.g. `child.exitCode.pipe(Effect.exit, Effect.flatMap(() =>
   * invalidate), Effect.forkScoped)` — for processes that can die on their
   * own.
   */
  invalidate: Effect.Effect<void>;
}

export interface StopContext {
  id: string;
  /**
   * Fully-qualified name (namespace path + logical id) — the key the
   * generated instance registry uses. Cross-restart state a provider keeps
   * outside instance scopes MUST be keyed by this, not `id`: two resources
   * in different namespaces can share a logical id (two `AWS.Website.*`
   * sites each declaring a `Command.Dev("Dev")`, ...).
   */
  fqn: string;
  instanceId: string;
}

export interface StablesContext<R extends ResourceLike, Config> extends LocalProviderInput<R> {
  config: Config;
  output: R["Attributes"] | undefined;
}

/** The default restart-relevant config when `resolveConfig` is omitted. */
export interface DefaultLocalConfig<R extends ResourceLike> {
  news: R["Props"];
  bindings: ResourceBinding<R["Binding"]>[];
}

export interface LocalProviderSpec<
  R extends ResourceLike,
  Config = DefaultLocalConfig<R>,
  StartR = never,
> {
  /**
   * Derive the restart-relevant desired config from resolved inputs.
   *
   * MUST return plain, canonically-serializable data (no closures, no
   * Effects — `Redacted` values are unwrapped by the hasher) and must be
   * cheap and side-effect-free: it runs inside `diff` on every plan. The
   * helper canonically hashes the result for the noop-vs-restart decision,
   * records it on the registry entry, and passes it to {@link start} so a
   * restart consumes exactly what was compared.
   *
   * Lifecycle-scoped services (`Stack`, `Stage`, `ResourceContext`, `Artifacts`)
   * are available ambiently (e.g. for `createPhysicalName`); resolve
   * anything else in the spec effect and close over it.
   *
   * @default `{ news: stripEffects(news), bindings }`
   */
  resolveConfig?: (ctx: LocalProviderInput<R>) => Effect.Effect<Config, any, any>;
  /**
   * Boot one instance: acquire the long-running process in the ambient
   * `Scope` and return the resource's Attributes once it is *ready* (URL
   * extracted, first serve succeeded, ...). The scope outlives the
   * reconcile that started it — it is forked from the provider root scope
   * and closed only when the instance is restarted (config change) or
   * deleted. The returned Effect MAY complete after readiness; liveness is
   * "registry entry with an open scope", not "unfinished fiber".
   *
   * Extra requirements beyond `Scope` (`StartR`) become requirements of
   * the provider layer — they must be present at layer build so the
   * lifecycle wrapper can hand them to `start` at runtime.
   */
  start: (
    ctx: StartContext<R, Config>,
  ) => Effect.Effect<R["Attributes"], any, Scope.Scope | StartR>;
  /**
   * Extra cleanup on delete, after the instance scope has closed — for
   * state that intentionally spans restarts and therefore cannot live in
   * the instance scope (proxy servers kept for URL stability, restart
   * hooks, ...). NOT called on restarts: a restarting instance keeps that
   * shared state. Must be idempotent; also called when nothing is running
   * (e.g. cleaning up a local row during a live deploy).
   */
  stop?: (ctx: StopContext) => Effect.Effect<void, any>;
  /**
   * Attributes that remain stable across the update the generated `diff`
   * is about to report (see `Diff.stables`). Called only when the diff is
   * an `update`.
   */
  stables?: (
    ctx: StablesContext<R, Config>,
  ) => Effect.Effect<Extract<keyof R["Attributes"], string>[] | undefined, any, any>;
  precreate?: AnyReqProviderService<R>["precreate"];
  tail?: AnyReqProviderService<R>["tail"];
  logs?: AnyReqProviderService<R>["logs"];
  /**
   * Override the generated `list` (which joins every registered instance's
   * fiber to its Attributes).
   */
  list?: AnyReqProviderService<R>["list"];
}

/**
 * {@link ProviderService} with every requirement channel widened to `any` —
 * passthrough spec hooks may use lifecycle-scoped services (`Stack`,
 * `ResourceContext`, ...) that the RpcProvider wrapper provides per call.
 */
type AnyReqProviderService<R extends ResourceLike> = ProviderService<
  R,
  any,
  any,
  any,
  any,
  any,
  any,
  any,
  any
>;

interface Instance<Attributes> {
  /** Identity guard so a replaced generation's delete cannot kill its successor. */
  instanceId: string;
  /** The resolved config the running instance was started with (for diagnostics). */
  config: unknown;
  configHash: string;
  fiber: Fiber.Fiber<Attributes, any>;
  scope: Scope.Closeable;
  /** Unique per start; guards invalidate/cleanup against racing restarts. */
  token: object;
}

/**
 * Canonical, collision-free hash of a plain-data value: SHA-256 over a
 * canonical JSON serialization (sorted keys, unwrapped `Redacted`,
 * `Uint8Array` and `bigint` encodings, cycle-safe).
 *
 * We deliberately do NOT use `Hash.structure`: Effect's structural hash
 * folds sibling fields together with XOR, so the same value change
 * appearing in two sibling subtrees cancels out and the hash is unchanged
 * — exactly the shape of a Worker config that mirrors `env` values into
 * derived `bindings`. An exact canonical serialization avoids the lossy
 * fingerprint; SHA-256 keeps the retained signature a fixed 64-char digest.
 */
export const canonicalHash = (value: unknown): Effect.Effect<string> => {
  const seen = new WeakSet<object>();
  const normalize = (input: unknown): unknown => {
    if (typeof input === "bigint") return `bigint:${input.toString()}`;
    if (input === null || typeof input !== "object") return input;
    if (Redacted.isRedacted(input)) {
      return { __redacted: input.pipe(Redacted.value, normalize) };
    }
    if (seen.has(input)) return "[circular]";
    seen.add(input);
    if (input instanceof Uint8Array) return { __bytes: Array.from(input) };
    if (Array.isArray(input)) return input.map(normalize);
    return Object.fromEntries(
      Object.keys(input)
        .sort()
        .map((key) => [key, normalize((input as Record<string, unknown>)[key])]),
    );
  };
  return sha256(JSON.stringify(normalize(value)));
};

/**
 * Build a local provider layer from a {@link LocalProviderSpec}.
 *
 * Generated lifecycle:
 *
 * - **diff** — `undefined` while inputs are unresolved; otherwise resolve
 *   the config and compare its canonical hash against the running
 *   instance: running + equal → `noop`, anything else → `update`. This is
 *   what encodes "the process may or may not be running" — state alone can
 *   never answer it.
 * - **reconcile** — same hash + running instance → join its fiber for the
 *   Attributes (redundant reconciles are free). Otherwise tear the old
 *   instance down and fork {@link LocalProviderSpec.start} in a fresh
 *   scope forked from the provider root scope, so the process outlives the
 *   deploy and dies with the sidecar.
 * - **delete** — tear down only if the registered instance belongs to the
 *   deleted `instanceId` (create-first replacement safety), then run
 *   {@link LocalProviderSpec.stop}. Idempotent.
 * - **list** — join every registered instance's fiber to its Attributes.
 *
 * All reconcile/delete work for one logical resource is serialized behind
 * a per-id semaphore so restarts never interleave.
 *
 * @param cls - the resource class (or Platform) this provider serves.
 * @param providersUrl - the provider group module this provider is registered
 *   in (see {@link RpcProvider.effect}).
 * @param spec - Effect constructing the {@link LocalProviderSpec}; resolve
 *   the services your callbacks need here and close over them.
 */
export const make = <
  R extends ResourceLike,
  Config = DefaultLocalConfig<R>,
  StartR = never,
  Req = never,
>(
  cls: ResourceClassLike<R> | Platform<R, any, any, any, any>,
  providersUrl: string,
  spec: Effect.Effect<LocalProviderSpec<R, Config, StartR>, never, Req>,
) =>
  RpcProvider.effect(
    cls,
    providersUrl,
    // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- StartR is re-provided by the RpcProvider wrapper, see comment at the cast below
    Effect.gen(function* () {
      const {
        resolveConfig = defaultResolveConfig<R, Config>,
        start,
        stop,
        stables,
        precreate,
        tail,
        logs,
        list,
      } = yield* spec;

      // The provider layer scope: in the sidecar this closes at session
      // shutdown, interrupting every registered instance and running its
      // finalizers (killing the processes).
      // Close independent instances concurrently at provider shutdown.
      const providerScope = yield* Effect.scope;
      // Registered before the fork, so it runs after every instance closed.
      let closingAt: number | undefined;
      yield* Scope.addFinalizer(
        providerScope,
        Effect.flatMap(Clock.currentTimeMillis, (now) =>
          closingAt === undefined
            ? Effect.void
            : Effect.logDebug(`shutdown: stopped ${cls.Type} instances in ${now - closingAt}ms`),
        ),
      );
      const rootScope = yield* Scope.fork(providerScope, "parallel");
      // Registered after the fork, so it runs first: the shutdown start.
      yield* Scope.addFinalizer(
        providerScope,
        Effect.flatMap(Clock.currentTimeMillis, (now) => {
          if (instances.size === 0) return Effect.void;
          closingAt = now;
          return Effect.logDebug(`shutdown: stopping ${instances.size} ${cls.Type} instance(s)`);
        }),
      );

      // Keyed by FQN (namespace path + logical id): a restart replaces the
      // entry, a replacement's new generation overwrites it (and the old
      // generation's delete is gated on `instanceId` so it cannot kill the
      // successor). NOT the logical id — that collides across namespaces
      // (two sites each declaring a `Command.Dev("Dev")` would evict each
      // other's running process).
      const instances = new Map<string, Instance<R["Attributes"]>>();

      // Serializes reconcile/delete per resource so a restart can never
      // interleave with another restart or a delete and leak a scope.
      const locks = new Map<string, Semaphore.Semaphore>();
      const lock = (id: string) => {
        let semaphore = locks.get(id);
        if (!semaphore) {
          semaphore = Semaphore.makeUnsafe(1);
          locks.set(id, semaphore);
        }
        return semaphore;
      };
      const withLock = <A, E, RR>(key: string, effect: Effect.Effect<A, E, RR>) =>
        Semaphore.withPermits(lock(key), 1)(effect);

      const resolveDesired = Effect.fn(function* (input: LocalProviderInput<R>) {
        const config = yield* resolveConfig(input);
        const configHash = yield* canonicalHash(config);
        return { config, configHash };
      });

      const teardown = Effect.fn(function* (fqn: string, instance: Instance<R["Attributes"]>) {
        const start = yield* Clock.currentTimeMillis;
        yield* Fiber.interrupt(instance.fiber);
        yield* Scope.close(instance.scope, Exit.void);
        const end = yield* Clock.currentTimeMillis;
        yield* Effect.logDebug(`stopped ${fqn} in ${end - start}ms`).pipe(
          Effect.annotateLogs(LogAnnotation.fqn, fqn),
        );
      });

      const startInstance = Effect.fn(function* (
        input: LocalProviderInput<R>,
        session: ScopedPlanStatusSession,
        config: Config,
        configHash: string,
      ) {
        const token = {};
        const invalidate = Effect.sync(() => {
          if (instances.get(input.fqn)?.token === token) {
            instances.delete(input.fqn);
          }
        });
        const scope = yield* Scope.fork(rootScope);
        const fiber = yield* start({
          ...input,
          config,
          session,
          invalidate,
        }).pipe(Effect.forkDetach, Scope.provide(scope));
        instances.set(input.fqn, {
          instanceId: input.instanceId,
          config,
          configHash,
          fiber,
          scope,
          token,
        });
        return yield* Fiber.join(fiber).pipe(
          Effect.onExit((exit) =>
            exit._tag === "Failure"
              ? // A failed start must not linger as "running" — the next
                // plan should report `update` and try again — nor keep what
                // it acquired: the instance scope would otherwise hold a
                // process that outlived its start (one still waiting for
                // its URL when the deploy was interrupted, say) until the
                // provider shut down.
                invalidate.pipe(Effect.andThen(Scope.close(scope, exit)))
              : Effect.void,
          ),
        );
      });

      const provider = {
        list:
          list ??
          (() =>
            Effect.forEach(
              Array.from(instances.values()),
              (instance) => Fiber.join(instance.fiber),
              { concurrency: "unbounded" },
            )),
        diff: Effect.fn(function* ({
          id,
          fqn,
          instanceId,
          news: rawNews,
          newBindings,
          output,
        }: {
          id: string;
          fqn: string;
          instanceId: string;
          news: any;
          newBindings: any;
          output: R["Attributes"] | undefined;
        }) {
          // Effect-valued leaves (tagged Worker classes in `env`, ...) never
          // resolve at plan time; their identity is carried by the resolved
          // binding data. Strip them so the config-based diff still runs.
          const news = stripEffects(rawNews);
          if (!isResolved(news) || !isResolved(newBindings)) return undefined;
          const input: LocalProviderInput<R> = {
            id,
            fqn,
            instanceId,
            news: news as R["Props"],
            bindings: newBindings as ResourceBinding<R["Binding"]>[],
          };
          const { config, configHash } = yield* resolveDesired(input);
          const existing = instances.get(fqn);
          if (existing && existing.configHash === configHash) {
            return { action: "noop" } satisfies Diff;
          }
          return {
            action: "update",
            stables: stables ? yield* stables({ ...input, config, output }) : undefined,
          } satisfies Diff;
        }),
        reconcile: Effect.fn(function* ({
          id,
          fqn,
          instanceId,
          news,
          bindings,
          session,
        }: {
          id: string;
          fqn: string;
          instanceId: string;
          news: R["Props"];
          bindings: ResourceBinding<R["Binding"]>[];
          session: ScopedPlanStatusSession;
        }) {
          return yield* withLock(
            fqn,
            Effect.gen(function* () {
              const input: LocalProviderInput<R> = {
                id,
                fqn,
                instanceId,
                news: stripEffects(news) as R["Props"],
                bindings,
              };
              const { config, configHash } = yield* resolveDesired(input);
              const existing = instances.get(fqn);
              if (existing) {
                if (existing.configHash === configHash) {
                  yield* Effect.log(`No changes, using existing instance`);
                  // Adopt the newest instanceId so a later replacement's
                  // old-generation delete cannot tear this instance down.
                  existing.instanceId = instanceId;
                  return yield* Fiber.join(existing.fiber);
                }
                yield* Effect.log(`Changes detected, restarting instance`);
                yield* teardown(fqn, existing);
                instances.delete(fqn);
              }
              return yield* startInstance(input, session, config, configHash);
            }).pipe(Effect.annotateLogs(LogAnnotation.fqn, fqn)),
          );
        }),
        delete: Effect.fn(function* ({
          id,
          fqn,
          instanceId,
        }: {
          id: string;
          fqn: string;
          instanceId: string;
        }) {
          yield* withLock(
            fqn,
            Effect.gen(function* () {
              const existing = instances.get(fqn);
              if (existing && existing.instanceId !== instanceId) {
                // A replacement's new generation is registered under this
                // logical id — the old generation's delete must not touch
                // it (nor the cross-restart state `stop` would clean up).
                return;
              }
              if (existing) {
                yield* teardown(fqn, existing);
                instances.delete(fqn);
              }
              // Runs even when nothing is registered: cross-restart state
              // (proxies, restart hooks) and out-of-session cleanup (e.g.
              // deleting a local row during a live deploy) still need it.
              if (stop) {
                yield* stop({ id, fqn, instanceId });
              }
            }),
          );
        }),
        ...(precreate ? { precreate } : {}),
        ...(tail ? { tail } : {}),
        ...(logs ? { logs } : {}),
      };

      return provider as any;
      // `StartR` (start's requirements beyond Scope) is surfaced as a layer
      // requirement: the RpcProvider wrapper captures the layer-build
      // context and provides it to every lifecycle call, so services the
      // layer demanded at build are available to `start` at runtime.
    }) as Effect.Effect<ProviderService<R>, never, Req | Exclude<StartR, Scope.Scope>>,
  );

const defaultResolveConfig = <R extends ResourceLike, Config>(
  input: LocalProviderInput<R>,
): Effect.Effect<Config, any> =>
  Effect.succeed({
    news: stripEffects(input.news),
    bindings: input.bindings,
  } as Config);