@andrey4emk/npm-app-back-b24 3.8.2 → 3.9.0

package/bitrix24/b24/instance.ts

@@ -0,0 +1,186 @@
+import { B24OAuth, Logger, LogLevel } from "@bitrix24/b24jssdk";
+import type { B24OAuthParams, B24OAuthSecret, AuthData, Handler, LogRecord, Formatter, RestrictionParams } from "@bitrix24/b24jssdk";
+import { logs } from "../../logs/logs.ts";
+import { APP_ENV, CLIENT_ID, CLIENT_SECRET, confAuthB24, cleanDomain } from "./config.ts";
+
+// ==================== Константы ====================
+
+/**
+ * Параметры ограничителя SDK. Передаются третьим аргументом конструктора B24OAuth
+ * и сливаются там с дефолтами `ParamsFactory.getDefault()`.
+ *
+ * Единый инвариант: **транспортные сбои SDK не повторяет вообще, повторяет только
+ * наш слой**, где работает гейт NON_IDEMPOTENT_METHOD_RE. У SDK нет понятия
+ * «создающий вызов»: оборванный crm.deal.add он повторил бы трижды и создал три сделки.
+ *
+ * Одного `retryOnNetworkError: false` для этого мало. Он добавляет в жёсткий список
+ * ровно два кода — NETWORK_ERROR и REQUEST_TIMEOUT, — а SDK конвертирует в них только
+ * `ERR_NETWORK` и `ECONNABORTED`. Остальные транспортные ошибки Node доезжают до
+ * лимитера под своим кодом (`ECONNRESET` при обрыве сокета, `ERR_BAD_RESPONSE` при
+ * 502/504 от шлюза), не находятся ни в жёстком, ни в мягком списке и потому считаются
+ * временными — то есть повторяются с backoff. Замерено на локальном сервере, рвущем
+ * соединение после приёма запроса: без hardErrorCodes портал выполняет crm.deal.add
+ * три раза, с ними — один. На SDK 2.0.0 был один: там транспорт маскировался в
+ * JSSDK_UNKNOWN_ERROR, а тот во встроенном жёстком списке.
+ *
+ * `ERR_NETWORK` и `ECONNABORTED` в списке не нужны: до лимитера они не доживают.
+ *
+ * Плата за список: `ECONNREFUSED`/`ENOTFOUND`/`EAI_AGAIN` доказывают, что запрос не ушёл,
+ * и SDK мог бы повторить их безопасно даже для создающих вызовов. Отказываемся сознательно —
+ * ровно так вёл себя 2.0.0, а один понятный инвариант дороже трёх сэкономленных попыток.
+ */
+export const SDK_RESTRICTION_PARAMS = {
+    retryOnNetworkError: false,
+    hardErrorCodes: [
+        "ECONNRESET",
+        "ECONNREFUSED",
+        "ENOTFOUND",
+        "ETIMEDOUT",
+        "EHOSTUNREACH",
+        "ENETUNREACH",
+        "EAI_AGAIN",
+        "EPIPE",
+        "EPROTO",
+        "ERR_BAD_RESPONSE",
+    ],
+} as const satisfies RestrictionParams;
+
+// ==================== Логгер SDK ====================
+
+/**
+ * Мост из логгера SDK в `logs` пакета.
+ *
+ * Порог WARNING обязателен: SDK пишет `post/send` и `post/response` на уровне `info`
+ * на каждый запрос и `http batch request starting/completed` на `debug` — без фильтра
+ * это залило бы лог.
+ *
+ * `AbstractHandler` объявлен в типах SDK, но в рантайме не экспортируется,
+ * поэтому реализуем интерфейс `Handler` обычным классом.
+ */
+export class B24SdkLogHandler implements Handler {
+    private formatter: Formatter | null = null;
+
+    isHandling(level: LogLevel): boolean {
+        return level >= LogLevel.WARNING;
+    }
+
+    shouldBubble(): boolean {
+        return true;
+    }
+
+    setFormatter(formatter: Formatter): void {
+        this.formatter = formatter;
+    }
+
+    getFormatter(): Formatter | null {
+        return this.formatter;
+    }
+
+    async handle(record: LogRecord): Promise<boolean> {
+        // Бросать отсюда нельзя ни при каких обстоятельствах: Logger.log() делает
+        // await handle(), но лимитер зовёт логгер без await — исключение стало бы
+        // unhandled rejection и на дефолтных настройках Node убило бы процесс.
+        // Путь к броску реален: logs.add() читает conf, а тот перечитывает файл
+        // на каждом обращении и падает на битом log.json. В catch пишем через
+        // console.error, а не через logs — иначе рискуем зациклиться на той же ошибке.
+        try {
+            const status = Number(record.context?.status);
+
+            // Лимитер SDK через error() пишет любой 4xx кроме 408/429 как
+            // «non-retryable client error». Портал отдаёт 400 на штатные «мягкие»
+            // ошибки (несуществующая сущность), которые README описывает как
+            // нормальный путь через getResultData(): проверка существования в цикле
+            // дала бы строку на итерацию. Такие сообщения — уровень debug.
+            //
+            // 408 и 429 из правила исключены на будущее, сегодня эта ветка недостижима:
+            // status попадает в контекст записи уровня WARNING и выше ровно в одном месте
+            // SDK — #logNonRetryableClientError, а он вызывается из-под условия, которое
+            // 408 и 429 уже исключает. Сообщения лимитера про 429/503 идут другим путём,
+            // без status в контексте, и маппятся в warn независимо от этой строки.
+            // Условие оставлено потому, что фейлит в безопасную сторону: начни SDK класть
+            // status в такие записи — таймаут и упор в лимит будут видны, а не утонут в debug.
+            //
+            // Остальное: уровень ERROR у SDK — это диагностика отдельной неуспешной
+            // попытки. На транспортном сбое их пять — по числу наших попыток, повторы SDK
+            // выключены (см. SDK_RESTRICTION_PARAMS). На 429/503 и неизвестных 5xx SDK
+            // повторяет по-прежнему, там до пятнадцати: три внутри каждой из наших пяти.
+            // Уровень error пакета уходит в чат B24, поэтому маппим SDK-ERROR в warn:
+            // окончательный провал вызова логирует retry-слой, ровно один раз.
+            const isQuietClientError = status >= 400 && status < 500 && status !== 408 && status !== 429;
+            const level = isQuietClientError ? "debug" : record.level >= LogLevel.CRITICAL ? "error" : "warn";
+
+            // Контекст SDK (requestId, method, code, wait, status) уже прогнан
+            // через redactSensitiveParams — токены в него не попадают
+            const context = record.context && Object.keys(record.context).length > 0 ? record.context : undefined;
+
+            logs.add(`SDK B24: ${record.message}`, level, context);
+        } catch (error: unknown) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.error(`B24SdkLogHandler: не удалось записать сообщение SDK — ${msg}`);
+        }
+
+        return true;
+    }
+}
+
+// ==================== Создание экземпляра B24OAuth ====================
+
+export function createB24Instance(): B24OAuth | null {
+    // Проект вообще не использует OAuth: ходит в B24 по входящему вебхуку либо берёт
+    // из пакета только logs/fetchRetry. Отсутствие авторизации для него — норма, а не
+    // ошибка, поэтому уровень debug: иначе ложная строка попадает в мониторинг.
+    // Признак «OAuth задуман» — наличие credentials приложения в .env.
+    if (!CLIENT_ID && !CLIENT_SECRET) {
+        logs.add("OAuth Bitrix24 не настроен (APP_B24_CLIENT_ID и APP_B24_CLIENT_SECRET не заданы), $b24 = null", "debug");
+        return null;
+    }
+
+    if (!CLIENT_ID || !CLIENT_SECRET) {
+        logs.add("Не заданы APP_B24_CLIENT_ID или APP_B24_CLIENT_SECRET в .env", "error");
+        return null;
+    }
+
+    const store = confAuthB24.store as Record<string, AuthData>;
+    const authConfig = store[APP_ENV];
+
+    if (!authConfig?.domain || !authConfig?.access_token || !authConfig?.refresh_token) {
+        logs.add("В конфиге authB24 не хватает данных для авторизации. Сохрани токены через клиент и перезагрузи докер", "error");
+        return null;
+    }
+
+    const domain = cleanDomain(authConfig.domain);
+
+    const authParams: B24OAuthParams = {
+        applicationToken: "",
+        userId: 0,
+        memberId: authConfig.member_id,
+        accessToken: authConfig.access_token,
+        refreshToken: authConfig.refresh_token,
+        expires: authConfig.expires,
+        expiresIn: authConfig.expires_in || 1800,
+        scope: "",
+        domain,
+        clientEndpoint: `https://${domain}/rest/`,
+        serverEndpoint: "https://oauth.bitrix.info/rest/",
+        status: "L",
+        issuer: "store",
+    };
+
+    const secret: B24OAuthSecret = { clientId: CLIENT_ID, clientSecret: CLIENT_SECRET };
+
+    // Параметры ограничителя задаём третьим аргументом конструктора: SDK сливает их
+    // с дефолтами (`{ ...ParamsFactory.getDefault(), ...restrictionParams }` в AbstractHttp)
+    // и передаёт обоим http-клиентам, v2 и v3, ещё до того как экземпляр можно использовать.
+    // Через setRestrictionManagerParams() было бы окно между созданием и настройкой,
+    // а результат вызова к тому же непроверяем: он завершается Promise.allSettled и
+    // не отклоняется никогда.
+    const b24 = new B24OAuth(authParams, secret, { restrictionParams: SDK_RESTRICTION_PARAMS });
+
+    // Диагностика SDK от WARNING и выше уходит в logs пакета: предупреждения
+    // callList/fetchList про игнорируемый order и остановку пагинации, сообщения лимитера.
+    // Дефолтный NullLogger не годится — LoggerFactory.forcedLog пишет мимо логгера
+    // прямо в console.warn, но после перехода на фасад этот путь у нас недостижим.
+    b24.setLogger(Logger.create("npm-app-back-b24").pushHandler(new B24SdkLogHandler()));
+
+    return b24;
+}

package/bitrix24/b24/proxy.ts

@@ -0,0 +1,78 @@
+import type { B24OAuth } from "@bitrix24/b24jssdk";
+import { createFacade } from "./facade.ts";
+import { withRetry } from "./retry.ts";
+import type { B24Client } from "./types.ts";
+
+// ==================== Константы ====================
+
+/** Методы фасада, оборачиваемые retry-логикой (fetchListMethod — async-генератор, его оборачивать нельзя) */
+export const RETRYABLE_METHODS = new Set(["callMethod", "callListMethod", "callBatch"]);
+
+/**
+ * Имена, которые Proxy резолвит в собственную реализацию пакета поверх `actions.v2.*`.
+ *
+ * Шире, чем RETRYABLE_METHODS: `fetchListMethod` и `callBatchByChunk` мы реализуем,
+ * но не ретраим. `callBatchByChunk` в наборе обязателен — пока хоть один deprecated-метод
+ * SDK достижим через `$b24`, он будет писать предупреждение об устаревании.
+ */
+export const FACADE_METHODS = new Set(["callMethod", "callListMethod", "fetchListMethod", "callBatch", "callBatchByChunk"]);
+
+// ==================== Proxy-обёртка ====================
+
+/**
+ * Proxy-обёртка вокруг B24OAuth.
+ *
+ * Имена из FACADE_METHODS резолвятся в собственные реализации пакета поверх
+ * `actions.v2.*`; из них методы RETRYABLE_METHODS дополнительно оборачиваются
+ * retry-логикой. Все остальные методы привязываются к оригинальному объекту
+ * через bind: класс B24OAuth использует приватные поля (#authOAuthManager),
+ * и при вызове метода с this === Proxy движок бросает "Cannot read private member".
+ *
+ * Обёртки кешируются — по одной на метод, чтобы не ломать сравнение по ссылке.
+ */
+export function wrapB24WithRetry(b24: B24OAuth): B24Client {
+    const methodCache = new Map<string, Function>();
+    // Фасад создаётся один раз на экземпляр: он замкнут на конкретный target,
+    // а пересоздание на каждом обращении ломало бы кеш и сравнение по ссылке
+    const facade = createFacade(b24);
+
+    return new Proxy(b24, {
+        get(target, prop) {
+            // Имена фасада проверяем до Reflect.get: пока SDK ещё объявляет свои
+            // deprecated-методы, иначе мы отдавали бы их, а не свои
+            if (typeof prop === "string" && FACADE_METHODS.has(prop)) {
+                if (!methodCache.has(prop)) {
+                    const impl = facade[prop]!;
+                    methodCache.set(prop, RETRYABLE_METHODS.has(prop) ? withRetry(impl, target, prop) : impl);
+                }
+
+                return methodCache.get(prop);
+            }
+
+            // Передаём target третьим аргументом: геттеры (например, auth)
+            // тоже должны исполняться с this === target
+            const value = Reflect.get(target, prop, target);
+
+            if (typeof prop !== "string" || typeof value !== "function") {
+                return value;
+            }
+
+            if (!methodCache.has(prop)) {
+                const wrapped = RETRYABLE_METHODS.has(prop)
+                    ? withRetry(value as (...args: any[]) => Promise<any>, target, prop)
+                    : value.bind(target);
+                methodCache.set(prop, wrapped);
+            }
+
+            return methodCache.get(prop);
+        },
+
+        // Страховка на будущее: когда SDK уберёт методы из прототипа,
+        // "callMethod" in $b24 обязано остаться истинным (eventB24.ts проверяет
+        // наличие метода перед работой). Цель расширяема, лишние true законны
+        has(target, prop) {
+            if (typeof prop === "string" && FACADE_METHODS.has(prop)) return true;
+            return Reflect.has(target, prop);
+        },
+    }) as B24Client;
+}