erlc-v2 1.0.0-beta.0

package/src/events/Poller.js

@@ -0,0 +1,312 @@
+const {
+  diffByKey,
+  getPlayerKey,
+  getVehicleKey,
+  areEqual,
+  buildLogSignature,
+  parseLogCommand,
+} = require("./diff");
+
+class SeenSignatures {
+  constructor({ ttlMs = 0, maxEntries = 5000 } = {}) {
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+    this.map = new Map();
+  }
+
+  _prune() {
+    if (this.ttlMs > 0) {
+      const now = Date.now();
+      for (const [key, expiresAt] of this.map.entries()) {
+        if (expiresAt <= now) this.map.delete(key);
+      }
+    }
+    while (this.map.size > this.maxEntries) {
+      const oldest = this.map.keys().next().value;
+      this.map.delete(oldest);
+    }
+  }
+
+  seed(signature) {
+    this._prune();
+    this.map.set(signature, this.ttlMs > 0 ? Date.now() + this.ttlMs : 0);
+  }
+
+  checkAndAdd(signature) {
+    this._prune();
+    if (this.map.has(signature)) {
+      return false;
+    }
+    this.map.set(signature, this.ttlMs > 0 ? Date.now() + this.ttlMs : 0);
+    return true;
+  }
+}
+
+class Poller {
+  constructor(client, options = {}) {
+    this.client = client;
+    this.intervalMs = Math.max(250, options.intervalMs ?? 2500);
+    this.enabled = options.enabled !== false;
+    this.bypassCache = options.bypassCache !== false;
+    this.running = false;
+    this.inFlight = false;
+    this.timer = null;
+    this.readyEmitted = false;
+    this.previous = null;
+    this.seen = {
+      kills: new SeenSignatures(),
+      joins: new SeenSignatures(),
+      commands: new SeenSignatures(),
+      modCalls: new SeenSignatures(),
+    };
+  }
+
+  start() {
+    if (!this.enabled || this.running) return;
+    this.running = true;
+    this._schedule(0);
+  }
+
+  stop() {
+    this.running = false;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  destroy() {
+    this.stop();
+    this.previous = null;
+  }
+
+  _schedule(waitMs) {
+    if (!this.running) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this._tick();
+    }, waitMs);
+  }
+
+  _primeSeen(snapshot) {
+    for (const item of snapshot.killLogs)
+      this.seen.kills.seed(buildLogSignature("kills", item));
+    for (const item of snapshot.joinLogs)
+      this.seen.joins.seed(buildLogSignature("joins", item));
+    for (const item of snapshot.commandLogs)
+      this.seen.commands.seed(buildLogSignature("commands", item));
+    for (const item of snapshot.modCalls)
+      this.seen.modCalls.seed(buildLogSignature("modCalls", item));
+  }
+
+  _emitServerUpdate(current) {
+    const prevSummary = this.previous
+      ? {
+          name: this.previous.name,
+          ownerId: this.previous.ownerId,
+          currentPlayers: this.previous.currentPlayers,
+          maxPlayers: this.previous.maxPlayers,
+          teamBalance: this.previous.teamBalance,
+          accVerifiedReq: this.previous.accVerifiedReq,
+        }
+      : null;
+    const currentSummary = {
+      name: current.name,
+      ownerId: current.ownerId,
+      currentPlayers: current.currentPlayers,
+      maxPlayers: current.maxPlayers,
+      teamBalance: current.teamBalance,
+      accVerifiedReq: current.accVerifiedReq,
+    };
+    if (!prevSummary || !areEqual(prevSummary, currentSummary)) {
+      this.client.emit("serverUpdate", {
+        previous: prevSummary,
+        current: currentSummary,
+      });
+    }
+  }
+
+  _emitPlayerEvents(previous, current) {
+    const hasPlayersData = Array.isArray(current.raw?.Players);
+    if (hasPlayersData) {
+      const diff = diffByKey(previous.players, current.players, getPlayerKey);
+      for (const player of diff.added) {
+        this.client.emit("playerJoin", {
+          player,
+          source: "players",
+          snapshot: current,
+        });
+      }
+      for (const player of diff.removed) {
+        this.client.emit("playerLeave", {
+          player,
+          source: "players",
+          snapshot: current,
+        });
+      }
+      return;
+    }
+
+    for (const entry of current.joinLogs) {
+      const signature = buildLogSignature("joins", entry);
+      if (!this.seen.joins.checkAndAdd(signature)) continue;
+      if (entry?.Join === true) {
+        this.client.emit("playerJoin", {
+          player: entry.Player,
+          log: entry,
+          source: "joinLogs",
+          snapshot: current,
+        });
+      } else if (entry?.Join === false) {
+        this.client.emit("playerLeave", {
+          player: entry.Player,
+          log: entry,
+          source: "joinLogs",
+          snapshot: current,
+        });
+      }
+    }
+  }
+
+  _emitVehicleEvents(previous, current) {
+    const diff = diffByKey(previous.vehicles, current.vehicles, getVehicleKey);
+    for (const vehicle of diff.added) {
+      this.client.emit("vehicleSpawn", {
+        vehicle,
+        snapshot: current,
+      });
+    }
+    for (const vehicle of diff.removed) {
+      this.client.emit("vehicleDespawn", {
+        vehicle,
+        snapshot: current,
+      });
+    }
+  }
+
+  _emitQueueAndStaff(previous, current) {
+    if (!areEqual(previous.queue, current.queue)) {
+      this.client.emit("queueUpdate", {
+        previous: previous.queue,
+        current: current.queue,
+        snapshot: current,
+      });
+    }
+    if (!areEqual(previous.staff, current.staff)) {
+      this.client.emit("staffUpdate", {
+        previous: previous.staff,
+        current: current.staff,
+        snapshot: current,
+      });
+    }
+  }
+
+  _emitLogEvents(current) {
+    for (const kill of current.killLogs) {
+      const signature = buildLogSignature("kills", kill);
+      if (!this.seen.kills.checkAndAdd(signature)) continue;
+      this.client.emit("kill", {
+        kill,
+        signature,
+        snapshot: current,
+      });
+    }
+
+    for (const modCall of current.modCalls) {
+      const signature = buildLogSignature("modCalls", modCall);
+      if (!this.seen.modCalls.checkAndAdd(signature)) continue;
+      this.client.emit("modCall", {
+        modCall,
+        signature,
+        snapshot: current,
+      });
+    }
+
+    for (const command of current.commandLogs) {
+      const signature = buildLogSignature("commands", command);
+      if (!this.seen.commands.checkAndAdd(signature)) continue;
+      const payload = {
+        command,
+        signature,
+        snapshot: current,
+      };
+      this.client.emit("commandLog", payload);
+
+      const parsedLogCommand = parseLogCommand(command);
+      if (parsedLogCommand) {
+        this.client.emit("logCommand", {
+          ...payload,
+          parsed: parsedLogCommand,
+        });
+      }
+    }
+  }
+
+  _handleSnapshot(current) {
+    if (!this.previous) {
+      this._primeSeen(current);
+      this.previous = current;
+      if (!this.readyEmitted) {
+        this.readyEmitted = true;
+        this.client.emit("ready");
+      }
+      return;
+    }
+
+    this._emitServerUpdate(current);
+    this._emitPlayerEvents(this.previous, current);
+    this._emitVehicleEvents(this.previous, current);
+    this._emitQueueAndStaff(this.previous, current);
+    this._emitLogEvents(current);
+    this.previous = current;
+  }
+
+  async _tick() {
+    if (!this.running || this.inFlight) return;
+    this.inFlight = true;
+    this.client.logger.debug({
+      msg: "poll_cycle_start",
+      intervalMs: this.intervalMs,
+    });
+
+    try {
+      const snapshot = await this.client.server.fetch(
+        {
+          players: true,
+          staff: true,
+          joinLogs: true,
+          queue: true,
+          killLogs: true,
+          commandLogs: true,
+          modCalls: true,
+          vehicles: true,
+        },
+        {
+          bypassCache: this.bypassCache,
+          dedupe: false,
+        },
+      );
+
+      this._handleSnapshot(snapshot);
+    } catch (error) {
+      if (this.running) {
+        if (this.client.listenerCount("error") > 0) {
+          this.client.emit("error", error);
+        } else {
+          this.client.logger.error({
+            msg: "poll_cycle_error",
+            error: error?.message,
+          });
+        }
+      }
+    } finally {
+      this.inFlight = false;
+      if (this.running) {
+        this._schedule(this.intervalMs);
+      }
+    }
+  }
+}
+
+module.exports = Poller;

package/src/events/diff.js

@@ -0,0 +1,119 @@
+const { stableStringify } = require("../util/stableStringify");
+
+function getPlayerKey(player) {
+  if (!player) return "";
+  if (typeof player === "string") return player;
+  return String(player.Player ?? player.Name ?? "");
+}
+
+function getVehicleKey(vehicle) {
+  if (!vehicle) return "";
+  const name = vehicle.Name ?? "";
+  const owner = vehicle.Owner ?? "";
+  const texture = vehicle.Texture ?? "";
+  const colorHex = vehicle.ColorHex ?? "";
+  const colorName = vehicle.ColorName ?? "";
+  return `${name}|${owner}|${texture}|${colorHex}|${colorName}`;
+}
+
+function diffByKey(previous, current, keyFn) {
+  const prevList = Array.isArray(previous) ? previous : [];
+  const currList = Array.isArray(current) ? current : [];
+
+  const prevMap = new Map();
+  for (const item of prevList) {
+    prevMap.set(keyFn(item), item);
+  }
+
+  const currMap = new Map();
+  for (const item of currList) {
+    currMap.set(keyFn(item), item);
+  }
+
+  const added = [];
+  const removed = [];
+
+  for (const [key, value] of currMap.entries()) {
+    if (!prevMap.has(key)) added.push(value);
+  }
+  for (const [key, value] of prevMap.entries()) {
+    if (!currMap.has(key)) removed.push(value);
+  }
+
+  return { added, removed };
+}
+
+function areEqual(a, b) {
+  return stableStringify(a) === stableStringify(b);
+}
+
+function buildLogSignature(type, item) {
+  switch (type) {
+    case "kills":
+      return stableStringify({
+        t: item?.Timestamp ?? null,
+        killer: item?.Killer ?? "",
+        killed: item?.Killed ?? "",
+        weapon: item?.Weapon ?? "",
+      });
+    case "joins":
+      return stableStringify({
+        t: item?.Timestamp ?? null,
+        player: item?.Player ?? "",
+        join: item?.Join ?? null,
+      });
+    case "commands":
+      return stableStringify({
+        t: item?.Timestamp ?? null,
+        player: item?.Player ?? "",
+        command: item?.Command ?? "",
+      });
+    case "modCalls":
+      return stableStringify({
+        t: item?.Timestamp ?? null,
+        caller: item?.Caller ?? "",
+        moderator: item?.Moderator ?? "",
+      });
+    default:
+      return stableStringify(item);
+  }
+}
+
+function parseCommand(commandLogEntry) {
+  const raw = String(commandLogEntry?.Command ?? "").trim();
+  if (!raw) return null;
+
+  const segments = raw.split(/\s+/);
+  const command = String(segments[0] ?? "").toLowerCase();
+  const args = segments.slice(1).join(" ");
+
+  return {
+    raw,
+    command,
+    args,
+    segments,
+  };
+}
+
+function parseLogCommand(commandLogEntry) {
+  const parsed = parseCommand(commandLogEntry);
+  if (!parsed || parsed.command !== ":log") return null;
+
+  const segments = parsed.segments.slice(1);
+  return {
+    raw: parsed.raw,
+    keyword: segments[0] ?? "",
+    args: segments.slice(1).join(" "),
+    segments,
+  };
+}
+
+module.exports = {
+  getPlayerKey,
+  getVehicleKey,
+  diffByKey,
+  areEqual,
+  buildLogSignature,
+  parseCommand,
+  parseLogCommand,
+};

package/src/index.js

@@ -0,0 +1,7 @@
+const Client = require("./Client");
+const errors = require("./errors");
+
+module.exports = {
+  Client,
+  ...errors,
+};

package/src/rest/RateLimiter.js

@@ -0,0 +1,163 @@
+class RateLimiter {
+  constructor(options = {}, logger) {
+    this.enabled = options.enabled !== false;
+    this.strictSerial = options.strictSerial !== false;
+    this.perBucketConcurrency = this.strictSerial
+      ? 1
+      : Math.max(1, options.perBucketConcurrency ?? 1);
+    this.globalConcurrency = this.strictSerial
+      ? 1
+      : Math.max(1, options.globalConcurrency ?? 4);
+    this.logger = logger;
+    this.buckets = new Map();
+    this.globalActive = 0;
+    this.destroyed = false;
+  }
+
+  _createState(bucketId) {
+    return {
+      id: bucketId,
+      limit: Infinity,
+      remaining: Infinity,
+      resetEpochMs: 0,
+      blockedUntilMs: 0,
+      active: 0,
+      queue: [],
+      timer: null,
+    };
+  }
+
+  _getState(bucketId) {
+    if (!this.buckets.has(bucketId)) {
+      this.buckets.set(bucketId, this._createState(bucketId));
+    }
+    return this.buckets.get(bucketId);
+  }
+
+  _clearTimer(state) {
+    if (state.timer) {
+      clearTimeout(state.timer);
+      state.timer = null;
+    }
+  }
+
+  _scheduleTimer(state, waitMs) {
+    this._clearTimer(state);
+    state.timer = setTimeout(() => {
+      state.timer = null;
+      this._drain(state.id);
+    }, waitMs);
+  }
+
+  _canRun(state) {
+    if (!this.enabled) return true;
+    if (this.destroyed) return false;
+    if (state.active >= this.perBucketConcurrency) return false;
+    if (this.globalActive >= this.globalConcurrency) return false;
+
+    const now = Date.now();
+    const resetBlock =
+      Number.isFinite(state.remaining) && state.remaining <= 0
+        ? state.resetEpochMs
+        : 0;
+    const blockedUntil = Math.max(state.blockedUntilMs || 0, resetBlock || 0);
+    if (blockedUntil > now) {
+      this.logger.debug({
+        msg: "rate_limit_wait",
+        bucket: state.id,
+        waitMs: blockedUntil - now,
+      });
+      this._scheduleTimer(state, Math.max(10, blockedUntil - now));
+      return false;
+    }
+    return true;
+  }
+
+  _drain(bucketId) {
+    const state = this._getState(bucketId);
+    if (!state.queue.length) return;
+    if (!this._canRun(state)) return;
+
+    const job = state.queue.shift();
+    state.active += 1;
+    this.globalActive += 1;
+
+    Promise.resolve()
+      .then(job.run)
+      .then(job.resolve, job.reject)
+      .finally(() => {
+        state.active -= 1;
+        this.globalActive -= 1;
+        this._drain(bucketId);
+      });
+  }
+
+  schedule(bucketId, run) {
+    if (this.destroyed) {
+      return Promise.reject(new Error("RateLimiter destroyed"));
+    }
+    const state = this._getState(bucketId || "global");
+    return new Promise((resolve, reject) => {
+      state.queue.push({ run, resolve, reject });
+      this._drain(state.id);
+    });
+  }
+
+  update(bucketId, headers = {}) {
+    const state = this._getState(bucketId || "global");
+    const limit = headers.limit != null ? Number(headers.limit) : Number.NaN;
+    const remaining =
+      headers.remaining != null ? Number(headers.remaining) : Number.NaN;
+    const resetEpochMs =
+      headers.resetEpochMs != null ? Number(headers.resetEpochMs) : Number.NaN;
+
+    if (!Number.isNaN(limit) && Number.isFinite(limit)) state.limit = limit;
+    if (!Number.isNaN(remaining) && Number.isFinite(remaining))
+      state.remaining = remaining;
+    if (!Number.isNaN(resetEpochMs) && Number.isFinite(resetEpochMs))
+      state.resetEpochMs = resetEpochMs;
+
+    if (state.remaining <= 0 && state.resetEpochMs > Date.now()) {
+      state.blockedUntilMs = Math.max(
+        state.blockedUntilMs || 0,
+        state.resetEpochMs,
+      );
+    }
+    this._drain(state.id);
+  }
+
+  block(bucketId, untilMs) {
+    const state = this._getState(bucketId || "global");
+    state.blockedUntilMs = Math.max(state.blockedUntilMs || 0, untilMs);
+    if (state.blockedUntilMs > Date.now()) {
+      const waitMs = state.blockedUntilMs - Date.now();
+      this.logger.debug({
+        msg: "rate_limit_block",
+        bucket: state.id,
+        waitMs,
+      });
+      this._scheduleTimer(state, Math.max(10, waitMs));
+    }
+  }
+
+  clearBucket(bucketId) {
+    const state = this.buckets.get(bucketId);
+    if (!state) return;
+    this._clearTimer(state);
+    this.buckets.delete(bucketId);
+  }
+
+  destroy(error) {
+    this.destroyed = true;
+    for (const state of this.buckets.values()) {
+      this._clearTimer(state);
+      while (state.queue.length) {
+        const job = state.queue.shift();
+        job.reject(error || new Error("RateLimiter destroyed"));
+      }
+    }
+    this.buckets.clear();
+  }
+}
+
+module.exports = RateLimiter;