effect 4.0.0-beta.104 → 4.0.0-beta.106

package/src/unstable/cluster/EntityProxy.ts

@@ -14,7 +14,7 @@ import * as HttpApiEndpoint from "../httpapi/HttpApiEndpoint.ts"
 import * as HttpApiGroup from "../httpapi/HttpApiGroup.ts"
 import * as Rpc from "../rpc/Rpc.ts"
 import * as RpcGroup from "../rpc/RpcGroup.ts"
-import { AlreadyProcessingMessage, MailboxFull, PersistenceError } from "./ClusterError.ts"
+import { AlreadyProcessingMessage, EntityNotAssignedToRunner, MailboxFull, PersistenceError } from "./ClusterError.ts"
 import type * as Entity from "./Entity.ts"
 import type { EntityId } from "./EntityId.ts"
 
@@ -24,6 +24,11 @@ const clientErrors = [
   PersistenceError
 ] as const
 
+const requestErrors = [
+  ...clientErrors,
+  EntityNotAssignedToRunner
+] as const
+
 /**
  * Derives an `RpcGroup` from an `Entity`.
  *
@@ -75,7 +80,7 @@ export const toRpcGroup = <Type extends string, Rpcs extends Rpc.Any>(
     }
     const rpc = Rpc.make(`${entity.type}.${parentRpc._tag}`, {
       payload: payloadSchema,
-      error: Schema.Union([parentRpc.errorSchema, ...clientErrors]),
+      error: Schema.Union([parentRpc.errorSchema, ...requestErrors]),
       success: parentRpc.successSchema
     }).annotateMerge(parentRpc.annotations)
     const rpcDiscard = Rpc.make(`${entity.type}.${parentRpc._tag}Discard`, {
@@ -115,11 +120,12 @@ export type ConvertRpcs<Rpcs extends Rpc.Any, Prefix extends string> = Rpcs exte
       }>,
       _Success,
       Schema.Codec<
-        _Error["Type"] | MailboxFull | AlreadyProcessingMessage | PersistenceError,
+        _Error["Type"] | MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner,
         | _Error["Encoded"]
         | typeof MailboxFull["Encoded"]
         | typeof AlreadyProcessingMessage["Encoded"]
-        | typeof PersistenceError["Encoded"],
+        | typeof PersistenceError["Encoded"]
+        | typeof EntityNotAssignedToRunner["Encoded"],
         _Error["DecodingServices"],
         _Error["EncodingServices"]
       >
@@ -193,7 +199,7 @@ export const toHttpApiGroup = <const Name extends string, Type extends string, R
       params: entityIdPath,
       payload: parentRpc.payloadSchema,
       success: parentRpc.successSchema,
-      error: [parentRpc.errorSchema, ...clientErrors]
+      error: [parentRpc.errorSchema, ...requestErrors]
     }).annotateMerge(parentRpc.annotations)
     const endpointDiscard = HttpApiEndpoint.post(
       `${parentRpc._tag}Discard`,
@@ -250,6 +256,7 @@ export type ConvertHttpApi<Rpcs extends Rpc.Any> = Rpcs extends Rpc.Rpc<
       | typeof MailboxFull
       | typeof AlreadyProcessingMessage
       | typeof PersistenceError
+      | typeof EntityNotAssignedToRunner
     >
     | HttpApiEndpoint.HttpApiEndpoint<
       `${_Tag}Discard`,

package/src/unstable/cluster/Reply.ts

@@ -242,10 +242,10 @@ export class Chunk<R extends Rpc.Any> extends Data.TaggedClass("Chunk")<{
       [success],
       ([success]) => (input, ast, options) => {
         if (!isReply(input) || input._tag !== "Chunk") {
-          return Effect.fail(new SchemaIssue.InvalidType(ast))
+          return Effect.fail(new SchemaIssue.InvalidType(ast, input, options))
         }
         return Effect.mapBothEager(SchemaParser.decodeEffect(Schema.NonEmptyArray(success))(input.values, options), {
-          onFailure: (issue) => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["values"], issue)]),
+          onFailure: (issue) => SchemaIssue.makeCompositeAtKey(ast, "values", issue, input, options),
           onSuccess: (values) => new Chunk({ ...input, values } as any)
         })
       },
@@ -351,10 +351,10 @@ export class WithExit<R extends Rpc.Any> extends Data.TaggedClass("WithExit")<{
       [exitSchema],
       ([exit]) => (input, ast, options) => {
         if (!isReply(input) || input._tag !== "WithExit") {
-          return Effect.fail(new SchemaIssue.InvalidType(ast))
+          return Effect.fail(new SchemaIssue.InvalidType(ast, input, options))
         }
         return Effect.mapBothEager(SchemaParser.decodeEffect(exit)(input.exit, options), {
-          onFailure: (issue) => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["exit"], issue)]),
+          onFailure: (issue) => SchemaIssue.makeCompositeAtKey(ast, "exit", issue, input, options),
           onSuccess: (exit) => new WithExit({ ...input, exit: exit as any })
         })
       },

package/src/unstable/cluster/Sharding.ts

@@ -124,7 +124,7 @@ export class Sharding extends Context.Service<Sharding, {
       entityId: string
     ) => RpcClient.RpcClient.From<
       Rpcs,
-      MailboxFull | AlreadyProcessingMessage | PersistenceError
+      MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner
     >
   >
 
@@ -178,7 +178,7 @@ export class Sharding extends Context.Service<Sharding, {
     discard: boolean
   ) => Effect.Effect<
     void,
-    MailboxFull | AlreadyProcessingMessage | PersistenceError
+    MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner
   >
 
   /**
@@ -967,18 +967,40 @@ const make = Effect.gen(function*() {
     retries?: number
   ): Effect.Effect<
     void,
-    MailboxFull | AlreadyProcessingMessage | PersistenceError
+    MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner
   > {
     const isPersisted = Context.get(
       message._tag === "OutgoingRequest" ? message.annotations : message.rpc.annotations,
       Persisted
     )
+    const shouldFail = !discard &&
+      (message._tag === "OutgoingRequest" || message.envelope._tag === "AckChunk")
+    const abandon = (error: EntityNotAssignedToRunner) => {
+      if (!isPersisted) {
+        return shouldFail
+          ? Effect.fail(error)
+          : Effect.logDebug("Abandoning outgoing message during shutdown", message.envelope.address)
+      }
+      const persist = message._tag === "OutgoingRequest"
+        ? storage.saveRequest(message)
+        : storage.saveEnvelope(message)
+      return Effect.catchTag(persist, "MalformedMessage", Effect.die).pipe(
+        Effect.andThen(
+          shouldFail
+            ? Effect.fail(error)
+            : Effect.logWarning("Persisting outgoing message abandoned during shutdown", message.envelope.address)
+        )
+      )
+    }
     return Effect.catchFilter(
       Effect.suspend(() => {
         const address = message.envelope.address
         if (isPersisted && !storageEnabled) {
           return Effect.die("Sharding.sendOutgoing: Persisted messages require MessageStorage")
         }
+        if (shouldFail && MutableRef.get(isShutdown)) {
+          return Effect.fail(new EntityNotAssignedToRunner({ address }))
+        }
         const maybeRunner = MutableHashMap.get(shardAssignments, address.shardId)
         const runnerIsLocal = Option.isSome(maybeRunner) && isLocalRunner(maybeRunner.value)
         if (isPersisted) {
@@ -1003,17 +1025,7 @@ const make = Effect.gen(function*() {
           const cannotRecover = MutableRef.get(isShutdown) ||
             (targetManager !== undefined && targetManager.status !== "alive")
           if (cannotRecover) {
-            if (!isPersisted) {
-              return Effect.logDebug("Abandoning outgoing message during shutdown", message.envelope.address)
-            }
-            const persist = message._tag === "OutgoingRequest"
-              ? storage.saveRequest(message)
-              : storage.saveEnvelope(message)
-            return Effect.catchTag(persist, "MalformedMessage", Effect.die).pipe(
-              Effect.andThen(
-                Effect.logWarning("Persisting outgoing message abandoned during shutdown", message.envelope.address)
-              )
-            )
+            return abandon(error)
           }
         }
         if (retries === 0) {
@@ -1183,7 +1195,7 @@ const make = Effect.gen(function*() {
     Entity<any, any>,
     (entityId: string) => RpcClient.RpcClient<
       any,
-      MailboxFull | AlreadyProcessingMessage
+      MailboxFull | AlreadyProcessingMessage | EntityNotAssignedToRunner
     >,
     never
   > = yield* ResourceMap.make(
@@ -1196,7 +1208,7 @@ const make = Effect.gen(function*() {
         flatten: true,
         onFromClient(options): Effect.Effect<
           void,
-          MailboxFull | AlreadyProcessingMessage | PersistenceError
+          MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner
         > {
           const address = Context.getUnsafe(options.context, ClientAddressTag)
           switch (options.message._tag) {
@@ -1337,7 +1349,7 @@ const make = Effect.gen(function*() {
   const makeClient = <Type extends string, Rpcs extends Rpc.Any>(entity: Entity<Type, Rpcs>): Effect.Effect<
     (
       entityId: string
-    ) => RpcClient.RpcClient.From<Rpcs, MailboxFull | AlreadyProcessingMessage>
+    ) => RpcClient.RpcClient.From<Rpcs, MailboxFull | AlreadyProcessingMessage | EntityNotAssignedToRunner>
   > => clients.get(entity) as any
 
   const clientRespondDiscard = (_reply: Reply.Reply<any>) => Effect.void

package/src/unstable/encoding/Msgpack.ts

@@ -387,25 +387,29 @@ export const transformation: SchemaTransformation.Transformation<
   unknown,
   Uint8Array<ArrayBuffer>
 > = SchemaTransformation.transformOrFail({
-  decode(e, _options) {
+  decode(e, options) {
     try {
       return Effect.succeed(Msgpackr.decode(e))
     } catch {
       return Effect.fail(
-        new SchemaIssue.InvalidValue({
-          message: "Expected valid MessagePack bytes"
-        })
+        new SchemaIssue.InvalidValue(
+          { expected: "valid MessagePack bytes" },
+          e,
+          options
+        )
       )
     }
   },
-  encode(t, _options) {
+  encode(t, options) {
     try {
       return Effect.succeed(Msgpackr.encode(t) as Uint8Array<ArrayBuffer>)
     } catch {
       return Effect.fail(
-        new SchemaIssue.InvalidValue({
-          message: "Expected a MessagePack-serializable value"
-        })
+        new SchemaIssue.InvalidValue(
+          { expected: "a MessagePack-serializable value" },
+          t,
+          options
+        )
       )
     }
   }

package/src/unstable/eventlog/EventLogEncryption.ts

@@ -19,14 +19,15 @@ import type { Identity } from "./EventLog.ts"
 import { makeGetIdentityRootSecretMaterial } from "./internal/identityRootSecretDerivation.ts"
 
 /**
- * Schema for an encrypted journal entry paired with the id of the original
- * entry.
+ * Schema for an encrypted journal entry paired with its initialization vector
+ * and the id of the original entry.
  *
  * @category models
  * @since 4.0.0
  */
 export const EncryptedEntry = Schema.Struct({
   entryId: EntryId,
+  iv: Transferable.Uint8Array,
   encryptedEntry: Transferable.Uint8Array
 })
 
@@ -76,10 +77,12 @@ export class EventLogEncryption extends Context.Service<EventLogEncryption, {
   readonly encrypt: (
     identity: Identity["Service"],
     entries: ReadonlyArray<Entry>
-  ) => Effect.Effect<{
-    readonly iv: Uint8Array<ArrayBuffer>
-    readonly encryptedEntries: ReadonlyArray<Uint8Array<ArrayBuffer>>
-  }>
+  ) => Effect.Effect<
+    ReadonlyArray<{
+      readonly iv: Uint8Array<ArrayBuffer>
+      readonly encryptedEntry: Uint8Array<ArrayBuffer>
+    }>
+  >
   readonly decrypt: (
     identity: Identity["Service"],
     entries: ReadonlyArray<EncryptedRemoteEntry>
@@ -104,22 +107,18 @@ export const makeEncryptionSubtle = (crypto: Crypto): Effect.Effect<EventLogEncr
       encrypt: Effect.fnUntraced(function*(identity, entries) {
         const data = yield* Effect.orDie(Entry.encodeArray(entries))
         const key = (yield* getIdentityRootSecretMaterial(identity)).encryptionKey
-        const iv = crypto.getRandomValues(new Uint8Array(12))
-        const encryptedEntries = yield* Effect.promise(() =>
+        return yield* Effect.promise(() =>
           Promise.all(
-            data.map((entry) =>
-              crypto.subtle.encrypt(
+            data.map((entry) => {
+              const iv = crypto.getRandomValues(new Uint8Array(12))
+              return crypto.subtle.encrypt(
                 { name: "AES-GCM", iv: toBufferSource(iv), tagLength: 128 },
                 key,
                 toBufferSource(entry)
-              )
-            )
+              ).then((encryptedEntry) => ({ iv, encryptedEntry: new Uint8Array(encryptedEntry) }))
+            })
           )
         )
-        return {
-          iv,
-          encryptedEntries: encryptedEntries.map((entry) => new Uint8Array(entry))
-        }
       }),
       decrypt: Effect.fnUntraced(function*(identity, entries) {
         const key = (yield* getIdentityRootSecretMaterial(identity)).encryptionKey

package/src/unstable/eventlog/EventLogMessage.ts

@@ -261,8 +261,8 @@ export class WriteChunkedRpc extends Rpc.make("EventLog.WriteChunked", {
  *
  * **Details**
  *
- * It includes the client public key, target store id, AES-GCM initialization
- * vector, and encrypted entries.
+ * It includes the client public key, target store id, and encrypted entries
+ * with their AES-GCM initialization vectors.
  *
  * @category protocols
  * @since 4.0.0
@@ -270,7 +270,6 @@ export class WriteChunkedRpc extends Rpc.make("EventLog.WriteChunked", {
 export class WriteEntries extends Schema.Class<WriteEntries>("effect/eventlog/EventLogRemote/WriteEntries")({
   publicKey: Schema.String,
   storeId: StoreId,
-  iv: Transferable.Uint8Array,
   encryptedEntries: Schema.Array(EncryptedEntry)
 }) {
   static FromMsgpack = Msgpack.schema(WriteEntries)

package/src/unstable/eventlog/EventLogRemote.ts

@@ -307,14 +307,14 @@ export const makeEncrypted = Effect.gen(function*(): Effect.fn.Return<
   return yield* makeWith({
     encodeWrite: (options) =>
       encryption.encrypt(options.identity, options.entries).pipe(
-        Effect.flatMap((msg) =>
+        Effect.flatMap((encryptedEntries) =>
           new WriteEntries({
             publicKey: options.identity.publicKey,
             storeId: options.storeId,
-            iv: msg.iv,
-            encryptedEntries: msg.encryptedEntries.map((entry, i) => ({
+            encryptedEntries: encryptedEntries.map((entry, i) => ({
               entryId: options.entries[i].id,
-              encryptedEntry: entry
+              iv: entry.iv,
+              encryptedEntry: entry.encryptedEntry
             }))
           }).encoded
         )

package/src/unstable/eventlog/EventLogServerEncrypted.ts

@@ -67,10 +67,10 @@ export const layerRpcHandlers = Layer.unwrap(Effect.gen(function*() {
         })
       }
       if (request.encryptedEntries.length === 0) return
-      const entries = request.encryptedEntries.map(({ encryptedEntry, entryId }) =>
+      const entries = request.encryptedEntries.map(({ encryptedEntry, entryId, iv }) =>
         new PersistedEntry({
           entryId,
-          iv: request.iv,
+          iv,
           encryptedEntry
         })
       )

package/src/unstable/http/HttpClient.ts

@@ -1267,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
@@ -1300,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
   }
@@ -1319,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
  */
@@ -1332,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
    */
@@ -1347,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
    */
@@ -1371,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)
@@ -1385,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
@@ -1401,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,
@@ -1422,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.
@@ -1438,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.
@@ -1454,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
          */
@@ -1489,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)
                 })
               },
@@ -1497,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)
@@ -1531,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
@@ -1541,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
   }
@@ -1554,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 = (