effect 4.0.7 → 4.1.1

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
   }
 
@@ -851,32 +836,37 @@ class ClientRequestImpl extends Inspectable.Class implements HttpServerRequest {
     if (this.bytesEffect) {
       return this.bytesEffect
     }
+    this.bytesEffect = Effect.withFiber((fiber) => {
+      const maxBodySize = fiber.getRef(HttpIncomingMessage.MaxBodySize)
+      return this.readBytes(maxBodySize === undefined ? undefined : Number(maxBodySize))
+    }).pipe(
+      Effect.cached,
+      Effect.runSync
+    )
+    return this.bytesEffect
+  }
+
+  private readBytes(maxBytes: number | undefined): Effect.Effect<Uint8Array, HttpServerError> {
     const body = this.source.body
-    let effect: Effect.Effect<Uint8Array, HttpServerError>
     switch (body._tag) {
       case "Empty": {
-        effect = Effect.succeed(new Uint8Array(0))
-        break
+        return Effect.succeed(new Uint8Array(0))
       }
       case "Uint8Array": {
-        effect = Effect.succeed(body.body)
-        break
+        return maxBytes !== undefined && body.body.byteLength > maxBytes
+          ? Effect.fail(bodyTooLargeError(this, new BodyTooLargeError(maxBytes)))
+          : Effect.succeed(body.body)
       }
       case "FormData": {
-        effect = bytesFromBodyInit(this, body.formData)
-        break
+        return bytesFromWeb(this, () => new Response(body.formData), maxBytes)
       }
       case "Stream": {
-        effect = Stream.mkUint8Array(this.stream)
-        break
+        return Stream.mkUint8Array(maxBytes === undefined ? this.stream : limitStream(this, this.stream, maxBytes))
       }
       case "Raw": {
-        effect = rawBodyBytes(this, body.body)
-        break
+        return rawBodyBytes(this, body.body, maxBytes)
       }
     }
-    this.bytesEffect = Effect.runSync(Effect.cached(effect))
-    return this.bytesEffect
   }
 
   get text(): Effect.Effect<string, HttpServerError> {
@@ -892,9 +882,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)
       }))
   }
@@ -977,23 +967,38 @@ const rawBodyStream = (request: HttpServerRequest, body: unknown): Stream.Stream
   return Stream.fail(requestParseError(request, "Unsupported body type"))
 }
 
-const rawBodyBytes = (request: HttpServerRequest, body: unknown): Effect.Effect<Uint8Array, HttpServerError> => {
+const rawBodyBytes = (
+  request: HttpServerRequest,
+  body: unknown,
+  maxBytes: number | undefined
+): Effect.Effect<Uint8Array, HttpServerError> => {
   if (body instanceof Request) {
-    return Effect.tryPromise({
-      try: () => body.arrayBuffer().then((buffer) => new Uint8Array(buffer)),
-      catch: (cause) => requestParseError(request, undefined, cause)
-    })
+    return bytesFromWeb(request, () => body, maxBytes)
   }
   if (isBodyInit(body)) {
-    return bytesFromBodyInit(request, body)
+    return bytesFromWeb(request, () => new Response(body), maxBytes)
   }
   return Effect.fail(requestParseError(request, "Unsupported body type"))
 }
 
-const bytesFromBodyInit = (request: HttpServerRequest, body: BodyInit): Effect.Effect<Uint8Array, HttpServerError> =>
+const bytesFromWeb = (
+  request: HttpServerRequest,
+  // Evaluated inside `try`, as wrapping an unreadable body in a `Response` throws.
+  evaluate: () => Request | Response,
+  maxBytes: number | undefined
+): Effect.Effect<Uint8Array, HttpServerError> =>
   Effect.tryPromise({
-    try: () => new Response(body).arrayBuffer().then((buffer) => new Uint8Array(buffer)),
-    catch: (cause) => requestParseError(request, undefined, cause)
+    try: async (signal) => {
+      const source = evaluate()
+      const buffer = maxBytes === undefined
+        ? await source.arrayBuffer()
+        : await readArrayBufferLimited(source, maxBytes, signal)
+      return new Uint8Array(buffer)
+    },
+    catch: (cause) =>
+      cause instanceof BodyTooLargeError
+        ? bodyTooLargeError(request, cause)
+        : requestParseError(request, undefined, cause)
   })
 
 const streamFromReadable = (
@@ -1020,6 +1025,24 @@ const requestParseError = (
     })
   })
 
+const limitStream = (
+  request: HttpServerRequest,
+  stream: Stream.Stream<Uint8Array, HttpServerError>,
+  maxBytes: number
+): Stream.Stream<Uint8Array, HttpServerError> =>
+  Stream.suspend(() => {
+    let bytes = 0
+    return Stream.mapEffect(stream, (chunk) => {
+      bytes += chunk.byteLength
+      return bytes > maxBytes
+        ? Effect.fail(bodyTooLargeError(request, new BodyTooLargeError(maxBytes)))
+        : Effect.succeed(chunk)
+    })
+  })
+
+const bodyTooLargeError = (request: HttpServerRequest, cause: BodyTooLargeError) =>
+  new HttpServerError({ reason: new RequestParseError({ request, reason: "BodyTooLarge", cause }) })
+
 const formDataToParts = (formData: FormData): Array<Multipart.Part> => {
   const parts: Array<Multipart.Part> = []
   for (const [key, value] of formData.entries()) {
@@ -1117,7 +1140,7 @@ class BodyTooLargeError extends Error {
 }
 
 const readArrayBufferLimited = async (
-  source: Request,
+  source: Request | Response,
   maxBytes: number,
   signal: AbortSignal
 ): Promise<ArrayBuffer> => {

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/mimeTypes.ts

@@ -1,5 +1,6 @@
 /**
- * Standard MIME type data copied from mime 4.1.0.
+ * Standard MIME type data copied from mime 4.1.0, plus `text/x-python` and
+ * `text/x-shellscript` for `py` and `sh` scripts.
  *
  * MIT License
  *
@@ -370,6 +371,8 @@ const types = {
   "text/vcard": ["vcard"],
   "text/vtt": ["vtt"],
   "text/wgsl": ["wgsl"],
+  "text/x-python": ["py"],
+  "text/x-shellscript": ["sh"],
   "text/xml": ["*xml"],
   "text/yaml": ["yaml", "yml"],
   "video/3gpp": ["3gp", "3gpp"],

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)))