first commit

docs/persistence/storage/storage-http/src/constants/constants.md

@@ -0,0 +1,60 @@
+# 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.