@arcote.tech/arc-host 0.7.4 → 0.7.6

package/dist/src/context-handler.d.ts

@@ -1,17 +1,19 @@
 import { type ArcContextAny, type ArcEventAny, type DatabaseAdapter, LocalEventPublisher, MasterDataStorage, Model } from "@arcote.tech/arc";
+import type { ArcTelemetry } from "@arcote.tech/arc-otel";
 import type { EventAuthContext, SyncableEvent, TokenPayload } from "./types";
 /**
  * Handles a single context on the host
  */
 export declare class ContextHandler {
     readonly context: ArcContextAny;
+    private readonly telemetry?;
     private model;
     private dataStorage;
     private eventPublisher;
     private eventDefinitions;
     private hostEventIdCounter;
     private initialized;
-    constructor(context: ArcContextAny, dbAdapter: Promise<DatabaseAdapter>);
+    constructor(context: ArcContextAny, dbAdapter: Promise<DatabaseAdapter>, telemetry?: ArcTelemetry | undefined);
     /**
      * Initialize the context handler and run seed data if needed.
      */
@@ -22,7 +24,9 @@ export declare class ContextHandler {
      */
     private runSeeds;
     /**
-     * Execute a command
+     * Execute a command. When `telemetry` is wired, the entire dispatch is
+     * traced as `command.<name>` with RPC semantic conventions, parented to
+     * whatever context is active (HTTP request span, WS message span, etc.).
      */
     executeCommand(commandName: string, params: any, rawToken: string | null): Promise<any>;
     /**

package/dist/src/context-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-handler.d.ts","sourceRoot":"","sources":["../../src/context-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,EAGN,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7E;;GAEG;AACH,qBAAa,cAAc;aASP,OAAO,EAAE,aAAa;IARxC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,gBAAgB,CAAkC;IAC1D,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,WAAW,CAAS;gBAGV,OAAO,EAAE,aAAa,EACtC,SAAS,EAAE,OAAO,CAAC,eAAe,CAAC;IAqBrC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B;;;OAGG;YACW,QAAQ;IA4BtB;;OAEG;IACG,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,GAAG,EACX,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,GAAG,CAAC;IA8Bf;;OAEG;IACG,aAAa,CACjB,MAAM,EAAE,KAAK,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,GAAG,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;KACvC,CAAC,EACF,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,YAAY,GAAG,IAAI,GACzB,OAAO,CAAC,aAAa,EAAE,CAAC;IA8C3B;;OAEG;IACG,cAAc,CAClB,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,KAAK,EAAE,YAAY,GAAG,IAAI,GACzB,OAAO,CAAC,aAAa,EAAE,CAAC;IAkD3B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC,aAAa,CAAC;IAIhC;;OAEG;IACH,cAAc,IAAI,iBAAiB;IAInC;;OAEG;IACH,mBAAmB,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC;IAI/C;;OAEG;IACH,iBAAiB,IAAI,mBAAmB;CAGzC"}
+{"version":3,"file":"context-handler.d.ts","sourceRoot":"","sources":["../../src/context-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,EAGN,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7E;;GAEG;AACH,qBAAa,cAAc;aASP,OAAO,EAAE,aAAa;IAEtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAV7B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,gBAAgB,CAAkC;IAC1D,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,WAAW,CAAS;gBAGV,OAAO,EAAE,aAAa,EACtC,SAAS,EAAE,OAAO,CAAC,eAAe,CAAC,EAClB,SAAS,CAAC,EAAE,YAAY,YAAA;IAqB3C;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B;;;OAGG;YACW,QAAQ;IA4BtB;;;;OAIG;IACG,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,GAAG,EACX,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,GAAG,CAAC;IAuDf;;OAEG;IACG,aAAa,CACjB,MAAM,EAAE,KAAK,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,GAAG,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;KACvC,CAAC,EACF,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,YAAY,GAAG,IAAI,GACzB,OAAO,CAAC,aAAa,EAAE,CAAC;IA8C3B;;OAEG;IACG,cAAc,CAClB,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,KAAK,EAAE,YAAY,GAAG,IAAI,GACzB,OAAO,CAAC,aAAa,EAAE,CAAC;IAkD3B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC,aAAa,CAAC;IAIhC;;OAEG;IACH,cAAc,IAAI,iBAAiB;IAInC;;OAEG;IACH,mBAAmB,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC;IAI/C;;OAEG;IACH,iBAAiB,IAAI,mBAAmB;CAGzC"}

package/dist/src/create-server.d.ts

@@ -1,4 +1,5 @@
 import type { ArcContextAny, DatabaseAdapter } from "@arcote.tech/arc";
+import type { ArcTelemetry } from "@arcote.tech/arc-otel";
 import type { Server } from "bun";
 import { ConnectionManager } from "./connection-manager";
 import { ContextHandler } from "./context-handler";
@@ -16,6 +17,11 @@ export interface ArcServerConfig {
     jwtSecret?: string;
     /** Extra callback when a WS client disconnects (e.g. to clean up platform state) */
     onWsClose?: (clientId: string) => void;
+    /** Optional OpenTelemetry instance. When provided, the HTTP fetch handler
+     *  and WS message dispatch are wrapped in spans, with parent context
+     *  extracted from `traceparent` (header / message field). All nested
+     *  handler code automatically attaches to the active span. */
+    telemetry?: ArcTelemetry;
 }
 export interface ArcServer {
     server: Server<WebSocketData>;

package/dist/src/create-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-server.d.ts","sourceRoot":"","sources":["../../src/create-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;AAElC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAOjD,OAAO,KAAK,EACV,cAAc,EAGd,YAAY,EACb,MAAM,oBAAoB,CAAC;AAG5B,KAAK,aAAa,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,CAAC;IACvB,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACzD,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IAC9B,cAAc,EAAE,cAAc,CAAC;IAC/B,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,aAAa,EAAE,aAAa,CAAC;IAC7B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,SAAS,CAAC,CAwLpB"}
+{"version":3,"file":"create-server.d.ts","sourceRoot":"","sources":["../../src/create-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EACV,YAAY,EAEb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;AAElC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAOjD,OAAO,KAAK,EACV,cAAc,EAGd,YAAY,EACb,MAAM,oBAAoB,CAAC;AAG5B,KAAK,aAAa,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,CAAC;IACvB,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACzD,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;kEAG8D;IAC9D,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IAC9B,cAAc,EAAE,cAAc,CAAC;IAC/B,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,aAAa,EAAE,aAAa,CAAC;IAC7B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,SAAS,CAAC,CA4PpB"}

package/package.json

@@ -4,11 +4,11 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "private": false,
   "author": "Przemysław Krasiński [arcote.tech]",
   "dependencies": {
-    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.4",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.6",
     "croner": "^9.0.0",
     "jsonwebtoken": "^9.0.2"
   },
@@ -24,6 +24,12 @@
     "@types/bun": "^1.2.0"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.7.4"
+    "@arcote.tech/arc": "^0.7.6",
+    "@arcote.tech/arc-otel": "^0.7.6"
+  },
+  "peerDependenciesMeta": {
+    "@arcote.tech/arc-otel": {
+      "optional": true
+    }
   }
 }

package/src/context-handler.ts

@@ -8,6 +8,7 @@ import {
   ScopedModel,
   mutationExecutor,
 } from "@arcote.tech/arc";
+import type { ArcTelemetry } from "@arcote.tech/arc-otel";
 import { canTokenEmitEvent, filterEventsForToken } from "./event-auth";
 import type { EventAuthContext, SyncableEvent, TokenPayload } from "./types";
 
@@ -25,6 +26,7 @@ export class ContextHandler {
   constructor(
     public readonly context: ArcContextAny,
     dbAdapter: Promise<DatabaseAdapter>,
+    private readonly telemetry?: ArcTelemetry,
   ) {
     this.dataStorage = new MasterDataStorage(dbAdapter);
     this.eventPublisher = new LocalEventPublisher(this.dataStorage);
@@ -88,39 +90,66 @@ export class ContextHandler {
   }
 
   /**
-   * Execute a command
+   * Execute a command. When `telemetry` is wired, the entire dispatch is
+   * traced as `command.<name>` with RPC semantic conventions, parented to
+   * whatever context is active (HTTP request span, WS message span, etc.).
    */
   async executeCommand(
     commandName: string,
     params: any,
     rawToken: string | null,
   ): Promise<any> {
-    // Create per-request scoped model with its own auth
-    const scoped = new ScopedModel(this.model, "request");
-    if (rawToken) scoped.setToken(rawToken);
-
-    const mutations = mutationExecutor(scoped);
-
-    // Support dotted names: "accounts.signIn" → mutations.accounts.signIn
-    let command: any;
-    if (commandName.includes(".")) {
-      const [elementName, methodName] = commandName.split(".");
-      const element = (mutations as any)[elementName];
-      command = element?.[methodName];
-    } else {
-      command = (mutations as any)[commandName];
-    }
+    const includePayloads = this.telemetry?.shouldIncludePayloads() ?? false;
+    const baseAttrs = {
+      "rpc.system": "arc",
+      "rpc.method": commandName,
+      "arc.command.name": commandName,
+      "arc.command.params_size": params ? JSON.stringify(params).length : 0,
+      ...(includePayloads ? { "arc.command.params": params } : {}),
+    };
+
+    const runCommand = async (): Promise<any> => {
+      const scoped = new ScopedModel(this.model, "request");
+      if (rawToken) scoped.setToken(rawToken);
+
+      const mutations = mutationExecutor(scoped);
+
+      let command: any;
+      if (commandName.includes(".")) {
+        const [elementName, methodName] = commandName.split(".");
+        const element = (mutations as any)[elementName];
+        command = element?.[methodName];
+      } else {
+        command = (mutations as any)[commandName];
+      }
 
-    if (!command) {
-      throw new Error(`Command '${commandName}' not found`);
-    }
+      if (!command) {
+        throw new Error(`Command '${commandName}' not found`);
+      }
 
+      try {
+        return await command(params);
+      } catch (error) {
+        console.error(`[ARC] Command '${commandName}' failed:`, error);
+        throw error;
+      }
+    };
+
+    if (!this.telemetry) return runCommand();
+    const start = Date.now();
     try {
-      const result = await command(params);
-      return result;
-    } catch (error) {
-      console.error(`[ARC] Command '${commandName}' failed:`, error);
-      throw error;
+      return await this.telemetry.startSpan(
+        `command.${commandName}`,
+        runCommand,
+        { attributes: baseAttrs },
+      );
+    } finally {
+      this.telemetry.measureSince("arc.command.duration_ms", start, {
+        "arc.command.name": commandName,
+      });
+      this.telemetry.incrementCounter("arc.commands.total", 1, {
+        "arc.command.name": commandName,
+      });
     }
   }
 

package/src/create-server.ts

@@ -1,4 +1,8 @@
 import type { ArcContextAny, DatabaseAdapter } from "@arcote.tech/arc";
+import type {
+  ArcTelemetry,
+  Span,
+} from "@arcote.tech/arc-otel";
 import type { Server } from "bun";
 import jwt from "jsonwebtoken";
 import { ConnectionManager } from "./connection-manager";
@@ -29,6 +33,11 @@ export interface ArcServerConfig {
   jwtSecret?: string;
   /** Extra callback when a WS client disconnects (e.g. to clean up platform state) */
   onWsClose?: (clientId: string) => void;
+  /** Optional OpenTelemetry instance. When provided, the HTTP fetch handler
+   *  and WS message dispatch are wrapped in spans, with parent context
+   *  extracted from `traceparent` (header / message field). All nested
+   *  handler code automatically attaches to the active span. */
+  telemetry?: ArcTelemetry;
 }
 
 export interface ArcServer {
@@ -55,9 +64,23 @@ export async function createArcServer(
     "arc-host-secret-change-in-production";
   const port = config.port || 5005;
 
-  // Init context handler
-  const dbAdapter = config.dbAdapterFactory(config.context);
-  const contextHandler = new ContextHandler(config.context, dbAdapter);
+  // Init context handler — telemetry (if any) flows through so executeCommand
+  // emits `command.<name>` spans parented to the active HTTP/WS span. The
+  // adapter is wrapped post-await so every transaction's find/set/remove/
+  // commit lands as a child span automatically.
+  const rawDbAdapter = config.dbAdapterFactory(config.context);
+  const dbAdapter = config.telemetry
+    ? rawDbAdapter.then(async (a) => {
+        const { wrapDbAdapter } = await import("@arcote.tech/arc-otel");
+        const dbSystem = process.env.DATABASE_URL ? "postgresql" : "sqlite";
+        return wrapDbAdapter(a, config.telemetry, dbSystem);
+      })
+    : rawDbAdapter;
+  const contextHandler = new ContextHandler(
+    config.context,
+    dbAdapter,
+    config.telemetry,
+  );
   await contextHandler.init();
 
   // Start cron scheduler
@@ -136,58 +159,74 @@ export async function createArcServer(
 
     async fetch(req, server) {
       const url = new URL(req.url);
-
-      // Build CORS headers with request origin
       const corsHeaders = buildCorsHeaders(req);
 
-      // CORS preflight
       if (req.method === "OPTIONS") {
         return new Response(null, { headers: corsHeaders });
       }
 
-      // Token extraction: Authorization header > query param > cookie
-      const authHeader = req.headers.get("Authorization");
-      let rawToken =
-        authHeader?.replace("Bearer ", "") ||
-        url.searchParams.get("token");
-
-      if (!rawToken) {
-        const cookieHeader = req.headers.get("Cookie");
-        if (cookieHeader) {
-          const match = cookieHeader.match(/arc_token=([^;]+)/);
-          if (match) rawToken = decodeURIComponent(match[1]);
+      // Inner request body — extracted so we can wrap it in an HTTP span
+      // when telemetry is enabled. The wrap MUST set the active context
+      // (via runWithExtractedContext + startSpan) so nested handlers'
+      // spans attach to this one as parent.
+      const handleRequest = async (span: Span | undefined): Promise<Response> => {
+        const authHeader = req.headers.get("Authorization");
+        let rawToken =
+          authHeader?.replace("Bearer ", "") ||
+          url.searchParams.get("token");
+
+        if (!rawToken) {
+          const cookieHeader = req.headers.get("Cookie");
+          if (cookieHeader) {
+            const match = cookieHeader.match(/arc_token=([^;]+)/);
+            if (match) rawToken = decodeURIComponent(match[1]);
+          }
         }
-      }
+        const tokenPayload = rawToken ? verifyToken(rawToken) : null;
 
-      const tokenPayload = rawToken ? verifyToken(rawToken) : null;
-
-      // WebSocket upgrade
-      if (
-        url.pathname === "/ws" &&
-        req.headers.get("Upgrade") === "websocket"
-      ) {
-        if (server.upgrade(req, { data: { clientId: "" } })) return undefined;
-        return new Response("WebSocket upgrade failed", {
-          status: 500,
-          headers: corsHeaders,
-        });
-      }
+        if (
+          url.pathname === "/ws" &&
+          req.headers.get("Upgrade") === "websocket"
+        ) {
+          if (server.upgrade(req, { data: { clientId: "" } })) return undefined as unknown as Response;
+          return new Response("WebSocket upgrade failed", {
+            status: 500,
+            headers: corsHeaders,
+          });
+        }
 
-      // Run HTTP handler chain
-      const reqCtx: ArcRequestContext = {
-        rawToken,
-        tokenPayload,
-        corsHeaders,
+        const reqCtx: ArcRequestContext = { rawToken, tokenPayload, corsHeaders };
+        for (const handler of httpHandlers) {
+          const response = await handler(req, url, reqCtx);
+          if (response) {
+            span?.setAttribute("http.response.status_code", response.status);
+            return response;
+          }
+        }
+        span?.setAttribute("http.response.status_code", 404);
+        return new Response("Not Found", { status: 404, headers: corsHeaders });
       };
-      for (const handler of httpHandlers) {
-        const response = await handler(req, url, reqCtx);
-        if (response) return response;
-      }
 
-      return new Response("Not Found", {
-        status: 404,
-        headers: corsHeaders,
-      });
+      const telemetry = config.telemetry;
+      if (!telemetry) return handleRequest(undefined);
+
+      return telemetry.runWithExtractedContext(req.headers, () =>
+        telemetry.startSpan(
+          `${req.method} ${url.pathname}`,
+          (span) => handleRequest(span),
+          {
+            kind: 2 /* SpanKind.SERVER */,
+            attributes: {
+              "http.request.method": req.method,
+              "http.route": url.pathname,
+              "url.scheme": url.protocol.replace(":", ""),
+              "url.path": url.pathname,
+              "server.address": url.host,
+              "user_agent.original": req.headers.get("user-agent") ?? undefined,
+            },
+          },
+        ),
+      );
     },
 
     websocket: {
@@ -198,15 +237,53 @@ export async function createArcServer(
         const client = connectionManager.getClientByWs(ws as any);
         if (!client) return;
 
+        let message: any;
         try {
-          const message = JSON.parse(messageStr as string);
-          for (const handler of wsHandlers) {
-            const handled = await handler(client, message, wsCtx);
-            if (handled) break;
-          }
+          message = JSON.parse(messageStr as string);
         } catch (error) {
           console.error("Failed to parse WS message:", error);
+          return;
         }
+
+        const dispatch = async (): Promise<void> => {
+          try {
+            for (const handler of wsHandlers) {
+              const handled = await handler(client, message, wsCtx);
+              if (handled) break;
+            }
+          } catch (error) {
+            console.error("WS handler error:", error);
+          }
+        };
+
+        const telemetry = config.telemetry;
+        if (!telemetry) {
+          await dispatch();
+          return;
+        }
+
+        // Parent context can travel inside the message under `traceparent`
+        // (and optionally `tracestate`) so distributed traces from the
+        // browser propagate over the persistent WS connection.
+        const carrier: Record<string, string> = {};
+        if (typeof message?.traceparent === "string") carrier.traceparent = message.traceparent;
+        if (typeof message?.tracestate === "string") carrier.tracestate = message.tracestate;
+
+        await telemetry.runWithExtractedContext(carrier, () =>
+          telemetry.startSpan(
+            `ws.${message?.type ?? "message"}`,
+            () => dispatch(),
+            {
+              kind: 2 /* SpanKind.SERVER */,
+              attributes: {
+                "messaging.system": "arc-ws",
+                "messaging.operation": "process",
+                "messaging.message.type": message?.type,
+                "arc.ws.client_id": client.id,
+              },
+            },
+          ),
+        );
       },
       close(ws) {
         const client = connectionManager.getClientByWs(ws as any);