effect 4.0.0-beta.98 → 4.0.0-rc.108

package/src/unstable/http/HttpClient.ts

@@ -34,6 +34,7 @@ import type { EqualsWith, ExcludeTag, ExtractTag, NoExcessProperties, NoInfer, T
 import type * as RateLimiter from "../persistence/RateLimiter.ts"
 import * as Cookies from "./Cookies.ts"
 import * as Headers from "./Headers.ts"
+import * as HttpBody from "./HttpBody.ts"
 import * as Error from "./HttpClientError.ts"
 import * as HttpClientRequest from "./HttpClientRequest.ts"
 import * as HttpClientResponse from "./HttpClientResponse.ts"
@@ -257,7 +258,7 @@ export const options: (url: string | URL, options?: HttpClientRequest.Options.No
  *
  * The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.
  *
- * @category mapping & sequencing
+ * @category mapping
  * @since 4.0.0
  */
 export const transform: {
@@ -268,7 +269,7 @@ export const transform: {
    *
    * The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   <E, R, E1, R1>(
@@ -284,7 +285,7 @@ export const transform: {
    *
    * The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   <E, R, E1, R1>(
@@ -309,14 +310,14 @@ export const transform: {
 /**
  * Transforms a client by applying an effectful transformation to each response effect.
  *
- * @category mapping & sequencing
+ * @category mapping
  * @since 4.0.0
  */
 export const transformResponse: {
   /**
    * Transforms a client by applying an effectful transformation to each response effect.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   <E, R, E1, R1>(
@@ -327,7 +328,7 @@ export const transformResponse: {
   /**
    * Transforms a client by applying an effectful transformation to each response effect.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   <E, R, E1, R1>(
@@ -569,14 +570,14 @@ export const catchTags: {
 /**
  * Filters the result of a response, or runs an alternative effect if the predicate fails.
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const filterOrElse: {
   /**
    * Filters the result of a response, or runs an alternative effect if the predicate fails.
    *
-   * @category filters
+   * @category filtering
    * @since 4.0.0
    */
   <B extends HttpClientResponse.HttpClientResponse, E2, R2>(
@@ -593,7 +594,7 @@ export const filterOrElse: {
   /**
    * Filters the result of a response, or runs an alternative effect if the predicate fails.
    *
-   * @category filters
+   * @category filtering
    * @since 4.0.0
    */
   <E2, R2>(
@@ -605,7 +606,7 @@ export const filterOrElse: {
   /**
    * Filters the result of a response, or runs an alternative effect if the predicate fails.
    *
-   * @category filters
+   * @category filtering
    * @since 4.0.0
    */
   <E, R, B extends HttpClientResponse.HttpClientResponse, E2, R2>(
@@ -623,7 +624,7 @@ export const filterOrElse: {
   /**
    * Filters the result of a response, or runs an alternative effect if the predicate fails.
    *
-   * @category filters
+   * @category filtering
    * @since 4.0.0
    */
   <E, R, E2, R2>(
@@ -638,14 +639,14 @@ export const filterOrElse: {
 /**
  * Filters successful responses, or fails with the error produced by `orFailWith` when the predicate does not match.
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const filterOrFail: {
   /**
    * Filters successful responses, or fails with the error produced by `orFailWith` when the predicate does not match.
    *
-   * @category filters
+   * @category filtering
    * @since 4.0.0
    */
   <B extends HttpClientResponse.HttpClientResponse, E2>(
@@ -655,7 +656,7 @@ export const filterOrFail: {
   /**
    * Filters successful responses, or fails with the error produced by `orFailWith` when the predicate does not match.
    *
-   * @category filters
+   * @category filtering
    * @since 4.0.0
    */
   <E2>(
@@ -665,7 +666,7 @@ export const filterOrFail: {
   /**
    * Filters successful responses, or fails with the error produced by `orFailWith` when the predicate does not match.
    *
-   * @category filters
+   * @category filtering
    * @since 4.0.0
    */
   <E, R, B extends HttpClientResponse.HttpClientResponse, E2>(
@@ -676,7 +677,7 @@ export const filterOrFail: {
   /**
    * Filters successful responses, or fails with the error produced by `orFailWith` when the predicate does not match.
    *
-   * @category filters
+   * @category filtering
    * @since 4.0.0
    */
   <E, R, E2>(
@@ -689,21 +690,21 @@ export const filterOrFail: {
 /**
  * Filters responses by HTTP status code.
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const filterStatus: {
   /**
    * Filters responses by HTTP status code.
    *
-   * @category filters
+   * @category filtering
    * @since 4.0.0
    */
   (f: (status: number) => boolean): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | Error.HttpClientError, R>
   /**
    * Filters responses by HTTP status code.
    *
-   * @category filters
+   * @category filtering
    * @since 4.0.0
    */
   <E, R>(self: HttpClient.With<E, R>, f: (status: number) => boolean): HttpClient.With<E | Error.HttpClientError, R>
@@ -716,7 +717,7 @@ export const filterStatus: {
 /**
  * Filters responses that return a 2xx status code.
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const filterStatusOk: <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | Error.HttpClientError, R> =
@@ -839,8 +840,10 @@ export const make = (
               span.attribute("url.query", query)
             }
             const redactedHeaderNames = fiber.getRef(Headers.CurrentRedactedNames)
+            const headerFilter = fiber.getRef(TracerHeaderFilter)
             const redactedHeaders = Headers.redact(request.headers, redactedHeaderNames)
             for (const name in redactedHeaders) {
+              if (!headerFilter(name, "request")) continue
               span.attribute(`http.request.header.${name}`, String(redactedHeaders[name]))
             }
             request = fiber.getRef(TracerPropagationEnabled)
@@ -854,6 +857,7 @@ export const make = (
                     span.attribute("http.response.status_code", response.status)
                     const redactedHeaders = Headers.redact(response.headers, redactedHeaderNames)
                     for (const name in redactedHeaders) {
+                      if (!headerFilter(name, "response")) continue
                       span.attribute(`http.response.header.${name}`, String(redactedHeaders[name]))
                     }
 
@@ -877,14 +881,14 @@ export const make = (
 /**
  * Appends a transformation of the request object before sending it.
  *
- * @category mapping & sequencing
+ * @category mapping
  * @since 4.0.0
  */
 export const mapRequest: {
   /**
    * Appends a transformation of the request object before sending it.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   (
@@ -893,7 +897,7 @@ export const mapRequest: {
   /**
    * Appends a transformation of the request object before sending it.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   <E, R>(
@@ -911,14 +915,14 @@ export const mapRequest: {
 /**
  * Appends an effectful transformation of the request object before sending it.
  *
- * @category mapping & sequencing
+ * @category mapping
  * @since 4.0.0
  */
 export const mapRequestEffect: {
   /**
    * Appends an effectful transformation of the request object before sending it.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   <E2, R2>(
@@ -927,7 +931,7 @@ export const mapRequestEffect: {
   /**
    * Appends an effectful transformation of the request object before sending it.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   <E, R, E2, R2>(
@@ -946,14 +950,14 @@ export const mapRequestEffect: {
 /**
  * Prepends a transformation of the request object before sending it.
  *
- * @category mapping & sequencing
+ * @category mapping
  * @since 4.0.0
  */
 export const mapRequestInput: {
   /**
    * Prepends a transformation of the request object before sending it.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   (
@@ -962,7 +966,7 @@ export const mapRequestInput: {
   /**
    * Prepends a transformation of the request object before sending it.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   <E, R>(
@@ -980,14 +984,14 @@ export const mapRequestInput: {
 /**
  * Prepends an effectful transformation of the request object before sending it.
  *
- * @category mapping & sequencing
+ * @category mapping
  * @since 4.0.0
  */
 export const mapRequestInputEffect: {
   /**
    * Prepends an effectful transformation of the request object before sending it.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   <E2, R2>(
@@ -996,7 +1000,7 @@ export const mapRequestInputEffect: {
   /**
    * Prepends an effectful transformation of the request object before sending it.
    *
-   * @category mapping & sequencing
+   * @category mapping
    * @since 4.0.0
    */
   <E, R, E2, R2>(
@@ -1263,7 +1267,8 @@ export declare namespace WithRateLimiter {
    *
    * **Details**
    *
-   * They define the backing limiter, initial limit window, keying strategy, algorithm, token cost, and whether response headers update future limits.
+   * They define the backing limiter, initial limit window, keying strategy,
+   * algorithm, token cost, retry count, and response header inspection.
    *
    * @category rate limiting
    * @since 4.0.0
@@ -1296,11 +1301,48 @@ export declare namespace WithRateLimiter {
      */
     readonly tokens?: number | ((request: HttpClientRequest.HttpClientRequest) => number) | undefined
     /**
-     * Disable automatic limits updates from response headers.
+     * The maximum number of automatic retries after an HTTP `429` response.
+     * Use a non-negative integer. Defaults to an unlimited number of retries.
+     * Set to `0` to disable automatic retries.
+     */
+    readonly times?: number | undefined
+    /**
+     * Overrides the response header names used for rate limit inspection.
+     * Header names are matched case-insensitively. An omitted field continues
+     * using the built-in names, while a configured field replaces them for
+     * that value. Header value formats are unchanged.
+     */
+    readonly responseHeaders?: {
+      /**
+       * Header containing the maximum number of requests in a window.
+       */
+      readonly limit?: string | undefined
+      /**
+       * Header containing the number of requests remaining in a window.
+       */
+      readonly remaining?: string | undefined
+      /**
+       * Header containing the rate limit reset time.
+       */
+      readonly reset?: string | undefined
+      /**
+       * Header containing the number of seconds until the rate limit resets.
+       */
+      readonly resetAfter?: string | undefined
+      /**
+       * Header containing the retry delay for an HTTP `429` response.
+       */
+      readonly retryAfter?: string | undefined
+    } | undefined
+    /**
+     * Disables automatic limit updates, `Retry-After` delays, and adaptive
+     * feedback from response headers. This does not disable automatic HTTP
+     * `429` retries. Set `times` to `0` to disable them.
      */
     readonly disableResponseInspection?: boolean | undefined
     /**
-     * Disable adaptive learning from `Retry-After` responses.
+     * Disables adaptive learning from `Retry-After` responses. Response
+     * inspection and direct `Retry-After` delays remain enabled.
      */
     readonly disableAdaptiveLearning?: boolean | undefined
   }
@@ -1315,6 +1357,12 @@ export declare namespace WithRateLimiter {
  * automatically retries HTTP `429` responses (or `HttpClientError` values
  * wrapping a `429` response) by forcing the retry back through the limiter.
  *
+ * **Gotchas**
+ *
+ * Automatic HTTP `429` retries are unlimited unless `times` is specified.
+ * Disabling response inspection does not disable retries; set `times` to `0`
+ * to return or fail with the first `429`.
+ *
  * @category rate limiting
  * @since 4.0.0
  */
@@ -1328,6 +1376,12 @@ export const withRateLimiter: {
    * automatically retries HTTP `429` responses (or `HttpClientError` values
    * wrapping a `429` response) by forcing the retry back through the limiter.
    *
+   * **Gotchas**
+   *
+   * Automatic HTTP `429` retries are unlimited unless `times` is specified.
+   * Disabling response inspection does not disable retries; set `times` to `0`
+   * to return or fail with the first `429`.
+   *
    * @category rate limiting
    * @since 4.0.0
    */
@@ -1343,6 +1397,12 @@ export const withRateLimiter: {
    * automatically retries HTTP `429` responses (or `HttpClientError` values
    * wrapping a `429` response) by forcing the retry back through the limiter.
    *
+   * **Gotchas**
+   *
+   * Automatic HTTP `429` retries are unlimited unless `times` is specified.
+   * Disabling response inspection does not disable retries; set `times` to `0`
+   * to return or fail with the first `429`.
+   *
    * @category rate limiting
    * @since 4.0.0
    */
@@ -1367,6 +1427,7 @@ export const withRateLimiter: {
     ? tokensOption
     : constant(tokensOption ?? 1)
   const adaptiveLearningEnabled = !options.disableAdaptiveLearning
+  const headerNames = resolveRateLimiterHeaderNames(options.responseHeaders)
 
   const getState = (key: string): RateLimiterState => {
     const current = states.get(key)
@@ -1381,13 +1442,13 @@ export const withRateLimiter: {
     ? undefined
     : (clock: Clock, key: string, headers: Headers.Headers, tokens: number) => {
       const current = getState(key)
-      const next = parseRateLimiterState(current, clock, headers, tokens)
+      const next = parseRateLimiterState(current, clock, headers, tokens, headerNames)
       if (next.limit !== current.limit || !Duration.equals(next.window, current.window)) {
         states.set(key, next)
       }
     }
 
-  return transform(self, function loop(effect, request): Effect.Effect<
+  return transform(self, function loop(effect, request, retries = 0): Effect.Effect<
     HttpClientResponse.HttpClientResponse,
     E | RateLimiter.RateLimiterError,
     R
@@ -1397,11 +1458,11 @@ export const withRateLimiter: {
     const key = resolveKey(request)
     const tokens = Math.max(resolveTokens(request), 1)
     const current = getState(key)
+    const canRetry = options.times === undefined || retries < options.times
     function retry(retryAfter: Duration.Duration | undefined) {
-      if (options.disableResponseInspection) return loop(effect, request)
       return retryAfter
-        ? Effect.flatMap(Effect.sleep(retryAfter), () => loop(effect, request))
-        : loop(effect, request)
+        ? Effect.flatMap(Effect.sleep(retryAfter), () => loop(effect, request, retries + 1))
+        : loop(effect, request, retries + 1)
     }
     const inspectResponse = (
       response: HttpClientResponse.HttpClientResponse,
@@ -1418,12 +1479,18 @@ export const withRateLimiter: {
          * automatically retries HTTP `429` responses (or `HttpClientError` values
          * wrapping a `429` response) by forcing the retry back through the limiter.
          *
+         * **Gotchas**
+         *
+         * Automatic HTTP `429` retries are unlimited unless `times` is specified.
+         * Disabling response inspection does not disable retries; set `times` to `0`
+         * to return or fail with the first `429`.
+         *
          * @category rate limiting
          * @since 4.0.0
          */
         Duration.Duration | undefined>(undefined);
       }
-      const retryAfter = parseRetryAfter(clock, getHeader(response.headers, "retry-after"))
+      const retryAfter = parseRetryAfter(clock, getHeader(response.headers, ...headerNames.retryAfter))
       if (retryAfter === undefined) {
         return Effect.succeed</**
          * Applies request rate limiting using the `RateLimiter` service.
@@ -1434,12 +1501,18 @@ export const withRateLimiter: {
          * automatically retries HTTP `429` responses (or `HttpClientError` values
          * wrapping a `429` response) by forcing the retry back through the limiter.
          *
+         * **Gotchas**
+         *
+         * Automatic HTTP `429` retries are unlimited unless `times` is specified.
+         * Disabling response inspection does not disable retries; set `times` to `0`
+         * to return or fail with the first `429`.
+         *
          * @category rate limiting
          * @since 4.0.0
          */
         Duration.Duration | undefined>(undefined);
       }
-      const delay = parseRateLimitWindow(clock, response.headers) ?? retryAfter
+      const delay = parseRateLimitWindow(clock, response.headers, headerNames) ?? retryAfter
       if (adaptive === undefined) {
         return Effect.succeed</**
          * Applies request rate limiting using the `RateLimiter` service.
@@ -1450,6 +1523,12 @@ export const withRateLimiter: {
          * automatically retries HTTP `429` responses (or `HttpClientError` values
          * wrapping a `429` response) by forcing the retry back through the limiter.
          *
+         * **Gotchas**
+         *
+         * Automatic HTTP `429` retries are unlimited unless `times` is specified.
+         * Disabling response inspection does not disable retries; set `times` to `0`
+         * to return or fail with the first `429`.
+         *
          * @category rate limiting
          * @since 4.0.0
          */
@@ -1485,7 +1564,7 @@ export const withRateLimiter: {
             const request = Effect.matchEffect(effect, {
               onSuccess(response) {
                 return Effect.flatMap(inspectResponse(response, adaptive), (retryAfter) => {
-                  if (response.status !== 429) return Effect.succeed(response)
+                  if (response.status !== 429 || !canRetry) return Effect.succeed(response)
                   return retry(retryAfter)
                 })
               },
@@ -1493,7 +1572,7 @@ export const withRateLimiter: {
                 if (isTooManyRequestsHttpClientError(error)) {
                   return Effect.flatMap(
                     inspectResponse(error.reason.response, adaptive),
-                    (retryAfter) => retry(retryAfter)
+                    (retryAfter) => canRetry ? retry(retryAfter) : Effect.fail(error)
                   )
                 }
                 return Effect.fail(error)
@@ -1527,6 +1606,34 @@ export const withRateLimiter: {
   });
 })
 
+interface RateLimiterHeaderNames {
+  readonly limit: ReadonlyArray<string>
+  readonly remaining: ReadonlyArray<string>
+  readonly reset: ReadonlyArray<string>
+  readonly resetAfter: ReadonlyArray<string>
+  readonly retryAfter: ReadonlyArray<string>
+}
+
+const resolveRateLimiterHeaderNames = (
+  responseHeaders: WithRateLimiter.Options["responseHeaders"]
+): RateLimiterHeaderNames => ({
+  limit: responseHeaders?.limit === undefined
+    ? ["ratelimit-limit", "x-ratelimit-limit"]
+    : [responseHeaders.limit.toLowerCase()],
+  remaining: responseHeaders?.remaining === undefined
+    ? ["ratelimit-remaining", "x-ratelimit-remaining"]
+    : [responseHeaders.remaining.toLowerCase()],
+  reset: responseHeaders?.reset === undefined
+    ? ["ratelimit-reset", "x-ratelimit-reset"]
+    : [responseHeaders.reset.toLowerCase()],
+  resetAfter: responseHeaders?.resetAfter === undefined
+    ? ["ratelimit-reset-after", "x-ratelimit-reset-after"]
+    : [responseHeaders.resetAfter.toLowerCase()],
+  retryAfter: responseHeaders?.retryAfter === undefined
+    ? ["retry-after"]
+    : [responseHeaders.retryAfter.toLowerCase()]
+})
+
 interface RateLimiterState {
   readonly limit: number
   readonly window: Duration.Duration
@@ -1537,10 +1644,11 @@ const parseRateLimiterState = (
   state: RateLimiterState,
   clock: Clock,
   headers: Headers.Headers,
-  tokens: number
+  tokens: number,
+  headerNames: RateLimiterHeaderNames
 ): RateLimiterState => {
-  const limit = parseRateLimitLimit(state, headers, tokens) ?? state.limit
-  const window = parseRateLimitWindow(clock, headers) ?? state.window
+  const limit = parseRateLimitLimit(state, headers, tokens, headerNames) ?? state.limit
+  const window = parseRateLimitWindow(clock, headers, headerNames) ?? state.window
   if (limit === state.limit && Duration.equals(window, state.window)) {
     return state
   }
@@ -1550,35 +1658,40 @@ const parseRateLimiterState = (
 const parseRateLimitLimit = (
   state: RateLimiterState,
   headers: Headers.Headers,
-  tokens: number
+  tokens: number,
+  headerNames: RateLimiterHeaderNames
 ): number | undefined => {
-  const raw = getHeader(headers, "ratelimit-limit", "x-ratelimit-limit")
+  const raw = getHeader(headers, ...headerNames.limit)
   const value = parseNumberHeader(raw)
   if (value !== undefined && value > 0) {
     return value
   }
-  const remaining = parseRateLimitRemaining(headers)
+  const remaining = parseRateLimitRemaining(headers, headerNames)
   if (remaining === undefined) {
     return undefined
   }
   return state.initial ? remaining + tokens : Math.max(remaining + tokens, state.limit)
 }
 
-const parseRateLimitRemaining = (headers: Headers.Headers): number | undefined => {
-  const raw = getHeader(headers, "ratelimit-remaining", "x-ratelimit-remaining")
+const parseRateLimitRemaining = (
+  headers: Headers.Headers,
+  headerNames: RateLimiterHeaderNames
+): number | undefined => {
+  const raw = getHeader(headers, ...headerNames.remaining)
   const value = parseNumberHeader(raw)
   return value !== undefined && value >= 0 ? value : undefined
 }
 
 const parseRateLimitWindow = (
   clock: Clock,
-  headers: Headers.Headers
+  headers: Headers.Headers,
+  headerNames: RateLimiterHeaderNames
 ): Duration.Duration | undefined => {
-  const resetAfter = parseResetAfter(getHeader(headers, "ratelimit-reset-after", "x-ratelimit-reset-after"))
+  const resetAfter = parseResetAfter(getHeader(headers, ...headerNames.resetAfter))
   if (resetAfter !== undefined) {
     return resetAfter
   }
-  return parseResetHeader(clock, getHeader(headers, "ratelimit-reset", "x-ratelimit-reset"))
+  return parseResetHeader(clock, getHeader(headers, ...headerNames.reset))
 }
 
 const parseRetryAfter = (
@@ -1654,14 +1767,14 @@ const getHeader = (headers: Headers.Headers, ...keys: Array<string>): string | u
 /**
  * Performs an additional effect after a successful request.
  *
- * @category mapping & sequencing
+ * @category sequencing
  * @since 4.0.0
  */
 export const tap: {
   /**
    * Performs an additional effect after a successful request.
    *
-   * @category mapping & sequencing
+   * @category sequencing
    * @since 4.0.0
    */
   <_, E2, R2>(
@@ -1670,7 +1783,7 @@ export const tap: {
   /**
    * Performs an additional effect after a successful request.
    *
-   * @category mapping & sequencing
+   * @category sequencing
    * @since 4.0.0
    */
   <E, R, _, E2, R2>(
@@ -1688,21 +1801,21 @@ export const tap: {
 /**
  * Performs an additional effect after an unsuccessful request.
  *
- * @category mapping & sequencing
+ * @category sequencing
  * @since 4.0.0
  */
 export const tapError: {
   /**
    * Performs an additional effect after an unsuccessful request.
    *
-   * @category mapping & sequencing
+   * @category sequencing
    * @since 4.0.0
    */
   <_, E, E2, R2>(f: (e: NoInfer<E>) => Effect.Effect<_, E2, R2>): <R>(self: HttpClient.With<E, R>) => HttpClient.With<E | E2, R | R2>
   /**
    * Performs an additional effect after an unsuccessful request.
    *
-   * @category mapping & sequencing
+   * @category sequencing
    * @since 4.0.0
    */
   <E, R, _, E2, R2>(
@@ -1720,21 +1833,21 @@ export const tapError: {
 /**
  * Performs an additional effect on the request before sending it.
  *
- * @category mapping & sequencing
+ * @category sequencing
  * @since 4.0.0
  */
 export const tapRequest: {
   /**
    * Performs an additional effect on the request before sending it.
    *
-   * @category mapping & sequencing
+   * @category sequencing
    * @since 4.0.0
    */
   <_, E2, R2>(f: (a: HttpClientRequest.HttpClientRequest) => Effect.Effect<_, E2, R2>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | E2, R | R2>
   /**
    * Performs an additional effect on the request before sending it.
    *
-   * @category mapping & sequencing
+   * @category sequencing
    * @since 4.0.0
    */
   <E, R, _, E2, R2>(
@@ -1864,17 +1977,29 @@ export const followRedirects: {
       ): Effect.Effect<HttpClientResponse.HttpClientResponse, E, R> =>
         Effect.flatMap(
           self.postprocess(Effect.succeed(request)),
-          (response) =>
-            response.status >= 300 && response.status < 400 && response.headers.location &&
-              redirects < (maxRedirects ?? 10)
-              ? loop(
-                HttpClientRequest.setUrl(
-                  request,
-                  new URL(response.headers.location, response.request.url)
-                ),
-                redirects + 1
-              )
-              : Effect.succeed(response)
+          (response) => {
+            if (
+              response.status < 300 || response.status >= 400 || !response.headers.location ||
+              redirects >= (maxRedirects ?? 10)
+            ) {
+              return Effect.succeed(response)
+            }
+            const url = new URL(response.headers.location, response.request.url)
+            let nextRequest = request
+            if (
+              ((response.status === 301 || response.status === 302) && request.method === "POST") ||
+              (response.status === 303 && request.method !== "GET" && request.method !== "HEAD")
+            ) {
+              nextRequest = HttpClientRequest.setMethod(nextRequest, "GET")
+              nextRequest = HttpClientRequest.setBody(nextRequest, HttpBody.empty)
+            }
+            if (url.origin !== new URL(response.request.url).origin) {
+              nextRequest = HttpClientRequest.removeHeader(nextRequest, "authorization")
+              nextRequest = HttpClientRequest.removeHeader(nextRequest, "proxy-authorization")
+              nextRequest = HttpClientRequest.removeHeader(nextRequest, "cookie")
+            }
+            return loop(HttpClientRequest.setUrl(nextRequest, url), redirects + 1)
+          }
         )
       return Effect.flatMap(request, (request) => loop(request, 0))
     },
@@ -1884,7 +2009,7 @@ export const followRedirects: {
 /**
  * Context reference for a predicate that disables client-side tracing for matching outgoing requests.
  *
- * @category references
+ * @category services
  * @since 4.0.0
  */
 export const TracerDisabledWhen = Context.Reference<
@@ -1893,10 +2018,22 @@ export const TracerDisabledWhen = Context.Reference<
   defaultValue: () => constFalse
 })
 
+/**
+ * Context reference for filtering request and response headers added to client spans.
+ *
+ * @category services
+ * @since 4.0.0
+ */
+export const TracerHeaderFilter = Context.Reference<
+  (headerName: string, phase: "request" | "response") => boolean
+>("effect/http/HttpClient/TracerHeaderFilter", {
+  defaultValue: () => constTrue
+})
+
 /**
  * Context reference that controls whether outgoing client spans are propagated to request headers.
  *
- * @category references
+ * @category services
  * @since 4.0.0
  */
 export const TracerPropagationEnabled = Context.Reference<boolean>("effect/HttpClient/TracerPropagationEnabled", {
@@ -1906,7 +2043,7 @@ export const TracerPropagationEnabled = Context.Reference<boolean>("effect/HttpC
 /**
  * Context reference for generating the span name used for outgoing client request spans.
  *
- * @category references
+ * @category services
  * @since 4.0.0
  */
 export const SpanNameGenerator = Context.Reference<