Retry After Verdict

Computes how long to wait from a server's Retry-After, RateLimit-Reset or X-RateLimit-Reset header, per RFC 9110 10.2.3 and 5.6.7 and draft-ietf-httpapi-ratelimit-headers-03 5.3 -- without guessing a vendor's epoch-versus-delta convention.

THE SILENT FAILURE. The value `1700000000` is either 'wait 54 years' or 'wait until this Unix timestamp', and the header alone does not say which. Guess wrong in one direction and the client hammers a server that asked for a long backoff; guess wrong in the other and it sleeps for hours through a window that reopened in thirty seconds. Neither raises an exception. Both look like a working retry loop in the code review.

IT NAMES THE AMBIGUITY INSTEAD OF RESOLVING IT SILENTLY. Where the convention is genuinely undecidable from the value, the verdict says so and names what would decide it -- the vendor, a companion header, a stated epoch -- rather than picking the more common reading and being confidently wrong for the other half of the internet.

IT ALSO HANDLES THE PARTS PEOPLE SKIP: HTTP-date in all three formats RFC 9110 requires a recipient to parse, including the obsolete ones; negative and past deltas; values large enough to overflow a naive milliseconds conversion; and the difference between a header that is absent and one that is present and unparseable.

VERIFICATION. An independent reviewer rebuilt this package from the README and the RFCs alone. Their rival passed the suite unchanged, and the suite caught a naive implementation -- the documented contract was complete enough to rebuild from.

VERIFIED: 126 tests, measured by running the suite, every mutation observed FAILING before restore.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function trimOws(raw: string): string;
  export function parseDelaySeconds(raw: string): number | null;
  export function evaluateRetryAfter(query: RetryAfterQuery): RetryAfterVerdict;
  export function parseHttpDate(value: string): HttpDateParseResult;

  export type HttpDateBasis = "http-date-imf-fixdate" | "http-date-rfc850" | "http-date-asctime";
  export type HttpDateParseResult = | { ok: true;
  export type RetryHeaderName = "retry-after" | "ratelimit-reset" | "x-ratelimit-reset";
  export type RetryAfterQuery = | { header: "retry-after";
  export type RetryAfterVerdict = RetryAfterOk | RetryAfterNotDeterminable;