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

import type { Server } from "node:http";
import * as Cause from "effect/Cause";
import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Fiber from "effect/Fiber";
import * as Scope from "effect/Scope";

export class ManagedHttpShutdownInvalidProps extends Data.TaggedError(
  "ManagedHttpShutdownInvalidProps",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class ManagedHttpShutdownOperationFailed extends Data.TaggedError(
  "ManagedHttpShutdownOperationFailed",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/** Internal HTTP and dependency lifetimes, separate from managed run fibers. */
export class ManagedHttpShutdown extends Context.Service<
  ManagedHttpShutdown,
  {
    readonly scope: Scope.Closeable;
    readonly dependencies: Scope.Closeable;
    readonly servers: Set<Server>;
    readonly drainTimeoutMs: number;
    readonly isStopping: () => boolean;
    readonly observeRequest: (fiber: Fiber.Fiber<unknown, unknown>) => void;
    readonly runnerFinished: (exit: Exit.Exit<unknown, unknown>, last: boolean) => void;
  }
>()("Alchemy.Runtime.ManagedHttpShutdown") {}

/**
 * Coordinate shutdown of an Alchemy-owned Fly Service process, including HTTP
 * requests, background runners, and their shared dependencies.
 *
 * The Fly bootstrap enables this when `ALCHEMY_FLY_SHUTDOWN_TIMEOUT_MS` is set.
 * The Service provider sets it for managed Services using blue/green or an
 * explicit shutdown policy. Raw images and external servers own their shutdown.
 *
 * This is a process-entrypoint helper, not a request timeout or a general-purpose
 * Effect combinator. Running it installs process-wide SIGTERM and SIGINT
 * listeners. They coexist with other listeners, but cannot prevent another
 * listener from exiting the process. Importing this module installs no listeners.
 *
 * Shutdown stops HTTP acceptance and interrupts background runners concurrently.
 * Existing responses and request finalizers drain before shared dependencies
 * close. Deadlines start on a signal, runner failure, completion of all runner
 * bodies, or program completion, not after `timeoutMs` of normal execution.
 *
 * At 80% of the budget, remaining HTTP connections are forcibly closed. At 90%,
 * a native timer calls `process.exit(1)`, even if Effect finalizers are still
 * running. This reserves time before Fly's own termination deadline; it does
 * not guarantee cleanup completes. These timers require a responsive event loop.
 * Repeated signals do not extend the budget. Listeners and timers are removed
 * when the wrapper's scope closes, unless the process exits first.
 *
 * @param program - The whole managed process program, not an individual handler.
 * @param timeoutMs - Fly's configured shutdown budget, from 1 to 300000 ms.
 * @returns Whether shutdown was requested before the program completed.
 * Cleanup failures and exceeded drain deadlines fail the Effect; the caller
 * owns the normal process exit after successful cleanup.
 * @internal
 */
export const withManagedHttpShutdown = (
  program: Effect.Effect<unknown, unknown>,
  timeoutMs: number,
) =>
  Effect.gen(function* () {
    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 300_000) {
      return yield* new ManagedHttpShutdownInvalidProps({
        message: "ALCHEMY_FLY_SHUTDOWN_TIMEOUT_MS must be a positive integer at most 300000",
      });
    }

    const signal = yield* Deferred.make<void>();
    const scope = yield* Scope.make("parallel");
    const dependencies = yield* Scope.make();
    const servers = new Set<Server>();
    let stopping = false;
    let drained = false;
    let timedOut = false;
    const runnerFailures: Cause.Cause<unknown>[] = [];
    const requestFailures: Cause.Cause<unknown>[] = [];
    const requests = new Set<Fiber.Fiber<unknown, unknown>>();
    let drainDeadline: ReturnType<typeof setTimeout> | undefined;
    let deadline: ReturnType<typeof setTimeout> | undefined;
    // Leave time for request/instance finalizers, then for Fly's own stop deadline.
    const drainTimeoutMs = Math.floor(timeoutMs * 0.8);
    const exitTimeoutMs = Math.min(Math.floor(timeoutMs * 0.9), 2 ** 31 - 1);

    // Native timers remain independent of uninterruptible Effect finalizers.
    const beginShutdown = () => {
      if (stopping) return;
      stopping = true;
      drainDeadline = setTimeout(() => {
        if (drained) return;
        timedOut = true;
        console.error("Managed HTTP drain deadline exceeded; closing connections.");
        for (const server of servers) server.closeAllConnections();
      }, drainTimeoutMs);
      deadline = setTimeout(() => {
        console.error("Managed HTTP shutdown deadline exceeded; exiting.");
        process.exit(1);
      }, exitTimeoutMs);
    };

    yield* Effect.acquireRelease(
      Effect.sync(() => {
        const onSignal = () => {
          beginShutdown();
          Deferred.doneUnsafe(signal, Effect.void);
        };
        process.on("SIGTERM", onSignal);
        process.on("SIGINT", onSignal);
        return onSignal;
      }),
      (onSignal) =>
        Effect.sync(() => {
          process.off("SIGTERM", onSignal);
          process.off("SIGINT", onSignal);
          if (drainDeadline !== undefined) clearTimeout(drainDeadline);
          if (deadline !== undefined) clearTimeout(deadline);
        }),
    );
    yield* Effect.addFinalizer((exit) => Scope.close(dependencies, exit));
    yield* Effect.addFinalizer((exit) => Scope.close(scope, exit));

    const fiber = yield* program.pipe(
      Effect.provideService(ManagedHttpShutdown, {
        scope,
        dependencies,
        servers,
        drainTimeoutMs,
        isStopping: () => stopping,
        observeRequest: (request) => {
          if (requests.has(request)) return;
          requests.add(request);
          request.addObserver((exit) => {
            requests.delete(request);
            if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)) {
              requestFailures.push(exit.cause);
              console.error("Managed HTTP request cleanup failed", Cause.pretty(exit.cause));
            }
          });
        },
        runnerFinished: (exit, last) => {
          if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)) {
            runnerFailures.push(exit.cause);
            console.error("Managed process cleanup failed", Cause.pretty(exit.cause));
            beginShutdown();
            Deferred.doneUnsafe(signal, Effect.void);
          } else if (last) {
            beginShutdown();
          }
        },
      }),
      Effect.forkChild,
    );
    const interrupted = yield* Effect.raceFirst(
      Deferred.await(signal).pipe(Effect.as(true)),
      Fiber.await(fiber).pipe(Effect.as(false)),
    );
    yield* Effect.sync(beginShutdown);
    // Neither HTTP drain nor one worker's finalizers may delay another's stop.
    const [httpExit, programExit] = yield* Effect.all(
      [
        Scope.close(scope, Exit.void).pipe(Effect.exit),
        Effect.gen(function* () {
          if (interrupted) yield* Fiber.interrupt(fiber);
          return yield* Fiber.await(fiber);
        }),
      ],
      { concurrency: "unbounded" },
    );
    // Socket closure is not completion of the request fiber's finalizers.
    yield* Fiber.awaitAll(requests);
    drained = true;
    const dependencyExit = yield* Scope.close(dependencies, programExit).pipe(Effect.exit);
    const failures = runnerFailures.concat(
      requestFailures,
      [httpExit, programExit, dependencyExit].flatMap((exit) =>
        Exit.isFailure(exit) && !(interrupted && Cause.hasInterruptsOnly(exit.cause))
          ? [exit.cause]
          : [],
      ),
    );
    for (const cause of failures) {
      yield* Effect.logError("Managed process cleanup failed", cause);
    }
    if (failures.length > 0) return yield* Effect.failCause(failures[0]!);
    if (timedOut) {
      return yield* new ManagedHttpShutdownOperationFailed({
        message: "Managed process drain deadline exceeded",
      });
    }
    return interrupted;
  }).pipe(Effect.scoped);