checkly 8.20.0 → 8.21.0

package/dist/rest/retry.d.ts

@@ -0,0 +1,55 @@
+import { AxiosInstance, AxiosResponse } from 'axios';
+declare module 'axios' {
+    interface AxiosRequestConfig {
+        /**
+         * Opts a mutating request (POST/PUT/PATCH/DELETE) into transient-error
+         * retries. Only set this on endpoints known to be idempotent: a mutation
+         * that received a gateway error may still have been applied upstream, and
+         * a retry would apply it again.
+         *
+         * Only honored by the shared REST instance created in api.ts — bare
+         * axios calls (e.g. presigned-URL asset downloads) register no retry
+         * interceptor, so the flag is inert there.
+         *
+         * Do not combine with a custom transformRequest: a retry replays the
+         * already-transformed body through the transform again, and reuses the
+         * previous attempt's Content-Length header, so a non-idempotent or
+         * length-changing transform silently corrupts or truncates the body on
+         * the wire. (The default JSON transform is idempotent, and
+         * stream-producing transforms are blocked by the stream-body guard.)
+         */
+        checklyRetry?: boolean;
+        /** Internal: attempts already made for this logical request. */
+        checklyRetryAttempt?: number;
+    }
+}
+export interface RetryOptions {
+    /** Total attempts including the initial request. */
+    attempts?: number;
+    /** Base delay for exponential backoff, in milliseconds. */
+    baseDelayMs?: number;
+    /** Cap for a single jittered backoff delay, in milliseconds. */
+    maxBackoffDelayMs?: number;
+    /** Largest server-provided Retry-After honored verbatim, in milliseconds. */
+    maxRetryAfterMs?: number;
+    /**
+     * Overridable in tests to avoid real sleeps. The abort signal fires when
+     * the wait is abandoned early; a sleep should cancel its timer then.
+     */
+    sleep?: (ms: number, abortSignal?: AbortSignal) => Promise<void>;
+    /** Overridable in tests to make jitter deterministic. */
+    random?: () => number;
+}
+/**
+ * Parses a Retry-After header value (delay-seconds or HTTP-date) into a
+ * delay in milliseconds, or undefined if the value is absent or malformed.
+ */
+export declare function parseRetryAfter(value: unknown): number | undefined;
+/**
+ * Creates an axios response rejection handler that retries transient upstream
+ * failures with bounded, jittered exponential backoff. Register it before the
+ * error-mapping interceptor so it sees the raw AxiosError; a successful retry
+ * resolves into the next interceptor's fulfilled handler, and an exhausted
+ * one rethrows into its rejection handler.
+ */
+export declare function createRetryInterceptor(api: AxiosInstance, options?: RetryOptions): (error: unknown) => Promise<AxiosResponse>;

package/dist/rest/retry.js

@@ -0,0 +1,169 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { isAxiosError } from 'axios';
+import Debug from 'debug';
+const debug = Debug('checkly:cli:rest:retry');
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 250;
+const DEFAULT_MAX_BACKOFF_DELAY_MS = 2000;
+// An explicit server hint is trusted for longer than our own backoff would
+// wait, but still bounded so interactive commands cannot stall indefinitely.
+const DEFAULT_MAX_RETRY_AFTER_MS = 10_000;
+// The transient gateway class only. 408 is deliberately excluded: the API
+// uses it to end long-poll requests, and the polling callers own that retry
+// cadence. Plain 500 is also a conscious exclusion, even though brief API
+// degradations have been observed to produce the occasional 500 alongside
+// 502s: a 500 is just as often a deterministic application failure, and
+// retrying those multiplies load and latency for no benefit.
+const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
+// Connection-level failures where no response arrived. Safe to retry for
+// idempotent requests even if the request reached the server.
+const RETRYABLE_ERROR_CODES = new Set([
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ECONNABORTED',
+    'EAI_AGAIN',
+    'ERR_NETWORK',
+    'EPIPE',
+]);
+const IDEMPOTENT_METHODS = new Set(['get', 'head', 'options']);
+// The timer must stay ref'd while the wait is live: the caller is awaiting
+// the retried request, and an unref'd timer would let the event loop drain
+// mid-backoff, silently exiting the process with the request unresolved.
+// When the wait is abandoned early (request aborted), the timer is cancelled
+// through the signal so it cannot keep the process alive for the remainder
+// of the delay either.
+function defaultSleep(ms, abortSignal) {
+    return delay(ms, undefined, { signal: abortSignal }).catch((err) => {
+        // A cancelled backoff sleep is not an error; the caller re-checks the
+        // request's own signal after waking up.
+        if (err?.name !== 'AbortError') {
+            throw err;
+        }
+    });
+}
+// Resolves when the sleep finishes or the signal aborts, whichever comes
+// first, so an aborted caller is not kept waiting out the backoff delay.
+async function sleepUnlessAborted(sleep, ms, signal) {
+    if (signal?.aborted) {
+        return;
+    }
+    // A real AbortController of our own (config.signal is only a
+    // GenericAbortSignal, which node's timers reject): aborted once the race
+    // settles, so a lost sleep timer cannot linger and keep the process alive.
+    const sleepAbort = new AbortController();
+    let onAbort;
+    try {
+        await Promise.race([
+            sleep(ms, sleepAbort.signal),
+            new Promise(resolve => {
+                onAbort = resolve;
+                signal?.addEventListener?.('abort', onAbort);
+            }),
+        ]);
+    }
+    finally {
+        sleepAbort.abort();
+        if (onAbort !== undefined) {
+            signal?.removeEventListener?.('abort', onAbort);
+        }
+    }
+}
+/**
+ * Parses a Retry-After header value (delay-seconds or HTTP-date) into a
+ * delay in milliseconds, or undefined if the value is absent or malformed.
+ */
+export function parseRetryAfter(value) {
+    if (typeof value !== 'string' || value === '') {
+        return undefined;
+    }
+    const seconds = Number(value);
+    if (!Number.isNaN(seconds)) {
+        return seconds >= 0 ? seconds * 1000 : undefined;
+    }
+    const date = Date.parse(value);
+    if (Number.isNaN(date)) {
+        return undefined;
+    }
+    return Math.max(0, date - Date.now());
+}
+function isStream(value) {
+    return value !== null && typeof value === 'object' && typeof value.pipe === 'function';
+}
+/**
+ * Whether the request itself may be replayed: idempotent method (or explicit
+ * opt-in), not aborted, and no single-use stream involved on either side.
+ */
+function isRetryableRequest(config) {
+    if (config.signal?.aborted) {
+        return false;
+    }
+    // Streamed responses (e.g. the deployment progress SSE stream) may have
+    // been partially consumed by the caller and cannot be transparently
+    // reissued. Streamed request bodies (e.g. gzipped payloads and file
+    // uploads) are single-use and already drained by the failed attempt. If
+    // upload resilience is wanted later, it belongs at the call site, which
+    // can re-create the stream (e.g. re-open the file) before retrying.
+    if (config.responseType === 'stream' || isStream(config.data)) {
+        return false;
+    }
+    const method = (config.method ?? 'get').toLowerCase();
+    return IDEMPOTENT_METHODS.has(method) || config.checklyRetry === true;
+}
+/**
+ * Whether the failure looks transient: a retryable gateway status, or a
+ * connection-level error with no response at all.
+ */
+function isRetryableFailure(error) {
+    if (error.response !== undefined) {
+        return RETRYABLE_STATUS_CODES.has(error.response.status);
+    }
+    return error.code !== undefined && RETRYABLE_ERROR_CODES.has(error.code);
+}
+/**
+ * Creates an axios response rejection handler that retries transient upstream
+ * failures with bounded, jittered exponential backoff. Register it before the
+ * error-mapping interceptor so it sees the raw AxiosError; a successful retry
+ * resolves into the next interceptor's fulfilled handler, and an exhausted
+ * one rethrows into its rejection handler.
+ */
+export function createRetryInterceptor(api, options) {
+    const { attempts = DEFAULT_ATTEMPTS, baseDelayMs = DEFAULT_BASE_DELAY_MS, maxBackoffDelayMs = DEFAULT_MAX_BACKOFF_DELAY_MS, maxRetryAfterMs = DEFAULT_MAX_RETRY_AFTER_MS, sleep = defaultSleep, random = Math.random, } = options ?? {};
+    return async function retryInterceptor(error) {
+        if (!isAxiosError(error) || error.config === undefined) {
+            throw error;
+        }
+        const { config } = error;
+        if (!isRetryableRequest(config) || !isRetryableFailure(error)) {
+            throw error;
+        }
+        const attempt = config.checklyRetryAttempt ?? 1;
+        if (attempt >= attempts) {
+            throw error;
+        }
+        const status = error.response?.status;
+        const retryAfterMs = parseRetryAfter(error.response?.headers?.['retry-after']);
+        let delayMs;
+        if (retryAfterMs !== undefined && retryAfterMs <= maxRetryAfterMs) {
+            delayMs = retryAfterMs;
+        }
+        else if (status === 429 && retryAfterMs !== undefined) {
+            // The server asked for a longer wait than our delay budget allows.
+            // Retrying earlier than requested would likely just get throttled
+            // again, so give up instead.
+            throw error;
+        }
+        else {
+            // Full jitter: a uniformly random delay up to the exponential bound
+            // spreads out concurrent clients hitting the same degraded gateway.
+            delayMs = Math.round(random() * Math.min(maxBackoffDelayMs, baseDelayMs * 2 ** (attempt - 1)));
+        }
+        debug('Retrying %s %s after %s (attempt %d of %d, delay %dms)', (config.method ?? 'get').toUpperCase(), config.url, status ?? error.code, attempt + 1, attempts, delayMs);
+        await sleepUnlessAborted(sleep, delayMs, config.signal);
+        if (config.signal?.aborted) {
+            throw error;
+        }
+        config.checklyRetryAttempt = attempt + 1;
+        return api.request(config);
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/rest/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/rest/retry.ts"],"names":[],"mappings":"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"}