effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/http/HttpMiddleware.ts

@@ -1,4 +1,26 @@
 /**
+ * Server-side HTTP middleware for wrapping `HttpServerResponse` effects with
+ * cross-cutting request and response behavior.
+ *
+ * A middleware is a function from one HTTP server app effect to another. The app
+ * is evaluated with the current `HttpServerRequest` service in its context, so
+ * middleware in this module can inspect or rewrite the request, provide
+ * request-scoped services, attach pre-response hooks, or observe the app exit
+ * while preserving normal Effect error and interruption semantics.
+ *
+ * Use this module for common server concerns such as access logging, trace span
+ * creation, trusting forwarded proxy headers, parsing search parameters, and
+ * adding CORS handling. Middleware can be applied directly when serving an
+ * `HttpServer` / `HttpEffect` app or registered through `HttpRouter.middleware`
+ * for route-scoped or global behavior.
+ *
+ * Middleware composition is order-sensitive, and each middleware may change the
+ * wrapped effect's requirements or error channel. These functions expect a
+ * per-request `HttpServerRequest` to be present; context-providing middleware
+ * should wrap handlers before they access the provided service, and
+ * error-handling middleware should be installed where its transformed error type
+ * matches the surrounding app or router registration.
+ *
  * @since 4.0.0
  */
 import { Clock } from "../../Clock.ts"
@@ -22,18 +44,24 @@ import * as TraceContext from "./HttpTraceContext.ts"
 import { appendPreResponseHandlerUnsafe } from "./internal/preResponseHandler.ts"
 
 /**
- * @since 4.0.0
+ * Middleware that transforms an HTTP server app effect into another HTTP server app effect.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface HttpMiddleware {
   <E, R>(self: Effect.Effect<HttpServerResponse, E, R | HttpServerRequest>): Effect.Effect<HttpServerResponse, any, any>
 }
 
 /**
+ * Namespace containing types associated with `HttpMiddleware`.
+ *
  * @since 4.0.0
  */
 export declare namespace HttpMiddleware {
   /**
+   * Callable type representing middleware already specialized to a particular transformed app type.
+   *
    * @since 4.0.0
    */
   export interface Applied<A extends Effect.Effect<HttpServerResponse, any, any>, E, R> {
@@ -42,8 +70,10 @@ export declare namespace HttpMiddleware {
 }
 
 /**
- * @since 4.0.0
+ * Defines an `HttpMiddleware` while preserving its precise type.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <M extends HttpMiddleware>(middleware: M): M => middleware
 
@@ -63,8 +93,10 @@ const stripSearchAndHash = (url: string): string => {
 }
 
 /**
- * @since 4.0.0
+ * Runs an effect with HTTP response logging disabled for the current server request.
+ *
  * @category Logger
+ * @since 4.0.0
  */
 export const withLoggerDisabled = <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | HttpServerRequest> =>
   Effect.withFiber((fiber) => {
@@ -74,8 +106,10 @@ export const withLoggerDisabled = <A, E, R>(self: Effect.Effect<A, E, R>): Effec
   })
 
 /**
- * @since 4.0.0
+ * Context reference for a predicate that disables server-side tracing for matching requests.
+ *
  * @category Tracer
+ * @since 4.0.0
  */
 export const TracerDisabledWhen = Context.Reference<Predicate<HttpServerRequest>>(
   "effect/http/HttpMiddleware/TracerDisabledWhen",
@@ -83,16 +117,20 @@ export const TracerDisabledWhen = Context.Reference<Predicate<HttpServerRequest>
 )
 
 /**
- * @since 4.0.0
+ * Creates a layer that disables server-side tracing for requests whose URL exactly matches one of the supplied URLs.
+ *
  * @category Tracer
+ * @since 4.0.0
  */
 export const layerTracerDisabledForUrls = (
   urls: ReadonlyArray<string>
 ): Layer.Layer<never> => Layer.succeed(TracerDisabledWhen)((req) => urls.includes(req.url))
 
 /**
- * @since 4.0.0
+ * Context reference for generating server span names from HTTP server requests.
+ *
  * @category Tracer
+ * @since 4.0.0
  */
 export const SpanNameGenerator = Context.Reference<(request: HttpServerRequest) => string>(
   "@effect/platform/HttpMiddleware/SpanNameGenerator",
@@ -100,14 +138,15 @@ export const SpanNameGenerator = Context.Reference<(request: HttpServerRequest)
 )
 
 /**
- * @since 4.0.0
+ * Middleware that logs sent HTTP responses with request method, request URL, and response status annotations.
+ *
  * @category Logger
+ * @since 4.0.0
  */
 export const logger: <E, R>(
   httpApp: Effect.Effect<HttpServerResponse, E, HttpServerRequest | R>
-) => Effect.Effect<HttpServerResponse, E, HttpServerRequest | R> = make((httpApp) => {
-  let counter = 0
-  return Effect.withFiber((fiber) => {
+) => Effect.Effect<HttpServerResponse, E, HttpServerRequest | R> = make((httpApp) =>
+  Effect.withFiber((fiber) => {
     const request = Context.getUnsafe(fiber.context, HttpServerRequest)
     const path = stripSearchAndHash(request.url)
     return Effect.withLogSpan(
@@ -134,14 +173,16 @@ export const logger: <E, R>(
           exit
         )
       }),
-      `http.span.${++counter}`
+      "http.span"
     )
   })
-})
+)
 
 /**
- * @since 4.0.0
+ * Middleware that creates a server trace span for each request and records request and response HTTP attributes.
+ *
  * @category Tracer
+ * @since 4.0.0
  */
 export const tracer: <E, R>(
   httpApp: Effect.Effect<HttpServerResponse, E, HttpServerRequest | R>
@@ -203,8 +244,10 @@ export const tracer: <E, R>(
 )
 
 /**
- * @since 4.0.0
+ * Middleware that trusts `X-Forwarded-Host` and `X-Forwarded-For`, updating the request host header and remote address.
+ *
  * @category Proxying
+ * @since 4.0.0
  */
 export const xForwardedHeaders = make((httpApp) =>
   Effect.updateService(httpApp, HttpServerRequest, (request) =>
@@ -221,8 +264,10 @@ export const xForwardedHeaders = make((httpApp) =>
 )
 
 /**
- * @since 4.0.0
+ * Middleware that parses the current request URL's search parameters and provides them as `ParsedSearchParams`.
+ *
  * @category Search params
+ * @since 4.0.0
  */
 export const searchParamsParser = <E, R>(
   httpApp: Effect.Effect<HttpServerResponse, E, R>
@@ -239,8 +284,10 @@ export const searchParamsParser = <E, R>(
   })
 
 /**
- * @since 4.0.0
+ * Middleware that handles CORS preflight requests and adds configured CORS headers to HTTP responses.
+ *
  * @category CORS
+ * @since 4.0.0
  */
 export const cors = (options?: {
   readonly allowedOrigins?: ReadonlyArray<string> | Predicate<string> | undefined

package/src/unstable/http/HttpPlatform.ts

@@ -1,4 +1,25 @@
 /**
+ * Platform-specific support for serving files as HTTP server responses.
+ *
+ * `HttpPlatform` is the boundary between the portable HTTP response model and
+ * the runtime that knows how to stream bytes from the host platform. Server
+ * code uses this service when it needs to return local files, static assets,
+ * downloads, byte ranges, or Web `File`-like values without constructing the
+ * response body by hand.
+ *
+ * The helpers in this module enrich those responses with file metadata such as
+ * `etag`, `last-modified`, and content length where available. Path-based
+ * responses require `FileSystem` and can fail with `PlatformError` while
+ * inspecting or streaming the file; `File`-like responses use the Web
+ * `ReadableStream` and `lastModified` metadata exposed by the value.
+ *
+ * Provide `layer` when the default streaming implementation is suitable, or
+ * use `make` to plug in a runtime-specific response constructor. The default
+ * layer supplies weak ETag generation itself, but the surrounding runtime still
+ * needs to provide the `FileSystem` service and run the resulting
+ * `HttpServerResponse` on an HTTP server adapter that understands Effect
+ * streams.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -15,8 +36,10 @@ import type * as Body from "./HttpBody.ts"
 import * as Response from "./HttpServerResponse.ts"
 
 /**
- * @since 4.0.0
+ * Service for platform-specific HTTP response helpers, including file-backed server responses.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export class HttpPlatform extends Context.Service<HttpPlatform, {
   readonly fileResponse: (
@@ -38,8 +61,10 @@ export class HttpPlatform extends Context.Service<HttpPlatform, {
 }>()("effect/http/HttpPlatform") {}
 
 /**
- * @since 4.0.0
+ * Creates an `HttpPlatform` service from platform-specific file response constructors, using `FileSystem` and `Etag.Generator`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make: (impl: {
   readonly fileResponse: (
@@ -117,11 +142,17 @@ export const make: (impl: {
 })
 
 /**
- * @since 4.0.0
+ * Provides the default `HttpPlatform` implementation for serving file paths and
+ * `File`-like values as streamed HTTP responses.
+ *
+ * The layer uses the `FileSystem` and weak ETag services to add file metadata
+ * headers such as `etag` and `last-modified`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = Layer.effect(HttpPlatform)(
-  Effect.flatMap(FileSystem.FileSystem.asEffect(), (fs) =>
+  Effect.flatMap(FileSystem.FileSystem, (fs) =>
     make({
       fileResponse(path, status, statusText, headers, start, end, contentLength) {
         return Response.stream(