constants

(no submodules)

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

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

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

Usage: Advanced

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.

2.7 KiB Raw Blame History