effect 4.0.7 → 4.1.1

package/src/http/HttpClient.ts

@@ -1335,6 +1335,208 @@ export const retryTransient: {
   }
 )
 
+/**
+ * Fails requests that do not receive a response within the given duration.
+ *
+ * **When to use**
+ *
+ * Use to configure a timeout once on the client, for example when providing
+ * the `HttpClient` service, while keeping the standard `HttpClientError` error
+ * model.
+ *
+ * **Details**
+ *
+ * A timed out request is interrupted and fails with an `HttpClientError` whose
+ * reason is a `TransportError` with a `Cause.TimeoutError` cause.
+ * `retryTransient` treats it as transient. Interrupting a request aborts the
+ * underlying transport, unless the request is attached to a scope with
+ * `withScope`, in which case it stays open until the scope closes.
+ *
+ * The timer starts after request preprocessing and covers everything the
+ * wrapped client does to produce a response. For a plain client this ends when
+ * the response headers arrive, but response middleware applied before
+ * `timeout`, such as `tap` or `retryTransient`, runs inside the budget,
+ * including any body reads it performs. Composition order therefore decides
+ * how it interacts with retries: applying `timeout` before `retryTransient`
+ * gives each attempt its own budget, while applying it after bounds the whole
+ * retry loop.
+ *
+ * **Gotchas**
+ *
+ * Body reads outside the timed client are not covered, including those made
+ * by response middleware applied after `timeout` and by consumers of the
+ * `HttpClient` service. Apply a separate timeout to body reads such as
+ * `response.json` or `response.stream` when needed.
+ *
+ * **Example** (Timing out each attempt)
+ *
+ * ```ts
+ * import { Effect, Layer } from "effect"
+ * import { FetchHttpClient, HttpClient } from "effect/http"
+ *
+ * const TimedHttpClient = Layer.effect(
+ *   HttpClient.HttpClient,
+ *   Effect.map(
+ *     HttpClient.HttpClient,
+ *     HttpClient.timeout("5 seconds")
+ *   )
+ * ).pipe(Layer.provide(FetchHttpClient.layer))
+ *
+ * const program = Effect.gen(function*() {
+ *   const client = (yield* HttpClient.HttpClient).pipe(
+ *     HttpClient.retryTransient({ times: 3 })
+ *   )
+ *   return yield* client.get("https://example.com")
+ * }).pipe(Effect.provide(TimedHttpClient))
+ * ```
+ *
+ * @stability unstable
+ * @category error handling
+ * @since 4.1.0
+ */
+export const timeout: {
+  /**
+   * Fails requests that do not receive a response within the given duration.
+   *
+   * **When to use**
+   *
+   * Use to configure a timeout once on the client, for example when providing
+   * the `HttpClient` service, while keeping the standard `HttpClientError` error
+   * model.
+   *
+   * **Details**
+   *
+   * A timed out request is interrupted and fails with an `HttpClientError` whose
+   * reason is a `TransportError` with a `Cause.TimeoutError` cause.
+   * `retryTransient` treats it as transient. Interrupting a request aborts the
+   * underlying transport, unless the request is attached to a scope with
+   * `withScope`, in which case it stays open until the scope closes.
+   *
+   * The timer starts after request preprocessing and covers everything the
+   * wrapped client does to produce a response. For a plain client this ends when
+   * the response headers arrive, but response middleware applied before
+   * `timeout`, such as `tap` or `retryTransient`, runs inside the budget,
+   * including any body reads it performs. Composition order therefore decides
+   * how it interacts with retries: applying `timeout` before `retryTransient`
+   * gives each attempt its own budget, while applying it after bounds the whole
+   * retry loop.
+   *
+   * **Gotchas**
+   *
+   * Body reads outside the timed client are not covered, including those made
+   * by response middleware applied after `timeout` and by consumers of the
+   * `HttpClient` service. Apply a separate timeout to body reads such as
+   * `response.json` or `response.stream` when needed.
+   *
+   * **Example** (Timing out each attempt)
+   *
+   * ```ts
+   * import { Effect, Layer } from "effect"
+   * import { FetchHttpClient, HttpClient } from "effect/http"
+   *
+   * const TimedHttpClient = Layer.effect(
+   *   HttpClient.HttpClient,
+   *   Effect.map(
+   *     HttpClient.HttpClient,
+   *     HttpClient.timeout("5 seconds")
+   *   )
+   * ).pipe(Layer.provide(FetchHttpClient.layer))
+   *
+   * const program = Effect.gen(function*() {
+   *   const client = (yield* HttpClient.HttpClient).pipe(
+   *     HttpClient.retryTransient({ times: 3 })
+   *   )
+   *   return yield* client.get("https://example.com")
+   * }).pipe(Effect.provide(TimedHttpClient))
+   * ```
+   *
+   * @stability unstable
+   * @category error handling
+   * @since 4.1.0
+   */
+  (duration: Duration.Input): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | Error.HttpClientError, R>
+  /**
+   * Fails requests that do not receive a response within the given duration.
+   *
+   * **When to use**
+   *
+   * Use to configure a timeout once on the client, for example when providing
+   * the `HttpClient` service, while keeping the standard `HttpClientError` error
+   * model.
+   *
+   * **Details**
+   *
+   * A timed out request is interrupted and fails with an `HttpClientError` whose
+   * reason is a `TransportError` with a `Cause.TimeoutError` cause.
+   * `retryTransient` treats it as transient. Interrupting a request aborts the
+   * underlying transport, unless the request is attached to a scope with
+   * `withScope`, in which case it stays open until the scope closes.
+   *
+   * The timer starts after request preprocessing and covers everything the
+   * wrapped client does to produce a response. For a plain client this ends when
+   * the response headers arrive, but response middleware applied before
+   * `timeout`, such as `tap` or `retryTransient`, runs inside the budget,
+   * including any body reads it performs. Composition order therefore decides
+   * how it interacts with retries: applying `timeout` before `retryTransient`
+   * gives each attempt its own budget, while applying it after bounds the whole
+   * retry loop.
+   *
+   * **Gotchas**
+   *
+   * Body reads outside the timed client are not covered, including those made
+   * by response middleware applied after `timeout` and by consumers of the
+   * `HttpClient` service. Apply a separate timeout to body reads such as
+   * `response.json` or `response.stream` when needed.
+   *
+   * **Example** (Timing out each attempt)
+   *
+   * ```ts
+   * import { Effect, Layer } from "effect"
+   * import { FetchHttpClient, HttpClient } from "effect/http"
+   *
+   * const TimedHttpClient = Layer.effect(
+   *   HttpClient.HttpClient,
+   *   Effect.map(
+   *     HttpClient.HttpClient,
+   *     HttpClient.timeout("5 seconds")
+   *   )
+   * ).pipe(Layer.provide(FetchHttpClient.layer))
+   *
+   * const program = Effect.gen(function*() {
+   *   const client = (yield* HttpClient.HttpClient).pipe(
+   *     HttpClient.retryTransient({ times: 3 })
+   *   )
+   *   return yield* client.get("https://example.com")
+   * }).pipe(Effect.provide(TimedHttpClient))
+   * ```
+   *
+   * @stability unstable
+   * @category error handling
+   * @since 4.1.0
+   */
+  <E, R>(self: HttpClient.With<E, R>, duration: Duration.Input): HttpClient.With<E | Error.HttpClientError, R>
+} = dual(
+  2,
+  <E, R>(self: HttpClient.With<E, R>, duration: Duration.Input): HttpClient.With<E | Error.HttpClientError, R> => {
+    const decoded = Duration.fromInputUnsafe(duration)
+    const description = `timed out after ${Duration.format(decoded)}`
+    return transform(self, (effect, request) =>
+      Effect.timeoutOrElse(effect, {
+        duration: decoded,
+        orElse: () =>
+          Effect.fail(
+            new Error.HttpClientError({
+              reason: new Error.TransportError({
+                request,
+                cause: new Cause.TimeoutError(`Operation ${description}`),
+                description
+              })
+            })
+          )
+      }))
+  }
+)
+
 /**
  * Namespace containing configuration types for `withRateLimiter`.
  *
@@ -1680,7 +1882,7 @@ export const withRateLimiter: {
  * Namespace containing configuration types for `withCircuitBreaker`.
  *
  * @stability experimental
- * @since 4.0.6
+ * @since 4.0.7
  */
 export declare namespace WithCircuitBreaker {
   /**
@@ -1688,7 +1890,7 @@ export declare namespace WithCircuitBreaker {
    *
    * @stability experimental
    * @category circuit breaking
-   * @since 4.0.6
+   * @since 4.0.7
    */
   export interface Options<E, R2 = never> {
     /**
@@ -1703,13 +1905,10 @@ export declare namespace WithCircuitBreaker {
     readonly key?: string | ((request: HttpClientRequest.HttpClientRequest) => string) | undefined
     /**
      * Classifies the `Exit` of each request that the breaker admitted.
+     * `context.probe` is `true` when the request is the HalfOpen probe.
      * Defaults to `circuitBreakerClassifier`.
      */
-    readonly classify?:
-      | ((
-        exit: Exit.Exit<HttpClientResponse.HttpClientResponse, E>
-      ) => CircuitBreaker.Outcome | Effect.Effect<CircuitBreaker.Outcome, never, R2>)
-      | undefined
+    readonly classify?: CircuitBreaker.Classifier<HttpClientResponse.HttpClientResponse, E, R2> | undefined
   }
 }
 
@@ -1830,7 +2029,7 @@ export declare namespace WithCircuitBreaker {
  *
  * @stability experimental
  * @category circuit breaking
- * @since 4.0.6
+ * @since 4.0.7
  */
 export const withCircuitBreaker: {
   /**
@@ -1950,7 +2149,7 @@ export const withCircuitBreaker: {
    *
    * @stability experimental
    * @category circuit breaking
-   * @since 4.0.6
+   * @since 4.0.7
    */
   <E, R2 = never>(options: WithCircuitBreaker.Options<E, R2>): <R>(
     self: HttpClient.With<E, R>
@@ -2072,7 +2271,7 @@ export const withCircuitBreaker: {
    *
    * @stability experimental
    * @category circuit breaking
-   * @since 4.0.6
+   * @since 4.0.7
    */
   <E, R, R2 = never>(self: HttpClient.With<E, R>, options: WithCircuitBreaker.Options<E, R2>): HttpClient.With<E | CircuitBreaker.CircuitBreakerError, R | R2>
 } = dual(2, <E, R, R2>(
@@ -2120,7 +2319,7 @@ const requestOrigin = (request: HttpClientRequest.HttpClientRequest): string =>
  *
  * @stability experimental
  * @category circuit breaking
- * @since 4.0.6
+ * @since 4.0.7
  */
 export const circuitBreakerClassifier = <E>(
   exit: Exit.Exit<HttpClientResponse.HttpClientResponse, E>
@@ -2456,12 +2655,20 @@ export const tapRequest: {
 )
 
 /**
- * Adds a `Ref` of cookies to the client for handling cookies across requests.
+ * Adds a `Ref` of stored cookies to the client for handling cookies across
+ * requests.
  *
  * **When to use**
  *
  * Use to add shared cookie storage to a client so response cookies are retained
- * and sent by later requests.
+ * and sent by later requests to a matching host, path, and scheme.
+ *
+ * **Details**
+ *
+ * Response cookies are merged into the ref with `Cookies.mergeIntoArray` for
+ * the response URL. Before each request, `Cookies.toRequestCookieHeader` selects
+ * the cookies for the request URL and sets them as the `cookie` header. Expiry
+ * uses the current `Clock`.
  *
  * @stability unstable
  * @category cookies
@@ -2469,52 +2676,66 @@ export const tapRequest: {
  */
 export const withCookiesRef: {
   /**
-   * Adds a `Ref` of cookies to the client for handling cookies across requests.
+   * Adds a `Ref` of stored cookies to the client for handling cookies across
+   * requests.
    *
    * **When to use**
    *
    * Use to add shared cookie storage to a client so response cookies are retained
-   * and sent by later requests.
+   * and sent by later requests to a matching host, path, and scheme.
+   *
+   * **Details**
+   *
+   * Response cookies are merged into the ref with `Cookies.mergeIntoArray` for
+   * the response URL. Before each request, `Cookies.toRequestCookieHeader` selects
+   * the cookies for the request URL and sets them as the `cookie` header. Expiry
+   * uses the current `Clock`.
    *
    * @stability unstable
    * @category cookies
    * @since 4.0.0
    */
-  (ref: Ref.Ref<Cookies.Cookies>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>
+  (ref: Ref.Ref<ReadonlyArray<Cookies.Cookie>>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>
   /**
-   * Adds a `Ref` of cookies to the client for handling cookies across requests.
+   * Adds a `Ref` of stored cookies to the client for handling cookies across
+   * requests.
    *
    * **When to use**
    *
    * Use to add shared cookie storage to a client so response cookies are retained
-   * and sent by later requests.
+   * and sent by later requests to a matching host, path, and scheme.
+   *
+   * **Details**
+   *
+   * Response cookies are merged into the ref with `Cookies.mergeIntoArray` for
+   * the response URL. Before each request, `Cookies.toRequestCookieHeader` selects
+   * the cookies for the request URL and sets them as the `cookie` header. Expiry
+   * uses the current `Clock`.
    *
    * @stability unstable
    * @category cookies
    * @since 4.0.0
    */
-  <E, R>(self: HttpClient.With<E, R>, ref: Ref.Ref<Cookies.Cookies>): HttpClient.With<E, R>
+  <E, R>(self: HttpClient.With<E, R>, ref: Ref.Ref<ReadonlyArray<Cookies.Cookie>>): HttpClient.With<E, R>
 } = dual(
   2,
   <E, R>(
     self: HttpClient.With<E, R>,
-    ref: Ref.Ref<Cookies.Cookies>
+    ref: Ref.Ref<ReadonlyArray<Cookies.Cookie>>
   ): HttpClient.With<E, R> =>
     makeWith(
       (request: Effect.Effect<HttpClientRequest.HttpClientRequest, E, R>) =>
-        Effect.tap(
-          self.postprocess(request),
-          (response) => Ref.update(ref, (cookies) => Cookies.merge(cookies, response.cookies))
-        ),
+        Effect.tap(self.postprocess(request), (response) => {
+          const now = Fiber.getCurrent()!.getRef(Clock).currentTimeMillisUnsafe()
+          return Ref.update(ref, Cookies.mergeIntoArray(response.url, response.cookies, now))
+        }),
       (request) =>
         Effect.flatMap(self.preprocess(request), (request) =>
-          Effect.map(
-            Ref.get(ref),
-            (cookies) =>
-              Cookies.isEmpty(cookies)
-                ? request
-                : HttpClientRequest.setHeader(request, "cookie", Cookies.toCookieHeader(cookies))
-          ))
+          Effect.map(Ref.get(ref), (cookies) => {
+            const now = Fiber.getCurrent()!.getRef(Clock).currentTimeMillisUnsafe()
+            const header = Cookies.toRequestCookieHeader(cookies, request.url, now)
+            return header === undefined ? request : HttpClientRequest.setHeader(request, "cookie", header)
+          }))
     )
 )
 
@@ -2980,7 +3201,38 @@ class InterruptibleResponse implements HttpClientResponse.HttpClientResponse, Pi
   }
 }
 
-const isTransientError = (error: unknown) => Cause.isTimeoutError(error) || isTransientHttpError(error)
+/**
+ * Returns `true` for an error that `retryTransient` retries by default: a
+ * timeout, a transport error, or a status code error with a transient response.
+ *
+ * **When to use**
+ *
+ * Use to classify failures the same way `retryTransient` does, for example in a
+ * custom retry policy or a circuit breaker.
+ *
+ * **Example** (Classifying client errors)
+ *
+ * ```ts import.meta.vitest
+ * import { Cause } from "effect"
+ * import { HttpClient, HttpClientError, HttpClientRequest } from "effect/http"
+ *
+ * const request = HttpClientRequest.get("https://example.com")
+ * const transportError = new HttpClientError.HttpClientError({
+ *   reason: new HttpClientError.TransportError({ request })
+ * })
+ *
+ * HttpClient.isTransientError(transportError) // => true
+ * HttpClient.isTransientError(new Cause.TimeoutError()) // => true
+ * HttpClient.isTransientError(new Error("boom")) // => false
+ * ```
+ *
+ * @see {@link isTransientResponse} for the response statuses it accepts
+ * @see {@link retryTransient} for the retry policy that uses it
+ * @stability unstable
+ * @category predicates
+ * @since 4.1.0
+ */
+export const isTransientError = (error: unknown): boolean => Cause.isTimeoutError(error) || isTransientHttpError(error)
 
 const isTransientHttpError = (error: unknown) =>
   Error.isHttpClientError(error) &&
@@ -3014,7 +3266,21 @@ const isTooManyRequestsHttpClientError = (
 ): error is Error.HttpClientError & { readonly reason: Error.StatusCodeError } =>
   Error.isHttpClientError(error) && error.reason._tag === "StatusCodeError" && error.reason.response.status === 429
 
-const isTransientResponse = (response: HttpClientResponse.HttpClientResponse) =>
+/**
+ * Returns `true` for a response whose status `retryTransient` retries by
+ * default: 408, 429, 500, 502, 503 or 504.
+ *
+ * **When to use**
+ *
+ * Use to retry the same responses as `retryTransient` in a custom retry policy.
+ *
+ * @see {@link isTransientError} for the matching error predicate
+ * @see {@link retryTransient} for the retry policy that uses it
+ * @stability unstable
+ * @category predicates
+ * @since 4.1.0
+ */
+export const isTransientResponse = (response: HttpClientResponse.HttpClientResponse): boolean =>
   response.status === 408 ||
   response.status === 429 ||
   response.status === 500 ||

package/src/http/HttpClientRequest.ts

@@ -56,7 +56,11 @@ export const isHttpClientRequest = (u: unknown): u is HttpClientRequest => hasPr
  */
 export interface HttpClientRequest extends Inspectable.Inspectable, Pipeable {
   readonly [TypeId]: typeof TypeId
-  readonly method: HttpMethod
+  /**
+   * The request method, which may be a method outside the known `HttpMethod`
+   * literals when the request was converted from a Web or server request.
+   */
+  readonly method: string
   readonly url: string
   readonly urlParams: UrlParams.UrlParams
   readonly hash: Option.Option<string>
@@ -126,7 +130,7 @@ const Proto = {
  * @since 4.0.0
  */
 export function makeWith(
-  method: HttpMethod,
+  method: string,
   url: string,
   urlParams: UrlParams.Input,
   hash: Option.Option<string>,
@@ -1171,7 +1175,7 @@ export interface CompressionOptions {
  * `Content-Length`. The compressed body does not retain the original lazy text.
  * Stream bodies are compressed lazily and have their content length removed.
  * They still require a client runtime that supports streaming request bodies
- * (Fetch requires `duplex: "half"`, which Safari and Firefox do not support).
+ * (stable Safari and Firefox do not; see `FetchHttpClient.StreamBodyFallback`).
  *
  * Returns the original request unchanged for empty, FormData, and raw bodies,
  * bodies with a known length below `options.minSize`, or requests with any
@@ -1203,7 +1207,7 @@ export const compressBody: {
    * `Content-Length`. The compressed body does not retain the original lazy text.
    * Stream bodies are compressed lazily and have their content length removed.
    * They still require a client runtime that supports streaming request bodies
-   * (Fetch requires `duplex: "half"`, which Safari and Firefox do not support).
+   * (stable Safari and Firefox do not; see `FetchHttpClient.StreamBodyFallback`).
    *
    * Returns the original request unchanged for empty, FormData, and raw bodies,
    * bodies with a known length below `options.minSize`, or requests with any
@@ -1235,7 +1239,7 @@ export const compressBody: {
    * `Content-Length`. The compressed body does not retain the original lazy text.
    * Stream bodies are compressed lazily and have their content length removed.
    * They still require a client runtime that supports streaming request bodies
-   * (Fetch requires `duplex: "half"`, which Safari and Firefox do not support).
+   * (stable Safari and Firefox do not; see `FetchHttpClient.StreamBodyFallback`).
    *
    * Returns the original request unchanged for empty, FormData, and raw bodies,
    * bodies with a known length below `options.minSize`, or requests with any
@@ -1694,16 +1698,15 @@ export function toUrl(self: HttpClientRequest): Option.Option<URL> {
  * @since 4.0.0
  */
 export const fromWeb = (request: globalThis.Request): HttpClientRequest => {
-  const method = request.method.toUpperCase() as HttpMethod
-  return modify(empty, {
-    method,
+  const method = request.method.toUpperCase()
+  return modify(makeWith(method, "", UrlParams.empty, Option.none(), Headers.empty, HttpBody.empty), {
     url: new URL(request.url),
     headers: request.headers,
     body: fromWebBody(request, method)
   })
 }
 
-const fromWebBody = (request: globalThis.Request, method: HttpMethod): HttpBody.HttpBody => {
+const fromWebBody = (request: globalThis.Request, method: string): HttpBody.HttpBody => {
   if (!hasBody(method) || request.body === null) {
     return HttpBody.empty
   }

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.