effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/unstable/http/HttpMiddleware.ts

@@ -23,12 +23,15 @@ import type { ReadonlyRecord } from "../../Record.ts"
 import { TracerEnabled } from "../../References.ts"
 import { ParentSpan } from "../../Tracer.ts"
 import * as Headers from "./Headers.ts"
+import type { CompressionAlgorithm } from "./HttpPlatform.ts"
+import { HttpPlatform } from "./HttpPlatform.ts"
 import { causeResponseStripped } from "./HttpServerError.ts"
 import { HttpServerRequest } from "./HttpServerRequest.ts"
 import * as Request from "./HttpServerRequest.ts"
 import * as Response from "./HttpServerResponse.ts"
 import type { HttpServerResponse } from "./HttpServerResponse.ts"
 import * as TraceContext from "./HttpTraceContext.ts"
+import * as compressionInternal from "./internal/compression.ts"
 import { appendPreResponseHandlerUnsafe } from "./internal/preResponseHandler.ts"
 
 /**
@@ -84,7 +87,7 @@ const stripSearchAndHash = (url: string): string => {
 /**
  * Runs an effect with HTTP response logging disabled for the current server request.
  *
- * @category Logger
+ * @category logging
  * @since 4.0.0
  */
 export const withLoggerDisabled = <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | HttpServerRequest> =>
@@ -97,7 +100,7 @@ export const withLoggerDisabled = <A, E, R>(self: Effect.Effect<A, E, R>): Effec
 /**
  * Context reference for a predicate that disables server-side tracing for matching requests.
  *
- * @category Tracer
+ * @category services
  * @since 4.0.0
  */
 export const TracerDisabledWhen = Context.Reference<Predicate<HttpServerRequest>>(
@@ -108,7 +111,7 @@ export const TracerDisabledWhen = Context.Reference<Predicate<HttpServerRequest>
 /**
  * Creates a layer that disables server-side tracing for requests whose URL exactly matches one of the supplied URLs.
  *
- * @category Tracer
+ * @category layers
  * @since 4.0.0
  */
 export const layerTracerDisabledForUrls = (
@@ -118,7 +121,7 @@ export const layerTracerDisabledForUrls = (
 /**
  * Context reference for generating server span names from HTTP server requests.
  *
- * @category Tracer
+ * @category services
  * @since 4.0.0
  */
 export const SpanNameGenerator = Context.Reference<(request: HttpServerRequest) => string>(
@@ -129,7 +132,7 @@ export const SpanNameGenerator = Context.Reference<(request: HttpServerRequest)
 /**
  * Middleware that logs sent HTTP responses with request method, request URL, and response status annotations.
  *
- * @category Logger
+ * @category logging
  * @since 4.0.0
  */
 export const logger: <E, R>(
@@ -170,7 +173,7 @@ export const logger: <E, R>(
 /**
  * Middleware that creates a server trace span for each request and records request and response HTTP attributes.
  *
- * @category Tracer
+ * @category tracing
  * @since 4.0.0
  */
 export const tracer: <E, R>(
@@ -193,32 +196,6 @@ export const tracer: <E, R>(
       fiber.setContext(prevServices)
       const endTime = fiber.getRef(Clock).currentTimeNanosUnsafe()
       fiber.currentDispatcher.scheduleTask(() => {
-        const url = Request.toURL(request)
-        if (Option.isSome(url) && (url.value.username !== "" || url.value.password !== "")) {
-          url.value.username = "REDACTED"
-          url.value.password = "REDACTED"
-        }
-        const redactedHeaderNames = fiber.getRef(Headers.CurrentRedactedNames)
-        const requestHeaders = Headers.redact(request.headers, redactedHeaderNames)
-        span.attribute("http.request.method", request.method)
-        if (Option.isSome(url)) {
-          span.attribute("url.full", url.value.toString())
-          span.attribute("url.path", url.value.pathname)
-          const query = url.value.search.slice(1)
-          if (query !== "") {
-            span.attribute("url.query", url.value.search.slice(1))
-          }
-          span.attribute("url.scheme", url.value.protocol.slice(0, -1))
-        }
-        if (request.headers["user-agent"] !== undefined) {
-          span.attribute("user_agent.original", request.headers["user-agent"])
-        }
-        for (const name in requestHeaders) {
-          span.attribute(`http.request.header.${name}`, String(requestHeaders[name]))
-        }
-        if (Option.isSome(request.remoteAddress)) {
-          span.attribute("client.address", request.remoteAddress.value)
-        }
         let response: HttpServerResponse
         let spanExit = exit
         if (Exit.isFailure(exit)) {
@@ -228,10 +205,38 @@ export const tracer: <E, R>(
         } else {
           response = exit.value
         }
-        span.attribute("http.response.status_code", response.status)
-        const responseHeaders = Headers.redact(response.headers, redactedHeaderNames)
-        for (const name in responseHeaders) {
-          span.attribute(`http.response.header.${name}`, String(responseHeaders[name]))
+        if (span.sampled) {
+          const url = Request.toURL(request)
+          if (Option.isSome(url) && (url.value.username !== "" || url.value.password !== "")) {
+            url.value.username = "REDACTED"
+            url.value.password = "REDACTED"
+          }
+          const redactedHeaderNames = fiber.getRef(Headers.CurrentRedactedNames)
+          const requestHeaders = Headers.redact(request.headers, redactedHeaderNames)
+          span.attribute("http.request.method", request.method)
+          if (Option.isSome(url)) {
+            span.attribute("url.full", url.value.toString())
+            span.attribute("url.path", url.value.pathname)
+            const query = url.value.search.slice(1)
+            if (query !== "") {
+              span.attribute("url.query", url.value.search.slice(1))
+            }
+            span.attribute("url.scheme", url.value.protocol.slice(0, -1))
+          }
+          if (request.headers["user-agent"] !== undefined) {
+            span.attribute("user_agent.original", request.headers["user-agent"])
+          }
+          for (const name in requestHeaders) {
+            span.attribute(`http.request.header.${name}`, String(requestHeaders[name]))
+          }
+          if (Option.isSome(request.remoteAddress)) {
+            span.attribute("client.address", request.remoteAddress.value)
+          }
+          span.attribute("http.response.status_code", response.status)
+          const responseHeaders = Headers.redact(response.headers, redactedHeaderNames)
+          for (const name in responseHeaders) {
+            span.attribute(`http.response.header.${name}`, String(responseHeaders[name]))
+          }
         }
         span.end(endTime, spanExit)
       }, 0)
@@ -243,7 +248,7 @@ export const tracer: <E, R>(
 /**
  * Middleware that trusts `X-Forwarded-Host` and `X-Forwarded-For`, updating the request host header and remote address.
  *
- * @category Proxying
+ * @category proxying
  * @since 4.0.0
  */
 export const xForwardedHeaders = make((httpApp) =>
@@ -263,7 +268,7 @@ export const xForwardedHeaders = make((httpApp) =>
 /**
  * Middleware that parses the current request URL's search parameters and provides them as `ParsedSearchParams`.
  *
- * @category search params
+ * @category parsing
  * @since 4.0.0
  */
 export const searchParamsParser = <E, R>(
@@ -283,7 +288,7 @@ export const searchParamsParser = <E, R>(
 /**
  * Middleware that handles CORS preflight requests and adds configured CORS headers to HTTP responses.
  *
- * @category CORS
+ * @category middleware
  * @since 4.0.0
  */
 export const cors = (options?: {
@@ -401,3 +406,161 @@ export const cors = (options?: {
       return httpApp
     })
 }
+
+/**
+ * Middleware that compresses HTTP response bodies based on the request's
+ * `Accept-Encoding` header.
+ *
+ * **Details**
+ *
+ * Content negotiation follows RFC 9110: the first algorithm in server
+ * preference order that the client accepts with a positive q-value and the
+ * platform supports is used. When no algorithm is acceptable the response is
+ * sent uncompressed.
+ *
+ * The body transform is performed by the `HttpPlatform` service.
+ *
+ * Responses are skipped when the status is 1xx, 204, 206, or 304, when a
+ * `Content-Encoding` is already present, when `Cache-Control: no-transform`
+ * is set, when the content type is absent or not compressible, when a known
+ * body length is below `minSize`, or when the body is empty or `FormData`. A
+ * response carrying `Content-Encoding: identity` opts out of compression and
+ * has the header stripped before sending.
+ *
+ * `Vary: Accept-Encoding` is set on every response that was eligible by
+ * status and content type, including ones skipped by negotiation or
+ * `minSize`.
+ *
+ * Do not combine this middleware with Deno's automatic response compression.
+ * On edge runtimes that already apply automatic compression, the middleware
+ * is unnecessary. Platforms backed by Web `CompressionStream` also cannot
+ * explicitly flush each input chunk, so incremental delivery depends on the
+ * runtime's implementation.
+ *
+ * **Security**
+ *
+ * Compression can expose secrets through BREACH-style attacks when one
+ * response contains both secret data and attacker-controlled input and an
+ * attacker can observe the compressed response length. For affected routes,
+ * disable compression with `Content-Encoding: identity` or
+ * `Cache-Control: no-transform`, or use `compressible` to restrict which
+ * response content types can be compressed.
+ *
+ * @category compression
+ * @since 4.0.0
+ */
+export const compression = (
+  options?: {
+    /**
+     * Server preference order. Negotiation picks the first accepted algorithm
+     * supported by the platform. Defaults to `["br", "gzip", "deflate"]`;
+     * `zstd` must be explicitly opted into.
+     */
+    readonly algorithms?: ReadonlyArray<CompressionAlgorithm> | undefined
+    /**
+     * Minimum body size in bytes when the length is known. Unknown-length bodies
+     * are always compressed. Defaults to `1024`.
+     */
+    readonly minSize?: number | undefined
+    /** Replaces the default content-type predicate. */
+    readonly compressible?: ((contentType: string) => boolean) | undefined
+    /** Per-algorithm levels. Platforms without a level knob ignore them. */
+    readonly levels?: {
+      readonly gzip?: number | undefined
+      readonly deflate?: number | undefined
+      readonly br?: number | undefined
+      readonly zstd?: number | undefined
+    } | undefined
+  } | undefined
+): <E, R>(
+  httpApp: Effect.Effect<HttpServerResponse, E, R>
+) => Effect.Effect<HttpServerResponse, E, R | HttpServerRequest | HttpPlatform> => {
+  const preferred = options?.algorithms ?? defaultAlgorithms
+  const minSize = options?.minSize ?? 1024
+  const compressible = options?.compressible ?? compressionInternal.defaultCompressible
+  const levels = { ...defaultLevels, ...options?.levels }
+  const levelOptions: Record<CompressionAlgorithm, { readonly level: number | undefined }> = {
+    gzip: { level: levels.gzip },
+    deflate: { level: levels.deflate },
+    br: { level: levels.br },
+    zstd: { level: levels.zstd }
+  }
+  const transform = (
+    compression: HttpPlatform["Service"]["compression"],
+    acceptEncoding: string | undefined,
+    response: HttpServerResponse
+  ): Effect.Effect<HttpServerResponse> => {
+    if (
+      response.status < 200 ||
+      response.status === 204 ||
+      response.status === 206 ||
+      response.status === 304
+    ) {
+      return Effect.succeed(response)
+    }
+    const currentEncoding = response.headers["content-encoding"]
+    if (currentEncoding !== undefined) {
+      return Effect.succeed(
+        currentEncoding.trim().toLowerCase() === "identity"
+          ? Response.removeHeader(response, "content-encoding")
+          : response
+      )
+    }
+    const body = response.body
+    if (body._tag === "Empty" || body._tag === "FormData") {
+      return Effect.succeed(response)
+    }
+    const cacheControl = response.headers["cache-control"]
+    if (cacheControl !== undefined && noTransformRegex.test(cacheControl)) {
+      return Effect.succeed(response)
+    }
+    const contentType = response.headers["content-type"] ?? body.contentType
+    if (contentType === undefined || !compressible(contentType)) {
+      return Effect.succeed(response)
+    }
+    const algorithm = compressionInternal.negotiate(acceptEncoding, preferred, compression.algorithms)
+    if (algorithm === undefined) {
+      return Effect.succeed(withVary(response))
+    }
+    const contentLength = body.contentLength ?? contentLengthHeader(response.headers)
+    if (contentLength !== undefined && contentLength < minSize) {
+      return Effect.succeed(withVary(response))
+    }
+    return compression.compressResponse(response, algorithm, levelOptions[algorithm])
+  }
+  return <E, R>(
+    httpApp: Effect.Effect<HttpServerResponse, E, R>
+  ): Effect.Effect<HttpServerResponse, E, R | HttpServerRequest | HttpPlatform> =>
+    Effect.withFiber((fiber) => {
+      const request = Context.getUnsafe(fiber.context, HttpServerRequest)
+      const compression = Context.getUnsafe(fiber.context, HttpPlatform).compression
+      appendPreResponseHandlerUnsafe(request, (request, response) =>
+        transform(compression, request.headers["accept-encoding"], response))
+      return httpApp
+    })
+}
+
+const withVary = (response: HttpServerResponse): HttpServerResponse => {
+  const vary = compressionInternal.varyAcceptEncoding(response.headers)
+  return vary === undefined ? response : Response.setHeader(response, "vary", vary)
+}
+
+const defaultAlgorithms: ReadonlyArray<CompressionAlgorithm> = ["br", "gzip", "deflate"]
+
+const defaultLevels = {
+  gzip: 6,
+  deflate: 6,
+  br: 4,
+  zstd: 3
+} as const
+
+const noTransformRegex = /(?:^|[\s,])no-transform(?:$|[\s,;])/i
+
+const contentLengthHeader = (headers: Headers.Headers): number | undefined => {
+  const value = headers["content-length"]
+  if (value === undefined) {
+    return undefined
+  }
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined
+}

package/src/unstable/http/HttpPlatform.ts

@@ -21,6 +21,7 @@ import * as Etag from "./Etag.ts"
 import * as Headers from "./Headers.ts"
 import type * as Body from "./HttpBody.ts"
 import * as Response from "./HttpServerResponse.ts"
+import * as internal from "./internal/compression.ts"
 
 /**
  * Service for platform-specific HTTP response helpers, including file-backed server responses.
@@ -29,6 +30,8 @@ import * as Response from "./HttpServerResponse.ts"
  * @since 4.0.0
  */
 export class HttpPlatform extends Context.Service<HttpPlatform, {
+  readonly platform: "deno" | "node" | "bun" | "web"
+  readonly compression: Compression
   readonly fileResponse: (
     path: string,
     options?: Response.Options.WithContent & {
@@ -54,6 +57,8 @@ export class HttpPlatform extends Context.Service<HttpPlatform, {
  * @since 4.0.0
  */
 export const make: (impl: {
+  readonly platform: "deno" | "node" | "bun" | "web"
+  readonly compression: Compression
   readonly fileResponse: (
     path: string,
     status: number,
@@ -83,6 +88,8 @@ export const make: (impl: {
   const etagGen = yield* Etag.Generator
 
   return HttpPlatform.of({
+    platform: impl.platform,
+    compression: internal.wrapCompression(impl.compression),
     fileResponse: Effect.fnUntraced(function*(path, options) {
       const info = yield* fs.stat(path)
       const etag = yield* etagGen.fromFileInfo(info)
@@ -143,6 +150,8 @@ export const make: (impl: {
 export const layer = Layer.effect(HttpPlatform)(
   Effect.flatMap(FileSystem.FileSystem, (fs) =>
     make({
+      platform: "web",
+      compression: internal.compressionWeb,
       fileResponse(path, status, statusText, headers, start, end, contentLength) {
         return Response.stream(
           fs.stream(path, {
@@ -163,3 +172,89 @@ export const layer = Layer.effect(HttpPlatform)(
       }
     }))
 ).pipe(Layer.provide(Etag.layerWeak))
+
+/**
+ * Content codings that HTTP response compression can apply.
+ *
+ * @category compression
+ * @since 4.0.0
+ */
+export type CompressionAlgorithm = "gzip" | "deflate" | "br" | "zstd"
+
+/**
+ * Options passed to a platform when compressing a response body.
+ *
+ * **Details**
+ *
+ * The `level` scale depends on the algorithm. Platforms without a level knob,
+ * such as the Web `CompressionStream` implementation, ignore it.
+ *
+ * @category compression
+ * @since 4.0.0
+ */
+export interface CompressionOptions {
+  readonly level?: number | undefined
+}
+
+/**
+ * Platform primitive for HTTP response compression.
+ *
+ * **Details**
+ *
+ * `algorithms` advertises what the platform can encode; content negotiation
+ * happens in the shared `HttpMiddleware.compression` middleware.
+ *
+ * `compressResponse` is only called when compression is definitely happening —
+ * all skip logic runs in the shared middleware first. The platform owns the
+ * body transform and removes `Content-Length` when the compressed size is not
+ * known in advance. The `make` wrapper owns the `Content-Encoding` and `Vary`
+ * headers.
+ *
+ * @category compression
+ * @since 4.0.0
+ */
+export interface Compression {
+  readonly algorithms: ReadonlySet<CompressionAlgorithm>
+  readonly compressResponse: (
+    response: Response.HttpServerResponse,
+    algorithm: CompressionAlgorithm,
+    options?: CompressionOptions | undefined
+  ) => Effect.Effect<Response.HttpServerResponse>
+}
+
+/**
+ * Creates a compression body transform backed by the Web `CompressionStream`
+ * API, for use with `makeCompressionWeb`.
+ *
+ * **Details**
+ *
+ * The format string is passed through to the runtime, so runtime-specific
+ * formats such as Bun's `"brotli"` and `"zstd"` are usable. `CompressionStream`
+ * has no compression level knob, so `CompressionOptions.level` does not apply.
+ *
+ * @category compression
+ * @since 4.0.0
+ */
+export const compressionTransformWeb: (
+  format: string
+) => (stream: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array> = internal.compressionTransformWeb
+
+/**
+ * Creates a `Compression` implementation from Web `ReadableStream`
+ * transforms.
+ *
+ * **Details**
+ *
+ * All supported bodies are transformed as streams. The `Content-Length`
+ * header is dropped in every case.
+ *
+ * @category compression
+ * @since 4.0.0
+ */
+export const makeCompressionWeb: (options: {
+  readonly algorithms: Iterable<CompressionAlgorithm>
+  readonly transform: (
+    algorithm: CompressionAlgorithm,
+    options?: CompressionOptions | undefined
+  ) => (stream: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>
+}) => Compression = internal.makeCompressionWeb