sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Runtime/ Process.ts

import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import { FileSystem } from "effect/FileSystem";
import * as Option from "effect/Option";
import type { Path } from "effect/Path";
import type { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
import type { Stdio } from "effect/Stdio";
import type { Terminal } from "effect/Terminal";
import type { HttpEffect } from "../Http.ts";
import * as Http from "../Http.ts";
import * as Output from "../Output.ts";
import { packEnvValue, unpackEnvValue, type BaseRuntimeContext } from "../RuntimeContext.ts";
import { ManagedHttpShutdown } from "./ManagedHttpShutdown.ts";

export type ProcessServices = ChildProcessSpawner | FileSystem | Path | Stdio | Terminal;

export interface ProcessContext extends BaseRuntimeContext {
  run: <Req = never, RunReq = never>(
    effect: Effect.Effect<void, never, RunReq>,
  ) => Effect.Effect<void, never, Req | RunReq>;
}

/**
 * Long-running host loop registration (`run`). Provided by `Platform` when the
 * execution context implements {@link ProcessContext} (i.e. carries `run`).
 *
 * `Platform` wires this automatically for every host runtime context that
 * implements `run` (EC2 instances, ECS tasks, processes), so an inline program
 * can `yield* ServerHost` and call `host.run(...)` during plan/deploy without
 * the caller providing the layer itself.
 */
export class ServerHost extends Context.Service<ServerHost, Pick<ProcessContext, "run">>()(
  "Alchemy::ServerHost",
) {}

/**
 * Deploy-time / plan-time host context for platforms that bundle a long-lived
 * program. It collects background work registered via `run` and HTTP handlers
 * registered via `serve` into a single `exports.program` effect that the
 * generated container/instance entrypoint runs.
 */
export interface HostRuntimeContext extends ProcessContext {
  serve: <Req = never>(
    handler: HttpEffect<Req> | Effect.Effect<HttpEffect<Req>>,
    options?: { shape?: Record<string, unknown> },
  ) => Effect.Effect<void, never, Req>;
  exports: Effect.Effect<{
    readonly program: Effect.Effect<void, never, any>;
  }>;
}

/**
 * Build a {@link HostRuntimeContext} for a hosted platform of the given
 * resource `type`. Both `run` (background loops) and `serve` (HTTP handlers)
 * append to a single list of runners; `exports.program` runs them all
 * concurrently. This is the shared host context used by `AWS.EC2.Instance` and
 * `AWS.ECS.Task`. Managed Fly shutdown gives each runner a sequential resource
 * scope; runner scopes close concurrently while HTTP and shared dependencies live.
 * A shutdown signal starts an independent deadline, including for application-owned
 * scopes. Without a signal, a nested `Effect.scoped` runner must finish its own
 * finalizers before the host can observe completion or failure. Applications must
 * bound that cleanup; the host cannot observe an opaque scope's earlier body exit.
 */
export const createHostRuntimeContext =
  (type: string) =>
  (id: string): HostRuntimeContext => {
    const runners: Effect.Effect<void, never, any>[] = [];
    const env: Record<string, any> = {};

    return {
      Type: type,
      id,
      env,
      set: (bindingId: string, output: Output.Output) =>
        Effect.sync(() => {
          const key = bindingId.replaceAll(/[^a-zA-Z0-9]/g, "_");
          // `packEnvValue` marker-packs Redacted values so they survive the
          // Output → env round-trip.
          env[key] = output.pipe(Output.map(packEnvValue));
          return key;
        }),
      get: <T>(key: string) =>
        // Read straight from `process.env` — see `unpackEnvValue` for why
        // this must never resolve through `Config.String`.
        Effect.sync(() => unpackEnvValue<T>(process.env[key]) as T),
      run: (effect: Effect.Effect<void, never, any>) =>
        Effect.sync(() => {
          runners.push(effect);
        }),
      serve: ((handler) =>
        Effect.sync(() => {
          // Register the HTTP handler as a runner. At container runtime the
          // ambient `HttpServer` (if provided) serves it; `Http.serve` is a
          // no-op when no server is bound, so this never crashes plan/deploy.
          runners.push(Http.serve(handler as HttpEffect<any>));
        })) as HostRuntimeContext["serve"],
      exports: Effect.sync(() => ({
        program: Effect.serviceOption(ManagedHttpShutdown).pipe(
          Effect.flatMap((managed) => {
            let remaining = runners.length;
            return Effect.all(
              Option.isSome(managed)
                ? runners.map((runner) =>
                    runner.pipe(
                      Effect.onExit((exit) =>
                        Effect.sync(() => managed.value.runnerFinished(exit, --remaining === 0)),
                      ),
                      Effect.scoped,
                      // Parent interruption may discard child finalizer defects.
                      Effect.onExit((exit) =>
                        Effect.sync(() => managed.value.runnerFinished(exit, false)),
                      ),
                    ),
                  )
                : runners,
              { concurrency: "unbounded" },
            );
          }),
        ),
      })),
    } satisfies HostRuntimeContext;
  };

/**
 * Host runtime context for container platforms (`AWS.ECS.Task`,
 * `AWS.ECS.Service`, `Docker.Service`): extends the shared process host
 * context so an impl shape's `run` effect is registered as a one-shot runner
 * (the container exits when it completes) and the HTTP server only boots when
 * the impl actually declares a `fetch` handler.
 */
export const createContainerRuntimeContext =
  (type: string) =>
  (id: string): HostRuntimeContext => {
    const base = createHostRuntimeContext(type)(id);
    // Capture the host serve BEFORE Object.assign overwrites `base.serve`
    // with the wrapper below — calling `base.serve` inside the wrapper would
    // resolve to the wrapper itself (property lookup happens at call time)
    // and recurse without bound the moment an impl declares `fetch`.
    const serveBase = base.serve;
    const serve: HostRuntimeContext["serve"] = (handler, options) =>
      Effect.gen(function* () {
        const shape = options?.shape;
        const run = shape?.run;
        if (Effect.isEffect(run)) {
          // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- `run` is a user program; the host runner surfaces its failures
          yield* base.run(run as Effect.Effect<void, never, any>);
        }
        // Boot the HTTP server only for an impl that declared `fetch` — a
        // pure one-shot `{ run }` program must exit when `run` completes
        // rather than parking behind the 404 fallback server forever.
        if (shape === undefined || shape.fetch !== undefined) {
          yield* serveBase(handler, options);
        }
      }) as Effect.Effect<void, never, never>;
    return Object.assign(base, { serve });
  };