effect 4.0.1 → 4.0.2

package/src/http/Headers.ts

@@ -749,7 +749,9 @@ export const isRedactedName = (
  *
  * **Details**
  *
- * Defaults include `authorization`, `cookie`, `set-cookie`, and `x-api-key`.
+ * Defaults include `authorization`, `cookie`, `set-cookie`, `x-api-key` and
+ * `AWSAccessKeyId`, `Signature`, `sig` and `X-Goog-Signature`. Names match
+ * case-insensitively, and providing a new list replaces the defaults.
  *
  * @stability unstable
  * @category services
@@ -762,6 +764,10 @@ export const CurrentRedactedNames = Context.Reference<
     "authorization",
     "cookie",
     "set-cookie",
-    "x-api-key"
+    "x-api-key",
+    "AWSAccessKeyId",
+    "Signature",
+    "sig",
+    "X-Goog-Signature"
   ]
 })

package/src/http/HttpClient.ts

@@ -18,15 +18,18 @@ import { Clock } from "../Clock.ts"
 import * as Context from "../Context.ts"
 import * as Duration from "../Duration.ts"
 import * as Effect from "../Effect.ts"
+import * as Exit from "../Exit.ts"
 import * as Fiber from "../Fiber.ts"
 import { constant, constFalse, constTrue, dual, flow, identity } from "../Function.ts"
 import * as Inspectable from "../Inspectable.ts"
+import { getStackTraceLimit, setStackTraceLimit } from "../internal/stackTraceLimit.ts"
 import * as Layer from "../Layer.ts"
 import * as Option from "../Option.ts"
 import type * as RateLimiter from "../persistence/RateLimiter.ts"
 import { type Pipeable, pipeArguments } from "../Pipeable.ts"
 import * as Predicate from "../Predicate.ts"
 import * as Ref from "../Ref.ts"
+import * as References from "../References.ts"
 import * as Result from "../Result.ts"
 import * as Schedule from "../Schedule.ts"
 import type * as Scope from "../Scope.ts"
@@ -42,6 +45,7 @@ import * as HttpClientResponse from "./HttpClientResponse.ts"
 import * as HttpIncomingMessage from "./HttpIncomingMessage.ts"
 import * as HttpMethod from "./HttpMethod.ts"
 import * as TraceContext from "./HttpTraceContext.ts"
+import * as tracing from "./internal/tracing.ts"
 import * as Url from "./Url.ts"
 
 const TypeId = "~effect/http/HttpClient"
@@ -900,26 +904,10 @@ export const make = (
           { kind: "client" },
           (span) => {
             span.attribute("http.request.method", request.method)
-            span.attribute("server.address", url.origin)
-            if (url.port !== "") {
-              span.attribute("server.port", +url.port)
-            }
-            span.attribute("url.full", url.toString())
-            span.attribute("url.path", url.pathname)
-            span.attribute("url.scheme", url.protocol.slice(0, -1))
-            const query = url.search.slice(1)
-            if (query !== "") {
-              span.attribute("url.query", query)
-            }
             const redactedHeaderNames = fiber.getRef(Headers.CurrentRedactedNames)
+            tracing.addUrlAttributes(span, url)
             const headerFilter = fiber.getRef(TracerHeaderFilter)
-            for (const name in request.headers) {
-              if (!headerFilter(name, "request")) continue
-              span.attribute(
-                `http.request.header.${name}`,
-                Headers.isRedactedName(name, redactedHeaderNames) ? "<redacted>" : request.headers[name]
-              )
-            }
+            tracing.addHeaderAttributes(span, "request", request.headers, headerFilter, redactedHeaderNames)
             request = fiber.getRef(TracerPropagationEnabled)
               ? HttpClientRequest.setHeaders(request, TraceContext.toHeaders(span))
               : request
@@ -929,12 +917,12 @@ export const make = (
                 Effect.matchCauseEffect({
                   onSuccess: (response) => {
                     span.attribute("http.response.status_code", response.status)
-                    for (const name in response.headers) {
-                      if (!headerFilter(name, "response")) continue
-                      span.attribute(
-                        `http.response.header.${name}`,
-                        Headers.isRedactedName(name, redactedHeaderNames) ? "<redacted>" : response.headers[name]
-                      )
+                    tracing.addHeaderAttributes(span, "response", response.headers, headerFilter, redactedHeaderNames)
+                    // OpenTelemetry marks client spans as failed for 4xx and
+                    // 5xx responses, while the response itself still succeeds.
+                    if (response.status >= 400 && response.status < 600) {
+                      span.attribute("error.type", String(response.status))
+                      endSpanWithStatusError(fiber, span, request, response)
                     }
 
                     if (scopedController) return Effect.succeed(response)
@@ -954,6 +942,26 @@ export const make = (
         )
       })), Effect.succeed as HttpClient.Preprocess<never, never>)
 
+const endSpanWithStatusError = (
+  fiber: Fiber.Fiber<unknown, unknown>,
+  span: Tracer.Span,
+  request: HttpClientRequest.HttpClientRequest,
+  response: HttpClientResponse.HttpClientResponse
+): void => {
+  const stackTraceLimit = getStackTraceLimit()
+  setStackTraceLimit(0)
+  let exit: Exit.Exit<never, Error.HttpClientError>
+  try {
+    exit = Exit.fail(new Error.HttpClientError({ reason: new Error.StatusCodeError({ request, response }) }))
+  } finally {
+    setStackTraceLimit(stackTraceLimit)
+  }
+  span.end(
+    fiber.getRef(References.TracerTimingEnabled) ? fiber.getRef(Clock).currentTimeNanosUnsafe() : BigInt(0),
+    exit
+  )
+}
+
 /**
  * Appends a transformation of the request object before sending it.
  *
@@ -2153,6 +2161,11 @@ export const TracerDisabledWhen = Context.Reference<
 /**
  * Context reference for filtering request and response headers added to client spans.
  *
+ * **Details**
+ *
+ * Header capture is opt-in: the default filter records no headers. Captured
+ * headers listed in `Headers.CurrentRedactedNames` are recorded as `<redacted>`.
+ *
  * @stability unstable
  * @category services
  * @since 4.0.0
@@ -2160,7 +2173,7 @@ export const TracerDisabledWhen = Context.Reference<
 export const TracerHeaderFilter = Context.Reference<
   (headerName: string, phase: "request" | "response") => boolean
 >("effect/http/HttpClient/TracerHeaderFilter", {
-  defaultValue: () => constTrue
+  defaultValue: () => constFalse
 })
 
 /**
@@ -2177,6 +2190,10 @@ export const TracerPropagationEnabled = Context.Reference<boolean>("effect/http/
 /**
  * Context reference for generating the span name used for outgoing client request spans.
  *
+ * **Details**
+ *
+ * Defaults to the request method unchanged.
+ *
  * @stability unstable
  * @category services
  * @since 4.0.0
@@ -2184,7 +2201,7 @@ export const TracerPropagationEnabled = Context.Reference<boolean>("effect/http/
 export const SpanNameGenerator = Context.Reference<
   (request: HttpClientRequest.HttpClientRequest) => string
 >("effect/http/HttpClient/SpanNameGenerator", {
-  defaultValue: () => (request) => `http.client ${request.method}`
+  defaultValue: () => (request) => request.method
 })
 
 /**
@@ -2226,7 +2243,7 @@ const responseRegistry = (() => {
     }
   }
 
-  const timers = new Map<HttpClientResponse.HttpClientResponse, any>()
+  const timers = new WeakMap<HttpClientResponse.HttpClientResponse, any>()
   return {
     register(response: HttpClientResponse.HttpClientResponse, controller: AbortController) {
       timers.set(response, setTimeout(() => controller.abort(), 5000))

package/src/http/HttpClientResponse.ts

@@ -341,7 +341,9 @@ class WebHttpClientResponse extends Inspectable.Class implements HttpClientRespo
     if (this.cachedCookies) {
       return this.cachedCookies
     }
-    return this.cachedCookies = Cookies.fromSetCookie(this.source.headers.getSetCookie())
+    // React Native's Headers does not implement getSetCookie, and it never
+    // exposes Set-Cookie to JavaScript anyway.
+    return this.cachedCookies = Cookies.fromSetCookie(this.source.headers.getSetCookie?.() ?? [])
   }
 
   get remoteAddress(): Option.Option<string> {

package/src/http/HttpEffect.ts

@@ -33,6 +33,9 @@ import * as preResponseHandler from "./internal/preResponseHandler.ts"
 /**
  * Runs an HTTP server effect, sends the produced response with the supplied handler, and converts failures into HTTP responses.
  * On handler failure, the request scope closes with the original cause.
+ * If the send handler returns an `HttpServerResponse`, such as the `101`
+ * response of an upgraded request, middleware observes it in place of the
+ * handler's response.
  *
  * @stability unstable
  * @category combinators
@@ -81,11 +84,17 @@ export const toHandled = <E, R, EH, RH>(
     const handler = preResponseHandler.requestPreResponseHandlers.get(request.source)
     if (handler === undefined) {
       ;(request as any)[handledSymbol] = true
-      return Effect.mapEager(handleResponse(request, response), () => response)
+      return Effect.mapEager(
+        handleResponse(request, response),
+        (sent) => Response.isHttpServerResponse(sent) ? sent : response
+      )
     }
     return Effect.flatMapEager(handler(request, response), (sentResponse) => {
       ;(request as any)[handledSymbol] = true
-      return Effect.mapEager(handleResponse(request, sentResponse), () => response)
+      return Effect.mapEager(
+        handleResponse(request, sentResponse),
+        (sent) => Response.isHttpServerResponse(sent) ? sent : response
+      )
     })
   }
 

package/src/http/HttpMiddleware.ts

@@ -11,6 +11,7 @@
  * @stability unstable
  * @since 4.0.0
  */
+import * as Cause from "../Cause.ts"
 import { Clock } from "../Clock.ts"
 import * as Context from "../Context.ts"
 import * as Effect from "../Effect.ts"
@@ -18,6 +19,7 @@ import * as Exit from "../Exit.ts"
 import type * as Fiber from "../Fiber.ts"
 import { constant, constFalse } from "../Function.ts"
 import * as internalEffect from "../internal/effect.ts"
+import { getStackTraceLimit, setStackTraceLimit } from "../internal/stackTraceLimit.ts"
 import * as Layer from "../Layer.ts"
 import * as Option from "../Option.ts"
 import type { Predicate } from "../Predicate.ts"
@@ -26,7 +28,7 @@ import { nativeTracer, ParentSpan, Tracer } from "../Tracer.ts"
 import * as Headers from "./Headers.ts"
 import type { CompressionAlgorithm } from "./HttpPlatform.ts"
 import { HttpPlatform } from "./HttpPlatform.ts"
-import { causeResponseStripped, ClientAbort } from "./HttpServerError.ts"
+import { causeResponseStripped, ClientAbort, HttpServerError, ResponseError } from "./HttpServerError.ts"
 import { HttpServerRequest } from "./HttpServerRequest.ts"
 import * as Request from "./HttpServerRequest.ts"
 import * as Response from "./HttpServerResponse.ts"
@@ -35,6 +37,7 @@ import * as TraceContext from "./HttpTraceContext.ts"
 import * as compressionInternal from "./internal/compression.ts"
 import * as bodyInternal from "./internal/httpBody.ts"
 import { appendPreResponseHandlerUnsafe } from "./internal/preResponseHandler.ts"
+import * as tracing from "./internal/tracing.ts"
 
 /**
  * Middleware that transforms an HTTP server app effect into another HTTP server app effect.
@@ -130,15 +133,37 @@ export const layerTracerDisabledForUrls = (
 /**
  * Context reference for generating server span names from HTTP server requests.
  *
+ * **Details**
+ *
+ * Defaults to the request method unchanged.
+ *
  * @stability unstable
  * @category services
  * @since 4.0.0
  */
 export const SpanNameGenerator = Context.Reference<(request: HttpServerRequest) => string>(
   "@effect/platform/HttpMiddleware/SpanNameGenerator",
-  { defaultValue: () => (request) => `http.server ${request.method}` }
+  { defaultValue: () => (request) => request.method }
 )
 
+/**
+ * Context reference for filtering request and response headers added to server spans.
+ *
+ * **Details**
+ *
+ * Header capture is opt-in: the default filter records no headers. Captured
+ * headers listed in `Headers.CurrentRedactedNames` are recorded as `<redacted>`.
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export const TracerHeaderFilter = Context.Reference<
+  (headerName: string, phase: "request" | "response") => boolean
+>("effect/http/HttpMiddleware/TracerHeaderFilter", {
+  defaultValue: () => constFalse
+})
+
 /**
  * Middleware that logs sent HTTP responses with request method, request URL, and response status annotations.
  *
@@ -195,6 +220,23 @@ export const isTracerDisabledUnsafe = (
   request: HttpServerRequest
 ): boolean => !fiber.cache.tracerEnabled || fiber.getRef(TracerDisabledWhen)(request)
 
+// OpenTelemetry requires failed server spans for 5xx responses.
+const responseSpanExit = (
+  request: HttpServerRequest,
+  response: HttpServerResponse
+): Exit.Exit<HttpServerResponse, HttpServerError> => {
+  if (!(response.status >= 500 && response.status < 600)) {
+    return Exit.succeed(response)
+  }
+  const stackTraceLimit = getStackTraceLimit()
+  setStackTraceLimit(0)
+  try {
+    return Exit.fail(new HttpServerError({ reason: new ResponseError({ request, response }) }))
+  } finally {
+    setStackTraceLimit(stackTraceLimit)
+  }
+}
+
 /**
  * Middleware that creates a server trace span for each request and records request and response HTTP attributes.
  *
@@ -221,71 +263,44 @@ export const tracer: <E, R>(
       fiber.setContext(prevServices)
       const endTime = fiber.getRef(Clock).currentTimeNanosUnsafe()
       if (Exit.isSuccess(exit) && (!span.sampled || fiber.getRef(Tracer) === nativeTracer)) {
-        span.end(endTime, exit)
+        span.end(endTime, responseSpanExit(request, exit.value))
         return undefined
       }
       const redactedHeaderNames = fiber.getRef(Headers.CurrentRedactedNames)
+      const headerFilter = fiber.getRef(TracerHeaderFilter)
       fiber.currentDispatcher.scheduleTask(() => {
         let response: HttpServerResponse
-        let spanExit = exit
+        let spanExit: Exit.Exit<HttpServerResponse, unknown>
         if (Exit.isFailure(exit)) {
           const [failureResponse, cause] = causeResponseStripped(exit.cause)
           response = failureResponse
-          spanExit = Option.isSome(cause) ? Exit.failCause(cause.value) : Exit.succeed(response)
+          // OpenTelemetry only treats 5xx responses as server span errors; interrupts still fail the span.
+          spanExit = Option.isSome(cause) && (response.status >= 500 || Cause.hasInterrupts(cause.value))
+            ? Exit.failCause(cause.value)
+            : responseSpanExit(request, response)
         } else {
           response = exit.value
+          spanExit = responseSpanExit(request, response)
         }
         if (span.sampled) {
           span.attribute("http.request.method", request.method)
-          if (request.url.startsWith("/")) {
-            const host = request.headers.host ?? "localhost"
-            const protocol = request.headers["x-forwarded-proto"] === "https" ? "https" : "http"
-            span.attribute("url.full", `${protocol}://${host}${request.url}`)
-            const queryIndex = request.url.indexOf("?")
-            if (queryIndex === -1) {
-              span.attribute("url.path", request.url)
-            } else {
-              span.attribute("url.path", request.url.slice(0, queryIndex))
-              if (queryIndex < request.url.length - 1) {
-                span.attribute("url.query", request.url.slice(queryIndex + 1))
-              }
-            }
-            span.attribute("url.scheme", protocol)
-          } else {
-            const url = Request.toURL(request)
-            if (Option.isSome(url)) {
-              if (url.value.username !== "" || url.value.password !== "") {
-                url.value.username = "REDACTED"
-                url.value.password = "REDACTED"
-              }
-              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", query)
-              }
-              span.attribute("url.scheme", url.value.protocol.slice(0, -1))
+          const url = Request.toURL(request)
+          if (Option.isSome(url)) {
+            if (!request.url.startsWith("/") && (url.value.username !== "" || url.value.password !== "")) {
+              url.value.username = "REDACTED"
+              url.value.password = "REDACTED"
             }
+            tracing.addUrlAttributes(span, url.value)
           }
           if (request.headers["user-agent"] !== undefined) {
             span.attribute("user_agent.original", request.headers["user-agent"])
           }
-          for (const name in request.headers) {
-            span.attribute(
-              `http.request.header.${name}`,
-              Headers.isRedactedName(name, redactedHeaderNames) ? "<redacted>" : request.headers[name]
-            )
-          }
+          tracing.addHeaderAttributes(span, "request", request.headers, headerFilter, redactedHeaderNames)
           if (Option.isSome(request.remoteAddress)) {
             span.attribute("client.address", request.remoteAddress.value)
           }
           span.attribute("http.response.status_code", response.status)
-          for (const name in response.headers) {
-            span.attribute(
-              `http.response.header.${name}`,
-              Headers.isRedactedName(name, redactedHeaderNames) ? "<redacted>" : response.headers[name]
-            )
-          }
+          tracing.addHeaderAttributes(span, "response", response.headers, headerFilter, redactedHeaderNames)
         }
         span.end(endTime, spanExit)
       }, 0)

package/src/http/HttpServer.ts

@@ -51,7 +51,7 @@ export class HttpServer extends Context.Service<HttpServer, {
     ): Effect.Effect<
       void,
       never,
-      Exclude<R, HttpServerRequest> | Scope.Scope
+      Exclude<Effect.Services<App>, HttpServerRequest> | Scope.Scope
     >
   }
 

package/src/http/internal/tracing.ts

@@ -0,0 +1,52 @@
+import type * as Tracer from "../../Tracer.ts"
+import * as Headers from "../Headers.ts"
+
+const defaultPorts: Record<string, number> = {
+  "http:": 80,
+  "https:": 443,
+  "ws:": 80,
+  "wss:": 443
+}
+
+/**
+ * Records the `url.*` and `server.*` attributes for a request URL.
+ *
+ * @internal
+ */
+export const addUrlAttributes = (
+  span: Tracer.Span,
+  url: URL
+): void => {
+  const query = url.search.slice(1)
+  span.attribute("url.full", url.toString())
+  span.attribute("url.path", url.pathname)
+  if (query !== "") {
+    span.attribute("url.query", query)
+  }
+  span.attribute("url.scheme", url.protocol.slice(0, -1))
+  if (url.hostname !== "") {
+    // URL keeps IPv6 brackets in the hostname, but the semantic conventions do not.
+    span.attribute("server.address", url.hostname.startsWith("[") ? url.hostname.slice(1, -1) : url.hostname)
+    const port = url.port === "" ? defaultPorts[url.protocol] : Number(url.port)
+    if (port !== undefined) {
+      span.attribute("server.port", port)
+    }
+  }
+}
+
+/** @internal */
+export const addHeaderAttributes = (
+  span: Tracer.Span,
+  phase: "request" | "response",
+  headers: Headers.Headers,
+  filter: (headerName: string, phase: "request" | "response") => boolean,
+  redactedNames: ReadonlyArray<string | RegExp>
+): void => {
+  for (const name in headers) {
+    if (!filter(name, phase)) continue
+    span.attribute(
+      `http.${phase}.header.${name}`,
+      Headers.isRedactedName(name, redactedNames) ? "<redacted>" : headers[name]
+    )
+  }
+}

package/src/http-api/HttpApiBuilder.ts

@@ -746,7 +746,11 @@ function buildPayloadDecoders(
 ): Map<string, PayloadDecoder> {
   const result = new Map<string, PayloadDecoder>()
   payloadMap.forEach(({ encoding, schemas }, contentType) => {
-    const decode = Schema.decodeUnknownEffect(Schema.Union(schemas), options)
+    const schema = Schema.Union(schemas)
+    const decode = Schema.decodeUnknownEffect(
+      encoding._tag === "FormUrlEncoded" ? Schema.toCodecArrayFromSingle(schema) : schema,
+      options
+    )
     if (encoding._tag === "Multipart") {
       result.set(contentType, { _tag: "Multipart", mode: encoding.mode, limits: encoding.limits, decode })
     } else {

package/src/http-api/HttpApiClient.ts

@@ -72,7 +72,16 @@ export type ForApi<Api extends HttpApi.Constraint, E = never, R = never> = Api e
   HttpApi.HttpApi<infer _Id, infer Groups> ? Client<Groups, E, R> :
   never
 
-type SuccessType<S> = S extends HttpApiSchema.WithHeaders<
+/**
+ * Computes the decoded success value a client receives for an endpoint
+ * success schema, including headers, streaming Server-Sent Events, and
+ * streaming byte responses.
+ *
+ * @stability unstable
+ * @category utility types
+ * @since 4.0.0
+ */
+export type SuccessType<S> = S extends HttpApiSchema.WithHeaders<
   infer _Inner,
   infer _Headers
 > ? HttpApiSchema.withHeaders<SuccessType<_Inner>, _Headers["Type"]>
@@ -126,9 +135,9 @@ export declare namespace Client {
    * @category models
    * @since 4.0.0
    */
-  export type Response<Success, Mode extends ResponseMode> = [Mode] extends ["decoded-and-response"]
+  export type Response<Success, Mode extends ResponseMode> = Mode extends "decoded-and-response"
     ? [Success, HttpClientResponse.HttpClientResponse]
-    : [Mode] extends ["response-only"] ? HttpClientResponse.HttpClientResponse
+    : Mode extends "response-only" ? HttpClientResponse.HttpClientResponse
     : Success
 
   type GroupByEndpoint<Group extends HttpApiGroup.Constraint, E, R> = Group["endpoints"] extends
@@ -184,7 +193,7 @@ export declare namespace Client {
     Endpoint extends HttpApiEndpoint.ConstraintRequest,
     E,
     R
-  > = <Mode extends ResponseMode = ResponseMode>(
+  > = <Mode extends ResponseMode = "decoded-only">(
     request: Simplify<
       HttpApiEndpoint.ClientRequest<
         Endpoint["~Params"],

package/src/http-api/HttpApiError.ts

@@ -467,8 +467,9 @@ export const HttpApiSchemaErrorTypeId: HttpApiSchemaErrorTypeId = "~effect/http-
 
 /**
  * Error raised when an HTTP API request or response component fails schema
- * decoding or encoding. It records which component failed and responds as an
- * empty `400 Bad Request` when rendered as a server response.
+ * decoding or encoding. Request decoding failures respond with an empty
+ * `400 Bad Request` and are ignored by error reporters. Response encoding
+ * failures respond with an empty `500 Internal Server Error` and are reported.
  *
  * @stability unstable
  * @category errors
@@ -479,7 +480,10 @@ export class HttpApiSchemaError extends Data.TaggedClass("HttpApiSchemaError")<{
   readonly cause: Schema.SchemaError
 }> {
   readonly [HttpApiSchemaErrorTypeId]: HttpApiSchemaErrorTypeId = HttpApiSchemaErrorTypeId
-  readonly [ErrorReporter.ignore] = true
+
+  get [ErrorReporter.ignore](): boolean {
+    return this.kind !== "Body" && this.kind !== "ResponseHeaders"
+  }
 
   static is(u: unknown): u is HttpApiSchemaError {
     return hasProperty(u, HttpApiSchemaErrorTypeId)
@@ -498,6 +502,6 @@ export class HttpApiSchemaError extends Data.TaggedClass("HttpApiSchemaError")<{
   readonly message = this.kind;
 
   [HttpServerRespondable.symbol]() {
-    return Effect.succeed(badRequestResponse)
+    return Effect.succeed(this[ErrorReporter.ignore] ? badRequestResponse : internalServerErrorResponse)
   }
 }

package/src/http-api/HttpApiSecurity.ts

@@ -126,8 +126,8 @@ const Proto = {
  *
  * **Details**
  *
- * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
- * security scheme.
+ * Use `HttpApiMiddleware.Service` with a `security` option to implement API
+ * middleware for this security scheme.
  *
  * @see {@link apiKey} for an API-key security scheme
  * @see {@link basic} for an HTTP Basic security scheme
@@ -155,8 +155,8 @@ export const http = (options: {
  *
  * **Details**
  *
- * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
- * security scheme.
+ * Use `HttpApiMiddleware.Service` with a `security` option to implement API
+ * middleware for this security scheme.
  *
  * @see {@link apiKey} for an API-key security scheme
  * @see {@link basic} for an HTTP Basic security scheme
@@ -176,8 +176,8 @@ export const bearer: Http = http({ scheme: "Bearer" })
  *
  * **Details**
  *
- * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
- * security scheme.
+ * Use `HttpApiMiddleware.Service` with a `security` option to implement API
+ * middleware for this security scheme.
  *
  * Use `HttpApiBuilder.securitySetCookie` to set the correct cookie in a
  * handler. By default, `in` is `"header"`.
@@ -208,8 +208,8 @@ export const apiKey = (options: {
  *
  * **Details**
  *
- * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
- * security scheme.
+ * Use `HttpApiMiddleware.Service` with a `security` option to implement API
+ * middleware for this security scheme.
  *
  * @see {@link bearer} for a Bearer token security scheme
  * @see {@link apiKey} for an API-key security scheme