# constants

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Centralises the tunable defaults used across `@suaveplan/storage-http`: key-length cap, retry attempts/backoff, ETag-cache capacity, and the transient-status set. Every other module reads from this file rather than embedding magic numbers, so operators have one knob to turn when tuning behaviour for a specific origin.

## Features

- `MAX_KEY_LENGTH = 2048` — conservative intersection of major CDN path limits.
- `DEFAULT_RETRY_MAX_ATTEMPTS = 3`, `DEFAULT_RETRY_BASE_DELAY_MS = 100`, `DEFAULT_RETRY_MAX_DELAY_MS = 30_000` — used when callers don't override.
- `RETRY_AFTER_MAX_DELAY_MS = 60_000` — hard cap on honouring `Retry-After` to protect against malicious origins that try to stall callers indefinitely.
- `DEFAULT_ETAG_CACHE_CAPACITY = 256` — LRU bound for the in-memory ETag cache.
- `TRANSIENT_HTTP_STATUSES` — frozen `Set` of non-`5xx` transient codes (`408`, `425`, `429`).

## Usage: Basic

```ts
import { MAX_KEY_LENGTH } from "@suaveplan/storage-http";

if (key.length > MAX_KEY_LENGTH) {
    throw new Error(`Key too long: ${key.length}`);
}
```

## Usage: Advanced

```ts
import {
    DEFAULT_RETRY_MAX_ATTEMPTS,
    RETRY_AFTER_MAX_DELAY_MS,
    TRANSIENT_HTTP_STATUSES,
} from "@suaveplan/storage-http";

function classify(status: number): "transient" | "fatal" {
    if (status >= 500 || TRANSIENT_HTTP_STATUSES.has(status)) return "transient";
    return "fatal";
}

const retryAfter = Math.min(parsedSeconds * 1000, RETRY_AFTER_MAX_DELAY_MS);
```

## API Reference

- `MAX_KEY_LENGTH: number` — character limit for sanitised keys.
- `DEFAULT_RETRY_MAX_ATTEMPTS: number` — default retry attempts.
- `DEFAULT_RETRY_BASE_DELAY_MS: number` — initial exponential-backoff delay.
- `DEFAULT_RETRY_MAX_DELAY_MS: number` — exponential-backoff ceiling.
- `RETRY_AFTER_MAX_DELAY_MS: number` — server-supplied `Retry-After` ceiling.
- `DEFAULT_ETAG_CACHE_CAPACITY: number` — LRU capacity for ETag cache.
- `TRANSIENT_HTTP_STATUSES: ReadonlySet<number>` — non-`5xx` transient codes.

## Implementation Notes

- `RETRY_AFTER_MAX_DELAY_MS` is **not** the maximum backoff for the adapter as a whole — `DEFAULT_RETRY_MAX_DELAY_MS` controls exponential-backoff. The 60s ceiling specifically caps the value honoured from the server's `Retry-After` header.
- `5xx` is intentionally NOT in the `TRANSIENT_HTTP_STATUSES` set — the retry classifier checks the range directly (`status >= 500 && status <= 599`) so callers reading the set don't have to enumerate 100 entries.
- `MAX_KEY_LENGTH` is per-key, not per-segment; segment URL-encoding may inflate the wire length beyond this number, but that is the encoder's concern, not the sanitiser's.