@wildix/xbees-conversations-utils 1.2.1 → 1.2.3

package/dist-cjs/normalization.js

@@ -205,7 +205,7 @@ function localizeStreamChannel(streamChannel) {
     const { data, state } = streamChannel;
     const wid = streamChannel.getClient().userID || '';
     const createdAt = new Date(normalizedChannel.createdAt);
-    const updatedAt = new Date(normalizedChannel.updatedAt || normalizedChannel?.createdBy);
+    const updatedAt = new Date(normalizedChannel.updatedAt || normalizedChannel?.createdAt);
     const members = Object.values(state.members).filter(({ user_id }) => user_id !== wid);
     const userId = data?.type === xbees_conversations_client_1.ChannelType.DIRECT && members.length > 0 ? members[0].user_id : null;
     const unread = state.read[wid]?.unread_messages || 0;

package/dist-cjs/rateLimits/RedisCooldown.js

@@ -0,0 +1,66 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', {value: true});
+exports.RedisCooldown = void 0;
+const constants_1 = require('./constants');
+
+class RedisCooldown {
+  static async getRemainingMs(cooldownKey, context) {
+    const {redis, logger} = context;
+
+    try {
+      const ttlMs = await redis.pttl(`${constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`);
+
+      if (ttlMs > 0) {
+        return ttlMs;
+      }
+    } catch (error) {
+      logger.warn('Failed to read stream rate-limit cooldown from Redis', {
+        cooldownKey,
+        error,
+      });
+    }
+
+    return 0;
+  }
+
+  static async setRemainingMs(cooldownKey, cooldownMs, context) {
+    if (cooldownMs <= 0) {
+      return;
+    }
+
+    const {redis, logger} = context;
+    const redisKey = `${constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`;
+
+    try {
+      await redis.eval(
+        `
+        local key = KEYS[1]
+        local new_ttl = tonumber(ARGV[1])
+        local current_ttl = redis.call('PTTL', key)
+
+        if current_ttl == -2 then
+          redis.call('SET', key, '1', 'PX', new_ttl)
+          return 1
+        end
+
+        if current_ttl == -1 or current_ttl < new_ttl then
+          redis.call('PEXPIRE', key, new_ttl)
+          return 2
+        end
+
+        return 0
+      `,
+        1,
+        redisKey,
+        cooldownMs.toString(),
+      );
+    } catch (error) {
+      logger.warn('Failed to write stream rate-limit cooldown to Redis', {
+        cooldownKey,
+        cooldownMs,
+        error,
+      });
+    }
+  }
+}
+exports.RedisCooldown = RedisCooldown;

package/dist-cjs/rateLimits/constants.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OPTIONS = 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_COOLDOWN_SLEEP_CHUNK_MS = exports.BUDGET_MINIMAL_DELAY_MAX_MS = exports.BUDGET_MINIMAL_DELAY_MIN_MS = exports.BUDGET_RELAXED_DELAY_MAX_MS = exports.BUDGET_RELAXED_DELAY_MIN_MS = exports.BUDGET_RELAXED_USAGE_THRESHOLD = exports.BUDGET_CLEAR_USAGE_THRESHOLD = exports.BUDGET_DELAY_MAX_MS = exports.BUDGET_DELAY_MIN_MS = exports.BUDGET_THRESHOLD = exports.STREAM_BUDGET_COOLDOWN_KEY = exports.STREAM_RATE_LIMIT_METADATA_KEY_SUFFIX = 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 = exports.STREAM_SYNC_METHOD_NAMES = exports.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = exports.STREAM_METHOD_NAMES = exports.STREAM_CHANNEL_RESULT_METHOD_NAMES = exports.CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES = exports.CHANNEL_SYNC_METHOD_NAMES = exports.CHANNEL_METHOD_NAMES = void 0;
+var generatedMethodNames_1 = require("./generatedMethodNames");
+Object.defineProperty(exports, "CHANNEL_METHOD_NAMES", { enumerable: true, get: function () { return generatedMethodNames_1.CHANNEL_METHOD_NAMES; } });
+Object.defineProperty(exports, "CHANNEL_SYNC_METHOD_NAMES", { enumerable: true, get: function () { return generatedMethodNames_1.CHANNEL_SYNC_METHOD_NAMES; } });
+Object.defineProperty(exports, "CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES", { enumerable: true, get: function () { return generatedMethodNames_1.CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES; } });
+Object.defineProperty(exports, "STREAM_CHANNEL_RESULT_METHOD_NAMES", { enumerable: true, get: function () { return generatedMethodNames_1.STREAM_CHANNEL_RESULT_METHOD_NAMES; } });
+Object.defineProperty(exports, "STREAM_METHOD_NAMES", { enumerable: true, get: function () { return generatedMethodNames_1.STREAM_METHOD_NAMES; } });
+Object.defineProperty(exports, "STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES", { enumerable: true, get: function () { return generatedMethodNames_1.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES; } });
+Object.defineProperty(exports, "STREAM_SYNC_METHOD_NAMES", { enumerable: true, get: function () { return generatedMethodNames_1.STREAM_SYNC_METHOD_NAMES; } });
+exports.DEFAULT_MAX_DELAY_MS = 5000;
+exports.DEFAULT_RETRY_AFTER_MS = 10000;
+exports.DEFAULT_JITTER_MS = 150;
+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_RATE_LIMIT_METADATA_KEY_SUFFIX = ':meta';
+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.BUDGET_CLEAR_USAGE_THRESHOLD = 0.6;
+exports.BUDGET_RELAXED_USAGE_THRESHOLD = 0.7;
+exports.BUDGET_RELAXED_DELAY_MIN_MS = 5000;
+exports.BUDGET_RELAXED_DELAY_MAX_MS = 10000;
+exports.BUDGET_MINIMAL_DELAY_MIN_MS = 1000;
+exports.BUDGET_MINIMAL_DELAY_MAX_MS = 2000;
+exports.BUDGET_COOLDOWN_SLEEP_CHUNK_MS = 3000;
+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 = 500;
+exports.SOFT_THROTTLE_DELAY_MEDIUM_MS = 1500;
+exports.SOFT_THROTTLE_DELAY_HIGH_MS = 3000;
+exports.DEFAULT_OPTIONS = {
+    maxAttempts: 3,
+    enableCooldown: true,
+    maxDelayMs: 5000,
+    maxRetryableDelayMs: 10000,
+};

package/dist-cjs/rateLimits/createRateLimitedStreamProxy.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRateLimitedStreamProxy = void 0;
+const constants_1 = require("./constants");
+const executeWithRateLimitHandling_1 = require("./helpers/executeWithRateLimitHandling");
+const isStreamChannelLike_1 = require("./helpers/isStreamChannelLike");
+const registerStreamInterceptors_1 = require("./helpers/registerStreamInterceptors");
+const splitCallArgsAndOptions_1 = require("./helpers/splitCallArgsAndOptions");
+const STREAM_SYNC_METHODS = new Set(constants_1.STREAM_SYNC_METHOD_NAMES);
+const STREAM_CHANNEL_RESULT_METHODS = new Set(constants_1.STREAM_CHANNEL_RESULT_METHOD_NAMES);
+const STREAM_SYNC_CHANNEL_RESULT_METHODS = new Set(constants_1.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES);
+const CHANNEL_SYNC_METHODS = new Set(constants_1.CHANNEL_SYNC_METHOD_NAMES);
+const CHANNEL_SYNC_PROXY_RESULT_METHODS = new Set(constants_1.CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES);
+function wrapKnownChannelResult(result, dependencies) {
+    if (Array.isArray(result)) {
+        return result.map((item) => wrapKnownChannelResult(item, dependencies));
+    }
+    if (typeof result !== 'object' || result === null) {
+        return result;
+    }
+    return wrapTarget(result, dependencies);
+}
+function normalizeStreamCallResult(result, dependencies, wrapAsChannelResult = false) {
+    if (wrapAsChannelResult) {
+        return wrapKnownChannelResult(result, dependencies);
+    }
+    if (Array.isArray(result)) {
+        return result.map((item) => normalizeStreamCallResult(item, dependencies));
+    }
+    if (!(0, isStreamChannelLike_1.isStreamChannelLike)(result)) {
+        return result;
+    }
+    return wrapTarget(result, dependencies);
+}
+function createRateLimitedMethodWrapper(target, value, operation, dependencies, wrapAsChannelResult) {
+    return async (...args) => {
+        const { callArgs, callOptions } = (0, splitCallArgsAndOptions_1.splitCallArgsAndOptions)(args);
+        const result = await (0, executeWithRateLimitHandling_1.executeWithRateLimitHandling)(() => Reflect.apply(value, target, callArgs), operation, dependencies.context, {
+            ...constants_1.DEFAULT_OPTIONS,
+            ...callOptions,
+        });
+        return normalizeStreamCallResult(result, dependencies, wrapAsChannelResult);
+    };
+}
+function wrapTarget(target, dependencies) {
+    const cachedObject = dependencies.cache.get(target);
+    if (cachedObject) {
+        return cachedObject;
+    }
+    const proxy = new Proxy(target, {
+        get: (originalTarget, property, receiver) => {
+            const value = Reflect.get(originalTarget, property, receiver);
+            if (typeof property !== 'string' || typeof value !== 'function') {
+                return value;
+            }
+            if (STREAM_SYNC_CHANNEL_RESULT_METHODS.has(property)) {
+                return (...args) => {
+                    const { callArgs } = (0, splitCallArgsAndOptions_1.splitCallArgsAndOptions)(args);
+                    const result = Reflect.apply(value, originalTarget, callArgs);
+                    return normalizeStreamCallResult(result, dependencies, true);
+                };
+            }
+            if (CHANNEL_SYNC_PROXY_RESULT_METHODS.has(property)) {
+                return (...args) => {
+                    const { callArgs } = (0, splitCallArgsAndOptions_1.splitCallArgsAndOptions)(args);
+                    const result = Reflect.apply(value, originalTarget, callArgs);
+                    if (typeof result === 'object' && result !== null) {
+                        return wrapTarget(result, dependencies);
+                    }
+                    return result;
+                };
+            }
+            if (STREAM_SYNC_METHODS.has(property) || CHANNEL_SYNC_METHODS.has(property)) {
+                return (...args) => {
+                    const { callArgs } = (0, splitCallArgsAndOptions_1.splitCallArgsAndOptions)(args);
+                    return Reflect.apply(value, originalTarget, callArgs);
+                };
+            }
+            return createRateLimitedMethodWrapper(originalTarget, value, property, dependencies, STREAM_CHANNEL_RESULT_METHODS.has(property));
+        },
+    });
+    dependencies.cache.set(target, proxy);
+    return proxy;
+}
+function createRateLimitedStreamProxy(stream, context) {
+    (0, registerStreamInterceptors_1.registerStreamInterceptors)(stream, context);
+    return wrapTarget(stream, {
+        context,
+        cache: new WeakMap(),
+    });
+}
+exports.createRateLimitedStreamProxy = createRateLimitedStreamProxy;

package/dist-cjs/rateLimits/exception/createRateLimitExceededException.js

@@ -0,0 +1,21 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', {value: true});
+exports.createRateLimitExceededException = void 0;
+const xbees_conversations_client_1 = require('@wildix/xbees-conversations-client');
+const constants_1 = require('../constants');
+
+function createRateLimitExceededException(options = {}) {
+  const {rateLimit, message, operation, retryAfterMs = constants_1.DEFAULT_RETRY_AFTER_MS} = options;
+  const defaultMessage = operation ? `Rate limit exceeded for ${operation}` : 'Rate limit exceeded';
+
+  return new xbees_conversations_client_1.RateLimitExceededException({
+    $metadata: {},
+    message: message || defaultMessage,
+    rateLimitRemaining: rateLimit?.remaining || 0,
+    retryAfter: rateLimit?.reset ? rateLimit.reset - Date.now() : retryAfterMs,
+    rateLimit: rateLimit?.limit?.toString() || 'unknown',
+    rateLimitReset: rateLimit?.reset || Date.now() + retryAfterMs,
+  });
+}
+
+exports.createRateLimitExceededException = createRateLimitExceededException;

package/dist-cjs/rateLimits/exception/processStreamRateLimitException.js

@@ -0,0 +1,47 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', {value: true});
+exports.processStreamRateLimitException = void 0;
+const createRateLimitExceededException_1 = require('./createRateLimitExceededException');
+
+function isStreamException(error) {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'metadata' in error &&
+    typeof error.metadata === 'object' &&
+    error.metadata !== null &&
+    'responseCode' in error.metadata
+  );
+}
+
+function isStreamAPIException(error) {
+  return typeof error === 'object' && !!error.code;
+}
+
+function processStreamRateLimitException(error, logger) {
+  if (isStreamException(error) && error.metadata?.responseCode === 429) {
+    const rateLimit = error.metadata?.rateLimit;
+    logger.warn('Stream rate limit exceeded [StreamException]', {rateLimit});
+
+    return (0, createRateLimitExceededException_1.createRateLimitExceededException)({
+      rateLimit,
+      message: error.message || 'Rate limit exceeded',
+    });
+  }
+
+  if (isStreamAPIException(error) && (error.code === 429 || error.StatusCode === 429)) {
+    logger.warn('Stream rate limit exceeded [StreamAPIException]', {code: error.code, StatusCode: error.StatusCode});
+
+    return (0, createRateLimitExceededException_1.createRateLimitExceededException)({
+      message: error.message || 'Rate limit exceeded',
+    });
+  }
+
+  if (typeof error === 'object' && error !== null && 'status' in error && error.status === 429) {
+    logger.warn('Stream rate limit exceeded [error.status === 429]');
+
+    return (0, createRateLimitExceededException_1.createRateLimitExceededException)({message: 'Rate limit exceeded'});
+  }
+}
+
+exports.processStreamRateLimitException = processStreamRateLimitException;

package/dist-cjs/rateLimits/executeStreamRequestWithRateLimitHandling.js

@@ -0,0 +1,94 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', {value: true});
+exports.executeStreamRequestWithRateLimitHandling = void 0;
+const promises_1 = require('node:timers/promises');
+const constants_1 = require('./constants');
+const createRateLimitExceededException_1 = require('./exception/createRateLimitExceededException');
+const processStreamRateLimitException_1 = require('./exception/processStreamRateLimitException');
+const RedisCooldown_1 = require('./RedisCooldown');
+
+function calculateRateLimitDelayMs(error, maxDelayMs) {
+  const retryAfterMs =
+    typeof error.retryAfter === 'number'
+      ? error.retryAfter + constants_1.RETRY_AFTER_BUFFER_MS
+      : constants_1.DEFAULT_RETRY_AFTER_MS;
+
+  if (retryAfterMs > 0) {
+    const jitterMs = Math.floor(Math.random() * constants_1.DEFAULT_JITTER_MS);
+
+    return Math.min(maxDelayMs, retryAfterMs + jitterMs);
+  }
+
+  return Math.min(maxDelayMs, constants_1.DEFAULT_FIXED_RATE_LIMIT_DELAY_MS);
+}
+
+async function executeStreamRequestWithRateLimitHandling(execute, operation, context, options = {}) {
+  const {logger, redis} = context;
+  const {enableCooldown, maxAttempts, maxDelayMs, maxRetryableDelayMs} = {
+    ...constants_1.DEFAULT_OPTS_1_ATTEMPT_NO_COOLDOWN,
+    ...options,
+  };
+  let attempt = 1;
+
+  if (enableCooldown) {
+    const cooldownMs = await RedisCooldown_1.RedisCooldown.getRemainingMs(operation, {redis, logger});
+
+    if (cooldownMs > 0) {
+      logger.warn('Skipping stream request due to active rate-limit cooldown', {
+        operation,
+        cooldown: cooldownMs,
+      });
+      throw (0, createRateLimitExceededException_1.createRateLimitExceededException)({
+        operation,
+        retryAfterMs: cooldownMs,
+      });
+    }
+  }
+
+  for (;;) {
+    try {
+      return await execute();
+    } catch (error) {
+      const rateLimitError = (0, processStreamRateLimitException_1.processStreamRateLimitException)(error, logger);
+
+      if (!rateLimitError) {
+        throw error;
+      }
+
+      const retryAfterMs = calculateRateLimitDelayMs(rateLimitError, maxDelayMs);
+
+      if (enableCooldown) {
+        await RedisCooldown_1.RedisCooldown.setRemainingMs(operation, retryAfterMs, {redis, logger});
+      }
+
+      if (attempt < maxAttempts && retryAfterMs <= maxRetryableDelayMs) {
+        logger.warn('Retrying stream request after rate limit', {
+          operation,
+          attempt,
+          maxAttempts,
+          retryAfterMs,
+          rateLimit: rateLimitError.rateLimit,
+          rateLimitRemaining: rateLimitError.rateLimitRemaining,
+          rateLimitReset: rateLimitError.rateLimitReset,
+        });
+        await (0, promises_1.setTimeout)(retryAfterMs);
+        attempt++;
+        continue;
+      }
+
+      logger.warn('Propagating stream rate limit w/o retry', {
+        operation,
+        attempt,
+        maxAttempts,
+        retryAfterMs,
+        maxRetryableDelayMs,
+        rateLimit: rateLimitError.rateLimit,
+        rateLimitRemaining: rateLimitError.rateLimitRemaining,
+        rateLimitReset: rateLimitError.rateLimitReset,
+      });
+      throw rateLimitError;
+    }
+  }
+}
+
+exports.executeStreamRequestWithRateLimitHandling = executeStreamRequestWithRateLimitHandling;