@wildix/xbees-conversations-utils 1.1.73 → 1.1.74

package/dist-cjs/rateLimits/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_OPTIONS = exports.CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES = exports.CHANNEL_SYNC_METHOD_NAMES = exports.STREAM_SYNC_METHOD_NAMES = exports.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = exports.BUDGET_DELAY_MAX_MS = exports.BUDGET_DELAY_MIN_MS = exports.BUDGET_THRESHOLD = exports.STREAM_BUDGET_COOLDOWN_KEY = exports.STREAM_RATE_LIMIT_OPTIONS_MARKER = exports.STREAM_BUDGET_COOLDOWN_KEY_PREFIX = exports.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = exports.RETRY_AFTER_BUFFER_MS = exports.DEFAULT_JITTER_MS = exports.DEFAULT_RETRY_AFTER_MS = exports.DEFAULT_MAX_DELAY_MS = void 0;
+exports.DEFAULT_OPTIONS = exports.CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES = exports.CHANNEL_SYNC_METHOD_NAMES = exports.STREAM_SYNC_METHOD_NAMES = exports.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = exports.SOFT_THROTTLE_DELAY_HIGH_MS = exports.SOFT_THROTTLE_DELAY_MEDIUM_MS = exports.SOFT_THROTTLE_DELAY_LOW_MS = exports.SOFT_THROTTLE_USAGE_HIGH = exports.SOFT_THROTTLE_USAGE_MEDIUM = exports.SOFT_THROTTLE_USAGE_LOW = exports.BUDGET_DELAY_MAX_MS = exports.BUDGET_DELAY_MIN_MS = exports.BUDGET_THRESHOLD = exports.STREAM_BUDGET_COOLDOWN_KEY = exports.STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY = exports.STREAM_RATE_LIMIT_OPTIONS_MARKER = exports.STREAM_BUDGET_COOLDOWN_KEY_PREFIX = exports.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = exports.RETRY_AFTER_BUFFER_MS = exports.DEFAULT_JITTER_MS = exports.DEFAULT_RETRY_AFTER_MS = exports.DEFAULT_MAX_DELAY_MS = void 0;
 exports.DEFAULT_MAX_DELAY_MS = 5000;
 exports.DEFAULT_RETRY_AFTER_MS = 10000;
 exports.DEFAULT_JITTER_MS = 150;
@@ -8,10 +8,17 @@ exports.RETRY_AFTER_BUFFER_MS = 1000;
 exports.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = 'stream-rate-limit-cooldown:';
 exports.STREAM_BUDGET_COOLDOWN_KEY_PREFIX = 'stream-budget-cooldown:';
 exports.STREAM_RATE_LIMIT_OPTIONS_MARKER = '__xbsRateLimitOptions';
+exports.STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY = 'stream-rate-limit-soft-global';
 exports.STREAM_BUDGET_COOLDOWN_KEY = 'stream-budget-global';
 exports.BUDGET_THRESHOLD = 0.8;
 exports.BUDGET_DELAY_MIN_MS = 30000;
 exports.BUDGET_DELAY_MAX_MS = 60000;
+exports.SOFT_THROTTLE_USAGE_LOW = 0.7;
+exports.SOFT_THROTTLE_USAGE_MEDIUM = 0.85;
+exports.SOFT_THROTTLE_USAGE_HIGH = 0.95;
+exports.SOFT_THROTTLE_DELAY_LOW_MS = 150;
+exports.SOFT_THROTTLE_DELAY_MEDIUM_MS = 500;
+exports.SOFT_THROTTLE_DELAY_HIGH_MS = 1200;
 exports.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = [
     'channel',
     'getChannelById',

package/dist-cjs/rateLimits/helpers/executeWithRateLimitHandling.js

@@ -34,6 +34,14 @@ async function executeWithRateLimitHandling(execute, operation, context, options
     const { enableCooldown, maxAttempts, maxDelayMs, maxRetryableDelayMs } = options;
     let attempt = 1;
     if (enableCooldown) {
+        const softCooldownMs = await RedisCooldown_1.RedisCooldown.getRemainingMs(constants_1.STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, { redis, logger }, { keyPrefix: constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX });
+        if (softCooldownMs > 0) {
+            logger.debug('Delaying stream request due to active soft rate-limit cooldown', {
+                operation,
+                cooldown: softCooldownMs,
+            });
+            await (0, promises_1.setTimeout)(softCooldownMs);
+        }
         const budgetCooldownMs = await RedisCooldown_1.RedisCooldown.getRemainingMs(constants_1.STREAM_BUDGET_COOLDOWN_KEY, { redis, logger }, { keyPrefix: constants_1.STREAM_BUDGET_COOLDOWN_KEY_PREFIX });
         if (budgetCooldownMs > 0) {
             logger.warn('Delaying stream request due to active budget cooldown', {

package/dist-cjs/rateLimits/helpers/processStreamRateLimitHeaders.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processStreamRateLimitHeaders = void 0;
+const constants_1 = require("../constants");
+const RedisCooldown_1 = require("./RedisCooldown");
+function parseHeaderNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+}
+function getHeaderCaseInsensitive(headers, key) {
+    if (!headers) {
+        return;
+    }
+    const direct = headers[key];
+    if (direct !== undefined) {
+        return direct;
+    }
+    const normalizedKey = key.toLowerCase();
+    for (const [headerKey, headerValue] of Object.entries(headers)) {
+        if (headerKey.toLowerCase() === normalizedKey) {
+            return headerValue;
+        }
+    }
+}
+function computeSoftThrottleDelayMs(limit, remaining) {
+    if (limit <= 0) {
+        return 0;
+    }
+    const usage = 1 - remaining / limit;
+    if (usage >= constants_1.SOFT_THROTTLE_USAGE_HIGH) {
+        return constants_1.SOFT_THROTTLE_DELAY_HIGH_MS;
+    }
+    if (usage >= constants_1.SOFT_THROTTLE_USAGE_MEDIUM) {
+        return constants_1.SOFT_THROTTLE_DELAY_MEDIUM_MS;
+    }
+    if (usage >= constants_1.SOFT_THROTTLE_USAGE_LOW) {
+        return constants_1.SOFT_THROTTLE_DELAY_LOW_MS;
+    }
+    return 0;
+}
+async function processStreamRateLimitHeaders(headers, context) {
+    const { logger } = context;
+    const limit = parseHeaderNumber(getHeaderCaseInsensitive(headers, 'x-ratelimit-limit'));
+    const remaining = parseHeaderNumber(getHeaderCaseInsensitive(headers, 'x-ratelimit-remaining'));
+    if (limit === undefined || remaining === undefined) {
+        return;
+    }
+    if (limit <= 0 || remaining < 0) {
+        return;
+    }
+    const delayMs = computeSoftThrottleDelayMs(limit, remaining);
+    if (delayMs > 0) {
+        await RedisCooldown_1.RedisCooldown.setRemainingMs(constants_1.STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, delayMs, context, {
+            keyPrefix: constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
+        });
+        logger.debug('Enabling soft stream rate-limit cooldown', {
+            rateLimit: limit,
+            rateLimitRemaining: remaining,
+            cooldownMs: delayMs,
+        });
+        return;
+    }
+    await RedisCooldown_1.RedisCooldown.clear(constants_1.STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, context, {
+        keyPrefix: constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
+    });
+}
+exports.processStreamRateLimitHeaders = processStreamRateLimitHeaders;

package/dist-cjs/rateLimits/helpers/registerStreamBudgetInterceptors.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerStreamBudgetInterceptors = void 0;
 const processStreamBudgetHeaders_1 = require("./processStreamBudgetHeaders");
+const processStreamRateLimitHeaders_1 = require("./processStreamRateLimitHeaders");
 const attachedInterceptors = new WeakSet();
 function hasResponseInterceptors(value) {
     return (typeof value === 'object' &&
@@ -35,9 +36,11 @@ function registerStreamBudgetInterceptors(stream, context) {
     }
     axiosInstance.interceptors.response.use(async (response) => {
         await (0, processStreamBudgetHeaders_1.processStreamBudgetHeaders)(response?.headers, context);
+        await (0, processStreamRateLimitHeaders_1.processStreamRateLimitHeaders)(response?.headers, context);
         return response;
     }, async (error) => {
         await (0, processStreamBudgetHeaders_1.processStreamBudgetHeaders)(error?.response?.headers, context);
+        await (0, processStreamRateLimitHeaders_1.processStreamRateLimitHeaders)(error?.response?.headers, context);
         return Promise.reject(error);
     });
     attachedInterceptors.add(axiosInstance);

package/dist-es/rateLimits/constants.js

@@ -5,10 +5,17 @@ export const RETRY_AFTER_BUFFER_MS = 1000;
 export const STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = 'stream-rate-limit-cooldown:';
 export const STREAM_BUDGET_COOLDOWN_KEY_PREFIX = 'stream-budget-cooldown:';
 export const STREAM_RATE_LIMIT_OPTIONS_MARKER = '__xbsRateLimitOptions';
+export const STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY = 'stream-rate-limit-soft-global';
 export const STREAM_BUDGET_COOLDOWN_KEY = 'stream-budget-global';
 export const BUDGET_THRESHOLD = 0.8;
 export const BUDGET_DELAY_MIN_MS = 30000;
 export const BUDGET_DELAY_MAX_MS = 60000;
+export const SOFT_THROTTLE_USAGE_LOW = 0.7;
+export const SOFT_THROTTLE_USAGE_MEDIUM = 0.85;
+export const SOFT_THROTTLE_USAGE_HIGH = 0.95;
+export const SOFT_THROTTLE_DELAY_LOW_MS = 150;
+export const SOFT_THROTTLE_DELAY_MEDIUM_MS = 500;
+export const SOFT_THROTTLE_DELAY_HIGH_MS = 1200;
 export const STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = [
     'channel',
     'getChannelById',

package/dist-es/rateLimits/helpers/executeWithRateLimitHandling.js

@@ -1,5 +1,5 @@
 import { setTimeout as sleep } from 'node:timers/promises';
-import { DEFAULT_JITTER_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_RETRY_AFTER_MS, RETRY_AFTER_BUFFER_MS, STREAM_BUDGET_COOLDOWN_KEY, STREAM_BUDGET_COOLDOWN_KEY_PREFIX, } from '../constants';
+import { DEFAULT_JITTER_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_RETRY_AFTER_MS, RETRY_AFTER_BUFFER_MS, STREAM_BUDGET_COOLDOWN_KEY, STREAM_BUDGET_COOLDOWN_KEY_PREFIX, STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX, STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, } from '../constants';
 import { createRateLimitExceededException } from './createRateLimitExceededException';
 import { processStreamRateLimitException } from './processStreamRateLimitException';
 import { RedisCooldown } from './RedisCooldown';
@@ -31,6 +31,14 @@ export async function executeWithRateLimitHandling(execute, operation, context,
     const { enableCooldown, maxAttempts, maxDelayMs, maxRetryableDelayMs } = options;
     let attempt = 1;
     if (enableCooldown) {
+        const softCooldownMs = await RedisCooldown.getRemainingMs(STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, { redis, logger }, { keyPrefix: STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX });
+        if (softCooldownMs > 0) {
+            logger.debug('Delaying stream request due to active soft rate-limit cooldown', {
+                operation,
+                cooldown: softCooldownMs,
+            });
+            await sleep(softCooldownMs);
+        }
         const budgetCooldownMs = await RedisCooldown.getRemainingMs(STREAM_BUDGET_COOLDOWN_KEY, { redis, logger }, { keyPrefix: STREAM_BUDGET_COOLDOWN_KEY_PREFIX });
         if (budgetCooldownMs > 0) {
             logger.warn('Delaying stream request due to active budget cooldown', {

package/dist-es/rateLimits/helpers/processStreamRateLimitHeaders.js

@@ -0,0 +1,70 @@
+import { SOFT_THROTTLE_DELAY_HIGH_MS, SOFT_THROTTLE_DELAY_LOW_MS, SOFT_THROTTLE_DELAY_MEDIUM_MS, SOFT_THROTTLE_USAGE_HIGH, SOFT_THROTTLE_USAGE_LOW, SOFT_THROTTLE_USAGE_MEDIUM, STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX, STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, } from '../constants';
+import { RedisCooldown } from './RedisCooldown';
+function parseHeaderNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+}
+function getHeaderCaseInsensitive(headers, key) {
+    if (!headers) {
+        return;
+    }
+    const direct = headers[key];
+    if (direct !== undefined) {
+        return direct;
+    }
+    const normalizedKey = key.toLowerCase();
+    for (const [headerKey, headerValue] of Object.entries(headers)) {
+        if (headerKey.toLowerCase() === normalizedKey) {
+            return headerValue;
+        }
+    }
+}
+function computeSoftThrottleDelayMs(limit, remaining) {
+    if (limit <= 0) {
+        return 0;
+    }
+    const usage = 1 - remaining / limit;
+    if (usage >= SOFT_THROTTLE_USAGE_HIGH) {
+        return SOFT_THROTTLE_DELAY_HIGH_MS;
+    }
+    if (usage >= SOFT_THROTTLE_USAGE_MEDIUM) {
+        return SOFT_THROTTLE_DELAY_MEDIUM_MS;
+    }
+    if (usage >= SOFT_THROTTLE_USAGE_LOW) {
+        return SOFT_THROTTLE_DELAY_LOW_MS;
+    }
+    return 0;
+}
+export async function processStreamRateLimitHeaders(headers, context) {
+    const { logger } = context;
+    const limit = parseHeaderNumber(getHeaderCaseInsensitive(headers, 'x-ratelimit-limit'));
+    const remaining = parseHeaderNumber(getHeaderCaseInsensitive(headers, 'x-ratelimit-remaining'));
+    if (limit === undefined || remaining === undefined) {
+        return;
+    }
+    if (limit <= 0 || remaining < 0) {
+        return;
+    }
+    const delayMs = computeSoftThrottleDelayMs(limit, remaining);
+    if (delayMs > 0) {
+        await RedisCooldown.setRemainingMs(STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, delayMs, context, {
+            keyPrefix: STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
+        });
+        logger.debug('Enabling soft stream rate-limit cooldown', {
+            rateLimit: limit,
+            rateLimitRemaining: remaining,
+            cooldownMs: delayMs,
+        });
+        return;
+    }
+    await RedisCooldown.clear(STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, context, {
+        keyPrefix: STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
+    });
+}

package/dist-es/rateLimits/helpers/registerStreamBudgetInterceptors.js

@@ -1,4 +1,5 @@
 import { processStreamBudgetHeaders } from './processStreamBudgetHeaders';
+import { processStreamRateLimitHeaders } from './processStreamRateLimitHeaders';
 const attachedInterceptors = new WeakSet();
 function hasResponseInterceptors(value) {
     return (typeof value === 'object' &&
@@ -32,9 +33,11 @@ export function registerStreamBudgetInterceptors(stream, context) {
     }
     axiosInstance.interceptors.response.use(async (response) => {
         await processStreamBudgetHeaders(response?.headers, context);
+        await processStreamRateLimitHeaders(response?.headers, context);
         return response;
     }, async (error) => {
         await processStreamBudgetHeaders(error?.response?.headers, context);
+        await processStreamRateLimitHeaders(error?.response?.headers, context);
         return Promise.reject(error);
     });
     attachedInterceptors.add(axiosInstance);

package/dist-types/rateLimits/constants.d.ts

@@ -6,10 +6,17 @@ export declare const RETRY_AFTER_BUFFER_MS = 1000;
 export declare const STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = "stream-rate-limit-cooldown:";
 export declare const STREAM_BUDGET_COOLDOWN_KEY_PREFIX = "stream-budget-cooldown:";
 export declare const STREAM_RATE_LIMIT_OPTIONS_MARKER = "__xbsRateLimitOptions";
+export declare const STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY = "stream-rate-limit-soft-global";
 export declare const STREAM_BUDGET_COOLDOWN_KEY = "stream-budget-global";
 export declare const BUDGET_THRESHOLD = 0.8;
 export declare const BUDGET_DELAY_MIN_MS = 30000;
 export declare const BUDGET_DELAY_MAX_MS = 60000;
+export declare const SOFT_THROTTLE_USAGE_LOW = 0.7;
+export declare const SOFT_THROTTLE_USAGE_MEDIUM = 0.85;
+export declare const SOFT_THROTTLE_USAGE_HIGH = 0.95;
+export declare const SOFT_THROTTLE_DELAY_LOW_MS = 150;
+export declare const SOFT_THROTTLE_DELAY_MEDIUM_MS = 500;
+export declare const SOFT_THROTTLE_DELAY_HIGH_MS = 1200;
 export declare const STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES: readonly ["channel", "getChannelById", "getChannelByMembers", "hydrateActiveChannels"];
 export declare const STREAM_SYNC_METHOD_NAMES: readonly ["_addChannelConfig", "_buildWSPayload", "_callClientListeners", "_deleteUserMessageReference", "_enrichAxiosOptions", "_getConnectionID", "_getToken", "_handleClientEvent", "_handleUserEvent", "_hasConnectionID", "_isUsingServerAuth", "_logApiError", "_logApiRequest", "_logApiResponse", "_muteStatus", "_normalizeDate", "_normalizeExpiration", "_sayHi", "_setUser", "_startCleaning", "_updateMemberWatcherReferences", "_updateUserMessageReferences", "_updateUserReferences", "_validateAndGetMessageId", "createAbortControllerForNextRequest", "createToken", "devToken", "dispatchEvent", "errorFromResponse", "getAuthType", "getUserAgent", "handleEvent", "handleResponse", "off", "on", "setBaseURL", "setLocalDevice", "setUserAgent", "userMuteStatus", "verifyWebhook"];
 export declare const CHANNEL_SYNC_METHOD_NAMES: readonly ["_channelURL", "countUnread", "countUnreadMentions", "getConfig", "lastMessage", "lastRead", "muteStatus", "off", "on"];

package/dist-types/rateLimits/helpers/processStreamRateLimitHeaders.d.ts

@@ -0,0 +1,6 @@
+import { LoggerContext, RedisContext, StreamHeaders } from '../types';
+/**
+ * Applies soft global throttle from x-ratelimit-* headers to smooth bursts
+ * before hard 429 throttling starts.
+ */
+export declare function processStreamRateLimitHeaders(headers: StreamHeaders | undefined, context: LoggerContext & RedisContext): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildix/xbees-conversations-utils",
-  "version": "1.1.73",
+  "version": "1.1.74",
   "description": "",
   "main": "./dist-cjs/index.js",
   "module": "./dist-es/index.js",