@crowdedkingdoms/crowdyjs 8.4.6 → 8.6.0

package/dist/metrics.js

@@ -0,0 +1,158 @@
+/**
+ * Realtime traffic metrics — SDK-owned counters for every spatial message the
+ * client sends (the `client.udp.send*` mutations, including the ones issued
+ * internally by the World Stores layers) and every notification delivered on
+ * the shared `udpNotifications` subscription.
+ *
+ * Exposed as `client.metrics`; call {@link RealtimeMetrics.snapshot} from a
+ * HUD/diagnostics loop. Byte counts measure the app-defined **payload** field
+ * of each message (`state` / `audioData` / `text` / `payload` / `voxelState`),
+ * not wire framing or GraphQL envelope overhead.
+ */
+const WINDOW_SECONDS = 10;
+/**
+ * Counter store behind `client.metrics`. All methods are cheap (plain counter
+ * increments and a fixed ring of per-second rate buckets), so recording on
+ * every message adds no meaningful overhead to the send/receive hot paths.
+ */
+export class RealtimeMetrics {
+    /** @param now - Clock override for tests. Defaults to `Date.now`. */
+    constructor(now = Date.now) {
+        this.now = now;
+        this.perKind = new Map();
+        this.totalSent = 0;
+        this.totalReceived = 0;
+        this.totalBytesSent = 0;
+        this.totalBytesReceived = 0;
+        this.buckets = Array.from({ length: WINDOW_SECONDS }, () => ({
+            second: -1,
+            sent: 0,
+            received: 0,
+            bytesSent: 0,
+            bytesReceived: 0,
+        }));
+        this.startedAtMs = this.now();
+    }
+    /** Record one outbound message. Called by the SDK's `udp.send*` methods. */
+    recordSent(kind, payloadBytes) {
+        this.totalSent += 1;
+        this.totalBytesSent += payloadBytes;
+        const entry = this.kindEntry(kind);
+        entry.sent.messages += 1;
+        entry.sent.bytes += payloadBytes;
+        const bucket = this.bucket();
+        bucket.sent += 1;
+        bucket.bytesSent += payloadBytes;
+    }
+    /** Record one delivered notification. Called by the realtime dispatch. */
+    recordReceived(kind, payloadBytes) {
+        this.totalReceived += 1;
+        this.totalBytesReceived += payloadBytes;
+        const entry = this.kindEntry(kind);
+        entry.received.messages += 1;
+        entry.received.bytes += payloadBytes;
+        const bucket = this.bucket();
+        bucket.received += 1;
+        bucket.bytesReceived += payloadBytes;
+    }
+    /**
+     * A point-in-time copy of all counters plus rates averaged over the sliding
+     * window. Safe to call every frame; allocation is proportional to the number
+     * of distinct message kinds.
+     */
+    snapshot() {
+        const nowMs = this.now();
+        const currentSecond = Math.floor(nowMs / 1000);
+        let sent = 0;
+        let received = 0;
+        let bytesSent = 0;
+        let bytesReceived = 0;
+        for (const bucket of this.buckets) {
+            if (bucket.second < 0 || currentSecond - bucket.second >= WINDOW_SECONDS)
+                continue;
+            sent += bucket.sent;
+            received += bucket.received;
+            bytesSent += bucket.bytesSent;
+            bytesReceived += bucket.bytesReceived;
+        }
+        // Average over the tracked lifetime when younger than the full window so
+        // early rates aren't diluted by empty seconds that never happened.
+        const elapsedSeconds = Math.max(1, Math.min(WINDOW_SECONDS, (nowMs - this.startedAtMs) / 1000));
+        const perKind = {};
+        for (const [kind, entry] of this.perKind) {
+            perKind[kind] = {
+                sent: { ...entry.sent },
+                received: { ...entry.received },
+            };
+        }
+        return {
+            totals: {
+                sent: this.totalSent,
+                received: this.totalReceived,
+                bytesSent: this.totalBytesSent,
+                bytesReceived: this.totalBytesReceived,
+            },
+            perKind,
+            rates: {
+                sentPerSecond: sent / elapsedSeconds,
+                receivedPerSecond: received / elapsedSeconds,
+                bytesSentPerSecond: bytesSent / elapsedSeconds,
+                bytesReceivedPerSecond: bytesReceived / elapsedSeconds,
+            },
+            startedAt: this.startedAtMs,
+        };
+    }
+    /** Zero every counter and restart the rate window. */
+    reset() {
+        this.totalSent = 0;
+        this.totalReceived = 0;
+        this.totalBytesSent = 0;
+        this.totalBytesReceived = 0;
+        this.perKind.clear();
+        for (const bucket of this.buckets) {
+            bucket.second = -1;
+            bucket.sent = 0;
+            bucket.received = 0;
+            bucket.bytesSent = 0;
+            bucket.bytesReceived = 0;
+        }
+        this.startedAtMs = this.now();
+    }
+    kindEntry(kind) {
+        let entry = this.perKind.get(kind);
+        if (!entry) {
+            entry = {
+                sent: { messages: 0, bytes: 0 },
+                received: { messages: 0, bytes: 0 },
+            };
+            this.perKind.set(kind, entry);
+        }
+        return entry;
+    }
+    bucket() {
+        const second = Math.floor(this.now() / 1000);
+        const bucket = this.buckets[second % WINDOW_SECONDS];
+        if (bucket.second !== second) {
+            bucket.second = second;
+            bucket.sent = 0;
+            bucket.received = 0;
+            bucket.bytesSent = 0;
+            bucket.bytesReceived = 0;
+        }
+        return bucket;
+    }
+}
+/**
+ * The size of a message's app-defined payload field: the first of `state`,
+ * `audioData`, `text`, `payload`, or `voxelState` present as a string. Base64
+ * and ASCII payloads measure 1 byte per character; multi-byte UTF-8 text is
+ * approximated by its UTF-16 length.
+ */
+export function payloadBytesOf(record) {
+    for (const key of ['state', 'audioData', 'text', 'payload', 'voxelState']) {
+        const value = record[key];
+        if (typeof value === 'string')
+            return value.length;
+    }
+    return 0;
+}

package/dist/realtime.d.ts

@@ -2,6 +2,7 @@ import type { SessionStore } from './session.js';
 import type { CrowdyLogger } from './logger.js';
 import { CrowdyRealtimeError } from './errors.js';
 import type { LbCookieStore } from './lb-cookie-store.js';
+import type { RealtimeMetrics } from './metrics.js';
 import { type UdpNotificationsSubscription } from './generated/graphql.js';
 /**
  * Lifecycle state of the realtime WebSocket connection, as reported by
@@ -224,6 +225,7 @@ export interface RealtimeConfig {
  */
 export declare class RealtimeClient {
     private readonly session;
+    private readonly metrics?;
     private readonly wsUrl;
     private readonly logger;
     private readonly retryAttempts;
@@ -249,8 +251,10 @@ export declare class RealtimeClient {
      *   the token tears the connection down (emitting an `AUTH_CLEARED`
      *   {@link CrowdyRealtimeError}), while a token change made while connected
      *   forces a reconnect using the new token.
+     * @param metrics - Optional traffic counters (`client.metrics`); each
+     *   delivered notification is recorded once, regardless of subscriber count.
      */
-    constructor(config: RealtimeConfig | undefined, session: SessionStore);
+    constructor(config: RealtimeConfig | undefined, session: SessionStore, metrics?: RealtimeMetrics | undefined);
     /**
      * The current connection state.
      *

package/dist/realtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"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"}

package/dist/realtime.js

@@ -2,6 +2,7 @@ import { print } from 'graphql';
 import { createClient } from 'graphql-ws';
 import { silentLogger } from './logger.js';
 import { CrowdyRealtimeError } from './errors.js';
+import { payloadBytesOf } from './metrics.js';
 import { UdpNotificationsDocument, } from './generated/graphql.js';
 /**
  * Manages the single WebSocket subscription to the game-api's
@@ -30,9 +31,12 @@ export class RealtimeClient {
      *   the token tears the connection down (emitting an `AUTH_CLEARED`
      *   {@link CrowdyRealtimeError}), while a token change made while connected
      *   forces a reconnect using the new token.
+     * @param metrics - Optional traffic counters (`client.metrics`); each
+     *   delivered notification is recorded once, regardless of subscriber count.
      */
-    constructor(config = {}, session) {
+    constructor(config = {}, session, metrics) {
         this.session = session;
+        this.metrics = metrics;
         this.client = null;
         this.release = null;
         this.desired = false;
@@ -293,6 +297,7 @@ export class RealtimeClient {
         this.ensureSubscription();
     }
     dispatch(notification) {
+        this.metrics?.recordReceived(notificationKind(notification.__typename), payloadBytesOf(notification));
         this.resolvePending(notification);
         // A non-retryable connection event (e.g. APP_ID_REQUIRED, AUTH_REQUIRED)
         // means the server completed the subscription and resubscribing would just
@@ -405,6 +410,26 @@ export class RealtimeClient {
         }
     }
 }
+/** GraphQL `__typename` → the handler-style kind name used by `client.metrics`. */
+const NOTIFICATION_KINDS = {
+    ActorUpdateNotification: 'actorUpdate',
+    ActorUpdateResponse: 'actorUpdateResponse',
+    VoxelUpdateNotification: 'voxelUpdate',
+    VoxelUpdateResponse: 'voxelUpdateResponse',
+    ClientAudioNotification: 'audio',
+    ClientTextNotification: 'text',
+    ClientEventNotification: 'clientEvent',
+    ServerEventNotification: 'serverEvent',
+    SingleActorMessageNotification: 'singleActorMessage',
+    ChannelMessageNotification: 'channelMessage',
+    GenericErrorResponse: 'genericError',
+    RealtimeConnectionEvent: 'connectionEvent',
+};
+function notificationKind(typename) {
+    if (!typename)
+        return 'unknown';
+    return NOTIFICATION_KINDS[typename] ?? typename;
+}
 function isNodeRuntime() {
     return (typeof process !== 'undefined' &&
         typeof process.versions?.node === 'string');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/crowdyjs",
-  "version": "8.4.6",
+  "version": "8.6.0",
   "description": "Client SDK for Crowded Kingdoms GraphQL API with UDP proxy support",
   "type": "module",
   "main": "dist/index.js",