erlc-v2 1.0.0-beta.0

package/src/rest/RequestManager.js

@@ -0,0 +1,306 @@
+const RateLimiter = require("./RateLimiter");
+const { createApiError, parseErrorCode } = require("../util/errors");
+const { ERLCHttpError, KeyExpiredError, KeyBannedError } = require("../errors");
+const { stableStringify } = require("../util/stableStringify");
+
+function parseResetHeader(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return null;
+  if (parsed < 1e12) return parsed * 1000;
+  return parsed;
+}
+
+function parseRetryAfterMs(body, headers) {
+  const retryRaw = body?.retry_after ?? body?.retryAfter ?? body?.RetryAfter;
+  if (
+    retryRaw !== undefined &&
+    retryRaw !== null &&
+    !Number.isNaN(Number(retryRaw))
+  ) {
+    return Math.max(0, Number(retryRaw) * 1000);
+  }
+  const resetEpochMs = parseResetHeader(headers.get("x-ratelimit-reset"));
+  if (resetEpochMs) {
+    return Math.max(0, resetEpochMs - Date.now());
+  }
+  return 0;
+}
+
+function parseJsonBody(text) {
+  if (!text || typeof text !== "string") return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function buildQueryString(query = {}) {
+  const params = new URLSearchParams();
+  const keys = Object.keys(query).sort();
+  for (const key of keys) {
+    const value = query[key];
+    if (value === undefined || value === null) continue;
+    if (typeof value === "boolean") {
+      params.set(key, String(value));
+      continue;
+    }
+    params.set(key, String(value));
+  }
+  return params.toString();
+}
+
+class RequestManager {
+  constructor(options) {
+    this.baseURL = options.baseURL;
+    this.serverKey = options.serverKey;
+    this.globalKey = options.globalKey;
+    this.cache = options.cache;
+    this.logger = options.logger;
+    this.rateLimiter = new RateLimiter(options.rateLimit || {}, this.logger);
+    this.routeBuckets = new Map();
+    this.inflight = new Map();
+    this.terminalError = null;
+    this.disconnected = false;
+    this.onDisconnect = options.onDisconnect;
+    this.unauthorizedThreshold = options.rateLimit?.unauthorizedThreshold ?? 3;
+    this.consecutiveForbidden = 0;
+    this.destroyed = false;
+  }
+
+  _getRouteKey(method, path) {
+    return `${method.toUpperCase()} ${path}`;
+  }
+
+  _buildCacheKey(method, path, query, body) {
+    const headerSubset = {
+      "Server-Key": this.serverKey,
+      Authorization: this.globalKey || "",
+    };
+    return stableStringify({
+      method: method.toUpperCase(),
+      path,
+      query,
+      body,
+      headers: headerSubset,
+    });
+  }
+
+  _setTerminal(error, reason) {
+    if (this.disconnected) return;
+    this.disconnected = true;
+    this.terminalError = error;
+    this.rateLimiter.destroy(error);
+    if (typeof this.onDisconnect === "function") {
+      this.onDisconnect(reason, error);
+    }
+  }
+
+  _evaluateDisconnect(error) {
+    if (error instanceof KeyExpiredError) {
+      this._setTerminal(error, "key_expired");
+      return;
+    }
+    if (error instanceof KeyBannedError) {
+      this._setTerminal(error, "key_banned");
+      return;
+    }
+
+    if (error.status === 403) {
+      this.consecutiveForbidden += 1;
+      if (this.consecutiveForbidden >= this.unauthorizedThreshold) {
+        this._setTerminal(error, "unauthorized");
+      }
+      return;
+    }
+
+    this.consecutiveForbidden = 0;
+  }
+
+  async _send(method, path, query, body) {
+    const routeKey = this._getRouteKey(method, path);
+    const currentBucket = this.routeBuckets.get(routeKey) || "global";
+    const queryString = buildQueryString(query);
+    const endpoint = queryString ? `${path}?${queryString}` : path;
+    const url = `${this.baseURL}${endpoint}`;
+
+    const result = await this.rateLimiter.schedule(currentBucket, async () => {
+      this.logger.debug({
+        msg: "request_start",
+        method,
+        route: path,
+        bucket: currentBucket,
+      });
+
+      let response;
+      try {
+        const headers = {
+          "Server-Key": this.serverKey,
+          ...(this.globalKey ? { Authorization: this.globalKey } : {}),
+        };
+        const hasBody = body !== undefined;
+        if (hasBody) {
+          headers["Content-Type"] = "application/json";
+        }
+
+        response = await fetch(url, {
+          method,
+          headers,
+          ...(hasBody ? { body: JSON.stringify(body) } : {}),
+        });
+      } catch (networkErr) {
+        throw new ERLCHttpError(
+          `Network error for ${endpoint}: ${networkErr?.message || "unknown"}`,
+          {
+          status: null,
+          endpoint,
+          bucket: currentBucket,
+          body: null,
+          },
+        );
+      }
+
+      const bucket =
+        response.headers.get("x-ratelimit-bucket") || currentBucket || "global";
+      const limit = Number(response.headers.get("x-ratelimit-limit"));
+      const remaining = Number(response.headers.get("x-ratelimit-remaining"));
+      const resetEpochMs = parseResetHeader(
+        response.headers.get("x-ratelimit-reset"),
+      );
+
+      this.routeBuckets.set(routeKey, bucket);
+      this.rateLimiter.update(bucket, { limit, remaining, resetEpochMs });
+
+      const text = await response.text();
+      const parsedBody = parseJsonBody(text);
+
+      if (response.ok) {
+        this.logger.debug({
+          msg: "request_success",
+          method,
+          route: path,
+          bucket,
+          status: response.status,
+        });
+        return {
+          status: response.status,
+          data: parsedBody ?? {},
+          endpoint,
+          bucket,
+          rateLimit: { limit, remaining, resetEpochMs },
+        };
+      }
+
+      const retryAfterMs = parseRetryAfterMs(parsedBody, response.headers);
+      if (response.status === 429) {
+        const blockUntil = Date.now() + retryAfterMs;
+        this.rateLimiter.block(bucket, Math.max(blockUntil, resetEpochMs || 0));
+        this.logger.warn({
+          msg: "request_rate_limited",
+          route: path,
+          bucket,
+          retryAfterMs,
+        });
+      }
+
+      const apiError = createApiError({
+        status: response.status,
+        endpoint,
+        bucket,
+        body: parsedBody,
+        retryAfterMs,
+        resetEpochMs,
+      });
+
+      throw apiError;
+    });
+
+    return result;
+  }
+
+  async request({
+    method = "GET",
+    path,
+    query = {},
+    body,
+    useCache = true,
+    cacheTtlMs,
+    dedupe = true,
+  }) {
+    if (this.destroyed) {
+      throw this.terminalError || new ERLCHttpError("Client destroyed");
+    }
+    if (this.terminalError) {
+      throw this.terminalError;
+    }
+
+    const normalizedMethod = method.toUpperCase();
+    const cacheKey = this._buildCacheKey(normalizedMethod, path, query, body);
+
+    if (normalizedMethod === "GET" && useCache && this.cache?.enabled) {
+      const cached = this.cache.get(cacheKey);
+      if (cached) {
+        this.logger.debug({ msg: "cache_hit", path });
+        return cached;
+      }
+    }
+
+    if (dedupe && this.inflight.has(cacheKey)) {
+      this.logger.debug({ msg: "request_deduped", path });
+      return this.inflight.get(cacheKey);
+    }
+
+    const run = this._send(normalizedMethod, path, query, body)
+      .then((result) => {
+        if (normalizedMethod === "GET" && useCache && this.cache?.enabled) {
+          this.cache.set(cacheKey, result, cacheTtlMs);
+        }
+        this.consecutiveForbidden = 0;
+        return result;
+      })
+      .catch((error) => {
+        const status = error?.status ?? null;
+        if (
+          status === null &&
+          parseErrorCode(error?.body) === 0 &&
+          !error.endpoint
+        ) {
+          const wrapped = new ERLCHttpError(
+            error.message || "Unknown request error",
+            {
+              status,
+              endpoint: path,
+              bucket:
+                this.routeBuckets.get(
+                  this._getRouteKey(normalizedMethod, path),
+                ) || "global",
+              body: null,
+            },
+          );
+          this._evaluateDisconnect(wrapped);
+          throw wrapped;
+        }
+
+        this._evaluateDisconnect(error);
+        throw error;
+      })
+      .finally(() => {
+        this.inflight.delete(cacheKey);
+      });
+
+    if (dedupe) {
+      this.inflight.set(cacheKey, run);
+    }
+
+    return run;
+  }
+
+  destroy(reasonError) {
+    this.destroyed = true;
+    this.terminalError = reasonError || this.terminalError;
+    this.rateLimiter.destroy(reasonError);
+    this.inflight.clear();
+  }
+}
+
+module.exports = RequestManager;

package/src/util/constants.js

@@ -0,0 +1,55 @@
+const API_ERROR_MESSAGES = {
+  0: "Unknown API error",
+  1001: "Error communicating with Roblox/private server",
+  1002: "Internal system error",
+  2000: "Missing server-key",
+  2001: "Invalid server-key format",
+  2002: "Invalid or expired server-key",
+  2003: "Invalid global API key",
+  2004: "Server-key banned",
+  3002: "Server offline (no players)",
+  4001: "Rate limited",
+  9998: "Restricted resource",
+  9999: "Module out of date",
+};
+
+const QUERY_FLAG_MAP = {
+  players: "Players",
+  staff: "Staff",
+  joinLogs: "JoinLogs",
+  queue: "Queue",
+  killLogs: "KillLogs",
+  commandLogs: "CommandLogs",
+  modCalls: "ModCalls",
+  vehicles: "Vehicles",
+};
+
+const DEFAULT_OPTIONS = {
+  serverKey: "",
+  globalKey: "",
+  logging: false,
+  logger: null,
+  cache: {
+    enabled: true,
+    ttlMs: 1500,
+    maxSize: 500,
+  },
+  rateLimit: {
+    enabled: true,
+    strictSerial: true,
+    perBucketConcurrency: 1,
+    globalConcurrency: 1,
+    unauthorizedThreshold: 3,
+  },
+  polling: {
+    enabled: true,
+    intervalMs: 2500,
+    bypassCache: true,
+  },
+};
+
+module.exports = {
+  API_ERROR_MESSAGES,
+  QUERY_FLAG_MAP,
+  DEFAULT_OPTIONS,
+};

package/src/util/errors.js

@@ -0,0 +1,79 @@
+const { API_ERROR_MESSAGES } = require("./constants");
+const {
+  ERLCHttpError,
+  ERLCAPIError,
+  RateLimitError,
+  KeyExpiredError,
+  KeyBannedError,
+  InvalidGlobalKeyError,
+  ServerOfflineError,
+  RestrictedError,
+  ModuleOutOfDateError,
+} = require("../errors");
+
+function parseErrorCode(body) {
+  const value = body?.ErrorCode ?? body?.errorCode ?? body?.Code ?? body?.code;
+  if (value === undefined || value === null || Number.isNaN(Number(value))) {
+    return 0;
+  }
+  return Number(value);
+}
+
+function parseErrorMessage(body, fallbackCode = 0) {
+  const message = body?.Message ?? body?.message ?? body?.error ?? body?.Error;
+  if (typeof message === "string" && message.trim()) {
+    return message;
+  }
+  return API_ERROR_MESSAGES[fallbackCode] ?? API_ERROR_MESSAGES[0];
+}
+
+function createApiError({
+  status,
+  endpoint,
+  bucket,
+  body,
+  retryAfterMs = 0,
+  resetEpochMs = null,
+}) {
+  const errorCode = parseErrorCode(body);
+  const message = parseErrorMessage(body, errorCode);
+  const common = {
+    status,
+    endpoint,
+    bucket,
+    body,
+    errorCode,
+    apiMessage: message,
+  };
+
+  if (status === 429 || errorCode === 4001) {
+    return new RateLimitError(message, {
+      ...common,
+      retryAfterMs,
+      resetEpochMs,
+    });
+  }
+
+  if (errorCode === 2002) return new KeyExpiredError(message, common);
+  if (errorCode === 2004) return new KeyBannedError(message, common);
+  if (errorCode === 2003) return new InvalidGlobalKeyError(message, common);
+  if (errorCode === 3002) return new ServerOfflineError(message, common);
+  if (errorCode === 9998) return new RestrictedError(message, common);
+  if (errorCode === 9999) return new ModuleOutOfDateError(message, common);
+
+  if (errorCode !== 0) {
+    return new ERLCAPIError(message, common);
+  }
+
+  return new ERLCHttpError(`HTTP ${status}`, {
+    status,
+    endpoint,
+    bucket,
+    body,
+  });
+}
+
+module.exports = {
+  createApiError,
+  parseErrorCode,
+};

package/src/util/logger.js

@@ -0,0 +1,39 @@
+const NOOP = () => {};
+
+function createLogger(logging, customLogger) {
+  if (!logging) {
+    return { info: NOOP, warn: NOOP, error: NOOP, debug: NOOP };
+  }
+
+  if (customLogger) {
+    return {
+      info:
+        typeof customLogger.info === "function"
+          ? customLogger.info.bind(customLogger)
+          : NOOP,
+      warn:
+        typeof customLogger.warn === "function"
+          ? customLogger.warn.bind(customLogger)
+          : NOOP,
+      error:
+        typeof customLogger.error === "function"
+          ? customLogger.error.bind(customLogger)
+          : NOOP,
+      debug:
+        typeof customLogger.debug === "function"
+          ? customLogger.debug.bind(customLogger)
+          : NOOP,
+    };
+  }
+
+  return {
+    info: (...args) => console.info(...args),
+    warn: (...args) => console.warn(...args),
+    error: (...args) => console.error(...args),
+    debug: (...args) => console.debug(...args),
+  };
+}
+
+module.exports = {
+  createLogger,
+};

package/src/util/normalize.js

@@ -0,0 +1,25 @@
+function normalizeServerResponse(raw = {}) {
+  return {
+    name: raw.Name ?? null,
+    ownerId: raw.OwnerId ?? null,
+    coOwnerIds: Array.isArray(raw.CoOwnerIds) ? raw.CoOwnerIds : [],
+    currentPlayers: raw.CurrentPlayers ?? 0,
+    maxPlayers: raw.MaxPlayers ?? 0,
+    joinKey: raw.JoinKey ?? null,
+    accVerifiedReq: raw.AccVerifiedReq ?? null,
+    teamBalance: raw.TeamBalance ?? null,
+    players: Array.isArray(raw.Players) ? raw.Players : [],
+    staff: raw.Staff ?? { Admins: {}, Mods: {}, Helpers: {} },
+    joinLogs: Array.isArray(raw.JoinLogs) ? raw.JoinLogs : [],
+    queue: Array.isArray(raw.Queue) ? raw.Queue : [],
+    killLogs: Array.isArray(raw.KillLogs) ? raw.KillLogs : [],
+    commandLogs: Array.isArray(raw.CommandLogs) ? raw.CommandLogs : [],
+    modCalls: Array.isArray(raw.ModCalls) ? raw.ModCalls : [],
+    vehicles: Array.isArray(raw.Vehicles) ? raw.Vehicles : [],
+    raw,
+  };
+}
+
+module.exports = {
+  normalizeServerResponse,
+};

package/src/util/options.js

@@ -0,0 +1,25 @@
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function mergeOptions(base, overrides) {
+  if (!isPlainObject(overrides)) {
+    return { ...base };
+  }
+
+  const output = { ...base };
+  const keys = Object.keys(overrides);
+  for (const key of keys) {
+    const nextValue = overrides[key];
+    if (isPlainObject(nextValue) && isPlainObject(output[key])) {
+      output[key] = mergeOptions(output[key], nextValue);
+    } else if (nextValue !== undefined) {
+      output[key] = nextValue;
+    }
+  }
+  return output;
+}
+
+module.exports = {
+  mergeOptions,
+};

package/src/util/stableStringify.js

@@ -0,0 +1,22 @@
+function sortValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortValue);
+  }
+  if (value && typeof value === "object") {
+    const sorted = {};
+    const keys = Object.keys(value).sort();
+    for (const key of keys) {
+      sorted[key] = sortValue(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+function stableStringify(value) {
+  return JSON.stringify(sortValue(value));
+}
+
+module.exports = {
+  stableStringify,
+};