@andrey4emk/npm-app-back-b24 5.1.0 → 5.2.1

package/README.md

@@ -242,7 +242,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     **Уровни логов.** Промежуточные попытки пишутся на `warn`, окончательный отказ — на `error`: исчерпание всех попыток и отмена повтора гейтом. Так один упавший вызов даёт одно сообщение в Телеграм-группу через ретранслятор вместо пяти, но при этом не теряется совсем. Логировать провал обязан сам Proxy: `errorB24()`, `Event` и `Smsgold` ошибку только возвращают вызывающему коду и в лог не пишут.
 
-    **Создающие вызовы не повторяются Proxy-слоем.** Если в вызове есть метод, создающий сущность или запускающий действие (`*.add`, `*.create`, `*.start`, `*.send`, `*.uploadfile`, `*.import`, `*.register` — в том числе среди команд `callBatch`), retry отменяется, а в лог идёт `повтор отменён`. Причина: транспортная ошибка не говорит, дошёл ли запрос до портала. Обрыв приходит и когда соединение не состоялось, и когда оно случилось после того, как портал уже принял и выполнил запрос — а повтор во втором случае создаёт вторую задачу, второй файл, второй экземпляр бизнес-процесса. Идемпотентные записи (`*.update`, `*.delete`, `*.set`) повторяются как прежде: повторное применение даёт то же состояние.
+    **Создающие вызовы не повторяются Proxy-слоем.** Если в вызове есть метод, создающий сущность или запускающий действие (`*.add`, `*.create`, `*.start`, `*.send`, `*.upload`, `*.uploadfile`, `*.import`, `*.register` — в том числе среди команд `callBatch`), retry отменяется, а в лог идёт `повтор отменён`. Причина: транспортная ошибка не говорит, дошёл ли запрос до портала. Обрыв приходит и когда соединение не состоялось, и когда оно случилось после того, как портал уже принял и выполнил запрос — а повтор во втором случае создаёт вторую задачу, второй файл, второй экземпляр бизнес-процесса. Идемпотентные записи (`*.update`, `*.delete`, `*.set`) повторяются как прежде: повторное применение даёт то же состояние. Загрузка файла в чат (`imbot.v2.File.upload`, `im.v2.File.upload`) под защитой с выпуска после 5.2.0: раньше обрыв связи повторял её до пяти раз, и в чат приходили одинаковые файлы.
 
     Ключевое слово ищется **в любой позиции** имени, а не только в конце: `imconnector.send.messages` и `imconnector.send.status.delivery` тоже под гейтом. После ключевого слова обязателен разделитель (`.`, `?` или конец строки), поэтому `crm.deal.addcustom` и `landing.landing.addbytemplate` повторяются как прежде.
 

package/bitrix24/b24/retry.ts

@@ -39,7 +39,7 @@ export const NETWORK_ERROR_CODES = new Set(["NETWORK_ERROR", "REQUEST_TIMEOUT",
 
 /**
  * REST-методы B24, повтор которых создаёт дубликат сущности или запускает
- * повторное действие: add, create, start, send, uploadfile, import, register.
+ * повторное действие: add, create, start, send, upload, uploadfile, import, register.
  *
  * Транспортная ошибка не говорит, дошёл ли запрос до портала: обрыв приходит
  * и когда соединение не состоялось, и когда оно оборвалось после того, как портал уже
@@ -66,8 +66,14 @@ export const NETWORK_ERROR_CODES = new Set(["NETWORK_ERROR", "REQUEST_TIMEOUT",
  * перестанет, и это осознанная плата за правило без списка исключений: потеря отметки
  * о доставке косметическая, переписку она не ломает, а ручной список молча устаревал бы
  * при появлении нового метода портала — ровно тот дефект, которым T-48 и был.
+ *
+ * Слово `upload` добавлено задачей T-73: `imbot.v2.File.upload` и `im.v2.File.upload`
+ * загружают файл в чат, а в перечне было только `uploadfile`, и обрыв связи давал до пяти
+ * одинаковых файлов в чате. Разделитель после слова по-прежнему обязателен, поэтому
+ * `upload` не срабатывает внутри `uploadfile` (тот ловится своим словом) и внутри
+ * имён вида `crm.deal.uploadcustom`.
  */
-export const NON_IDEMPOTENT_METHOD_RE = /\.(add|create|start|send|uploadfile|import|register)(\.|\?|$)/i;
+export const NON_IDEMPOTENT_METHOD_RE = /\.(add|create|start|send|upload|uploadfile|import|register)(\.|\?|$)/i;
 
 /**
  * Методы, повтор которых теряет данные, хотя сущностей не создаёт.
@@ -133,8 +139,11 @@ export function retryDelayFor(error: unknown, attempt: number): number {
     return isNonJsonResponseError(error) ? NON_JSON_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) : RETRY_DELAY_MS;
 }
 
+/** Начало фразы про создающий вызов — по нему уровень отмены повтора отличает её от резервирующей */
+const CREATING_REASON_HEAD = "вызов создаёт сущности (";
+
 /** Фраза для лога: повтор отменён, потому что вызов создаёт сущности */
-const creatingReason = (what: string): string => `вызов создаёт сущности (${what})`;
+const creatingReason = (what: string): string => `${CREATING_REASON_HEAD}${what})`;
 
 /** Фраза для лога: повтор отменён, потому что вызов резервирует данные на портале */
 const reservingReason = (what: string): string => `вызов резервирует данные на портале (${what})`;
@@ -447,8 +456,16 @@ export async function runWithRetry<T>(fn: () => Promise<T>, label: string, block
             // потеряться уже после того, как портал его выполнил. Различить нельзя,
             // поэтому вызовы под ограничением не повторяем — лучше вернуть ошибку,
             // чем создать дубликат или потерять зарезервированный пакет
+            // Отмена только резервирующего вызова (event.offline.get) — warn: повтор потерю не
+            // исправит, а зависшие пакеты подбирает само приложение (b24_conector#T-97). Строки
+            // приложений о транспортном обрыве (socket hang up, ECONNRESET, таймаут) несут сетевой
+            // признак и уходят только сводкой, поэтому одиночный обрыв виден лишь в Loki — это
+            // принято сознательно. Строка об ответе без JSON («портал вернул не JSON: HTTP 200,
+            // text/html…») сетевого признака не несёт и уходит в Телеграм сразу.
+            // Отмена создающего остаётся error: сущность могла не создаться
             if (blockReason && !proven) {
-                logs.add(`${label}${code}: повтор отменён, ${blockReason} — ${msg}`, "error");
+                const level = blockReason.includes(CREATING_REASON_HEAD) ? "error" : "warn";
+                logs.add(`${label}${code}: повтор отменён, ${blockReason} — ${msg}`, level);
                 throw error;
             }
 

package/logs/logs.ts

@@ -68,6 +68,33 @@ function describeSendError(error: unknown): string {
     return typeof causeLabel === "string" && causeLabel ? `${name} (${causeLabel})` : name;
 }
 
+/**
+ * Признаки разового сетевого сбоя в тексте error-лога: обрыв, таймаут, недоступный хост.
+ * Проверяется текст, а не тип ошибки: строки о сбое пишут и сами приложения
+ * («Не удалось получить события. read ECONNRESET»), типа ошибки у логгера нет
+ */
+const NETWORK_FAILURE_RE =
+    /ECONNRESET|socket hang up|ETIMEDOUT|ECONNREFUSED|EHOSTUNREACH|ENETUNREACH|ENOTFOUND|EAI_AGAIN|UND_ERR_SOCKET|UND_ERR_CONNECT_TIMEOUT|Request timeout exceeded|fetch failed|other side closed|Error connecting to authorization server/i;
+
+/**
+ * Строки с сетевым признаком, которые уходят сразу и по одной: отменённое создание
+ * сущности, провал обмена токена, неизвестный статус доставки, потерянное после повторов
+ * сообщение («[tg_1] Сообщение оператора не доставлено после 5 повторных попыток…: fetch failed»
+ * из b24_conector) — их разбирает человек.
+ * Фраза «не доставлено» выводит из сводки и вторую строку b24_conector:
+ * «[<ключ>] Сообщение не доставлено в Битрикс24: соединение не состоялось (id: N): getaddrinfo ENOTFOUND …»
+ * (reportSendFailure в server/api/telegram/b24MessageBuffer.ts, уровень error). Это тоже настоящая
+ * потеря сообщения, так задумано. Следствие: если портал долго недоступен, в Телеграм придёт
+ * по одному сообщению на каждое входящее сообщение клиента
+ */
+const NETWORK_KEEP_RE = /вызов создаёт сущности|обновление токена не удалось|статус неизвестен|не доставлено/;
+
+/** Окно, за которое считаются сетевые сбои, и пауза между сводками, мс */
+const NETWORK_WINDOW_MS = 15 * 60_000;
+
+/** Со скольких сетевых сбоев за окно в Телеграм уходит сводка */
+const NETWORK_THRESHOLD = 3;
+
 /** Ключ ретранслятора — только видимые символы ASCII, без пробелов и управляющих */
 const RELAY_KEY_RE = /^[\x21-\x7e]+$/;
 
@@ -140,6 +167,12 @@ class LogsAPI {
     /** Ключ клиента ретранслятора (`LOG_RELAY_KEY`); `undefined` — канал выключен */
     private readonly relayKey: string | undefined;
 
+    /** Время сетевых сбоев за последние `NETWORK_WINDOW_MS`, мс */
+    private networkFailures: number[] = [];
+
+    /** Когда ушла последняя сводка сетевых сбоев, мс */
+    private lastNetworkSummaryAt = Number.NEGATIVE_INFINITY;
+
     constructor() {
         this.initConfig();
         const url = process.env.LOG_RELAY_URL?.trim() || undefined;
@@ -189,6 +222,7 @@ class LogsAPI {
      * независимо от настройки `error.enabled` в `log.json`. Настройка `enabled`
      * управляет только выводом в консоль. Это сделано намеренно, чтобы критические
      * ошибки всегда доходили до команды даже при отключённом консольном логировании.
+     * Исключение — разовые сетевые сбои: они уходят сводкой, см. `routeToRelay()`.
      *
      * @param message - Текст сообщения или объект для вывода
      * @param level - Уровень логирования (trace, debug, info, warn, error)
@@ -204,7 +238,7 @@ class LogsAPI {
         // В консоль ниже уходят исходные message и jsonData — маскировка телефонов
         // касается только текста для Телеграма
         if (levelStr === "error") {
-            this.sendToRelay(messageText, jsonData);
+            this.routeToRelay(messageText, jsonData);
         }
 
         // Проверяем конфиг, и если логирование отключено, то выходим
@@ -228,6 +262,36 @@ class LogsAPI {
         }
     }
 
+    /**
+     * Решает, уходит ли error-лог в Телеграм сразу.
+     *
+     * Разовый сетевой сбой проходит сам, а сообщение о нём в Телеграме — шум: 25.10.2026
+     * один недоступный сервер авторизации дал 14 сообщений подряд. Поэтому строка
+     * с сетевым признаком остаётся только в консоли, а в Телеграм уходит одна сводка,
+     * когда за 15 минут набралось 3 сбоя и больше; следующая — не раньше чем через 15 минут.
+     * Длинный обрыв так и виден — сводкой раз в 15 минут.
+     */
+    private routeToRelay(message: string, jsonData?: unknown): void {
+        if (!this.relayUrl || !this.relayKey) return;
+
+        if (!NETWORK_FAILURE_RE.test(message) || NETWORK_KEEP_RE.test(message)) {
+            this.sendToRelay(message, jsonData);
+            return;
+        }
+
+        const now = Date.now();
+        this.networkFailures = this.networkFailures.filter((at) => now - at < NETWORK_WINDOW_MS);
+        this.networkFailures.push(now);
+
+        if (this.networkFailures.length < NETWORK_THRESHOLD) return;
+        if (now - this.lastNetworkSummaryAt < NETWORK_WINDOW_MS) return;
+
+        this.lastNetworkSummaryAt = now;
+        const minutes = NETWORK_WINDOW_MS / 60_000;
+        const summary = `Сетевые сбои: ${this.networkFailures.length} за ${minutes} мин (одиночные в Телеграм не отправляются, все строки — в логе контейнера). Последний:\n${message}`;
+        this.sendToRelay(summary, jsonData);
+    }
+
     /**
      * Готовит текст error-лога и отправляет его в ретранслятор (fire-and-forget).
      *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@andrey4emk/npm-app-back-b24",
-    "version": "5.1.0",
+    "version": "5.2.1",
     "description": "Bitrix24 OAuth helpers for Node.js projects",
     "main": "index.ts",
     "type": "module",