@andrey4emk/npm-app-back-b24 3.7.1 → 3.8.1

package/utils/fetchRetry.ts

@@ -12,11 +12,112 @@ const NETWORK_ERROR_CODES = [
     "UND_ERR_SOCKET",
 ];
 
+// ==================== Таймауты ====================
+
+/** Дефолтный бюджет на один запрос, мс. 0 — таймаут выключен */
+const FALLBACK_TIMEOUT_MS = 60_000;
+
+/**
+ * Потолок таймера Node. Выше `AbortSignal.timeout()` либо бросает `ERR_OUT_OF_RANGE`
+ * (свыше 2^32-1), либо переполняется и превращает бюджет в 1 мс (от 2^31 до 2^32-1) —
+ * то есть обрывает вообще все запросы. Проверка обязательна: `FETCH_TIMEOUT_MS`
+ * описан как аварийный рычаг, а типовое действие в аварии — «поставлю побольше».
+ */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+/** Годится ли значение как бюджет: целое от 0 до потолка таймера */
+function isValidTimeout(value: number): boolean {
+    return Number.isInteger(value) && value >= 0 && value <= MAX_TIMEOUT_MS;
+}
+
+/**
+ * Читает бюджет запроса из переменной окружения `FETCH_TIMEOUT_MS`.
+ *
+ * `dotenv.config()` вызывается в `logs/logs.ts`, а этот модуль импортирует `logs`
+ * первой строкой — значит к моменту чтения `process.env` файл `.env` уже загружен.
+ *
+ * Значение принимается, только если это целое число >= 0 (0 означает «без таймаута»).
+ * Любой мусор в переменной не должен молча превращаться в `NaN` или в обрезанное
+ * `parseInt`-число, поэтому проверяем фактом и падаем на дефолт с записью в лог.
+ */
+function readTimeoutFromEnv(): number {
+    const raw = process.env.FETCH_TIMEOUT_MS;
+    if (raw === undefined || raw.trim() === "") return FALLBACK_TIMEOUT_MS;
+
+    const parsed = Number(raw);
+    if (!isValidTimeout(parsed)) {
+        logs.add(`FETCH_TIMEOUT_MS: значение '${raw}' непригодно (нужно целое от 0 до ${MAX_TIMEOUT_MS}) — берём ${FALLBACK_TIMEOUT_MS}мс`, "warn");
+        return FALLBACK_TIMEOUT_MS;
+    }
+
+    return parsed;
+}
+
+/**
+ * Бюджет одной попытки по умолчанию, мс. Читается один раз при загрузке модуля
+ * из `FETCH_TIMEOUT_MS`, иначе 60 000. Значение 0 полностью выключает таймаут —
+ * это аварийный рычаг для случая, когда дефолт обрывает живой долгий запрос.
+ */
+export const DEFAULT_FETCH_TIMEOUT_MS: number = readTimeoutFromEnv();
+
+/**
+ * Именованные бюджеты для вызовов внутри пакета: смысл каждого запроса тут известен,
+ * поэтому дефолт 60с (рассчитанный на чужой неизвестный код) им избыточен.
+ *
+ * - `quick` — проверка, обновление и выпуск токена;
+ * - `api` — короткое чтение (проверка номера, список лицензий, получение контакта);
+ * - `send` — отправка текста, создание контакта, отправка SMS;
+ * - `transfer` — скачивание файла и отправка файла/вложения.
+ */
+export const FETCH_TIMEOUTS = { quick: 10_000, api: 20_000, send: 30_000, transfer: 60_000 } as const;
+
+/** Читает `name` с произвольного значения ошибки, не полагаясь на её тип */
+function getErrorName(error: unknown): string | null {
+    if (typeof error !== "object" || error === null) return null;
+
+    const name = (error as { name?: unknown }).name;
+    return typeof name === "string" ? name : null;
+}
+
+/**
+ * Проверяет, что запрос прерван по таймауту (`AbortSignal.timeout`).
+ *
+ * Прерывание по таймауту даёт `DOMException` с `name: "TimeoutError"`.
+ * Проверка идёт по `name`, а не по `instanceof DOMException`: у части потребителей
+ * в `lib` нет DOM, и `DOMException` как значение там не объявлен.
+ *
+ * @param error — пойманная ошибка
+ * @returns true, если ответа не дождались
+ */
+export function isTimeoutError(error: unknown): boolean {
+    return getErrorName(error) === "TimeoutError";
+}
+
+/**
+ * Проверяет, что запрос отменён по сигналу вызывающего кода (`AbortController.abort()`).
+ *
+ * Отмена без причины даёт `DOMException` с `name: "AbortError"`. Если отмена сделана
+ * с явной причиной (`abort(new Error(...))`), наружу приходит сам объект причины —
+ * такой случай этой проверкой не ловится, и ловиться не должен: тип причины выбирает
+ * тот, кто отменял.
+ *
+ * @param error — пойманная ошибка
+ * @returns true, если операцию отменили
+ */
+export function isAbortError(error: unknown): boolean {
+    return getErrorName(error) === "AbortError";
+}
+
 /**
  * Проверяет, является ли ошибка сетевой (стоит повторить запрос).
  * Экспортируется для использования в других retry-обёртках (например, для $b24).
  */
 export function isNetworkError(error: unknown): boolean {
+    // Прерывание по сигналу сетевой ошибкой не считается: повторять решает тот,
+    // кто владеет сигналом. Проверка обязана стоять до ветки с TypeError —
+    // внешняя отмена может нести любую причину, включая TypeError
+    if (isTimeoutError(error) || isAbortError(error)) return false;
+
     if (error instanceof TypeError) return true;
 
     if (error instanceof Error) {
@@ -85,44 +186,186 @@ export function maskUrl(url: string | URL | Request): string {
     );
 }
 
+// ==================== Работа с сигналами ====================
+
+/**
+ * Собирает сигналы отмены, которые пришли снаружи: из `options.signal` и из самого
+ * `Request`, если запрос передан объектом.
+ *
+ * Сигнал у `Request` учитывается обязательно: `fetch(request, init)` затирает
+ * собственный сигнал запроса тем, что лежит в `init`, — без этой склейки чужая
+ * отмена молча перестала бы работать.
+ *
+ * Но признаком «вызывающий сам управляет бюджетом» этот сигнал не является:
+ * у любого `Request` он есть всегда, даже пустой. Решение о дефолтном таймауте
+ * принимается только по `options.signal` — см. `resolveTimeoutMs()`.
+ */
+function collectExternalSignals(url: string | URL | Request, options?: RequestInit): AbortSignal[] {
+    const signals: AbortSignal[] = [];
+
+    if (options?.signal) signals.push(options.signal);
+    if (url instanceof Request && url.signal) signals.push(url.signal);
+
+    return signals;
+}
+
+/**
+ * Считает бюджет попытки.
+ *
+ * Явно переданный `timeoutMs` побеждает всегда (включая 0 — «без таймаута»), но
+ * непригодное значение отбрасываем: `AbortSignal.timeout()` бросает на дробном,
+ * отрицательном и NaN, а молча выключать защиту такое значение не должно.
+ *
+ * Если бюджет не задан, а вызывающий передал сигнал **в `options`**, свой дефолт не
+ * навязываем: он обрезал бы осознанно выставленный чужой таймаут. Сигнал самого
+ * `Request` таким признаком не является — он есть у любого `Request`, даже когда
+ * вызывающий его не задавал, и учёт этого сигнала здесь выключил бы таймаут
+ * для всех вызовов с объектом `Request`.
+ */
+function resolveTimeoutMs(explicit: number | undefined, hasOwnBudget: boolean): number {
+    if (explicit !== undefined) {
+        if (isValidTimeout(explicit)) return explicit;
+
+        logs.add(`fetchRetry: timeoutMs=${explicit} непригоден (нужно целое от 0 до ${MAX_TIMEOUT_MS}) — берём ${DEFAULT_FETCH_TIMEOUT_MS}мс`, "warn");
+        return DEFAULT_FETCH_TIMEOUT_MS;
+    }
+
+    return hasOwnBudget ? 0 : DEFAULT_FETCH_TIMEOUT_MS;
+}
+
+/**
+ * Собирает параметры вызова fetch со склеенными сигналами.
+ *
+ * Поле `signal` либо отсутствует вовсе, либо содержит конкретный объект: явный
+ * `undefined` не подходит полю `signal?: AbortSignal | null` при
+ * `exactOptionalPropertyTypes` у части потребителей.
+ */
+function buildInit(options: RequestInit | undefined, signals: AbortSignal[]): RequestInit | undefined {
+    if (signals.length === 0) return options;
+
+    const first = signals[0];
+    if (signals.length === 1 && first) {
+        return { ...(options ?? {}), signal: first };
+    }
+
+    return { ...(options ?? {}), signal: AbortSignal.any(signals) };
+}
+
+/**
+ * Одиночный fetch с бюджетом времени — без повторных попыток и без логирования.
+ *
+ * Для неидемпотентных операций (отправка сообщения, создание сущности): повтор
+ * там запрещён, а защита от зависшего соединения нужна.
+ *
+ * Ошибка пробрасывается как есть: таймаут — `DOMException` с `name: "TimeoutError"`
+ * (проверяется через `isTimeoutError()`), отмена по чужому сигналу — причина этой отмены.
+ *
+ * Бюджет продолжает действовать и после возврата из функции — во время чтения тела
+ * (`res.text()`, `res.arrayBuffer()`), потому что сигнал живёт до конца запроса.
+ *
+ * @param url — адрес запроса
+ * @param options — параметры fetch (метод, заголовки, body и т.д.)
+ * @param timeoutMs — бюджет запроса в мс; 0 — без таймаута; не передан — `DEFAULT_FETCH_TIMEOUT_MS`
+ *                    (а при наличии своего `options.signal` — без своего таймаута)
+ * @returns Response от fetch
+ */
+export async function fetchWithTimeout(url: string | URL | Request, options?: RequestInit, timeoutMs?: number): Promise<Response> {
+    const externalSignals = collectExternalSignals(url, options);
+    const effectiveTimeout = resolveTimeoutMs(timeoutMs, Boolean(options?.signal));
+    const ownSignal = effectiveTimeout > 0 ? AbortSignal.timeout(effectiveTimeout) : null;
+
+    return await fetch(url, buildInit(options, ownSignal ? [...externalSignals, ownSignal] : externalSignals));
+}
+
 /**
  * Обёртка над fetch с повторными попытками при сетевых ошибках.
  * Повторяет запрос только при проблемах с сетью (TypeError, ECONNRESET и т.д.),
  * HTTP-ошибки (4xx, 5xx) НЕ вызывают повторных попыток.
  *
+ * Таймаут:
+ * - бюджет `timeoutMs` даётся **каждой попытке** заново, свой таймаут повторяется
+ *   наравне с прочими сетевыми ошибками (`ETIMEDOUT` уже в этом списке);
+ * - худший случай по времени — `retries × (timeoutMs + delay)`;
+ * - бюджет действует и после возврата из функции: если тело ответа читается дольше
+ *   бюджета, `res.text()` / `res.arrayBuffer()` упадут тем же `TimeoutError`;
+ * - если вызывающий передал свой `options.signal` (или `signal` у `Request`), а `timeoutMs`
+ *   не задан, свой дефолт НЕ добавляется — чужой осознанный таймаут не обрезается;
+ * - отмена по чужому сигналу никогда не повторяется, ошибка пробрасывается как есть.
+ *
+ * Тип ошибки таймаута не оборачивается намеренно: потребители разбирают её по
+ * `name === "TimeoutError"` / `"AbortError"`. Понятный текст уходит в лог, а не в тип ошибки.
+ *
  * @param url — адрес запроса
  * @param options — параметры fetch (метод, заголовки, body и т.д.)
  * @param retries — количество попыток (по умолчанию 5)
  * @param delay — задержка между попытками в мс (по умолчанию 500)
+ * @param timeoutMs — бюджет одной попытки в мс; 0 — без таймаута; не передан —
+ *                    `DEFAULT_FETCH_TIMEOUT_MS` либо 0 при наличии чужого сигнала
  * @returns Response от fetch
  */
 export async function fetchRetry(
     url: string | URL | Request,
     options?: RequestInit,
     retries: number = 5,
-    delay: number = 500
+    delay: number = 500,
+    timeoutMs?: number
 ): Promise<Response> {
     let lastError: Error | null = null;
 
+    const externalSignals = collectExternalSignals(url, options);
+    const effectiveTimeout = resolveTimeoutMs(timeoutMs, Boolean(options?.signal));
+
     for (let attempt = 1; attempt <= retries; attempt++) {
+        // Свой сигнал на каждую попытку: сигнал одноразовый, и второй попытке
+        // достался бы уже сгоревший
+        const ownSignal = effectiveTimeout > 0 ? AbortSignal.timeout(effectiveTimeout) : null;
+
         try {
-            const response = await fetch(url, options);
+            const response = await fetch(url, buildInit(options, ownSignal ? [...externalSignals, ownSignal] : externalSignals));
             return response;
         } catch (error: unknown) {
+            // DOMException наследует Error, поэтому TimeoutError доходит до вызывающего
+            // в исходном виде — оборачивать его в «понятную» ошибку нельзя, на name
+            // завязан разбор у потребителей
             lastError = error instanceof Error ? error : new Error(String(error));
 
-            if (!isNetworkError(error) || attempt === retries) {
+            // Отмена пришла снаружи — повтор был бы прямым нарушением решения вызывающего.
+            // Различаем по объекту сигнала, а не по типу ошибки: причиной отмены может
+            // оказаться любой объект, включая TypeError, который isNetworkError() считает сетевым.
+            // Бросаем lastError, а не error: DOMException наследует Error и доходит нетронутым,
+            // а произвольная причина (abort("строка")) приводится к Error — контракт функции
+            // «наружу летит только Error» держится с самой первой версии
+            if (externalSignals.some((signal) => signal.aborted)) throw lastError;
+
+            const isOwnTimeout = ownSignal?.aborted === true;
+
+            if (!isOwnTimeout && !isNetworkError(error)) {
                 throw lastError;
             }
 
-            logs.add(
-                `fetchRetry: попытка ${attempt}/${retries} не удалась (${lastError.message}), повтор через ${delay}мс — ${maskUrl(url)}`,
-                "warn"
-            );
+            if (attempt === retries) {
+                if (isOwnTimeout) {
+                    logs.add(`fetchRetry: таймаут ${effectiveTimeout}мс на каждой из попыток (${retries}) — ${maskUrl(url)}`, "warn");
+                }
+                throw lastError;
+            }
+
+            if (isOwnTimeout) {
+                logs.add(
+                    `fetchRetry: попытка ${attempt}/${retries} прервана по таймауту ${effectiveTimeout}мс, повтор через ${delay}мс — ${maskUrl(url)}`,
+                    "warn"
+                );
+            } else {
+                logs.add(
+                    `fetchRetry: попытка ${attempt}/${retries} не удалась (${lastError.message}), повтор через ${delay}мс — ${maskUrl(url)}`,
+                    "warn"
+                );
+            }
 
             await new Promise((resolve) => setTimeout(resolve, delay));
         }
     }
 
-    throw lastError;
+    // Сюда попадаем только при retries <= 0: цикл не выполнился ни разу
+    throw lastError ?? new Error("fetchRetry: retries должно быть >= 1");
 }