effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/unstable/http/HttpServer.ts

@@ -1,4 +1,22 @@
 /**
+ * Service and helpers for running Effect HTTP applications on a concrete server
+ * runtime.
+ *
+ * This module defines the `HttpServer` service tag used by platform integrations
+ * to expose a listening server, plus accessors for serving an
+ * `HttpServerResponse` effect, formatting and logging server addresses, and
+ * building test clients against a running server. It is intended for low-level
+ * server runtimes, router integrations, HTTP API tests, and applications that
+ * need to start serving from a provided `Layer`.
+ *
+ * The server supplies `HttpServerRequest` for each request, so application
+ * effects should rely on the server for request-scoped data while still
+ * providing their other services through the surrounding environment. `serve`
+ * returns a `Layer` whose listener lifetime is managed by the layer scope; use
+ * `serveEffect` when composing directly in an effect with an explicit `Scope`.
+ * Test clients only support TCP addresses, and rewrite `0.0.0.0` to
+ * `127.0.0.1` for local requests.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -17,8 +35,13 @@ import type { HttpServerRequest } from "./HttpServerRequest.ts"
 import type { HttpServerResponse } from "./HttpServerResponse.ts"
 
 /**
- * @since 4.0.0
+ * Service tag for an HTTP server runtime.
+ *
+ * The service can serve an HTTP response effect and exposes the address where the
+ * server is listening.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class HttpServer extends Context.Service<HttpServer, {
   readonly serve: {
@@ -41,14 +64,20 @@ export class HttpServer extends Context.Service<HttpServer, {
 }>()("effect/http/HttpServer") {}
 
 /**
- * @since 4.0.0
+ * Address where an HTTP server is listening.
+ *
+ * The address is either a TCP host and port or a Unix domain socket path.
+ *
  * @category address
+ * @since 4.0.0
  */
 export type Address = UnixAddress | TcpAddress
 
 /**
- * @since 4.0.0
+ * TCP address for an HTTP server, identified by hostname and port.
+ *
  * @category address
+ * @since 4.0.0
  */
 export interface TcpAddress {
   readonly _tag: "TcpAddress"
@@ -57,8 +86,10 @@ export interface TcpAddress {
 }
 
 /**
- * @since 4.0.0
+ * Unix domain socket address for an HTTP server.
+ *
  * @category address
+ * @since 4.0.0
  */
 export interface UnixAddress {
   readonly _tag: "UnixAddress"
@@ -66,8 +97,11 @@ export interface UnixAddress {
 }
 
 /**
- * @since 4.0.0
+ * Constructs an `HttpServer` service from a serving implementation and listening
+ * address.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (
   options: {
@@ -80,20 +114,41 @@ export const make = (
 ): HttpServer["Service"] => options
 
 /**
- * @since 4.0.0
+ * Creates a layer that starts serving an HTTP response effect with the current
+ * `HttpServer`.
+ *
+ * The request service is supplied by the server for each request; the returned
+ * layer still requires the server, a scope, and any non-request dependencies of
+ * the response effect or middleware.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const serve: {
   /**
-   * @since 4.0.0
+   * Creates a layer that starts serving an HTTP response effect with the current
+   * `HttpServer`.
+   *
+   * The request service is supplied by the server for each request; the returned
+   * layer still requires the server, a scope, and any non-request dependencies of
+   * the response effect or middleware.
+   *
    * @category accessors
+   * @since 4.0.0
    */
   (): <E, R>(
     effect: Effect.Effect<HttpServerResponse, E, R>
   ) => Layer.Layer<never, never, HttpServer | Exclude<R, HttpServerRequest | Scope.Scope>>
   /**
-   * @since 4.0.0
+   * Creates a layer that starts serving an HTTP response effect with the current
+   * `HttpServer`.
+   *
+   * The request service is supplied by the server for each request; the returned
+   * layer still requires the server, a scope, and any non-request dependencies of
+   * the response effect or middleware.
+   *
    * @category accessors
+   * @since 4.0.0
    */
   <E, R, App extends Effect.Effect<HttpServerResponse, any, any>>(middleware: Middleware.HttpMiddleware.Applied<App, E, R>): (
     effect: Effect.Effect<HttpServerResponse, E, R>
@@ -103,13 +158,27 @@ export const serve: {
     HttpServer | Exclude<Effect.Services<App>, HttpServerRequest | Scope.Scope>
   >
   /**
-   * @since 4.0.0
+   * Creates a layer that starts serving an HTTP response effect with the current
+   * `HttpServer`.
+   *
+   * The request service is supplied by the server for each request; the returned
+   * layer still requires the server, a scope, and any non-request dependencies of
+   * the response effect or middleware.
+   *
    * @category accessors
+   * @since 4.0.0
    */
   <E, R>(effect: Effect.Effect<HttpServerResponse, E, R>): Layer.Layer<never, never, HttpServer | Exclude<R, HttpServerRequest | Scope.Scope>>
   /**
-   * @since 4.0.0
+   * Creates a layer that starts serving an HTTP response effect with the current
+   * `HttpServer`.
+   *
+   * The request service is supplied by the server for each request; the returned
+   * layer still requires the server, a scope, and any non-request dependencies of
+   * the response effect or middleware.
+   *
    * @category accessors
+   * @since 4.0.0
    */
   <E, R, App extends Effect.Effect<HttpServerResponse, any, any>>(
     effect: Effect.Effect<HttpServerResponse, E, R>,
@@ -132,20 +201,41 @@ export const serve: {
   ) as any)
 
 /**
- * @since 4.0.0
+ * Effect that starts serving an HTTP response effect with the current
+ * `HttpServer`.
+ *
+ * The request service is supplied by the server for each request; the effect
+ * requires a scope and any non-request dependencies of the response effect or
+ * middleware.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const serveEffect: {
   /**
-   * @since 4.0.0
+   * Effect that starts serving an HTTP response effect with the current
+   * `HttpServer`.
+   *
+   * The request service is supplied by the server for each request; the effect
+   * requires a scope and any non-request dependencies of the response effect or
+   * middleware.
+   *
    * @category accessors
+   * @since 4.0.0
    */
   (): <E, R>(
     effect: Effect.Effect<HttpServerResponse, E, R>
   ) => Effect.Effect<void, never, Scope.Scope | HttpServer | Exclude<R, HttpServerRequest>>
   /**
-   * @since 4.0.0
+   * Effect that starts serving an HTTP response effect with the current
+   * `HttpServer`.
+   *
+   * The request service is supplied by the server for each request; the effect
+   * requires a scope and any non-request dependencies of the response effect or
+   * middleware.
+   *
    * @category accessors
+   * @since 4.0.0
    */
   <E, R, App extends Effect.Effect<HttpServerResponse, any, any>>(middleware: Middleware.HttpMiddleware.Applied<App, E, R>): (
     effect: Effect.Effect<HttpServerResponse, E, R>
@@ -155,13 +245,27 @@ export const serveEffect: {
     Scope.Scope | HttpServer | Exclude<Effect.Services<App>, HttpServerRequest>
   >
   /**
-   * @since 4.0.0
+   * Effect that starts serving an HTTP response effect with the current
+   * `HttpServer`.
+   *
+   * The request service is supplied by the server for each request; the effect
+   * requires a scope and any non-request dependencies of the response effect or
+   * middleware.
+   *
    * @category accessors
+   * @since 4.0.0
    */
   <E, R>(effect: Effect.Effect<HttpServerResponse, E, R>): Effect.Effect<void, never, Scope.Scope | HttpServer | Exclude<R, HttpServerRequest>>
   /**
-   * @since 4.0.0
+   * Effect that starts serving an HTTP response effect with the current
+   * `HttpServer`.
+   *
+   * The request service is supplied by the server for each request; the effect
+   * requires a scope and any non-request dependencies of the response effect or
+   * middleware.
+   *
    * @category accessors
+   * @since 4.0.0
    */
   <E, R, App extends Effect.Effect<HttpServerResponse, any, any>>(
     effect: Effect.Effect<HttpServerResponse, E, R>,
@@ -181,8 +285,13 @@ export const serveEffect: {
 > => HttpServer.use((server) => server.serve(effect, middleware!)) as any)
 
 /**
- * @since 4.0.0
+ * Formats a server address as a display string.
+ *
+ * TCP addresses are formatted as `http://host:port`; Unix socket addresses are
+ * formatted as `unix://path`.
+ *
  * @category address
+ * @since 4.0.0
  */
 export const formatAddress = (address: Address): string => {
   switch (address._tag) {
@@ -194,8 +303,11 @@ export const formatAddress = (address: Address): string => {
 }
 
 /**
- * @since 4.0.0
+ * Reads the current server address, formats it with `formatAddress`, and passes
+ * the formatted address to the supplied effectful function.
+ *
  * @category address
+ * @since 4.0.0
  */
 export const addressFormattedWith = <A, E, R>(
   f: (address: string) => Effect.Effect<A, E, R>
@@ -206,16 +318,20 @@ export const addressFormattedWith = <A, E, R>(
   )
 
 /**
- * @since 4.0.0
+ * Logs the formatted address of the current HTTP server.
+ *
  * @category address
+ * @since 4.0.0
  */
 export const logAddress: Effect.Effect<void, never, HttpServer> = addressFormattedWith((_) =>
   Effect.log(`Listening on ${_}`)
 )
 
 /**
- * @since 4.0.0
+ * Adds address logging to a layer that provides an `HttpServer`.
+ *
  * @category address
+ * @since 4.0.0
  */
 export const withLogAddress = <A, E, R>(
   layer: Layer.Layer<A, E, R>
@@ -225,8 +341,13 @@ export const withLogAddress = <A, E, R>(
   )
 
 /**
- * @since 4.0.0
+ * Builds an `HttpClient` that sends requests to the current test HTTP server.
+ *
+ * For TCP servers, requests are prefixed with the server URL and `0.0.0.0` is
+ * rewritten to `127.0.0.1`. Unix socket addresses are not supported.
+ *
  * @category Testing
+ * @since 4.0.0
  */
 export const makeTestClient: Effect.Effect<
   HttpClient.HttpClient,
@@ -245,8 +366,10 @@ export const makeTestClient: Effect.Effect<
 })
 
 /**
- * @since 4.0.0
+ * Layer that provides the test `HttpClient` created by `makeTestClient`.
+ *
  * @category Testing
+ * @since 4.0.0
  */
 export const layerTestClient: Layer.Layer<
   HttpClient.HttpClient,
@@ -255,8 +378,14 @@ export const layerTestClient: Layer.Layer<
 > = Layer.effect(HttpClient.HttpClient)(makeTestClient)
 
 /**
- * @since 4.0.0
+ * Testing layer that provides the platform services commonly needed by HTTP
+ * server tests.
+ *
+ * It includes `HttpPlatform`, `Path`, a weak ETag generator, and a no-op
+ * `FileSystem`.
+ *
  * @category Testing
+ * @since 4.0.0
  */
 export const layerServices: Layer.Layer<
   | Path.Path

package/src/unstable/http/HttpServerError.ts

@@ -1,4 +1,24 @@
 /**
+ * Error types and response conversion helpers used by the HTTP server runtime.
+ *
+ * This module models the failure cases that can happen around a server request:
+ * malformed or unreadable requests, unmatched routes, unexpected handler
+ * failures, response construction or delivery failures, and lower-level server
+ * implementation failures. These errors keep the relevant request, and for
+ * response failures the response that was being produced, so applications can
+ * report, inspect, or translate failures without losing HTTP context.
+ *
+ * Most users encounter these errors when decoding request bodies, implementing
+ * fallback routes, adding error reporting, or customizing how handler failures
+ * become responses. Request parse errors become `400` responses, missing routes
+ * become `404` responses and are ignored by the error reporter, and internal or
+ * response errors become `500` responses. A `ResponseError` records the response
+ * involved in the failure, but its default conversion intentionally sends an
+ * empty `500` instead of reusing a response that may already be invalid or
+ * partially failed. Handler causes can also contain respondable failures,
+ * response defects, or interrupts; the conversion helpers preserve those
+ * distinctions, including `499` for client aborts and `503` for server aborts.
+ *
  * @since 4.0.0
  */
 import * as Cause from "../../Cause.ts"
@@ -17,8 +37,14 @@ import * as Response from "./HttpServerResponse.ts"
 const TypeId = "~effect/http/HttpServerError"
 
 /**
- * @since 4.0.0
+ * Tagged error for failures that occur while handling an HTTP server request.
+ *
+ * It wraps a `HttpServerErrorReason`, exposes the associated request and optional
+ * response, and can be converted to an HTTP response through the `Respondable`
+ * protocol.
+ *
  * @category error
+ * @since 4.0.0
  */
 export class HttpServerError extends Data.TaggedError("HttpServerError")<{
   readonly reason: HttpServerErrorReason
@@ -62,8 +88,12 @@ export class HttpServerError extends Data.TaggedError("HttpServerError")<{
 }
 
 /**
- * @since 4.0.0
+ * Error describing a failure to parse or read an incoming request.
+ *
+ * When converted to a response it produces an empty `400` response.
+ *
  * @category error
+ * @since 4.0.0
  */
 export class RequestParseError extends Data.TaggedError("RequestParseError")<{
   readonly request: Request.HttpServerRequest
@@ -71,6 +101,8 @@ export class RequestParseError extends Data.TaggedError("RequestParseError")<{
   readonly cause?: unknown
 }> implements Respondable.Respondable {
   /**
+   * Converts the request error into a `400 Bad Request` response.
+   *
    * @since 4.0.0
    */
   [Respondable.symbol]() {
@@ -87,8 +119,13 @@ export class RequestParseError extends Data.TaggedError("RequestParseError")<{
 }
 
 /**
- * @since 4.0.0
+ * Error indicating that no route matched the incoming request.
+ *
+ * When converted to a response it produces an empty `404` response, and it is
+ * ignored by the error reporter.
+ *
  * @category error
+ * @since 4.0.0
  */
 export class RouteNotFound extends Data.TaggedError("RouteNotFound")<{
   readonly request: Request.HttpServerRequest
@@ -111,8 +148,12 @@ export class RouteNotFound extends Data.TaggedError("RouteNotFound")<{
 }
 
 /**
- * @since 4.0.0
+ * Error describing an unexpected server-side failure while handling a request.
+ *
+ * When converted to a response it produces an empty `500` response.
+ *
  * @category error
+ * @since 4.0.0
  */
 export class InternalError extends Data.TaggedError("InternalError")<{
   readonly request: Request.HttpServerRequest
@@ -120,6 +161,8 @@ export class InternalError extends Data.TaggedError("InternalError")<{
   readonly cause?: unknown
 }> implements Respondable.Respondable {
   /**
+   * Converts the server error into a `500 Internal Server Error` response.
+   *
    * @since 4.0.0
    */
   [Respondable.symbol]() {
@@ -136,14 +179,21 @@ export class InternalError extends Data.TaggedError("InternalError")<{
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` when the supplied value is an `HttpServerError`.
+ *
  * @category predicates
+ * @since 4.0.0
  */
 export const isHttpServerError = (u: unknown): u is HttpServerError => hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Error describing a failure related to an HTTP response.
+ *
+ * It carries the request and response involved in the failure. When converted to
+ * a response it produces an empty `500` response.
+ *
  * @category error
+ * @since 4.0.0
  */
 export class ResponseError extends Data.TaggedError("ResponseError")<{
   readonly request: Request.HttpServerRequest
@@ -166,28 +216,42 @@ export class ResponseError extends Data.TaggedError("ResponseError")<{
 }
 
 /**
- * @since 4.0.0
+ * Union of errors that are tied directly to an incoming server request.
+ *
  * @category error
+ * @since 4.0.0
  */
 export type RequestError = RequestParseError | RouteNotFound | InternalError
 
 /**
- * @since 4.0.0
+ * Reason carried by an `HttpServerError`.
+ *
+ * It is either a request-level error or a response-level error.
+ *
  * @category error
+ * @since 4.0.0
  */
 export type HttpServerErrorReason = RequestError | ResponseError
 
 /**
- * @since 4.0.0
+ * Error wrapping a low-level failure from the HTTP server implementation.
+ *
  * @category error
+ * @since 4.0.0
  */
 export class ServeError extends Data.TaggedError("ServeError")<{
   readonly cause: unknown
 }> {}
 
 /**
- * @since 4.0.0
+ * Context annotation used to mark an interrupt as caused by the client aborting
+ * the request.
+ *
+ * `causeResponse` uses this annotation to map a pure client abort to a `499`
+ * response instead of a server abort response.
+ *
  * @category Annotations
+ * @since 4.0.0
  */
 export class ClientAbort extends Context.Service<ClientAbort, true>()("effect/http/HttpServerError/ClientAbort") {
   static annotation = this.context(true).pipe(
@@ -205,6 +269,13 @@ const formatRequestMessage = (reason: string, description: string | undefined, i
 }
 
 /**
+ * Converts a failed handler cause into the HTTP response that should be sent and
+ * the cause that should be reported.
+ *
+ * Respondable failures and defects can choose their own response, defects that
+ * are already `HttpServerResponse` values are used directly, and pure interrupts
+ * produce either `499` for client aborts or `503` for server aborts.
+ *
  * @since 4.0.0
  */
 export const causeResponse = <E>(
@@ -253,6 +324,12 @@ export const causeResponse = <E>(
 }
 
 /**
+ * Synchronously derives an HTTP response from a failed handler cause.
+ *
+ * If the cause contains a defect that is already an `HttpServerResponse`, that
+ * response is used and removed from the remaining cause. Otherwise the response
+ * defaults to `500`.
+ *
  * @since 4.0.0
  */
 export const causeResponseStripped = <E>(
@@ -278,6 +355,9 @@ const clientAbortError = Effect.succeed(Response.empty({ status: 499 }))
 const serverAbortError = Effect.succeed(Response.empty({ status: 503 }))
 
 /**
+ * Extracts the response from a successful handler exit, or derives a response
+ * from the failure cause.
+ *
  * @since 4.0.0
  */
 export const exitResponse = <E>(exit: Exit.Exit<Response.HttpServerResponse, E>): Response.HttpServerResponse => {