effect 4.0.7 → 4.1.0

package/src/http/HttpClientResponse.ts

@@ -25,6 +25,7 @@ import * as Headers from "./Headers.ts"
 import * as Error from "./HttpClientError.ts"
 import * as HttpClientRequest from "./HttpClientRequest.ts"
 import * as HttpIncomingMessage from "./HttpIncomingMessage.ts"
+import * as internalUrlParams from "./internal/urlParams.ts"
 import { getWebSource, WebSourceSymbol } from "./internal/webResponse.ts"
 import * as UrlParams from "./UrlParams.ts"
 
@@ -454,9 +455,9 @@ class WebHttpClientResponse extends Inspectable.Class implements HttpClientRespo
   }
 
   get urlParamsBody(): Effect.Effect<UrlParams.UrlParams, Error.HttpClientError> {
-    return Effect.flatMap(this.text, (_) =>
+    return Effect.flatMap(this.arrayBuffer, (bytes) =>
       Effect.try({
-        try: () => UrlParams.fromInput(new URLSearchParams(_)),
+        try: () => UrlParams.fromInput(internalUrlParams.fromBody(bytes)),
         catch: (cause) =>
           new Error.HttpClientError({
             reason: new Error.DecodeError({

package/src/http/HttpMethod.ts

@@ -57,12 +57,20 @@ export declare namespace HttpMethod {
 /**
  * Returns `true` when a method can carry a request body and narrows it to `HttpMethod.WithBody`.
  *
+ * **Details**
+ *
+ * Methods outside the known `HttpMethod` literals, such as a received
+ * `"PROPFIND"`, are treated as capable of carrying a body but are not narrowed.
+ *
  * @stability unstable
  * @category guards
  * @since 4.0.0
  */
-export const hasBody = (method: HttpMethod): method is HttpMethod.WithBody =>
-  method !== "GET" && method !== "HEAD" && method !== "OPTIONS" && method !== "TRACE"
+export function hasBody(method: HttpMethod): method is HttpMethod.WithBody
+export function hasBody(method: string): boolean
+export function hasBody(method: string): boolean {
+  return method !== "GET" && method !== "HEAD" && method !== "OPTIONS" && method !== "TRACE"
+}
 
 /**
  * Provides a readonly set containing every supported `HttpMethod` literal.

package/src/http/HttpServerRequest.ts

@@ -32,10 +32,11 @@ import * as Headers from "./Headers.ts"
 import * as HttpBody from "./HttpBody.ts"
 import * as HttpClientRequest from "./HttpClientRequest.ts"
 import * as HttpIncomingMessage from "./HttpIncomingMessage.ts"
-import { hasBody, type HttpMethod } from "./HttpMethod.ts"
+import { hasBody } from "./HttpMethod.ts"
 import { HttpServerError, type RequestError, RequestParseError } from "./HttpServerError.ts"
 import * as bodyInternal from "./internal/httpBody.ts"
 import * as lazyStream from "./internal/lazyStream.ts"
+import * as internalUrlParams from "./internal/urlParams.ts"
 import * as Multipart from "./Multipart.ts"
 import * as UrlParams from "./UrlParams.ts"
 
@@ -90,7 +91,11 @@ export interface HttpServerRequest extends HttpIncomingMessage.HttpIncomingMessa
   readonly source: object
   readonly url: string
   readonly originalUrl: string
-  readonly method: HttpMethod
+  /**
+   * The uppercase request method as received, which may be a method outside
+   * the known `HttpMethod` literals (for example `"PROPFIND"`).
+   */
+  readonly method: string
   readonly cookies: ReadonlyRecord<string, string>
 
   readonly multipart: Effect.Effect<
@@ -563,8 +568,8 @@ class ServerRequestImpl extends Inspectable.Class implements HttpServerRequest {
       options.protocol ?? this.protocol
     )
   }
-  get method(): HttpMethod {
-    return this.source.method.toUpperCase() as HttpMethod
+  get method(): string {
+    return this.source.method.toUpperCase()
   }
   get originalUrl() {
     return this.source.url
@@ -612,27 +617,7 @@ class ServerRequestImpl extends Inspectable.Class implements HttpServerRequest {
 
   private textEffect: Effect.Effect<string, HttpServerError> | undefined
   get text(): Effect.Effect<string, HttpServerError> {
-    if (this.textEffect) {
-      return this.textEffect
-    }
-    this.textEffect = Effect.withFiber((fiber) =>
-      fiber.getRef(HttpIncomingMessage.MaxBodySize) === undefined
-        ? Effect.tryPromise({
-          try: () => this.source.text(),
-          catch: (cause) =>
-            new HttpServerError({
-              reason: new RequestParseError({
-                request: this,
-                cause
-              })
-            })
-        })
-        : Effect.map(this.arrayBuffer, (buffer) => textDecoder.decode(buffer))
-    ).pipe(
-      Effect.cached,
-      Effect.runSync
-    )
-    return this.textEffect
+    return this.textEffect ??= Effect.map(this.arrayBuffer, (buffer) => textDecoder.decode(buffer))
   }
 
   get json(): Effect.Effect<Schema.Json, HttpServerError> {
@@ -650,9 +635,9 @@ class ServerRequestImpl extends Inspectable.Class implements HttpServerRequest {
   }
 
   get urlParamsBody(): Effect.Effect<UrlParams.UrlParams, HttpServerError> {
-    return Effect.flatMap(this.text, (_) =>
+    return Effect.flatMap(this.arrayBuffer, (bytes) =>
       Effect.try({
-        try: () => UrlParams.fromInput(new URLSearchParams(_)),
+        try: () => UrlParams.fromInput(internalUrlParams.fromBody(bytes)),
         catch: (cause) =>
           new HttpServerError({
             reason: new RequestParseError({
@@ -797,7 +782,7 @@ class ClientRequestImpl extends Inspectable.Class implements HttpServerRequest {
     )
   }
 
-  get method(): HttpMethod {
+  get method(): string {
     return this.source.method
   }
 
@@ -892,9 +877,9 @@ class ClientRequestImpl extends Inspectable.Class implements HttpServerRequest {
   }
 
   get urlParamsBody(): Effect.Effect<UrlParams.UrlParams, HttpServerError> {
-    return Effect.flatMap(this.text, (_) =>
+    return Effect.flatMap(this.bytes, (bytes) =>
       Effect.try({
-        try: () => UrlParams.fromInput(new URLSearchParams(_)),
+        try: () => UrlParams.fromInput(internalUrlParams.fromBody(bytes)),
         catch: (cause) => requestParseError(this, undefined, cause)
       }))
   }

package/src/http/HttpServerResponse.ts

@@ -38,6 +38,7 @@ import * as HttpIncomingMessage from "./HttpIncomingMessage.ts"
 import type { HttpPlatform } from "./HttpPlatform.ts"
 import * as headersInternal from "./internal/headers.ts"
 import * as bodyInternal from "./internal/httpBody.ts"
+import * as internalUrlParams from "./internal/urlParams.ts"
 import * as Template from "./Template.ts"
 import * as UrlParams from "./UrlParams.ts"
 
@@ -1653,9 +1654,9 @@ class ServerHttpClientResponse extends Inspectable.Class implements HttpClientRe
   }
 
   get urlParamsBody(): Effect.Effect<UrlParams.UrlParams, HttpClientError.HttpClientError> {
-    return Effect.flatMap(this.text, (_) =>
+    return Effect.flatMap(this.bytes, (bytes) =>
       Effect.try({
-        try: () => UrlParams.fromInput(new URLSearchParams(_)),
+        try: () => UrlParams.fromInput(internalUrlParams.fromBody(bytes)),
         catch: (cause) =>
           new HttpClientError.HttpClientError({
             reason: new HttpClientError.DecodeError({

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/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/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/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
   }
 
@@ -188,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/urlParams.ts

@@ -18,6 +18,14 @@ export const stripSearchAndHash = (url: string): string => {
   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 */

package/src/http-api/HttpApiBuilder.ts

@@ -957,6 +957,8 @@ 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)
@@ -989,19 +991,23 @@ 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.orDie(
-            encodeUpgradeHeaders === undefined
-              ? httpRequest.upgrade
-              : Effect.flatMap(
-                HttpApiSchemaError.wrap("ResponseHeaders", encodeUpgradeHeaders(options?.headers)),
-                (headers) => httpRequest.upgradeWith({ headers: headers as Record<string, string> })
-              )
-          )
+          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)
@@ -1016,7 +1022,10 @@ function handlerToHttpEffect(
       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()
       }
@@ -1367,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)
 }
 

package/src/http-api/HttpApiClient.ts

@@ -106,6 +106,24 @@ export type SuccessType<S> = S extends HttpApiSchema.WithHeaders<
   : S extends Schema.Constraint ? S["Type"]
   : never
 
+/**
+ * Runtime brand key used to mark `Upgraded` values.
+ *
+ * @stability unstable
+ * @category type IDs
+ * @since 4.1.0
+ */
+export const UpgradedTypeId = "~effect/http-api/HttpApiClient/Upgraded"
+
+/**
+ * Type-level brand identifier used by `Upgraded` values.
+ *
+ * @stability unstable
+ * @category type IDs
+ * @since 4.1.0
+ */
+export type UpgradedTypeId = typeof UpgradedTypeId
+
 /**
  * The value a client method returns for an endpoint declared with
  * `HttpApiSchema.Upgrade`: the headers of the `101 Switching Protocols`
@@ -117,15 +135,63 @@ export type SuccessType<S> = S extends HttpApiSchema.WithHeaders<
  * one. See `HttpClientResponse.upgrade` for how the connection behaves and
  * when it closes.
  *
+ * When the endpoint also declares ordinary success responses, the method
+ * returns either an `Upgraded` value or the decoded ordinary success. Use
+ * {@link isUpgraded} to tell them apart.
+ *
  * @stability unstable
  * @category models
  * @since 4.0.6
  */
 export interface Upgraded<Headers = Headers.Headers> {
+  readonly [UpgradedTypeId]: UpgradedTypeId
   readonly headers: Headers
   readonly socket: Socket.Socket
 }
 
+/**
+ * Returns `true` when a client method result is an upgraded connection.
+ *
+ * **Details**
+ *
+ * An endpoint may declare `HttpApiSchema.Upgrade` alongside ordinary success
+ * responses, because a server can decline an upgrade (RFC 9110 §7.8). The
+ * client method then returns either an `Upgraded` value or the decoded
+ * ordinary success, depending on the response status. This predicate narrows
+ * that union.
+ *
+ * **Example** (Handling a declined upgrade)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api"
+ *
+ * const Api = HttpApi.make("docker").add(
+ *   HttpApiGroup.make("exec").add(
+ *     HttpApiEndpoint.post("start", "/exec/:id/start", {
+ *       params: { id: Schema.String },
+ *       payload: Schema.Struct({ Detach: Schema.Boolean }),
+ *       success: [HttpApiSchema.Upgrade({ protocol: "tcp" }), HttpApiSchema.Empty(200)]
+ *     })
+ *   )
+ * )
+ *
+ * const program = Effect.gen(function*() {
+ *   const client = yield* HttpApiClient.make(Api)
+ *   const result = yield* client.exec.start({ params: { id: "abc" }, payload: { Detach: false } })
+ *   if (HttpApiClient.isUpgraded(result)) {
+ *     const writer = yield* result.socket.writer
+ *     yield* writer.write("ls\n")
+ *   }
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.1.0
+ */
+export const isUpgraded = (u: unknown): u is Upgraded<unknown> => Predicate.hasProperty(u, UpgradedTypeId)
+
 type SuccessDecodingServices<S> = S extends HttpApiSchema.StreamSse<
   infer _Events,
   infer _Error,
@@ -1041,7 +1107,7 @@ const makeEndpointDecoder = (options: {
       Effect.uninterruptibleMask((restore) =>
         Effect.flatMap(response.upgrade, (socket) =>
           restore(decodeHeaders(response.headers)).pipe(
-            Effect.map((headers): Upgraded<unknown> => ({ headers, socket })),
+            Effect.map((headers): Upgraded<unknown> => ({ [UpgradedTypeId]: UpgradedTypeId, headers, socket })),
             // nothing takes the connection on failure, so close it: releasing
             // the reader's scope closes the connection
             Effect.onError(() => Effect.ignore(Effect.scoped(socket.reader)))

package/src/http-api/HttpApiEndpoint.ts

@@ -1440,10 +1440,12 @@ function getErrorResponse(
 }
 
 function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, method: HttpMethod, payload: PayloadMap) {
-  if (schemas.some(HttpApiSchema.isUpgrade)) {
-    if (schemas.length > 1) {
-      throw new Error("Cannot combine an upgrade with other success responses")
-    }
+  const upgrades = schemas.filter(HttpApiSchema.isUpgrade)
+  if (upgrades.length > 1) {
+    throw new Error("Cannot declare more than one upgrade")
+  }
+  const hasUpgrade = upgrades.length === 1
+  if (hasUpgrade) {
     if (method === "HEAD") {
       throw new Error("HEAD endpoints cannot declare an upgrade")
     }
@@ -1453,7 +1455,6 @@ function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, meth
         throw new Error("Upgrade endpoints cannot declare a streaming payload")
       }
     }
-    return
   }
   let hasStream = false
   const statuses = new Map<number, {
@@ -1463,9 +1464,17 @@ function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, meth
   }>()
 
   for (const schema of schemas) {
+    // The server may decline the upgrade (RFC 9110 §7.8) and answer with one of the other successes.
+    if (HttpApiSchema.isUpgrade(schema)) continue
     const inner = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
     const status = HttpApiSchema.getStatusSuccessSchema(schema)
+    if (hasUpgrade && status === 101) {
+      throw new Error("Cannot combine an upgrade with another success response for status: 101")
+    }
     if (HttpApiSchema.isStreamSchema(inner)) {
+      if (hasUpgrade) {
+        throw new Error("Cannot combine an upgrade with a streaming success response")
+      }
       validateStreamSuccess(inner, method)
       if (hasStream) {
         throw new Error("Multiple streaming success responses are not supported")