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

package/bitrix24/b24/tokens.ts

@@ -0,0 +1,280 @@
+import { SdkError } from "@bitrix24/b24jssdk";
+import type { AuthData } from "@bitrix24/b24jssdk";
+import { logs } from "../../logs/logs.ts";
+import { isPreConnectionError } from "../../utils/fetchRetry.ts";
+import { RETRY_COUNT, RETRY_DELAY_MS, delay } from "./retry.ts";
+import { APP_ENV, confAuthB24, cleanDomain } from "./config.ts";
+import { $b24 } from "./state.ts";
+import type { SaveResult } from "./types.ts";
+
+// ==================== Константы ====================
+
+/** 25 минут при времени жизни токена около часа */
+export const PROACTIVE_REFRESH_INTERVAL_MS = 25 * 60 * 1000;
+/** 2 минуты — ускоренный интервал при ошибке обновления */
+export const PROACTIVE_RETRY_ON_ERROR_MS = 2 * 60 * 1000;
+
+/**
+ * Бюджет одного обмена refresh-токена. По его истечении сторож освобождает мьютекс.
+ *
+ * Совпадает с PROACTIVE_RETRY_ON_ERROR_MS намеренно: сторож не отменяет обмен, а лишь
+ * возвращает управление, и следующую попытку делает проактивный таймер — то есть при
+ * залипании процесс пробует обновить токен примерно раз в четыре минуты. При времени
+ * жизни токена около часа этого с запасом хватает, чтобы дожить до восстановления сети.
+ *
+ * Собственный цикл повторов внутри обмена укладывается в бюджет целиком: пять попыток
+ * с линейно растущей задержкой дают около пяти секунд плюс сетевое время.
+ *
+ * Плата за то, что сторож обмен не отменяет: при недоступности oauth-хоста висящие
+ * запросы копятся примерно по одному на четыре минуты и рассасываются сами, когда
+ * сокеты добьют таймауты ОС. Это не утечка, а следствие отсутствия сигнала отмены
+ * внутри SDK — искать её в другом месте не нужно.
+ *
+ * Известный компромисс: если ротация на сервере всё же прошла, второй обмен пойдёт
+ * с уже отозванным refresh-токеном и вернёт отказ. Отказ виден в логах и лечится
+ * проактивным таймером, тогда как залипание лечилось только перезапуском процесса.
+ *
+ * Переменной окружения для бюджета нет намеренно: рычаг, которым можно выключить
+ * защиту, в аварийном пути опаснее отсутствия настройки.
+ */
+export const REFRESH_STUCK_TIMEOUT_MS = 2 * 60 * 1000;
+
+// ==================== Работа с токенами ====================
+
+/** Проверяет, что authData содержит все обязательные непустые поля */
+function isValidAuthData(data: AuthData): boolean {
+    return !!(
+        data &&
+        typeof data.access_token === "string" && data.access_token.length > 0 &&
+        typeof data.refresh_token === "string" && data.refresh_token.length > 0 &&
+        typeof data.domain === "string" && data.domain.length > 0 &&
+        data.expires
+    );
+}
+
+/** Сохраняет токены в authB24.json, нормализуя домен без протокола */
+export function saveTokens(authData: AuthData): SaveResult {
+    try {
+        if (!isValidAuthData(authData)) {
+            const msg = "Попытка сохранить невалидные токены — операция отклонена";
+            logs.add(msg, "error");
+            return { error: true, message: msg };
+        }
+
+        confAuthB24.set(APP_ENV, { ...authData, domain: cleanDomain(authData.domain) });
+        logs.add("Токены Bitrix24 сохранены", "debug");
+        return { error: false, message: "Токены сохранены." };
+    } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logs.add(`Ошибка сохранения токенов: ${message}`, "error");
+        return { error: true, message };
+    }
+}
+
+// ==================== Мьютекс для refresh токена ====================
+
+/**
+ * Дедупликация refresh-запросов.
+ * Пока промис не завершён, все новые вызовы ждут его результат
+ * вместо параллельных запросов к oauth.bitrix.info.
+ */
+let refreshInProgress: Promise<AuthData> | null = null;
+
+/**
+ * Владелец мьютекса. По нему поздно завершившийся обмен узнаёт, что мьютекс уже
+ * не его: без билета его завершение обнулило бы `refreshInProgress` нового обмена,
+ * и два запроса к oauth.bitrix.info пошли бы параллельно.
+ *
+ * Проверка появляется вместе со сторожем: до него новый обмен не мог начаться раньше,
+ * чем отработает `finally` предыдущего, и гонки не существовало.
+ */
+let refreshTicket: object | null = null;
+
+/**
+ * Снимает мьютекс, только если он всё ещё принадлежит этому обмену.
+ *
+ * Возвращает `true`, когда мьютекс был снят, и `false`, когда он уже принадлежит
+ * другому обмену. По этому значению сторож выбирает формулировку: строка «мьютекс
+ * освобождён» после `reinitializeB24()` сообщала бы о том, чего не было, и уводила
+ * разбор аварии в сторону.
+ */
+function releaseRefreshMutex(ticket: object): boolean {
+    if (refreshTicket !== ticket) return false;
+    refreshInProgress = null;
+    refreshTicket = null;
+    return true;
+}
+
+/**
+ * Отвязывает мьютекс от текущего обмена, не дожидаясь его.
+ *
+ * Нужен `reinitializeB24()`: `refreshInProgress` — переменная модуля, общая для всех
+ * экземпляров, и без сброса свежесозданный экземпляр приклеился бы к обмену старого,
+ * то есть к запросу со старым refresh-токеном. Билет прежнего обмена после сброса
+ * никому не принадлежит, поэтому его завершение мьютекс не тронет.
+ *
+ * Наружу пакета имя не уходит: `b24.ts` реэкспортирует явным списком.
+ */
+export function resetRefreshMutex(): void {
+    refreshInProgress = null;
+    refreshTicket = null;
+}
+
+/**
+ * Сам обмен токена: пять попыток с линейно растущей задержкой.
+ * Мьютексом не распоряжается — это забота вызывающего.
+ */
+async function runRefreshAttempts(): Promise<AuthData> {
+    if (!$b24) throw new Error("$b24 не инициализирован");
+
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= RETRY_COUNT; attempt++) {
+        try {
+            return await $b24.auth.refreshAuth();
+        } catch (error) {
+            lastError = error;
+
+            // Повторяем только когда соединение заведомо не состоялось.
+            // При таймауте или обрыве сервер мог уже провести ротацию: тогда
+            // локальный refresh-токен мёртв независимо от наших действий, и повтор
+            // не помогает, а лишь маскирует проблему серией одинаковых отказов.
+            // Следующая попытка всё равно будет — проактивный таймер повторит
+            // через 2 минуты при времени жизни токена около часа
+            if (!isPreConnectionError(error) || attempt === RETRY_COUNT) throw error;
+
+            const msg = error instanceof Error ? error.message : String(error);
+            const code = error instanceof SdkError ? ` [${error.code}]` : "";
+            const delayMs = RETRY_DELAY_MS * attempt;
+            logs.add(`refreshAuth${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${delayMs}мс`, "warn");
+            await delay(delayMs);
+        }
+    }
+    throw lastError;
+}
+
+/**
+ * Обмен токена под мьютексом со сторожевым таймером.
+ *
+ * Обмен идёт отдельным экземпляром axios внутри SDK и таймаута не имеет вовсе,
+ * поэтому зависший сокет означал бы вечно занятый мьютекс: все дальнейшие обновления
+ * приклеились бы к мёртвому промису, а через час процесс начал бы получать 401
+ * на каждый вызов. Сторож это разрывает.
+ *
+ * Сторож освобождает ТОЛЬКО мьютекс: сам обмен не отменяется и его результат
+ * не отбрасывается. Отменить его нечем (axios-клиент создан внутри SDK, сигнала
+ * туда не передать), а гонка `Promise.race` потеряла бы токен, пришедший секундой
+ * позже. Поздний успех всё равно попадёт в authB24.json: колбэк сохранения SDK
+ * зовёт сам, внутри refreshAuth(), до возврата значения (oauth/auth.mjs:106–110).
+ */
+function refreshAuthWithMutex(): Promise<AuthData> {
+    if (refreshInProgress) {
+        logs.add("refreshAuth: ожидаем завершения текущего refresh", "debug");
+        return refreshInProgress;
+    }
+
+    const ticket = {};
+    refreshTicket = ticket;
+
+    // Промис живёт своей жизнью: сторож его не отменяет и результат не отбрасывает
+    const work = runRefreshAttempts();
+
+    const guarded = new Promise<AuthData>((resolve, reject) => {
+        const watchdog = setTimeout(() => {
+            const released = releaseRefreshMutex(ticket);
+
+            // Билет мог уже отобрать resetRefreshMutex() из reinitializeB24() —
+            // тогда мьютекс принадлежит другому обмену, и трогать его нечем
+            const mutexPart = released
+                ? "мьютекс освобождён"
+                : "обмен признан зависшим, мьютекс уже принадлежит другому обмену";
+
+            // Уровень warn, а не error, намеренно: брошенную ниже ошибку поймает
+            // refreshAndSaveTokens и напишет свою строку уровня error, а error уходит
+            // в чат B24 — иначе на одно залипание пришло бы два сообщения
+            logs.add(
+                `refreshAuth: обмен токена не завершился за ${REFRESH_STUCK_TIMEOUT_MS / 60000} мин — ${mutexPart}, зависший запрос продолжает работу и сохранит токены сам, если ответ придёт`,
+                "warn"
+            );
+            reject(new Error(`обмен refresh-токена завис (не завершился за ${REFRESH_STUCK_TIMEOUT_MS / 60000} мин)`));
+        }, REFRESH_STUCK_TIMEOUT_MS);
+
+        // unref(), чтобы сторож не держал процесс живым: у потребителя это фоновая
+        // страховка, а не работа. Приведение типа нужно потому, что пакет публикуется
+        // исходниками — у потребителя с lib.dom в tsconfig setTimeout может резолвиться
+        // в браузерную перегрузку, возвращающую number
+        (watchdog as unknown as { unref?: () => void }).unref?.();
+
+        const settle = (finish: () => void) => {
+            clearTimeout(watchdog);
+            releaseRefreshMutex(ticket);
+            finish();
+        };
+
+        // Обработчика обязательно два: поздний отказ зависшего обмена без своего
+        // обработчика стал бы unhandled rejection и уронил процесс потребителя.
+        // По той же причине здесь нельзя .finally() — производный промис отклонится
+        work.then(
+            (authData) => settle(() => resolve(authData)),
+            (error: unknown) => settle(() => reject(error))
+        );
+    });
+
+    refreshInProgress = guarded;
+    return guarded;
+}
+
+/**
+ * Обновляет токены через мьютекс и сохраняет в файл.
+ * Используется проактивным таймером и может вызываться вручную.
+ */
+export async function refreshAndSaveTokens(): Promise<SaveResult> {
+    if (!$b24) {
+        return { error: true, message: "$b24 не инициализирован." };
+    }
+
+    try {
+        const authData = await refreshAuthWithMutex();
+        return saveTokens(authData);
+    } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logs.add(`Ошибка обновления токенов: ${message}`, "error");
+        return { error: true, message };
+    }
+}
+
+// ==================== Проактивное обновление токена ====================
+
+let proactiveRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+/** Запускает проактивное обновление токена. При ошибке — повтор через 2 мин, при успехе — через 25 мин */
+export function startProactiveRefresh(): void {
+    if (proactiveRefreshTimer) {
+        clearTimeout(proactiveRefreshTimer);
+        proactiveRefreshTimer = null;
+    }
+
+    const scheduleNext = (delayMs: number) => {
+        proactiveRefreshTimer = setTimeout(async () => {
+            logs.add("Проактивное обновление токена Bitrix24", "debug");
+            const result = await refreshAndSaveTokens();
+
+            if (result.error) {
+                logs.add(`Ошибка проактивного обновления токена, повтор через ${PROACTIVE_RETRY_ON_ERROR_MS / 60000} мин`, "error");
+                scheduleNext(PROACTIVE_RETRY_ON_ERROR_MS);
+            } else {
+                scheduleNext(PROACTIVE_REFRESH_INTERVAL_MS);
+            }
+        }, delayMs);
+    };
+
+    scheduleNext(PROACTIVE_REFRESH_INTERVAL_MS);
+    logs.add(`Проактивное обновление токена запущено (каждые ${PROACTIVE_REFRESH_INTERVAL_MS / 60000} мин)`, "debug");
+}
+
+/** Останавливает проактивное обновление токена */
+export function stopProactiveRefresh(): void {
+    if (!proactiveRefreshTimer) return;
+    clearTimeout(proactiveRefreshTimer);
+    proactiveRefreshTimer = null;
+    logs.add("Проактивное обновление токена остановлено", "debug");
+}

package/bitrix24/b24/types.ts

@@ -0,0 +1,93 @@
+import type { B24OAuth, AjaxResult, Result, BatchCommandsArrayUniversal, BatchCommandsObjectUniversal, BatchNamedCommandsUniversal } from "@bitrix24/b24jssdk";
+
+// ==================== Типы ====================
+
+/** Результат операций с токенами */
+export interface SaveResult {
+    error: boolean;
+    message: string;
+}
+
+/**
+ * Минимальный контракт HTTP-запроса, который читает `saveAuthB24Handler`.
+ *
+ * Своя структура вместо `Request` из `@types/express`: три потребителя
+ * (`b24_rnp`, `b24_ai`, `marketing_vk_ads`) `express` не ставят вовсе и жили
+ * на нашей копии типов, приезжавшей транзитивно. С 4.0.0 `@types/*` в
+ * `devDependencies`, поэтому такой копии больше нет.
+ *
+ * Express подставляет сюда свой `Request` без правок у потребителя:
+ * параметры контравариантны, и `Request.body: any` подходит под `body: unknown`.
+ */
+export interface AuthSaveRequest {
+    body: unknown;
+}
+
+/** Минимальный контракт HTTP-ответа, который пишет `saveAuthB24Handler` */
+export interface AuthSaveResponse {
+    status(code: number): { json(body: unknown): unknown };
+}
+
+/**
+ * `B24OAuth` плюс пять методов, которые пакет реализует сам поверх `actions.v2.*`.
+ *
+ * SDK 2.x помечает `callMethod`/`callListMethod`/`fetchListMethod`/`callBatch`/`callBatchByChunk`
+ * к удалению в следующем major. Пакет предоставляет их сам, поэтому сигнатуры для потребителя
+ * не меняются, а зависимости от удаляемого API у нас больше нет.
+ *
+ * Тип расширяет `B24OAuth`, поэтому `$b24` по-прежнему передаётся туда, где ждут `B24OAuth`
+ * (`new Smsgold(auth, $b24)`, `new Event($b24)`).
+ *
+ * Пять сигнатур ниже объявлены НАМЕРЕННО и сегодня дублируют то, что и так приходит
+ * по наследству от `B24OAuth`. Удалять их нельзя: в SDK 3.x этих методов в `AbstractB24`
+ * не будет, и вместе с ними из типа пропадёт вся поверхность фасада — а тайпчек на
+ * SDK 2.2.0 останется зелёным, то есть пропажа обнаружится только у потребителя.
+ * Страховка от «уборки дублей» — `tests/client-type.test.ts`: он читает текст этого
+ * файла и падает, если хоть одно объявление отсюда исчезло.
+ *
+ * `any` в сигнатурах оставлен НАМЕРЕННО и снятию по T-53 не подлежит: это дефолты
+ * дженериков публичной поверхности, дословно повторяющие `AbstractB24`. На них стоит
+ * код потребителей — `for await (const chunk of $b24.fetchListMethod(...))
+ * chunk.forEach((x) => x.ID)` и `callBatch([["crm.deal.get", { id }]])`. `unknown`
+ * в дефолте уронил бы каждое такое место, ничего не дав взамен: узкий тип задаётся
+ * параметром типа на месте вызова (`callMethod<Deal>(...)`).
+ */
+export interface B24Client extends B24OAuth {
+    callMethod<T = any>(method: string, params?: object, start?: number): Promise<AjaxResult<T>>;
+    callListMethod(method: string, params?: object, progress?: null | ((progress: number) => void), customKeyForResult?: string | null): Promise<Result>;
+    fetchListMethod(method: string, params?: any, idKey?: string, customKeyForResult?: string | null): AsyncGenerator<any[]>;
+    callBatch(calls: Array<any> | object, isHaltOnError?: boolean, returnAjaxResult?: boolean): Promise<Result>;
+    callBatchByChunk(calls: Array<any>, isHaltOnError: boolean): Promise<Result>;
+}
+
+/**
+ * Минимальный контракт «умеет вызывать REST-методы B24».
+ *
+ * Нужен внутренним классам (`Event`, `Smsgold`), которые принимают экземпляр извне.
+ * Объявляет `callMethod` сам, поэтому переживёт удаление метода из `B24OAuth`.
+ *
+ * Объединение `B24OAuth | B24Client` эту задачу не решает: `B24Client` расширяет
+ * `B24OAuth`, union схлопывается в супертип, а вызов метода на union требует его
+ * наличия в обеих ветках — то есть после удаления из SDK тайпчек сломается всё равно.
+ *
+ * Структурный тип шире `B24OAuth`, поэтому публичные сигнатуры конструкторов
+ * не сужаются: и `B24OAuth`, и `$b24`, и любой свой объект с `callMethod` подходят.
+ */
+export interface B24MethodCaller {
+    // Дженерика здесь быть не должно: у SDK метод не generic, и `B24OAuth`
+    // потребителя перестал бы подходить под этот тип. Проверено тайпчеком
+    callMethod(method: string, params?: object, start?: number): Promise<AjaxResult>;
+}
+
+/** Набор методов фасада — то, что Proxy отдаёт вместо реализаций SDK */
+export type FacadeMethods = Pick<B24Client, "callMethod" | "callListMethod" | "fetchListMethod" | "callBatch" | "callBatchByChunk">;
+
+/** Формы списка команд batch, которые принимает actions.v2 */
+export type BatchCalls = BatchCommandsArrayUniversal | BatchCommandsObjectUniversal | BatchNamedCommandsUniversal;
+
+/** Конверт ответа restApi:v2 — то, что прислал портал, до того как AjaxResult его урезал */
+export interface V2Envelope {
+    result?: unknown;
+    next?: unknown;
+    total?: unknown;
+}