@privateclaw/privateclaw-relay 0.1.7 → 0.1.9

package/dist/relay-server.d.ts

@@ -1,3 +1,4 @@
+import { type RelayAdminMetricsStore } from "./admin-metrics-store.js";
 import type { RelayServerConfig } from "./config.js";
 import { type EncryptedFrameCache } from "./frame-cache.js";
 import { type RelayPushRegistrationStore } from "./push-registration-store.js";
@@ -33,6 +34,7 @@ export interface RelayServerDependencies {
     sessionStore?: RelaySessionStore;
     pushRegistrationStore?: RelayPushRegistrationStore;
     pushNotifier?: RelayPushNotifier;
+    adminMetricsStore?: RelayAdminMetricsStore;
     cluster?: RelayClusterClient;
     clusterFactory?: (callbacks: RelayClusterCallbacks) => RelayClusterClient;
     now?: () => number;

package/dist/relay-server.js

@@ -1,12 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { createServer, } from "node:http";
 import { WebSocket, WebSocketServer } from "ws";
+import { handleRelayAdminRequest } from "./admin-api.js";
+import { createRelayAdminMetricsStore, } from "./admin-metrics-store.js";
 import { createEncryptedFrameCache, } from "./frame-cache.js";
 import { createRelayPushRegistrationStore, } from "./push-registration-store.js";
 import { createRelayPushNotifier, } from "./push-notifier.js";
 import { createRedisRelayClusterClient, RelayClaimConflictError, } from "./relay-cluster.js";
 import { createRelaySessionStore, } from "./session-store.js";
-import { serveRelayWebRequest } from "./relay-web.js";
+import { resolveRelayAdminWebRootDir, serveRelayWebRequest, } from "./relay-web.js";
 const HEARTBEAT_INTERVAL_MS = 15_000;
 const PUSH_WAKE_COOLDOWN_MS = 5_000;
 const DEFAULT_PROTOCOL_MESSAGE_BYTES = 24 * 1024 * 1024;
@@ -65,6 +67,14 @@ class FixedWindowRateLimiter {
     now() {
         return this.params.now?.() ?? Date.now();
     }
+    async recordAdminMetric(action, label) {
+        try {
+            await action();
+        }
+        catch (error) {
+            console.error(`[privateclaw-relay] failed to record ${label}`, error);
+        }
+    }
     allow(key) {
         const now = this.now();
         const existing = this.entries.get(key);
@@ -194,6 +204,14 @@ class SessionHub {
     now() {
         return this.params.now?.() ?? Date.now();
     }
+    async recordAdminMetric(action, label) {
+        try {
+            await action();
+        }
+        catch (error) {
+            console.error(`[privateclaw-relay] failed to record ${label}`, error);
+        }
+    }
     wakeKey(sessionId, appId) {
         return `${sessionId}:${appId}`;
     }
@@ -255,7 +273,7 @@ class SessionHub {
             await this.cluster.subscribeApp(binding.sessionId, binding.appId);
         }
     }
-    async forgetLocalAppBinding(appSocket, binding) {
+    async forgetLocalAppBinding(appSocket, binding, reason) {
         const appSockets = this.sessionApps.get(binding.sessionId);
         if (!appSockets || appSockets.get(binding.appId) !== appSocket) {
             this.appSessions.delete(appSocket);
@@ -270,6 +288,9 @@ class SessionHub {
             await this.cluster.unsubscribeApp(binding.sessionId, binding.appId);
             await this.cluster.releaseApp(binding);
         }
+        if (reason) {
+            await this.recordAdminMetric(() => this.params.adminMetricsStore.recordAppDetached(binding.sessionId, binding.appId, this.now(), reason), "app detach metrics");
+        }
         return true;
     }
     async attachProvider(providerId, providerSocket) {
@@ -309,6 +330,7 @@ class SessionHub {
         };
         await this.params.sessionStore.saveSession(session);
         await this.rememberLocalProviderSession(providerId, session.sessionId);
+        await this.recordAdminMetric(() => this.params.adminMetricsStore.recordSessionCreated(session, this.now()), "session creation metrics");
         return session;
     }
     async requireSession(sessionId) {
@@ -357,6 +379,7 @@ class SessionHub {
         };
         await this.params.sessionStore.saveSession(renewedSession);
         await this.params.pushRegistrationStore.touchSession(sessionId, renewedSession.expiresAt);
+        await this.recordAdminMetric(() => this.params.adminMetricsStore.recordSessionRenewed(renewedSession, this.now()), "session renewal metrics");
         return renewedSession;
     }
     async registerAppPushToken(sessionId, appId, token) {
@@ -479,6 +502,7 @@ class SessionHub {
             }
         }
         await this.rememberLocalAppBinding(binding, appSocket);
+        await this.recordAdminMetric(() => this.params.adminMetricsStore.recordAppAttached(session, normalizedAppId, this.now()), "app attach metrics");
         return session;
     }
     deliverLocalToApp(sessionId, envelope, targetAppId) {
@@ -583,7 +607,7 @@ class SessionHub {
             if (!binding || binding.appId !== appId) {
                 continue;
             }
-            await this.forgetLocalAppBinding(appSocket, binding);
+            await this.forgetLocalAppBinding(appSocket, binding, reason);
             sendJson(appSocket, {
                 type: "relay:session_closed",
                 sessionId,
@@ -611,6 +635,7 @@ class SessionHub {
         await this.params.sessionStore.deleteSession(sessionId);
         await this.params.pushRegistrationStore.clearSession(sessionId);
         this.clearWakeState(sessionId);
+        await this.recordAdminMetric(() => this.params.adminMetricsStore.recordSessionClosed(sessionId, reason, this.now()), "session close metrics");
         if (!this.hasLocalSession(sessionId) && !this.cluster) {
             await this.params.frameCache.clear(sessionId);
             return;
@@ -661,7 +686,7 @@ class SessionHub {
         if (!binding) {
             return;
         }
-        await this.forgetLocalAppBinding(appSocket, binding);
+        await this.forgetLocalAppBinding(appSocket, binding, "app_disconnected");
     }
     async closeLocalApp(sessionId, appId, reason) {
         const appSocket = this.sessionApps.get(sessionId)?.get(appId);
@@ -672,7 +697,7 @@ class SessionHub {
         if (!binding) {
             return;
         }
-        await this.forgetLocalAppBinding(appSocket, binding);
+        await this.forgetLocalAppBinding(appSocket, binding, reason);
         sendJson(appSocket, {
             type: "relay:session_closed",
             sessionId,
@@ -734,6 +759,36 @@ class SessionHub {
             appBindings,
         });
     }
+    getAdminLocalSnapshot() {
+        const providerIds = [...this.providerSockets.entries()]
+            .filter(([, socket]) => socket.readyState === WebSocket.OPEN)
+            .map(([providerId]) => providerId)
+            .sort();
+        const participantBindings = [];
+        const sessionIds = new Set(this.sessionProviders.keys());
+        for (const [appSocket, binding] of this.appSessions.entries()) {
+            const currentSocket = this.sessionApps.get(binding.sessionId)?.get(binding.appId);
+            if (currentSocket !== appSocket || appSocket.readyState !== WebSocket.OPEN) {
+                continue;
+            }
+            participantBindings.push({
+                sessionId: binding.sessionId,
+                appId: binding.appId,
+            });
+            sessionIds.add(binding.sessionId);
+        }
+        participantBindings.sort((left, right) => left.sessionId.localeCompare(right.sessionId) ||
+            left.appId.localeCompare(right.appId));
+        return {
+            activeProviders: providerIds.length,
+            activeApps: participantBindings.length,
+            localSessions: sessionIds.size,
+            providerIds,
+            sessionIds: [...sessionIds].sort(),
+            participantBindings,
+            memoryUsage: process.memoryUsage(),
+        };
+    }
     async closeAll(reason) {
         const sessionIds = new Set([
             ...this.sessionProviders.keys(),
@@ -773,12 +828,21 @@ export function createRelayServer(config, deps = {}) {
             fcmClientEmail: config.fcmClientEmail,
             fcmPrivateKey: config.fcmPrivateKey,
         });
+    const ownsAdminMetricsStore = !deps.adminMetricsStore;
+    const adminMetricsStore = deps.adminMetricsStore ??
+        createRelayAdminMetricsStore({
+            ...(config.redisUrl ? { redisUrl: config.redisUrl } : {}),
+        });
+    const relayStartedAt = Date.now();
+    const adminWebRootDir = config.adminToken &&
+        (config.adminWebRootDir ?? resolveRelayAdminWebRootDir());
     const sessionHub = new SessionHub({
         defaultTtlMs: config.sessionTtlMs,
         frameCache,
         sessionStore,
         pushRegistrationStore,
         pushNotifier,
+        adminMetricsStore,
         ...(deps.now ? { now: deps.now } : {}),
     });
     const appMessageRateLimiter = new FixedWindowRateLimiter({
@@ -826,6 +890,22 @@ export function createRelayServer(config, deps = {}) {
     let startedPort = config.port;
     let startedUrl = "";
     let started = false;
+    async function recordAdminMetric(action, label) {
+        try {
+            await action();
+        }
+        catch (error) {
+            console.error(`[privateclaw-relay] failed to record ${label}`, error);
+        }
+    }
+    async function recordInstanceHeartbeat() {
+        await recordAdminMetric(() => adminMetricsStore.recordInstanceHeartbeat({
+            instanceId: clusterNodeId,
+            startedAt: relayStartedAt,
+            recordedAt: deps.now?.() ?? Date.now(),
+            snapshot: sessionHub.getAdminLocalSnapshot(),
+        }), "relay instance heartbeat");
+    }
     async function handleHttpRequest(request, response) {
         const url = new URL(request.url ?? "/", `http://${request.headers.host ?? `${config.host}:${startedPort}`}`);
         try {
@@ -836,6 +916,29 @@ export function createRelayServer(config, deps = {}) {
                 response.end(JSON.stringify({ ok: true, sessions, instanceId: clusterNodeId }));
                 return;
             }
+            const handledAdminApi = await handleRelayAdminRequest({
+                request,
+                response,
+                url,
+                metricsStore: adminMetricsStore,
+                ...(config.adminToken ? { adminToken: config.adminToken } : {}),
+                ...(deps.now ? { now: deps.now } : {}),
+            });
+            if (handledAdminApi) {
+                return;
+            }
+            if (adminWebRootDir && url.pathname.startsWith("/admin")) {
+                const handledAdminWeb = await serveRelayWebRequest({
+                    request,
+                    response,
+                    url,
+                    webRootDir: adminWebRootDir,
+                    mountPath: "/admin",
+                });
+                if (handledAdminWeb) {
+                    return;
+                }
+            }
             if (config.webRootDir) {
                 const handled = await serveRelayWebRequest({
                     request,
@@ -885,6 +988,7 @@ export function createRelayServer(config, deps = {}) {
         void sessionHub.refreshClusterPresence().catch((error) => {
             console.error("[privateclaw-relay] failed to refresh relay presence", error);
         });
+        void recordInstanceHeartbeat();
     }, HEARTBEAT_INTERVAL_MS);
     function terminateSockets(server) {
         for (const socket of server.clients) {
@@ -898,12 +1002,14 @@ export function createRelayServer(config, deps = {}) {
     }
     async function handleProviderMessage(socket, raw) {
         let requestId;
+        let requestType = "unknown";
         try {
             assertMessageSizeWithinLimit(raw, maxMessageBytes, "Provider");
             const message = parseJson(raw);
             if (!isObject(message) || typeof message.type !== "string") {
                 throw new RelayProtocolError("invalid_message", "Provider message is missing a type field.");
             }
+            requestType = message.type;
             if ("requestId" in message &&
                 typeof message.requestId === "string" &&
                 message.requestId !== "") {
@@ -944,6 +1050,12 @@ export function createRelayServer(config, deps = {}) {
                         sessionId: session.sessionId,
                         expiresAt: new Date(session.expiresAt).toISOString(),
                     });
+                    await recordInstanceHeartbeat();
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "provider",
+                        type: requestType,
+                        ok: true,
+                    }), "provider request metrics");
                     return;
                 }
                 case "provider:renew_session": {
@@ -967,6 +1079,12 @@ export function createRelayServer(config, deps = {}) {
                         sessionId: session.sessionId,
                         expiresAt: new Date(session.expiresAt).toISOString(),
                     });
+                    await recordInstanceHeartbeat();
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "provider",
+                        type: requestType,
+                        ok: true,
+                    }), "provider request metrics");
                     return;
                 }
                 case "provider:frame": {
@@ -978,7 +1096,16 @@ export function createRelayServer(config, deps = {}) {
                         typeof message.targetAppId !== "string") {
                         throw new RelayProtocolError("invalid_target_app_id", "provider:frame targetAppId must be a string when provided.");
                     }
-                    await sessionHub.forwardToApp(socket, message.sessionId, message.envelope, message.targetAppId);
+                    const sessionIdValue = message.sessionId;
+                    await sessionHub.forwardToApp(socket, sessionIdValue, message.envelope, message.targetAppId);
+                    await recordAdminMetric(async () => {
+                        await adminMetricsStore.recordProviderFrame(sessionIdValue, deps.now?.() ?? Date.now());
+                        await adminMetricsStore.recordRequest({
+                            actor: "provider",
+                            type: requestType,
+                            ok: true,
+                        });
+                    }, "provider frame metrics");
                     return;
                 }
                 case "provider:close_session": {
@@ -988,6 +1115,12 @@ export function createRelayServer(config, deps = {}) {
                     await sessionHub.closeSessionForProvider(socket, message.sessionId, typeof message.reason === "string"
                         ? message.reason
                         : "provider_closed");
+                    await recordInstanceHeartbeat();
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "provider",
+                        type: requestType,
+                        ok: true,
+                    }), "provider request metrics");
                     return;
                 }
                 case "provider:close_app": {
@@ -999,6 +1132,12 @@ export function createRelayServer(config, deps = {}) {
                     await sessionHub.closeAppForProvider(socket, message.sessionId, message.appId, typeof message.reason === "string"
                         ? message.reason
                         : "provider_closed_app");
+                    await recordInstanceHeartbeat();
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "provider",
+                        type: requestType,
+                        ok: true,
+                    }), "provider request metrics");
                     return;
                 }
                 default:
@@ -1007,6 +1146,14 @@ export function createRelayServer(config, deps = {}) {
         }
         catch (error) {
             const relayError = toRelayProtocolError(error);
+            await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                actor: "provider",
+                type: requestType === "unknown" && relayError.code === "invalid_json"
+                    ? "invalid_json"
+                    : requestType,
+                ok: false,
+                errorCode: relayError.code,
+            }), "provider error metrics");
             sendJson(socket, {
                 type: "relay:error",
                 code: relayError.code,
@@ -1016,6 +1163,7 @@ export function createRelayServer(config, deps = {}) {
         }
     }
     async function handleAppMessage(socket, sessionId, appId, raw) {
+        let requestType = "unknown";
         try {
             assertMessageSizeWithinLimit(raw, maxMessageBytes, "App");
             if (!appMessageRateLimiter.allow(`${sessionId}:${appId}`)) {
@@ -1025,21 +1173,40 @@ export function createRelayServer(config, deps = {}) {
             if (!isObject(message) || typeof message.type !== "string") {
                 throw new RelayProtocolError("invalid_message", "App message is missing a type field.");
             }
+            requestType = message.type;
             switch (message.type) {
                 case "app:frame":
                     if (!isEncryptedEnvelope(message.envelope)) {
                         throw new RelayProtocolError("invalid_frame", "app:frame must include a valid encrypted envelope.");
                     }
                     await sessionHub.forwardToProvider(sessionId, message.envelope);
+                    await recordAdminMetric(async () => {
+                        await adminMetricsStore.recordAppFrame(sessionId, appId, deps.now?.() ?? Date.now());
+                        await adminMetricsStore.recordRequest({
+                            actor: "app",
+                            type: requestType,
+                            ok: true,
+                        });
+                    }, "app frame metrics");
                     return;
                 case "app:register_push":
                     if (typeof message.token !== "string") {
                         throw new RelayProtocolError("invalid_push_token", "app:register_push requires a string token.");
                     }
                     await sessionHub.registerAppPushToken(sessionId, appId, message.token);
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "app",
+                        type: requestType,
+                        ok: true,
+                    }), "app request metrics");
                     return;
                 case "app:unregister_push":
                     await sessionHub.unregisterAppPushToken(sessionId, appId);
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "app",
+                        type: requestType,
+                        ok: true,
+                    }), "app request metrics");
                     return;
                 default:
                     throw new RelayProtocolError("unsupported_message", `Unsupported app message type: ${String(message.type)}`);
@@ -1047,6 +1214,14 @@ export function createRelayServer(config, deps = {}) {
         }
         catch (error) {
             const relayError = toRelayProtocolError(error);
+            await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                actor: "app",
+                type: requestType === "unknown" && relayError.code === "invalid_json"
+                    ? "invalid_json"
+                    : requestType,
+                ok: false,
+                errorCode: relayError.code,
+            }), "app error metrics");
             sendJson(socket, {
                 type: "relay:error",
                 code: relayError.code,
@@ -1063,6 +1238,7 @@ export function createRelayServer(config, deps = {}) {
         void (async () => {
             try {
                 await sessionHub.attachProvider(providerId, socket);
+                await recordInstanceHeartbeat();
             }
             catch (error) {
                 const relayError = toRelayProtocolError(error);
@@ -1082,9 +1258,15 @@ export function createRelayServer(config, deps = {}) {
                 void handleProviderMessage(socket, data.toString());
             });
             socket.on("close", () => {
-                void sessionHub.detachProvider(socket).catch((error) => {
-                    console.error("[privateclaw-relay] failed to detach provider socket", error);
-                });
+                void (async () => {
+                    try {
+                        await sessionHub.detachProvider(socket);
+                    }
+                    catch (error) {
+                        console.error("[privateclaw-relay] failed to detach provider socket", error);
+                    }
+                    await recordInstanceHeartbeat();
+                })();
             });
         })();
     });
@@ -1107,6 +1289,7 @@ export function createRelayServer(config, deps = {}) {
             let session;
             try {
                 session = await sessionHub.attachApp(sessionId, appId, socket);
+                await recordInstanceHeartbeat();
             }
             catch (error) {
                 const relayError = toRelayProtocolError(error);
@@ -1131,9 +1314,15 @@ export function createRelayServer(config, deps = {}) {
                 void handleAppMessage(socket, sessionId, appId, data.toString());
             });
             socket.on("close", () => {
-                void sessionHub.detachApp(socket).catch((error) => {
-                    console.error("[privateclaw-relay] failed to detach app socket", error);
-                });
+                void (async () => {
+                    try {
+                        await sessionHub.detachApp(socket);
+                    }
+                    catch (error) {
+                        console.error("[privateclaw-relay] failed to detach app socket", error);
+                    }
+                    await recordInstanceHeartbeat();
+                })();
             });
         })();
     });
@@ -1170,6 +1359,9 @@ export function createRelayServer(config, deps = {}) {
         if (ownsFrameCache) {
             closes.push(frameCache.close());
         }
+        if (ownsAdminMetricsStore) {
+            closes.push(adminMetricsStore.close());
+        }
         await Promise.all(closes);
     }
     return {
@@ -1197,6 +1389,7 @@ export function createRelayServer(config, deps = {}) {
             startedPort = address.port;
             startedUrl = `http://${config.host}:${startedPort}`;
             started = true;
+            await recordInstanceHeartbeat();
             return { port: startedPort, url: startedUrl };
         },
         async stop() {
@@ -1224,6 +1417,7 @@ export function createRelayServer(config, deps = {}) {
                     resolve();
                 });
             });
+            await recordAdminMetric(() => adminMetricsStore.unregisterInstance(clusterNodeId), "relay instance shutdown");
             await closeOwnedResources();
             started = false;
             startedUrl = "";