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

/**
 * HTTP runtime bridges and platform services for Effect's HTTP APIs.
 */
import * as Cause from "effect/Cause";
import * as Config from "effect/Config";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as ErrorReporter from "effect/ErrorReporter";
import * as FileSystem from "effect/FileSystem";
import * as Etag from "effect/http/Etag";
import type { HttpBodyError } from "effect/http/HttpBody";
import * as HttpPlatform from "effect/http/HttpPlatform";
import { causeResponse, type HttpServerError } from "effect/http/HttpServerError";
import { HttpServerRequest } from "effect/http/HttpServerRequest";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Scope from "effect/Scope";
import { ManagedHttpShutdown } from "./Runtime/ManagedHttpShutdown.ts";

export type HttpEffect<Req = never> = Effect.Effect<
  HttpServerResponse.HttpServerResponse,
  HttpServerError | HttpBodyError,
  HttpServerRequest | Scope.Scope | Req
>;

/**
 * `effect`'s HttpEffect brands a request scope as "ejected" when ownership
 * is transferred to a consumer that outlives the handler's return — a
 * streaming response body, a WebSocket upgrade, an RPC stream. Bridges check
 * this before their close-on-return path: an ejected scope is closed by its
 * new owner when it finishes, not by the bridge.
 */
const scopeEjected = Symbol.for("effect/http/HttpEffect/scopeEjected");

export const isScopeEjected = (scope: Scope.Scope) => scopeEjected in scope;

export const serve = <Req = never>(
  handler: Effect.Effect<
    HttpServerResponse.HttpServerResponse,
    HttpServerError | HttpBodyError,
    HttpServerRequest | Scope.Scope | Req
  >,
) =>
  Effect.serviceOption(HttpServer).pipe(
    Effect.map(Option.getOrUndefined),
    Effect.flatMap((http) =>
      http
        ? // `HttpServer.serve` registers the server on the ambient Scope and
          // RETURNS; the server lives until that scope closes. A host program
          // (ECS task/service, EC2 instance) must therefore park forever after
          // a successful registration — otherwise a pure `{ fetch }` program
          // completes immediately, `Effect.scoped` closes the scope, and the
          // container exits 0 in a crash-loop. (One-shot `{ run }` programs
          // never call `serve`, so they still exit when `run` completes.)
          Effect.andThen(http.serve(handler), Effect.never)
        : Effect.void,
    ),
  );

export class HttpServer extends Context.Service<
  HttpServer,
  {
    serve: <Req = never>(
      handler: Effect.Effect<
        HttpServerResponse.HttpServerResponse,
        HttpServerError | HttpBodyError,
        Req
      >,
      options?: { port?: number },
    ) => Effect.Effect<void, never, Exclude<Req, HttpServerRequest> | Scope.Scope>;
  }
>()("HttpServer") {}

export const safeHttpEffect = <Req = never>(
  handler: HttpEffect<Req> | Effect.Effect<HttpEffect<Req>>,
): Effect.Effect<
  HttpServerResponse.HttpServerResponse,
  never,
  Req | HttpServerRequest | Scope.Scope
> =>
  Effect.catchCause(
    handler.pipe(
      // @ts-expect-error
      Effect.flatMap((response) =>
        HttpServerResponse.isHttpServerResponse(response) ? Effect.succeed(response) : response,
      ),
    ) as any as HttpEffect<Req>,
    (cause) =>
      // `causeResponse` is effect's native failure boundary: Respondable
      // failures keep their intended response (e.g. RouteNotFound -> 404),
      // client aborts map to 499, and everything else becomes an empty 500 —
      // the cause is never echoed to the network, as it can contain sensitive
      // data (prompt contents, API keys baked into error messages, internal
      // file paths).
      causeResponse(cause).pipe(
        Effect.flatMap(([response, reportableCause]) =>
          Effect.withFiber((fiber) =>
            fiber.getRef(ErrorReporter.CurrentErrorReporters).size > 0
              ? ErrorReporter.report(reportableCause)
              : logUnreportedCause(reportableCause),
          ).pipe(Effect.as(response)),
        ),
      ),
  );

/**
 * No `ErrorReporter` is registered by default, so without a fallback a defect
 * in a deployed Function/Worker would produce a bare 500 and vanish without a
 * trace. Log the cause server-side so operators can debug, applying the same
 * filtering `ErrorReporter.make` reporters do: interrupts (client aborts) and
 * `ErrorReporter.ignore`-annotated values (Respondable errors like
 * RouteNotFound, and the response `causeResponse` appends) are not failures
 * and are skipped.
 */
const logUnreportedCause = (cause: Cause.Cause<unknown>) => {
  const failures = cause.reasons.filter(
    (reason) =>
      reason._tag !== "Interrupt" &&
      !ErrorReporter.isIgnored(reason._tag === "Fail" ? reason.error : reason.defect),
  );
  return failures.length === 0
    ? Effect.void
    : Effect.logError("HTTP handler failed", Cause.fromReasons(failures));
};

export const resolvePort = (options: { port?: number } | undefined) =>
  options?.port !== undefined
    ? Effect.succeed(options.port)
    : Config.Number("PORT").pipe(Config.withDefault(3000));

export interface BunHttpServerOptions {
  /**
   * Network interface on which the Bun HTTP server listens.
   *
   * Always passed explicitly to `Bun.serve` so container bootstraps bind a
   * predictable IPv4 wildcard regardless of the platform default
   * (`@effect/platform-bun` ≥ 4.0.0-rc.115 defaults to `::`; rc.113/114
   * crash-looped on the omitted-hostname case).
   *
   * @default "0.0.0.0"
   */
  hostname?: string;
}

export const BunHttpServer = (serverOptions?: BunHttpServerOptions) =>
  Layer.effect(
    HttpServer,
    Effect.gen(function* () {
      const BunHttpServerPlatform = yield* Effect.promise(
        () => import("@effect/platform-bun/BunHttpServer"),
      );
      return {
        serve: (handler, options) =>
          Effect.gen(function* () {
            const port = yield* resolvePort(options);
            const server = yield* BunHttpServerPlatform.make({
              port,
              hostname: serverOptions?.hostname ?? "0.0.0.0",
            });
            yield* server.serve(safeHttpEffect(handler));
          }).pipe(Effect.orDie),
      };
    }),
  );

export interface NodeHttpServerOptions {
  /**
   * Address the Node HTTP server binds. Fly / Hetzner / Railway machines
   * need `0.0.0.0`; omit to use that default.
   * @default "0.0.0.0"
   */
  hostname?: string;
  /**
   * Port the Node HTTP server binds when the handler is served without an
   * explicit port. Omit to read `PORT` (default `3000`).
   */
  port?: number;
}

export const NodeHttpServer = (serverOptions?: NodeHttpServerOptions) =>
  Layer.effect(
    HttpServer,
    Effect.gen(function* () {
      const NodeHttpServerPlatform = yield* Effect.promise(
        () => import("@effect/platform-node/NodeHttpServer"),
      );
      const NodeHttp = yield* Effect.promise(() => import("node:http"));
      return {
        serve: (handler, options) =>
          Effect.gen(function* () {
            const port = yield* resolvePort({ port: options?.port ?? serverOptions?.port });
            const shutdown = yield* Effect.serviceOption(ManagedHttpShutdown);
            const managed = Option.getOrUndefined(shutdown);
            if (managed?.isStopping()) return yield* Effect.interrupt;
            const serve = Effect.gen(function* () {
              const server = yield* NodeHttpServerPlatform.make(
                () => {
                  const server = NodeHttp.createServer();
                  managed?.servers.add(server);
                  server.once("close", () => managed?.servers.delete(server));
                  return server;
                },
                {
                  port,
                  host: serverOptions?.hostname ?? "0.0.0.0",
                  gracefulShutdownTimeout: managed?.drainTimeoutMs,
                },
              );
              // The Node bridge masks interruption, including streaming writes.
              yield* managed
                ? server.serve(safeHttpEffect(handler), (handled) =>
                    Effect.withFiber((fiber) => {
                      // Observe outside the adapter's request-scope finalization.
                      managed.observeRequest(fiber);
                      return Effect.interruptible(handled);
                    }),
                  )
                : server.serve(safeHttpEffect(handler));
            });
            if (managed) {
              const scope = yield* Scope.fork(managed.scope);
              yield* serve.pipe(Scope.provide(scope));
            } else {
              yield* serve;
            }
          }).pipe(Effect.orDie),
      };
    }),
  );

const HttpPlatformStub: Layer.Layer<HttpPlatform.HttpPlatform> = Layer.succeed(
  HttpPlatform.HttpPlatform,
  {
    platform: "web",
    // Advertises no algorithms, so the compression middleware never engages
    // and compressResponse is never called.
    compression: {
      algorithms: new Set<HttpPlatform.CompressionAlgorithm>(),
      compressResponse: (response) => Effect.succeed(response),
    },
    fileResponse: () => Effect.die("HttpPlatform.fileResponse not supported"),
    fileWebResponse: () => Effect.die("HttpPlatform.fileWebResponse not supported"),
  },
);

/**
 * The `HttpPlatform`, `Etag`, `Path`, and no-op `FileSystem` services `HttpApiBuilder.layer`
 * wants, for runtimes without a filesystem: Workers, Lambda. File responses
 * die, compression never engages.
 *
 * Provide it to `HttpApiBuilder.layer(api)` in a Worker or a Lambda:
 *
 * ```typescript
 * HttpApiBuilder.layer(Api).pipe(
 *   Layer.provide(handlers),
 *   Layer.provide(Http.Platform),
 *   HttpRouter.toHttpEffect,
 * )
 * ```
 */
export const Platform: Layer.Layer<
  Etag.Generator | HttpPlatform.HttpPlatform | Path.Path | FileSystem.FileSystem
> = Layer.mergeAll(Etag.layer, HttpPlatformStub, Path.layer, FileSystem.layerNoop({}));