effect 4.0.5 → 4.0.7

package/src/http/HttpClientError.ts

@@ -92,6 +92,15 @@ const formatMessage = (reason: string, description: string | undefined, info: st
 const formatMethodAndUrl = (request: HttpClientRequest.HttpClientRequest) =>
   `${request.method} ${UrlParams.redactUrl(request.url)}`
 
+// Serialized reasons carry the same request and response information as the
+// message, so headers, URL parameters and bodies stay out of logs. The full
+// objects remain available through the `request` and `response` properties.
+const reasonToJSON = (reason: HttpClientErrorReason, json: unknown) => ({
+  ...(json as object),
+  request: { _id: "HttpClientRequest", method: reason.request.method, url: UrlParams.redactUrl(reason.request.url) },
+  ...("response" in reason ? { response: { _id: "HttpClientResponse", status: reason.response.status } } : undefined)
+})
+
 /**
  * Error describing transport-level failures that occur while sending an HTTP request.
  *
@@ -123,6 +132,10 @@ export class TransportError extends Data.TaggedError("TransportError")<{
   override get message() {
     return formatMessage(formatReason(this._tag), this.description, this.methodAndUrl)
   }
+
+  override toJSON(): unknown {
+    return reasonToJSON(this, super.toJSON())
+  }
 }
 
 /**
@@ -156,6 +169,10 @@ export class EncodeError extends Data.TaggedError("EncodeError")<{
   override get message() {
     return formatMessage(formatReason(this._tag), this.description, this.methodAndUrl)
   }
+
+  override toJSON(): unknown {
+    return reasonToJSON(this, super.toJSON())
+  }
 }
 
 /**
@@ -189,6 +206,10 @@ export class InvalidUrlError extends Data.TaggedError("InvalidUrlError")<{
   override get message() {
     return formatMessage(formatReason(this._tag), this.description, this.methodAndUrl)
   }
+
+  override toJSON(): unknown {
+    return reasonToJSON(this, super.toJSON())
+  }
 }
 
 /**
@@ -224,10 +245,15 @@ export class StatusCodeError extends Data.TaggedError("StatusCodeError")<{
     const info = `${this.response.status} ${this.methodAndUrl}`
     return formatMessage(formatReason(this._tag), this.description, info)
   }
+
+  override toJSON(): unknown {
+    return reasonToJSON(this, super.toJSON())
+  }
 }
 
 /**
- * Response error for failures while decoding an HTTP response body.
+ * Response error for failures while decoding an HTTP response, including a
+ * response with an undeclared status.
  *
  * @stability unstable
  * @category errors
@@ -259,6 +285,10 @@ export class DecodeError extends Data.TaggedError("DecodeError")<{
     const info = `${this.response.status} ${this.methodAndUrl}`
     return formatMessage(formatReason(this._tag), this.description, info)
   }
+
+  override toJSON(): unknown {
+    return reasonToJSON(this, super.toJSON())
+  }
 }
 
 /**
@@ -294,6 +324,10 @@ export class EmptyBodyError extends Data.TaggedError("EmptyBodyError")<{
     const info = `${this.response.status} ${this.methodAndUrl}`
     return formatMessage(formatReason(this._tag), this.description, info)
   }
+
+  override toJSON(): unknown {
+    return reasonToJSON(this, super.toJSON())
+  }
 }
 
 /**

package/src/http/HttpClientRequest.ts

@@ -13,6 +13,7 @@
 import type * as ByteSize from "../ByteSize.ts"
 import * as Context from "../Context.ts"
 import * as Effect from "../Effect.ts"
+import * as Base64 from "../encoding/Base64.ts"
 import type * as FileSystem from "../FileSystem.ts"
 import { dual } from "../Function.ts"
 import * as Inspectable from "../Inspectable.ts"
@@ -483,7 +484,8 @@ export const removeHeader: {
 )
 
 /**
- * Sets the `Authorization` header using HTTP Basic authentication credentials.
+ * Sets the `Authorization` header using HTTP Basic authentication credentials,
+ * encoded as UTF-8 before base64 encoding.
  *
  * @stability unstable
  * @category combinators
@@ -491,7 +493,8 @@ export const removeHeader: {
  */
 export const basicAuth: {
   /**
-   * Sets the `Authorization` header using HTTP Basic authentication credentials.
+   * Sets the `Authorization` header using HTTP Basic authentication credentials,
+   * encoded as UTF-8 before base64 encoding.
    *
    * @stability unstable
    * @category combinators
@@ -499,7 +502,8 @@ export const basicAuth: {
    */
   (username: string | Redacted.Redacted, password: string | Redacted.Redacted): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * Sets the `Authorization` header using HTTP Basic authentication credentials.
+   * Sets the `Authorization` header using HTTP Basic authentication credentials,
+   * encoded as UTF-8 before base64 encoding.
    *
    * @stability unstable
    * @category combinators
@@ -517,7 +521,11 @@ export const basicAuth: {
     username: string | Redacted.Redacted,
     password: string | Redacted.Redacted
   ): HttpClientRequest =>
-    setHeader(self, "Authorization", `Basic ${btoa(`${stringOrRedacted(username)}:${stringOrRedacted(password)}`)}`)
+    setHeader(
+      self,
+      "Authorization",
+      `Basic ${Base64.encode(`${stringOrRedacted(username)}:${stringOrRedacted(password)}`)}`
+    )
 )
 
 /**
@@ -585,6 +593,136 @@ export const accept: {
  */
 export const acceptJson: (self: HttpClientRequest) => HttpClientRequest = accept("application/json")
 
+/**
+ * Asks the server to switch the connection to another protocol by setting the
+ * `Connection: Upgrade` and `Upgrade` headers.
+ *
+ * **When to use**
+ *
+ * Use to switch an HTTP/1.1 connection to a raw byte stream, such as Docker's
+ * `Upgrade: tcp` for container attach. For WebSocket, use `Socket.makeWebSocket`.
+ *
+ * **Details**
+ *
+ * The request is otherwise ordinary, so client transforms such as base URLs,
+ * authentication, and tracing apply to it. When the server answers `101
+ * Switching Protocols`, `HttpClientResponse.upgrade` hands over the
+ * connection as a `Socket`. Any other response is read as usual.
+ *
+ * **Example** (Attaching to a Docker container)
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ * import { HttpClient, HttpClientRequest } from "effect/http"
+ *
+ * const program = Effect.gen(function*() {
+ *   const client = yield* HttpClient.HttpClient
+ *   const response = yield* client.execute(
+ *     HttpClientRequest.post("/containers/abc/attach?stream=1&stdout=1").pipe(
+ *       HttpClientRequest.upgrade("tcp")
+ *     )
+ *   )
+ *   const socket = yield* response.upgrade
+ *   const reader = yield* socket.reader
+ *   return yield* reader.pull
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.0.6
+ */
+export const upgrade: {
+  /**
+   * Asks the server to switch the connection to another protocol by setting the
+   * `Connection: Upgrade` and `Upgrade` headers.
+   *
+   * **When to use**
+   *
+   * Use to switch an HTTP/1.1 connection to a raw byte stream, such as Docker's
+   * `Upgrade: tcp` for container attach. For WebSocket, use `Socket.makeWebSocket`.
+   *
+   * **Details**
+   *
+   * The request is otherwise ordinary, so client transforms such as base URLs,
+   * authentication, and tracing apply to it. When the server answers `101
+   * Switching Protocols`, `HttpClientResponse.upgrade` hands over the
+   * connection as a `Socket`. Any other response is read as usual.
+   *
+   * **Example** (Attaching to a Docker container)
+   *
+   * ```ts
+   * import { Effect } from "effect"
+   * import { HttpClient, HttpClientRequest } from "effect/http"
+   *
+   * const program = Effect.gen(function*() {
+   *   const client = yield* HttpClient.HttpClient
+   *   const response = yield* client.execute(
+   *     HttpClientRequest.post("/containers/abc/attach?stream=1&stdout=1").pipe(
+   *       HttpClientRequest.upgrade("tcp")
+   *     )
+   *   )
+   *   const socket = yield* response.upgrade
+   *   const reader = yield* socket.reader
+   *   return yield* reader.pull
+   * })
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.0.6
+   */
+  (protocol: string): (self: HttpClientRequest) => HttpClientRequest
+  /**
+   * Asks the server to switch the connection to another protocol by setting the
+   * `Connection: Upgrade` and `Upgrade` headers.
+   *
+   * **When to use**
+   *
+   * Use to switch an HTTP/1.1 connection to a raw byte stream, such as Docker's
+   * `Upgrade: tcp` for container attach. For WebSocket, use `Socket.makeWebSocket`.
+   *
+   * **Details**
+   *
+   * The request is otherwise ordinary, so client transforms such as base URLs,
+   * authentication, and tracing apply to it. When the server answers `101
+   * Switching Protocols`, `HttpClientResponse.upgrade` hands over the
+   * connection as a `Socket`. Any other response is read as usual.
+   *
+   * **Example** (Attaching to a Docker container)
+   *
+   * ```ts
+   * import { Effect } from "effect"
+   * import { HttpClient, HttpClientRequest } from "effect/http"
+   *
+   * const program = Effect.gen(function*() {
+   *   const client = yield* HttpClient.HttpClient
+   *   const response = yield* client.execute(
+   *     HttpClientRequest.post("/containers/abc/attach?stream=1&stdout=1").pipe(
+   *       HttpClientRequest.upgrade("tcp")
+   *     )
+   *   )
+   *   const socket = yield* response.upgrade
+   *   const reader = yield* socket.reader
+   *   return yield* reader.pull
+   * })
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.0.6
+   */
+  (self: HttpClientRequest, protocol: string): HttpClientRequest
+} = dual(2, (self: HttpClientRequest, protocol: string): HttpClientRequest =>
+  makeWith(
+    self.method,
+    self.url,
+    self.urlParams,
+    self.hash,
+    Headers.set(Headers.set(self.headers, "connection", "Upgrade"), "upgrade", protocol),
+    self.body
+  ))
+
 /**
  * Sets the request URL. When given a `URL`, its search parameters and hash are extracted into the request's structured fields.
  *
@@ -1135,7 +1273,15 @@ export const compressBody: {
     }
     return Effect.map(
       compression.compressBody(self.body, algorithm, options),
-      (body) => body === self.body ? self : setHeader(setBody(self, body), "content-encoding", algorithm)
+      (body) =>
+        body === self.body ? self : makeWith(
+          self.method,
+          self.url,
+          self.urlParams,
+          self.hash,
+          Headers.set(bodyInternal.updateContentLength(self.headers, body), "content-encoding", algorithm),
+          body
+        )
     )
   }
 )

package/src/http/HttpClientResponse.ts

@@ -17,6 +17,7 @@ import * as Option from "../Option.ts"
 import { type Pipeable, pipeArguments } from "../Pipeable.ts"
 import * as Schema from "../Schema.ts"
 import type { ParseOptions } from "../SchemaAST.ts"
+import type * as Socket from "../socket/Socket.ts"
 import * as Stream from "../Stream.ts"
 import type { Unify } from "../Unify.ts"
 import * as Cookies from "./Cookies.ts"
@@ -24,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 { getWebSource, WebSourceSymbol } from "./internal/webResponse.ts"
 import * as UrlParams from "./UrlParams.ts"
 
 /**
@@ -83,6 +85,23 @@ export interface HttpClientResponse extends HttpIncomingMessage.HttpIncomingMess
   readonly status: number
   readonly cookies: Cookies.Cookies
   readonly formData: Effect.Effect<FormData, Error.HttpClientError>
+  /**
+   * Hands over the connection of a `101 Switching Protocols` response as a
+   * `Socket`.
+   *
+   * **Details**
+   *
+   * Ask for an upgrade with `HttpClientRequest.upgrade`. Bytes the server
+   * sent after the response head come first on the reader. Releasing the
+   * writer's scope half-closes the connection, and releasing the reader's
+   * scope closes it. Closing the request's scope (see `HttpClient.withScope`)
+   * also closes it.
+   *
+   * Fails with a `StatusCodeError` for any other status, so a refusal can be
+   * read from the response body as usual. Backends that cannot hand over a
+   * connection, such as fetch, never produce a `101` and fail the same way.
+   */
+  readonly upgrade: Effect.Effect<Socket.Socket, Error.HttpClientError>
 }
 
 /**
@@ -95,6 +114,42 @@ export interface HttpClientResponse extends HttpIncomingMessage.HttpIncomingMess
 export const fromWeb = (request: HttpClientRequest.HttpClientRequest, source: Response): HttpClientResponse =>
   new WebHttpClientResponse(request, source)
 
+/**
+ * Returns the original Web `Response` of a fetch-backed `HttpClientResponse`.
+ *
+ * **When to use**
+ *
+ * Use to hand a response body to a Web API without copying it, such as
+ * writing a fetched file to Cloudflare R2. The original body keeps runtime
+ * capabilities, such as workerd's known length, that a stream converted from
+ * `stream` does not.
+ *
+ * **Details**
+ *
+ * Returns `Some` for responses created with `fromWeb`, which includes every
+ * response from `FetchHttpClient`, and `None` for other backends.
+ *
+ * Calling `toWeb` hands the body over: the response is no longer aborted when
+ * the `HttpClientResponse` is garbage collected, so read or cancel the body
+ * through the returned `Response`.
+ *
+ * **Gotchas**
+ *
+ * The body can be read once. After converting, read it from the returned
+ * `Response`, not from the `HttpClientResponse`.
+ *
+ * After the hand-off, Effect aborts the request only when the scope of
+ * `HttpClient.withScope` closes. When the request streams its body, finishing
+ * or cancelling the returned body does not stop the upload; execute the
+ * request with `HttpClient.withScope` and close the scope to stop it.
+ *
+ * @stability unstable
+ * @category converting
+ * @since 4.0.0
+ */
+export const toWeb = (self: HttpClientResponse): Option.Option<globalThis.Response> =>
+  Option.fromUndefinedOr(getWebSource(self))
+
 /**
  * Creates a decoder for a response's status, headers, and JSON body using the supplied schema.
  *
@@ -350,6 +405,10 @@ class WebHttpClientResponse extends Inspectable.Class implements HttpClientRespo
     return Option.none()
   }
 
+  [WebSourceSymbol](): globalThis.Response {
+    return this.source
+  }
+
   get stream(): Stream.Stream<Uint8Array, Error.HttpClientError> {
     return this.source.body
       ? Stream.fromReadableStream({
@@ -443,6 +502,18 @@ class WebHttpClientResponse extends Inspectable.Class implements HttpClientRespo
     return this.arrayBufferBody
   }
 
+  get upgrade(): Effect.Effect<Socket.Socket, Error.HttpClientError> {
+    return Effect.fail(
+      new Error.HttpClientError({
+        reason: new Error.StatusCodeError({
+          request: this.request,
+          response: this,
+          description: "fetch cannot hand over the connection of an HTTP upgrade"
+        })
+      })
+    )
+  }
+
   pipe() {
     return pipeArguments(this, arguments)
   }

package/src/http/HttpEffect.ts

@@ -28,7 +28,7 @@ import { HttpServerRequest } from "./HttpServerRequest.ts"
 import * as Request from "./HttpServerRequest.ts"
 import type { HttpServerResponse } from "./HttpServerResponse.ts"
 import * as Response from "./HttpServerResponse.ts"
-import * as preResponseHandler from "./internal/preResponseHandler.ts"
+import * as requestState from "./internal/requestState.ts"
 
 /**
  * Runs an HTTP server effect, sends the produced response with the supplied handler, and converts failures into HTTP responses.
@@ -55,7 +55,7 @@ export const toHandled = <E, R, EH, RH>(
     return Effect.flatMapEager(causeResponse(cause), ([response, cause]) => {
       const fiber = Fiber.getCurrent()!
       reportCauseUnsafe(fiber, cause)
-      const handler = preResponseHandler.requestPreResponseHandlers.get(request.source)
+      const handler = frame.preResponseHandler
       const cont = cause.reasons.length === 0 ? Effect.succeed(response) : Effect.failCause(cause)
       if (handler === undefined) {
         ;(request as any)[handledSymbol] = true
@@ -78,10 +78,11 @@ export const toHandled = <E, R, EH, RH>(
   // Writes the response, applying any registered pre-response handler first.
   // Returns an `Exit` when the write completes synchronously.
   const sendResponse = (
-    request: HttpServerRequest,
+    frame: RequestFrame,
     response: HttpServerResponse
   ): Effect.Effect<HttpServerResponse, EH | HttpServerError, RH> => {
-    const handler = preResponseHandler.requestPreResponseHandlers.get(request.source)
+    const request = frame.request
+    const handler = frame.preResponseHandler
     if (handler === undefined) {
       ;(request as any)[handledSymbol] = true
       return Effect.mapEager(
@@ -105,7 +106,7 @@ export const toHandled = <E, R, EH, RH>(
   > => {
     const request = frame.request
     const responded = Effect.matchCauseEffect(self, {
-      onSuccess: (response) => sendResponse(request, response),
+      onSuccess: (response) => sendResponse(frame, response),
       onFailure: (cause) => handleCause(frame, cause)
     })
     return middleware === undefined ?
@@ -152,18 +153,19 @@ export const toHandled = <E, R, EH, RH>(
       return Scope.closeUnsafe(frame.scope, frame.cause === undefined ? exit : Exit.failCause(frame.cause))
     }, true)
 
-  class RequestFrame {
+  class RequestFrame extends requestState.RequestState {
     readonly scope: Scope.Closeable
     readonly prev: Context.Context<never>
     readonly request: HttpServerRequest
     cause: Cause.Cause<E | EH | HttpServerError> | undefined
     constructor(scope: Scope.Closeable, prev: Context.Context<never>, request: HttpServerRequest) {
+      super()
       this.scope = scope
       this.prev = prev
       this.request = request
     }
     [contA](response: HttpServerResponse, fiber: Fiber.Fiber<unknown, unknown>) {
-      const sent = sendResponse(this.request, response)
+      const sent = sendResponse(this, response)
       // Most response writes complete synchronously.
       if (effectIsExit(sent) && sent._tag === "Success") {
         fiber.setContext(this.prev)
@@ -182,7 +184,7 @@ export const toHandled = <E, R, EH, RH>(
     fiberEnterUninterruptibleUnsafe(fiber)
     const scope = Scope.makeUnsafe()
     const frame = new RequestFrame(scope, fiber.context, Context.getUnsafe(fiber.context, HttpServerRequest))
-    fiber.setContext(Context.add(frame.prev, Scope.Scope, scope))
+    fiber.setContext(Context.add(Context.add(frame.prev, Scope.Scope, scope), requestState.CurrentRequestState, frame))
     // The native tracer has no backend, so its spans are unobservable.
     const currentTracer = fiber.cache.tracer
     if (
@@ -262,22 +264,20 @@ export type PreResponseHandler = (
  * @since 4.0.0
  */
 export const appendPreResponseHandler = (handler: PreResponseHandler): Effect.Effect<void, never, HttpServerRequest> =>
-  HttpServerRequest.use((request) => {
-    appendPreResponseHandlerUnsafe(request, handler)
-    return Effect.void
-  })
+  withPreResponseHandler(Effect.void, handler)
 
 /**
- * Registers a pre-response handler for the supplied HTTP server request.
+ * Registers a pre-response handler for the HTTP server request that owns the
+ * supplied fiber context. Does nothing outside a server request.
  *
  * @stability unstable
  * @category unsafe
  * @since 4.0.0
  */
 export const appendPreResponseHandlerUnsafe: (
-  request: HttpServerRequest,
+  context: Context.Context<never>,
   handler: PreResponseHandler
-) => void = preResponseHandler.appendPreResponseHandlerUnsafe
+) => void = requestState.appendPreResponseHandlerUnsafe
 
 /**
  * Runs an effect after registering a pre-response handler for the current HTTP server request.
@@ -304,25 +304,13 @@ export const withPreResponseHandler: {
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, handler: PreResponseHandler): Effect.Effect<A, E, R | HttpServerRequest>
 } = dual<
-  /**
-   * Runs an effect after registering a pre-response handler for the current HTTP server request.
-   *
-   * @stability unstable
-   * @category handlers
-   * @since 4.0.0
-   */
-  (handler: PreResponseHandler) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | HttpServerRequest>,
-  /**
-   * Runs an effect after registering a pre-response handler for the current HTTP server request.
-   *
-   * @stability unstable
-   * @category handlers
-   * @since 4.0.0
-   */
+  (
+    handler: PreResponseHandler
+  ) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | HttpServerRequest>,
   <A, E, R>(self: Effect.Effect<A, E, R>, handler: PreResponseHandler) => Effect.Effect<A, E, R | HttpServerRequest>
 >(2, (self, handler) =>
-  HttpServerRequest.use((request) => {
-    appendPreResponseHandlerUnsafe(request, handler)
+  Effect.withFiber((fiber) => {
+    appendPreResponseHandlerUnsafe(fiber.context, handler)
     return self
   }))
 
@@ -398,6 +386,9 @@ export const toWebHandler: <E>(
  *
  * **Details**
  *
+ * Every call to `dispose` returns the same promise, which resolves once the
+ * layer resources have been released.
+ *
  * The layer is built immediately, so the cost is paid when the handler is
  * created rather than on the first request. A layer that performs asynchronous
  * work while building may still be in progress when the first request arrives,
@@ -435,7 +426,8 @@ export const toWebHandlerLayerWith = <
     ) => Promise<globalThis.Response>
 } => {
   const scope = Scope.makeUnsafe()
-  const dispose = () => Effect.runPromise(Scope.close(scope, Exit.void))
+  let disposing: Promise<void> | undefined
+  const dispose = () => disposing ??= Effect.runPromise(Scope.close(scope, Exit.void))
 
   let handlerCache:
     | ((request: Request, context?: Context.Context<ReqR> | undefined) => Promise<globalThis.Response>)

package/src/http/HttpIncomingMessage.ts

@@ -145,37 +145,17 @@ export const MaxBodySize = Context.Reference<ByteSize.ByteSize | undefined>(
 )
 
 /**
- * Builds an inspectable object for an incoming message, redacting headers and including a synchronously readable JSON or text body when available.
+ * Builds an inspectable object for an incoming message and redacts headers.
+ * The body is left unread.
  *
  * @stability unstable
  * @category converting
  * @since 4.0.0
  */
 export const inspect = <E>(self: HttpIncomingMessage<E>, that: object): object => {
-  const contentType = self.headers["content-type"] ?? ""
-  let body: unknown
-  if (contentType.includes("application/json")) {
-    try {
-      body = Effect.runSync(self.json)
-      // oxlint-disable-next-line @typescript-eslint/no-unused-vars
-    } catch (_) {
-      //
-    }
-  } else if (contentType.includes("text/") || contentType.includes("urlencoded")) {
-    try {
-      body = Effect.runSync(self.text)
-      // oxlint-disable-next-line @typescript-eslint/no-unused-vars
-    } catch (_) {
-      //
-    }
-  }
-  const obj: any = {
+  return {
     ...that,
     headers: redact(self.headers),
     remoteAddress: self.remoteAddress
   }
-  if (body !== undefined) {
-    obj.body = body
-  }
-  return obj
 }