/**
* 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({}));