effect 4.0.6 → 4.1.0

package/src/http/HttpStaticServer.ts

@@ -121,7 +121,9 @@ export const make: (options: {
   ) => Effect.Effect<HttpServerResponse.HttpServerResponse, HttpServerError.HttpServerError> = Effect.fnUntraced(
     function*(request, filePath, fileSize) {
       const rangeHeader = request.method === "GET" ? request.headers["range"] : undefined
-      const shouldEvaluateConditionals = request.headers["if-none-match"] !== undefined ||
+      const shouldEvaluateConditionals = request.headers["if-match"] !== undefined ||
+        request.headers["if-unmodified-since"] !== undefined ||
+        request.headers["if-none-match"] !== undefined ||
         request.headers["if-modified-since"] !== undefined
 
       let fullResponse: HttpServerResponse.HttpServerResponse | undefined
@@ -446,6 +448,22 @@ const stripWeakEtagPrefix = (value: string): string => {
   return /^w\//i.test(trimmed) ? trimmed.slice(2) : trimmed;
 }
 
+// If-Match uses strong comparison (RFC 9110 §13.1.1), so weak tags never
+// match. Tags may contain commas, so the list is validated whole rather than
+// split, and a malformed list matches nothing.
+const entityTagList = /^[\s,]*(?:(?:W\/)?"[^"]*"\s*(?:,[\s,]*|$))*$/
+const entityTag = /(?:W\/)?"[^"]*"/g
+
+const matchesIfMatch = (ifMatch: string, etag: string | undefined): boolean => {
+  if (ifMatch.trim() === "*") {
+    return true
+  }
+  if (etag === undefined || !etag.startsWith("\"") || !entityTagList.test(ifMatch)) {
+    return false
+  }
+  return ifMatch.match(entityTag)?.includes(etag) ?? false
+}
+
 const matchesIfNoneMatch = (ifNoneMatch: string, etag: string | undefined): boolean => {
   const normalizedEtag = etag === undefined ? undefined : stripWeakEtagPrefix(etag)
   for (const candidate of ifNoneMatch.split(",")) {
@@ -463,18 +481,19 @@ const matchesIfNoneMatch = (ifNoneMatch: string, etag: string | undefined): bool
   return false
 }
 
-// An invalid date on either side disables the precondition (RFC 9110 §13.1.3).
-const isNotModifiedSince = (ifModifiedSince: string, lastModified: string | undefined): boolean => {
+// An invalid date on either side disables the precondition (RFC 9110 §13.1.3–4).
+const isModifiedSince = (since: string, lastModified: string | undefined): boolean | undefined => {
   if (lastModified === undefined) {
-    return false
+    return undefined
   }
-  const ifModifiedSinceDate = Headers.parseHttpDate(ifModifiedSince)
-  if (Result.isFailure(ifModifiedSinceDate)) {
-    return false
+  const sinceDate = Headers.parseHttpDate(since)
+  if (Result.isFailure(sinceDate)) {
+    return undefined
   }
   const lastModifiedDate = Headers.parseHttpDate(lastModified)
-  return Result.isSuccess(lastModifiedDate) &&
-    DateTime.toEpochMillis(lastModifiedDate.success) <= DateTime.toEpochMillis(ifModifiedSinceDate.success)
+  return Result.isSuccess(lastModifiedDate)
+    ? DateTime.toEpochMillis(lastModifiedDate.success) > DateTime.toEpochMillis(sinceDate.success)
+    : undefined
 }
 
 // Only a strong entity-tag can match (RFC 9110 §13.1.5). Weak tags start
@@ -485,21 +504,18 @@ const matchesIfRange = (ifRange: string, etag: string | undefined): boolean => {
   return value.startsWith("\"") && value === etag
 }
 
+// Headers a 304 must repeat from the 200 response (RFC 9110 §15.4.5), plus Last-Modified for revalidation.
+const notModifiedHeaders = ["cache-control", "content-location", "date", "etag", "expires", "last-modified", "vary"]
+
 const notModifiedResponse = (
   response: HttpServerResponse.HttpServerResponse
 ): HttpServerResponse.HttpServerResponse => {
   const headers: Record<string, string> = {}
-  const etag = response.headers["etag"]
-  if (etag !== undefined) {
-    headers["ETag"] = etag
-  }
-  const cacheControl = response.headers["cache-control"]
-  if (cacheControl !== undefined) {
-    headers["Cache-Control"] = cacheControl
-  }
-  const lastModified = response.headers["last-modified"]
-  if (lastModified !== undefined) {
-    headers["Last-Modified"] = lastModified
+  for (const name of notModifiedHeaders) {
+    const value = response.headers[name]
+    if (value !== undefined) {
+      headers[name] = value
+    }
   }
   return HttpServerResponse.empty({
     status: 304,
@@ -511,12 +527,25 @@ const evaluateConditionalRequest = (
   request: HttpServerRequest.HttpServerRequest,
   response: HttpServerResponse.HttpServerResponse
 ): HttpServerResponse.HttpServerResponse | undefined => {
+  const etag = response.headers["etag"]
+  const lastModified = response.headers["last-modified"]
+  const ifMatch = request.headers["if-match"]
+  if (ifMatch !== undefined) {
+    if (!matchesIfMatch(ifMatch, etag)) {
+      return HttpServerResponse.empty({ status: 412 })
+    }
+  } else {
+    const ifUnmodifiedSince = request.headers["if-unmodified-since"]
+    if (ifUnmodifiedSince !== undefined && isModifiedSince(ifUnmodifiedSince, lastModified) === true) {
+      return HttpServerResponse.empty({ status: 412 })
+    }
+  }
   const ifNoneMatch = request.headers["if-none-match"]
   if (ifNoneMatch !== undefined) {
-    return matchesIfNoneMatch(ifNoneMatch, response.headers["etag"]) ? notModifiedResponse(response) : undefined
+    return matchesIfNoneMatch(ifNoneMatch, etag) ? notModifiedResponse(response) : undefined
   }
   const ifModifiedSince = request.headers["if-modified-since"]
-  if (ifModifiedSince !== undefined && isNotModifiedSince(ifModifiedSince, response.headers["last-modified"])) {
+  if (ifModifiedSince !== undefined && isModifiedSince(ifModifiedSince, lastModified) === false) {
     return notModifiedResponse(response)
   }
   return undefined

package/src/http/HttpTraceContext.ts

@@ -130,10 +130,11 @@ export const xb3: FromHeaders = (headers) => {
   }))
 }
 
-const w3cTraceId = /^[0-9a-f]{32}$/i
-const w3cSpanId = /^[0-9a-f]{16}$/i
+const w3cTraceId = /^[0-9a-f]{32}$/
+const w3cSpanId = /^[0-9a-f]{16}$/
+const w3cTraceFlags = /^[0-9a-f]{2}$/
 
-const b3TraceId = /^(?:[0-9a-f]{16}|[0-9a-f]{32})$/i
+const b3TraceId = /^(?:[0-9a-f]{16}|[0-9a-f]{32})$/
 const isB3Ids = (traceId: string, spanId: string): boolean => b3TraceId.test(traceId) && w3cSpanId.test(spanId)
 
 /**
@@ -141,7 +142,8 @@ const isB3Ids = (traceId: string, spanId: string): boolean => b3TraceId.test(tra
  *
  * **Details**
  *
- * Only version `00` headers with valid trace and span identifiers are accepted.
+ * Only version `00` headers with valid trace and span identifiers and trace
+ * flags are accepted.
  *
  * @stability unstable
  * @category decoding
@@ -160,6 +162,7 @@ export const w3c: FromHeaders = (headers) => {
     case "00": {
       if (
         w3cTraceId.test(traceId) === false || w3cSpanId.test(spanId) === false ||
+        w3cTraceFlags.test(flags) === false ||
         traceId === "00000000000000000000000000000000" || spanId === "0000000000000000"
       ) {
         return Option.none()

package/src/http/MultipartParser/internal/contentType.ts

@@ -16,14 +16,14 @@
  * quoted-pair   = "\" ( HTAB / SP / VCHAR / obs-text )
  */
 const paramRE =
-  /; *([!#$%&'*+.^\w`|~-]+)=("(?:[\v\u0020\u0021\u0023-\u005b\u005d-\u007e\u0080-\u{10ffff}]|\\[\v\u0020-\u{10ffff}])*"|[!#$%&'*+.^\w`|~-]+) */gu
+  /; *([!#$%&'*+.^\w`|~-]+)=("(?:[\t\u0020\u0021\u0023-\u005b\u005d-\u007e\u0080-\u{10ffff}]|\\[\t\u0020-\u{10ffff}])*"|[!#$%&'*+.^\w`|~-]+) */gu
 
 /**
  * RegExp to match *( ";" disposition-parm ) in RFC 6266 sec 4.1, which allows
  * optional whitespace around separators
  */
 const dispositionParamRE =
-  /;[ \t]*([!#$%&'*+.^\w`|~-]+)[ \t]*=[ \t]*("(?:[\v\u0020\u0021\u0023-\u005b\u005d-\u007e\u0080-\u{10ffff}]|\\[\v\u0020-\u{10ffff}])*"|[!#$%&'*+.^\w`|~-]+)[ \t]*/gu
+  /;[ \t]*([!#$%&'*+.^\w`|~-]+)[ \t]*=[ \t]*("(?:[\t\u0020\u0021\u0023-\u005b\u005d-\u007e\u0080-\u{10ffff}]|\\[\t\u0020-\u{10ffff}])*"|[!#$%&'*+.^\w`|~-]+)[ \t]*/gu
 
 /**
  * RegExp to match quoted-pair in RFC 7230 sec 3.2.6
@@ -31,7 +31,7 @@ const dispositionParamRE =
  * quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text )
  * obs-text    = %x80-FF
  */
-const quotedPairRE = /\\([\v\u0020-\u{10ffff}])/gu
+const quotedPairRE = /\\([\t\u0020-\u{10ffff}])/gu
 
 /**
  * RegExp to match type in RFC 7231 sec 3.1.1.1

package/src/http/ProblemDetails.ts

@@ -0,0 +1,149 @@
+/**
+ * RFC 9457 Problem Details values for HTTP responses.
+ *
+ * A problem details object is the `application/problem+json` body a server
+ * sends to describe an error. This module provides the reusable value shape,
+ * a lenient codec that follows the parsing rules of RFC 9457, and a response
+ * constructor. The `effect/http-api` modules build typed problem declarations,
+ * built-in error rendering and OpenAPI output on top of it.
+ *
+ * @stability unstable
+ * @since 4.0.6
+ */
+import * as Effect from "../Effect.ts"
+import * as Schema_ from "../Schema.ts"
+import * as HttpServerResponse from "./HttpServerResponse.ts"
+
+/**
+ * The media type of a problem details response body.
+ *
+ * @stability unstable
+ * @category constants
+ * @since 4.0.6
+ */
+export const contentType = "application/problem+json"
+
+/**
+ * The problem type URI RFC 9457 assigns to problems that only carry an HTTP
+ * status.
+ *
+ * @stability unstable
+ * @category constants
+ * @since 4.0.6
+ */
+export const blankType = "about:blank"
+
+/**
+ * A decoded RFC 9457 problem details object.
+ *
+ * **Details**
+ *
+ * The standard members are `type`, `status`, `title`, `detail` and
+ * `instance`. Any other member is an extension and is kept as-is.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface ProblemDetails {
+  readonly type: string
+  readonly status?: number
+  readonly title?: string
+  readonly detail?: string
+  readonly instance?: string
+  readonly [extension: string]: unknown
+}
+
+/**
+ * The encoded form of a problem details object, where `type` may be omitted.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface ProblemDetailsEncoded {
+  readonly type?: string
+  readonly status?: number
+  readonly title?: string
+  readonly detail?: string
+  readonly instance?: string
+  readonly [extension: string]: unknown
+}
+
+/**
+ * A standard member that is dropped when it is missing or has the wrong JSON
+ * type, as RFC 9457 section 3.1 requires.
+ *
+ * @internal
+ */
+export const optionalMember = <S extends Schema_.Constraint>(schema: S) =>
+  Schema_.optionalKey(schema).pipe(Schema_.catchDecoding(() => Effect.succeedNone))
+
+const withFallback = <S extends Schema_.Constraint>(
+  schema: S,
+  value: S["Encoded"] & S["Type"]
+): Schema_.middlewareDecoding<Schema_.withDecodingDefaultKey<S>, S["DecodingServices"]> =>
+  Schema_.withDecodingDefaultKey<S>(Effect.succeed(value))(schema).pipe(
+    Schema_.catchDecoding(() => Effect.succeedSome(value))
+  )
+
+/**
+ * A required member that decodes to a fixed value when it is missing or has
+ * the wrong JSON type. The value is also the constructor default.
+ *
+ * @internal
+ */
+export const fixedMember = <const L extends string | number>(value: L) => withFallback(Schema_.tag(value), value)
+
+/**
+ * The lenient codec for problem details objects.
+ *
+ * **Details**
+ *
+ * Decoding follows RFC 9457: a missing `type` defaults to `about:blank`,
+ * standard members with the wrong JSON type are ignored, and unknown members
+ * are kept as extensions. Encoding always emits `type`.
+ *
+ * **Example** (Decoding a problem with an extension)
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { ProblemDetails } from "effect/http"
+ *
+ * const problem = Schema.decodeUnknownSync(ProblemDetails.Schema)({
+ *   status: 404,
+ *   detail: "No such user",
+ *   traceId: "abc-123"
+ * })
+ * problem // => { type: "about:blank", status: 404, detail: "No such user", traceId: "abc-123" }
+ * ```
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.6
+ */
+export const Schema: Schema_.Codec<ProblemDetails, ProblemDetailsEncoded> = Schema_.StructWithRest(
+  Schema_.Struct({
+    type: withFallback(Schema_.String, blankType),
+    status: optionalMember(Schema_.Number),
+    title: optionalMember(Schema_.String),
+    detail: optionalMember(Schema_.String),
+    instance: optionalMember(Schema_.String)
+  }),
+  [Schema_.Record(Schema_.String, Schema_.Unknown)]
+)
+
+/**
+ * Renders a problem details object as an `application/problem+json` response.
+ *
+ * **Details**
+ *
+ * The response status is the problem's `status` member, or `500` when it is
+ * absent.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const toResponse = (problem: ProblemDetails): HttpServerResponse.HttpServerResponse =>
+  HttpServerResponse.jsonUnsafe(problem, { status: problem.status ?? 500, contentType })

package/src/http/UrlParams.ts

@@ -870,7 +870,9 @@ const currentRedactedNames = (): ReadonlyArray<string | RegExp> =>
  *
  * **Details**
  *
- * Defaults include `AWSAccessKeyId`, `Signature`, `sig` and `X-Goog-Signature`.
+ * Defaults match the OpenTelemetry `url.full` list: `X-Amz-Signature`,
+ * `X-Amz-Credential`, `X-Amz-Security-Token`, `AWSAccessKeyId`, `Signature`,
+ * `sig` and `X-Goog-Signature`.
  * A custom list replaces the defaults. Matching uses `isRedactedName`.
  * Redaction leaves request URLs and parameter values unchanged. `Redacted`
  * values are redacted regardless of this list.
@@ -883,6 +885,9 @@ export const CurrentRedactedNames = Context.Reference<
   ReadonlyArray<string | RegExp>
 >("effect/http/UrlParams/CurrentRedactedNames", {
   defaultValue: () => [
+    "X-Amz-Signature",
+    "X-Amz-Credential",
+    "X-Amz-Security-Token",
     "AWSAccessKeyId",
     "Signature",
     "sig",

package/src/http/index.ts

@@ -167,6 +167,12 @@ export * as Multipart from "./Multipart.ts"
  */
 export * as MultipartParser from "./MultipartParser.ts"
 
+/**
+ * @stability unstable
+ * @since 4.0.6
+ */
+export * as ProblemDetails from "./ProblemDetails.ts"
+
 /**
  * @stability unstable
  * @since 4.0.0

package/src/http/internal/compression.ts

@@ -155,13 +155,12 @@ const acceptMember = /^([a-z0-9!#$%&'*+.^_`|~-]+)(?:;q=(0(?:\.[0-9]{0,3})?|1(?:\
  * @internal
  */
 export const parseAcceptEncoding = (header: string): ReadonlyMap<string, number> | undefined => {
-  const trimmed = header.trim()
-  if (trimmed === "") {
-    return undefined
-  }
   const accepted = new Map<string, number>()
-  for (const part of trimmed.split(",")) {
+  for (const part of header.split(",")) {
     const member = part.trim().toLowerCase().replace(/[ \t]*;[ \t]*/g, ";")
+    if (member === "") {
+      continue
+    }
     const match = acceptMember.exec(member)
     if (match === null) {
       return undefined

package/src/http/internal/decompression.ts

@@ -8,12 +8,12 @@ import type * as Socket from "../../socket/Socket.ts"
 import * as Stream from "../../Stream.ts"
 import * as Headers from "../Headers.ts"
 import * as HttpIncomingMessage from "../HttpIncomingMessage.ts"
-import type { HttpMethod } from "../HttpMethod.ts"
 import { HttpServerError, RequestParseError } from "../HttpServerError.ts"
 import * as HttpServerRequest from "../HttpServerRequest.ts"
 import * as Multipart from "../Multipart.ts"
 import * as UrlParams from "../UrlParams.ts"
 import * as lazyStream from "./lazyStream.ts"
+import * as internalUrlParams from "./urlParams.ts"
 
 /**
  * @internal
@@ -100,7 +100,7 @@ export class DecompressedRequest extends Inspectable.Class implements HttpServer
     return this.inner.originalUrl
   }
 
-  get method(): HttpMethod {
+  get method(): string {
     return this.inner.method
   }
 
@@ -124,6 +124,12 @@ export class DecompressedRequest extends Inspectable.Class implements HttpServer
     return this.inner.upgrade
   }
 
+  upgradeWith(
+    options: { readonly headers?: Headers.Input | undefined }
+  ): Effect.Effect<Socket.Socket, HttpServerError> {
+    return this.inner.upgradeWith(options)
+  }
+
   // Platform accessors such as `NodeHttpServerRequest.toServerResponse` read
   // the response handle from the request.
   get response(): unknown {
@@ -182,9 +188,9 @@ export class DecompressedRequest extends Inspectable.Class implements HttpServer
   }
 
   get urlParamsBody(): Effect.Effect<UrlParams.UrlParams, HttpServerError> {
-    return Effect.flatMap(this.text, (text) =>
+    return Effect.flatMap(this.bytes, (bytes) =>
       Effect.try({
-        try: () => UrlParams.fromInput(new URLSearchParams(text)),
+        try: () => UrlParams.fromInput(internalUrlParams.fromBody(bytes)),
         catch: (cause) => this.parseError(cause)
       }))
   }

package/src/http/internal/httpBody.ts

@@ -11,9 +11,17 @@ export const updateHeaders = (headers: Headers.Headers, body: HttpBody.HttpBody)
   headers = body.contentType === undefined
     ? Headers.remove(headers, "content-type")
     : Headers.set(headers, "content-type", body.contentType)
-  return body.contentLength === undefined
+  return updateContentLength(headers, body)
+}
+
+/**
+ * @internal
+ */
+export const updateContentLength = (headers: Headers.Headers, body: HttpBody.HttpBody): Headers.Headers => {
+  const contentLength = body._tag === "Empty" || body._tag === "FormData" ? undefined : body.contentLength
+  return contentLength === undefined
     ? Headers.remove(headers, "content-length")
-    : Headers.set(headers, "content-length", body.contentLength.toString())
+    : Headers.set(headers, "content-length", contentLength.toString())
 }
 
 /**

package/src/http/internal/urlParams.ts

@@ -3,3 +3,40 @@ import * as Redacted from "../../Redacted.ts"
 /** @internal */
 export const unwrap = (value: string | Redacted.Redacted): string =>
   typeof value === "string" ? value : Redacted.value(value)
+
+/** @internal */
+export const stripSearchAndHash = (url: string): string => {
+  const queryIndex = url.indexOf("?")
+  const hashIndex = url.indexOf("#")
+
+  if (queryIndex === -1) {
+    return hashIndex === -1 ? url : url.slice(0, hashIndex)
+  }
+  if (hashIndex === -1) {
+    return url.slice(0, queryIndex)
+  }
+  return url.slice(0, Math.min(queryIndex, hashIndex))
+}
+
+// URL-encoded bodies keep a leading U+FEFF as form data
+const bodyDecoder = new TextDecoder("utf-8", { ignoreBOM: true })
+
+/** @internal */
+export const fromBody = (bytes: ArrayBuffer | Uint8Array): URLSearchParams =>
+  // A leading "?" is form data; URLSearchParams would drop it as a query prefix.
+  new URLSearchParams(bodyDecoder.decode(bytes).replace(/^\?/, "%3F"))
+
+const originForm = /^\/(?![/\\])/
+
+/** @internal */
+export const toPath = (url: string): string => {
+  // Origin-form targets and "*" are already paths; absolute URLs can carry credentials.
+  if (url === "*" || originForm.test(url)) {
+    return stripSearchAndHash(url)
+  }
+  try {
+    return new URL(url, "http://localhost").pathname
+  } catch {
+    return "<invalid URL>"
+  }
+}

package/src/http-api/HttpApi.ts

@@ -371,12 +371,9 @@ export class AdditionalSchemas extends Context.Service<
  *
  * Header codecs receive all HTTP headers, including undeclared transport
  * headers such as `content-type`, `content-length`, `host`, `user-agent` and
- * proxy headers. Without `HeadersParseOptions`, headers use `ParseOptions`:
- *
- * - `onExcessProperty: "error"` rejects real requests and `WithHeaders`
- *   responses with transport headers.
- * - `onExcessProperty: "preserve"` includes transport headers in the decoded
- *   value.
+ * proxy headers. Without `HeadersParseOptions`, headers use `ParseOptions`, so
+ * `onExcessProperty: "error"` rejects real requests and `WithHeaders` responses
+ * with transport headers.
  *
  * Set `HeadersParseOptions` to `{}` at the API level to use Schema defaults for
  * headers, even if an endpoint sets `ParseOptions`.

package/src/http-api/HttpApiBuilder.ts

@@ -90,19 +90,33 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Constraint>
       | Path
     >()
     const routes: Array<HttpRouter.Route<any, any>> = []
+    const routeOwners = new Map<string, string>()
     const availableGroups = Array.from(services.mapUnsafe.keys()).filter((key) =>
       key.startsWith("effect/http-api/HttpApiGroup/")
     )
     const groups = Object.values(api.groups) as ReadonlyArray<HttpApiGroup.Top>
     for (const group of groups) {
-      const groupRoutes = services.mapUnsafe.get(group.key)?.routes as Array<HttpRouter.Route<any, any>>
-      if (groupRoutes === undefined) {
+      const service = services.mapUnsafe.get(group.key) as GroupService | undefined
+      if (service === undefined) {
         const available = availableGroups.length === 0 ? "none" : availableGroups.join(", ")
         return yield* Effect.die(
           `HttpApiGroup "${group.identifier}" not found (key: "${group.key}"). Did you forget to provide HttpApiBuilder.group(api, "${group.identifier}", ...)? Available groups: ${available}`
         )
       }
-      routes.push(...groupRoutes)
+      for (const { endpoint } of service.handlers.values()) {
+        const owner = `${group.identifier}.${endpoint.identifier}`
+        const key = `${endpoint.method} ${HttpApiPath.toRouterPath(endpoint.path, endpoint.params)}`
+        const existing = routeOwners.get(key)
+        if (existing !== undefined) {
+          return yield* Effect.die(
+            new Error(
+              `HttpApiEndpoint "${owner}" (${endpoint.method} ${endpoint.path}) has the same method and path as "${existing}". Declare one endpoint whose query, headers, payload or success schemas cover each variant instead.`
+            )
+          )
+        }
+        routeOwners.set(key, owner)
+      }
+      routes.push(...service.routes)
     }
     yield* (router.addAll(routes) as Effect.Effect<void>)
     if (options?.openapiPath) {
@@ -159,12 +173,8 @@ export const group = <
     for (const item of handlers.handlers.values()) {
       routes.push(handlerToRoute(api, group as any, item, services))
     }
-    return Context.makeUnsafe(
-      new Map([[group.key, {
-        routes,
-        handlers: handlers.handlers
-      }]])
-    )
+    const service: GroupService = { routes, handlers: handlers.handlers }
+    return Context.makeUnsafe(new Map([[group.key, service]]))
   })) as any
 
 /**
@@ -245,6 +255,14 @@ export interface HandlerRuntime {
   readonly uninterruptible: boolean
 }
 
+/**
+ * @internal
+ */
+export interface GroupService {
+  readonly routes: Array<HttpRouter.Route<any, any>>
+  readonly handlers: Map<string, HandlerRuntime>
+}
+
 type HandleAllEntry<Endpoint extends HttpApiEndpoint.Constraint> =
   | HttpApiEndpoint.Handler<
     Endpoint,
@@ -939,6 +957,12 @@ function handlerToHttpEffect(
   const encodeStream = makeStreamEncoder(endpoint, options.success)
   const encodeWithHeaders = makeWithHeadersEncoder(endpoint, options.success, options.headers)
   const upgrade = getUpgradeSuccessSchema(endpoint)
+  // The handler of a mixed endpoint may decline the upgrade and return one of the other successes.
+  const upgradeOnly = upgrade !== undefined && endpoint.success.size === 1
+  const encodeUpgradeHeaders = UndefinedOr.map(
+    upgrade?.headers,
+    (schema) => Schema.encodeUnknownEffect(schema, options.headers)
+  )
 
   const shouldParsePayload = endpoint.payload.size > 0 && !isRaw
   const payloadBy = shouldParsePayload ? buildPayloadDecoders(endpoint.payload, options.payload) : undefined
@@ -967,6 +991,24 @@ function handlerToHttpEffect(
       if (decodeQuery) {
         request.query = yield* HttpApiSchemaError.wrap("Query", decodeQuery(query))
       }
+      let upgraded = false
+      if (upgrade !== undefined) {
+        if (!isUpgradeRequest(httpRequest, upgrade.protocol)) {
+          return upgradeRequired(upgrade.protocol)
+        }
+        request.upgrade = (options?: { readonly headers?: unknown }) =>
+          Effect.suspend(() => {
+            upgraded = true
+            return Effect.orDie(
+              encodeUpgradeHeaders === undefined
+                ? httpRequest.upgrade
+                : Effect.flatMap(
+                  HttpApiSchemaError.wrap("ResponseHeaders", encodeUpgradeHeaders(options?.headers)),
+                  (headers) => httpRequest.upgradeWith({ headers: headers as Record<string, string> })
+                )
+            )
+          })
+      }
       if (payloadBy) {
         const result = decodePayload(payloadBy, httpRequest, query)
         if (Response.isHttpServerResponse(result)) {
@@ -976,17 +1018,14 @@ function handlerToHttpEffect(
           request.payload = yield* HttpApiSchemaError.wrap("Payload", result)
         }
       }
-      if (upgrade !== undefined) {
-        if (!isUpgradeRequest(httpRequest, upgrade.protocol)) {
-          return upgradeRequired(upgrade.protocol)
-        }
-        request.socket = yield* Effect.orDie(httpRequest.upgrade)
-      }
       let response = yield* handler(request)
       if (Response.isHttpServerResponse(response)) {
         return response
       }
-      if (upgrade !== undefined) {
+      if (upgradeOnly || upgraded) {
+        if (response !== undefined && !upgradeOnly) {
+          return yield* Effect.die(new Error("Cannot return a success value after calling upgrade()"))
+        }
         // The server replaces this with the 101 once the connection is upgraded.
         return Response.empty()
       }
@@ -1337,9 +1376,12 @@ function makeSuccessSchema(
   endpoint: HttpApiEndpoint.Top,
   headersOptions: SchemaAST.ParseOptions | undefined
 ): Schema.ConstraintEncoder<HttpServerResponse, unknown> {
-  const schemas = HttpApiEndpoint.getSuccessSchemas(endpoint).map((schema) =>
-    toResponseSuccessSchema(schema, headersOptions)
-  )
+  const schemas: Array<Schema.ConstraintEncoder<HttpServerResponse, unknown>> = []
+  for (const schema of HttpApiEndpoint.getSuccessSchemas(endpoint)) {
+    // The 101 is written by the transport, so the upgrade has no response encoder.
+    if (HttpApiSchema.isUpgrade(schema)) continue
+    schemas.push(toResponseSuccessSchema(schema, headersOptions))
+  }
   return schemas.length === 1 ? schemas[0] : Schema.Union(schemas)
 }