sonamu 0.11.16 → 0.13.0

package/src/stream/index.ts

@@ -3,6 +3,7 @@ export * from "./ws-audience";
 export * from "./ws-cluster-bus";
 export * from "./ws-core";
 export * from "./ws-presence-store";
+export * from "./ws-session-id";
 export * from "./ws-telemetry";
 export * from "./ws-telemetry-memory";
 export * from "./ws-telemetry-trace";

package/src/stream/ws-audience-resolver.ts

@@ -1,11 +1,10 @@
 import { type WebSocketAudience } from "./ws-audience";
 import { type WebSocketPresenceStore } from "./ws-presence-store";
+import { parseWebSocketSessionNodeId } from "./ws-session-id";
 
-export type WebSocketRoutingPlan = {
-  localSessionIds: string[];
-  remoteNodeIds: string[];
-};
-
+/**
+ * publish 대상 중 원격 노드를 찾는다. 로컬 대상은 registry 메모리로 해석하므로 여기서는 원격 노드만 다룬다.
+ */
 export class WebSocketAudienceResolver {
   constructor(
     private readonly options: {
@@ -14,22 +13,25 @@ export class WebSocketAudienceResolver {
     },
   ) {}
 
-  resolve(audience: WebSocketAudience): WebSocketRoutingPlan {
-    const localSessionIds: string[] = [];
-    const remoteNodeIds = new Set<string>();
-
-    for (const meta of this.options.presenceStore.queryAudience(audience)) {
-      if (meta.nodeId === this.options.nodeId) {
-        localSessionIds.push(meta.sessionId);
-        continue;
+  /**
+   * `connections` audience는 세션 ID에 든 노드 ID로 store 조회 없이 라우팅한다.
+   * 그 밖의 audience는 store.resolveRoute를 호출하며, 동기 throw도 rejection으로 바꾼다.
+   */
+  async resolveRemoteNodeIds(audience: WebSocketAudience): Promise<string[]> {
+    if (audience.type === "connections") {
+      const nodeIds = new Set<string>();
+      for (const connectionId of audience.connectionIds) {
+        const nodeId = parseWebSocketSessionNodeId(connectionId);
+        if (nodeId !== undefined && nodeId !== this.options.nodeId) {
+          nodeIds.add(nodeId);
+        }
       }
-
-      remoteNodeIds.add(meta.nodeId);
+      return [...nodeIds];
     }
 
-    return {
-      localSessionIds,
-      remoteNodeIds: [...remoteNodeIds],
-    };
+    const plan = await Promise.resolve().then(() =>
+      this.options.presenceStore.resolveRoute(audience, this.options.nodeId),
+    );
+    return [...new Set(plan.remoteNodeIds)].filter((nodeId) => nodeId !== this.options.nodeId);
   }
 }

package/src/stream/ws-cluster-bus.ts

@@ -1,13 +1,18 @@
 import { type WebSocketAudience } from "./ws-audience";
+import { type MaybePromise } from "./ws-core";
 
+/**
+ * 노드 간 publish envelope. 원본 data 대신 발행 노드가 route별로 한 번 검증·인코딩한 frame을 싣는다.
+ * 수신 노드는 자기 메모리로 audience를 해석하고, 각 연결의 route frame을 재검증 없이 그대로 보낸다.
+ */
 export type WebSocketClusterEnvelope = {
   id: string;
   sourceNodeId: string;
-  targetNodeIds?: string[];
-  namespace?: string;
+  targetNodeIds: string[];
   audience: WebSocketAudience;
   event: string;
-  data: unknown;
+  // routeKey → 인코딩된 frame. 이벤트를 선언하지 않았거나 검증에 실패한 route는 빠진다
+  frames: Record<string, string>;
   emittedAt: number;
 };
 
@@ -16,8 +21,11 @@ export type WebSocketClusterEnvelopeHandler = (
 ) => void | Promise<void>;
 
 export interface WebSocketClusterBus {
+  // 설정하면 runtime nodeId와 같아야 한다. 다르면 runtime 생성이 실패한다
+  readonly nodeId?: string;
   publish(envelope: WebSocketClusterEnvelope): void | Promise<void>;
-  subscribe(handler: WebSocketClusterEnvelopeHandler): () => void;
+  // 구독 완료를 promise로 알릴 수 있다. 반환한 해제 함수는 runtime shutdown에서 한 번 호출된다
+  subscribe(handler: WebSocketClusterEnvelopeHandler): MaybePromise<() => void>;
   shutdown(): void | Promise<void>;
 }
 

package/src/stream/ws-core.ts

@@ -1,5 +1,8 @@
+import { type z } from "zod";
+
 export type WebSocketUserId = number | string;
 export type WebSocketRoomId = string;
+export type MaybePromise<T> = T | Promise<T>;
 
 export interface ManagedWebSocketConnection {
   id: string;
@@ -11,6 +14,17 @@ export interface ManagedWebSocketConnection {
   close(code?: number, reason?: string): void;
 }
 
+/**
+ * registry가 소유하는 로컬 연결. 인코딩된 frame을 그대로 보내는 경로와 route 식별자를 가진다.
+ */
+export interface WebSocketFrameConnection extends ManagedWebSocketConnection {
+  // route table의 키. 원격 노드가 보낸 envelope에서 이 연결이 받을 frame을 고를 때 쓴다
+  readonly routeKey?: string;
+  // route table에 없는 연결이 로컬 publish를 받을 때 쓰는 자기 스키마
+  readonly outEvents: z.ZodObject;
+  sendFrame(event: string, frame: string): void;
+}
+
 export type WebSocketRegistryStats = {
   totalConnections: number;
   totalRooms: number;

package/src/stream/ws-delivery.ts

@@ -1,10 +1,13 @@
 import { randomUUID } from "node:crypto";
 
+import { type z } from "zod";
+
 import { runtimeTypeOf } from "../runtime-type";
 import { type WebSocketAudience } from "./ws-audience";
 import { type WebSocketAudienceResolver } from "./ws-audience-resolver";
 import { type WebSocketClusterBus, type WebSocketClusterEnvelope } from "./ws-cluster-bus";
-import { type ManagedWebSocketConnection } from "./ws-core";
+import { type WebSocketFrameConnection } from "./ws-core";
+import { encodeWebSocketFrame, type WebSocketFrameEncoding } from "./ws-frame";
 import { type WebSocketLocalConnectionStore } from "./ws-local-connection-store";
 import {
   NoopWebSocketTelemetryController,
@@ -14,15 +17,33 @@ import {
 // fan-out을 event loop tick 단위로 나눠 한 번에 긴 동기 루프를 만들지 않게 함
 const FAN_OUT_BATCH_SIZE = 250;
 
+export type WebSocketRouteDefinition = {
+  routeKey: string;
+  outEvents: z.ZodObject;
+};
+
+type FanOutTarget = {
+  connection: WebSocketFrameConnection;
+  frame: string;
+};
+
+type FanOutJob = {
+  targets: FanOutTarget[];
+  event: string;
+  cursor: number;
+};
+
+type Unsubscribe = () => void;
+
 export class WebSocketDeliveryEngine {
-  private readonly pendingFanOutJobs: Array<{
-    targets: ManagedWebSocketConnection[];
-    event: string;
-    data: unknown;
-    cursor: number;
-  }> = [];
+  private readonly pendingFanOutJobs: FanOutJob[] = [];
   private fanOutFlushScheduled = false;
-  private readonly unsubscribe: () => void;
+  // routeKey → outEvents. 모든 노드가 같은 route 집합을 등록하므로 routeKey는 클러스터 전체에서 일관된다
+  private readonly routes = new Map<string, z.ZodObject>();
+  // 노드 단위 직렬 publish 큐. 앞선 publish의 라우팅이 느려도 원격 envelope 순서가 뒤바뀌지 않는다
+  private publishQueue: Promise<void> = Promise.resolve();
+  private readonly subscription: Promise<Unsubscribe | undefined>;
+  private stopped = false;
   private readonly telemetry: WebSocketTelemetryController;
   private readonly unregisterMetricSource: () => void;
 
@@ -30,98 +51,146 @@ export class WebSocketDeliveryEngine {
     private readonly options: {
       nodeId: string;
       localConnections: WebSocketLocalConnectionStore;
+      // registry 메모리 기준으로 audience에 속한 로컬 활성 세션 ID를 반환한다
+      resolveLocalSessionIds: (audience: WebSocketAudience) => string[];
       audienceResolver: WebSocketAudienceResolver;
       clusterBus: WebSocketClusterBus;
       telemetryController?: WebSocketTelemetryController;
     },
   ) {
     this.telemetry = this.options.telemetryController ?? new NoopWebSocketTelemetryController();
-    this.unsubscribe = this.options.clusterBus.subscribe((envelope) => {
-      this.handleClusterEnvelope(envelope);
-    });
+    this.subscription = this.subscribe();
     this.unregisterMetricSource = this.telemetry.registerMetricSource({
       collect: () => this.getTelemetrySnapshot(),
     });
   }
 
-  publishToAudience<Data>(audience: WebSocketAudience, event: string, data: Data): void {
-    const routingPlan = this.options.audienceResolver.resolve(audience);
-    const localTargets = this.options.localConnections.getConnections(routingPlan.localSessionIds);
+  registerRoute(routeKey: string, outEvents: z.ZodObject): void {
+    this.routes.set(routeKey, outEvents);
+  }
 
-    this.telemetry.emit({
-      name: "ws.fanout.resolved",
-      level: "debug",
-      detail: {
-        localTargetCount: localTargets.length,
-        remoteNodeCount: routingPlan.remoteNodeIds.length,
-      },
-    });
-    this.telemetry.recordMetric({
-      name: "sonamu.ws.fanout.targets",
-      kind: "histogram",
-      value: localTargets.length + routingPlan.remoteNodeIds.length,
-      unit: "1",
-      tags: { audience_type: audience.type },
-    });
+  replaceRoutes(routes: WebSocketRouteDefinition[]): void {
+    this.routes.clear();
+    for (const route of routes) {
+      this.routes.set(route.routeKey, route.outEvents);
+    }
+  }
 
-    this.enqueueFanOut(localTargets, event, data);
+  /**
+   * 발행 노드에서 route별로 한 번 검증·인코딩하고, 로컬 fan-out은 즉시 큐에 넣는다.
+   * 원격 라우팅과 cluster publish는 노드 단위 직렬 큐에서 처리한다. 반환한 promise는 reject하지 않는다.
+   */
+  publishToAudience<Data>(audience: WebSocketAudience, event: string, data: Data): Promise<void> {
+    try {
+      let declared = false;
+      let rejected = false;
+      const record = (encoding: WebSocketFrameEncoding) => {
+        if (encoding.status !== "unknownEvent") {
+          declared = true;
+        }
+        if (encoding.status === "invalidPayload") {
+          rejected = true;
+        }
+      };
 
-    if (routingPlan.remoteNodeIds.length === 0) {
-      return;
-    }
+      // 이벤트를 선언한 route마다 한 번만 검증·인코딩한다. 원격 수신자도 이 frame을 그대로 받는다
+      const routeFrames: Record<string, string> = {};
+      for (const [routeKey, outEvents] of this.routes) {
+        const encoding = encodeWebSocketFrame(outEvents, event, data);
+        record(encoding);
+        if (encoding.status === "encoded") {
+          routeFrames[routeKey] = encoding.frame;
+        }
+      }
 
-    const envelope: WebSocketClusterEnvelope = {
-      id: randomUUID(),
-      sourceNodeId: this.options.nodeId,
-      targetNodeIds: routingPlan.remoteNodeIds,
-      audience,
-      event,
-      data,
-      emittedAt: Date.now(),
-    };
+      // route table에 없는 로컬 연결은 자기 스키마로 인코딩한다(스키마 객체당 한 번)
+      const fallbackEncodings = new Map<z.ZodObject, WebSocketFrameEncoding>();
+      const localTargets: FanOutTarget[] = [];
+      for (const connection of this.options.localConnections.getConnections(
+        this.options.resolveLocalSessionIds(audience),
+      )) {
+        let frame: string | undefined;
+        if (connection.routeKey !== undefined && this.routes.has(connection.routeKey)) {
+          frame = getOwnFrame(routeFrames, connection.routeKey);
+        } else {
+          let encoding = fallbackEncodings.get(connection.outEvents);
+          if (!encoding) {
+            encoding = encodeWebSocketFrame(connection.outEvents, event, data);
+            fallbackEncodings.set(connection.outEvents, encoding);
+            record(encoding);
+          }
+          frame = encoding.status === "encoded" ? encoding.frame : undefined;
+        }
 
-    const publishStartedAt = performance.now();
-    Promise.resolve(this.options.clusterBus.publish(envelope))
-      .then(() => {
-        const durationMs = performance.now() - publishStartedAt;
-        this.telemetry.emit({
-          name: "ws.cluster.envelope.published",
-          level: "debug",
-          detail: { event, targetNodeCount: routingPlan.remoteNodeIds.length },
-        });
-        this.telemetry.recordSpan({
-          operationName: "ws.cluster.publish",
-          kind: "producer",
-          durationMs,
-          status: "unset",
-          attributes: {
-            event,
-            targetNodeCount: routingPlan.remoteNodeIds.length,
-          },
-        });
-      })
-      .catch((cause: unknown) => {
-        const durationMs = performance.now() - publishStartedAt;
-        this.telemetry.emit({
-          name: "ws.cluster.envelope.failed",
-          level: "error",
-          detail: { event },
-        });
-        this.telemetry.recordSpan({
-          operationName: "ws.cluster.publish",
-          kind: "producer",
-          durationMs,
-          status: "error",
-          attributes: { event },
-          errorType: cause instanceof Error ? cause.name : runtimeTypeOf(cause),
+        // 이벤트를 선언하지 않았거나 검증에 실패한 route의 연결은 닫지 않고 건너뛴다
+        if (frame !== undefined) {
+          localTargets.push({ connection, frame });
+        }
+      }
+
+      if (!declared) {
+        this.emitPublishRejected(event, "unknownEvent");
+      } else if (rejected) {
+        this.emitPublishRejected(event, "invalidPayload");
+      }
+
+      this.enqueueFanOut(localTargets, event);
+
+      if (Object.keys(routeFrames).length === 0) {
+        this.emitFanOutResolved(audience, localTargets.length, 0);
+        return Promise.resolve();
+      }
+
+      // 원격 라우팅(store 조회)은 앞선 publish를 기다리지 않고 지금 바로 시작한다. store가 멈춰도 버스트 비용이 N×T가 아닌 약 T다.
+      // 반면 envelope 발행은 노드 단위 큐에 이어 붙여 publish 순서를 지킨다. 뒤 publish의 라우팅이 먼저 끝나도 앞 발행을 기다린다
+      const routing = this.resolveRemoteNodeIds(audience, event);
+      const task = this.publishQueue
+        .then(() => routing)
+        .then((remoteNodeIds) =>
+          this.publishRemote(audience, event, routeFrames, localTargets.length, remoteNodeIds),
+        )
+        .catch((cause: unknown) => {
+          this.emitRouteFailed(event, audience, cause);
         });
-      });
+      this.publishQueue = task;
+      return task;
+    } catch (cause) {
+      // 스키마 transform 예외 등 예상하지 못한 실패도 호출자에게 reject로 새지 않게 한다
+      this.emitRouteFailed(event, audience, cause);
+      return Promise.resolve();
+    }
+  }
+
+  // 진행 중인 publish(원격 포함)와 구독 시도가 모두 끝나면 resolve한다
+  async drainPublishes(): Promise<void> {
+    await Promise.all([this.publishQueue, this.subscription]);
   }
 
-  async shutdown(): Promise<void> {
+  /**
+   * 구독을 해제하고 cluster bus를 종료한다. 구독이 deadline까지 끝나지 않으면 늦게 끝날 때 해제한다.
+   */
+  async shutdown(deadline: Promise<void>): Promise<void> {
+    this.stopped = true;
     this.unregisterMetricSource();
-    this.unsubscribe();
-    await this.options.clusterBus.shutdown();
+
+    const unsubscribe = await Promise.race([this.subscription, deadline.then(() => null)]);
+    if (unsubscribe === null) {
+      this.subscription.then((lateUnsubscribe) => {
+        this.safeUnsubscribe(lateUnsubscribe);
+      });
+    } else {
+      this.safeUnsubscribe(unsubscribe);
+    }
+
+    try {
+      await Promise.resolve().then(() => this.options.clusterBus.shutdown());
+    } catch (cause) {
+      this.telemetry.emit({
+        name: "ws.cluster.shutdown.failed",
+        level: "error",
+        detail: { errorType: describeError(cause) },
+      });
+    }
   }
 
   getTelemetrySnapshot() {
@@ -137,7 +206,117 @@ export class WebSocketDeliveryEngine {
     };
   }
 
+  // 구독 실패는 로컬 전용 동작으로 수렴시키고 telemetry만 남긴다
+  private subscribe(): Promise<Unsubscribe | undefined> {
+    return Promise.resolve()
+      .then(() =>
+        this.options.clusterBus.subscribe((envelope) => {
+          this.handleClusterEnvelope(envelope);
+        }),
+      )
+      .then(
+        (unsubscribe) => unsubscribe,
+        (cause: unknown) => {
+          this.telemetry.emit({
+            name: "ws.cluster.subscribe.failed",
+            level: "error",
+            detail: { errorType: describeError(cause) },
+          });
+          return undefined;
+        },
+      );
+  }
+
+  private safeUnsubscribe(unsubscribe: Unsubscribe | undefined): void {
+    try {
+      unsubscribe?.();
+    } catch (cause) {
+      this.telemetry.emit({
+        name: "ws.cluster.unsubscribe.failed",
+        level: "error",
+        detail: { errorType: describeError(cause) },
+      });
+    }
+  }
+
+  // 라우팅 실패는 여기서 telemetry로 바꿔 undefined를 돌려준다. 즉시 catch를 붙이므로 큐 차례를 기다리는 동안에도 unhandled rejection이 생기지 않는다
+  private resolveRemoteNodeIds(
+    audience: WebSocketAudience,
+    event: string,
+  ): Promise<string[] | undefined> {
+    return this.options.audienceResolver.resolveRemoteNodeIds(audience).catch((cause: unknown) => {
+      this.emitRouteFailed(event, audience, cause);
+      return undefined;
+    });
+  }
+
+  private async publishRemote(
+    audience: WebSocketAudience,
+    event: string,
+    frames: Record<string, string>,
+    localTargetCount: number,
+    resolvedNodeIds: string[] | undefined,
+  ): Promise<void> {
+    // 라우팅 실패(undefined) 시 로컬 전달은 이미 끝났으므로 이 publish의 원격 envelope만 건너뛴다
+    const remoteNodeIds = resolvedNodeIds ?? [];
+    this.emitFanOutResolved(audience, localTargetCount, remoteNodeIds.length);
+    if (remoteNodeIds.length === 0) {
+      return;
+    }
+
+    const envelope: WebSocketClusterEnvelope = {
+      id: randomUUID(),
+      sourceNodeId: this.options.nodeId,
+      targetNodeIds: remoteNodeIds,
+      audience,
+      event,
+      frames,
+      emittedAt: Date.now(),
+    };
+
+    const publishStartedAt = performance.now();
+    try {
+      await Promise.resolve().then(() => this.options.clusterBus.publish(envelope));
+      const durationMs = performance.now() - publishStartedAt;
+      this.telemetry.emit({
+        name: "ws.cluster.envelope.published",
+        level: "debug",
+        detail: { event, targetNodeCount: remoteNodeIds.length },
+      });
+      this.telemetry.recordSpan({
+        operationName: "ws.cluster.publish",
+        kind: "producer",
+        durationMs,
+        status: "unset",
+        attributes: {
+          event,
+          targetNodeCount: remoteNodeIds.length,
+        },
+      });
+    } catch (cause) {
+      const durationMs = performance.now() - publishStartedAt;
+      this.telemetry.emit({
+        name: "ws.cluster.envelope.failed",
+        level: "error",
+        detail: { event },
+      });
+      this.telemetry.recordSpan({
+        operationName: "ws.cluster.publish",
+        kind: "producer",
+        durationMs,
+        status: "error",
+        attributes: { event },
+        errorType: describeError(cause),
+      });
+    }
+  }
+
+  // 수신 노드는 store 없이 자기 메모리로 audience를 해석하고, 각 연결의 route frame을 재검증 없이 그대로 보낸다
   private handleClusterEnvelope(envelope: WebSocketClusterEnvelope): void {
+    if (this.stopped) {
+      return;
+    }
+
     if (envelope.sourceNodeId === this.options.nodeId) {
       this.telemetry.emit({
         name: "ws.cluster.envelope.ignored",
@@ -148,7 +327,6 @@ export class WebSocketDeliveryEngine {
     }
 
     if (
-      envelope.targetNodeIds &&
       envelope.targetNodeIds.length > 0 &&
       !envelope.targetNodeIds.includes(this.options.nodeId)
     ) {
@@ -167,9 +345,19 @@ export class WebSocketDeliveryEngine {
       detail: { event: envelope.event, sourceNodeId: envelope.sourceNodeId },
     });
 
-    const routingPlan = this.options.audienceResolver.resolve(envelope.audience);
-    const localTargets = this.options.localConnections.getConnections(routingPlan.localSessionIds);
-    this.enqueueFanOut(localTargets, envelope.event, envelope.data);
+    const localTargets: FanOutTarget[] = [];
+    for (const connection of this.options.localConnections.getConnections(
+      this.options.resolveLocalSessionIds(envelope.audience),
+    )) {
+      const frame =
+        connection.routeKey === undefined
+          ? undefined
+          : getOwnFrame(envelope.frames, connection.routeKey);
+      if (frame !== undefined) {
+        localTargets.push({ connection, frame });
+      }
+    }
+    this.enqueueFanOut(localTargets, envelope.event);
 
     this.telemetry.recordSpan({
       operationName: "ws.cluster.receive",
@@ -184,11 +372,42 @@ export class WebSocketDeliveryEngine {
     });
   }
 
-  private enqueueFanOut<Data>(
-    targets: ManagedWebSocketConnection[],
-    event: string,
-    data: Data,
+  private emitPublishRejected(event: string, reason: "unknownEvent" | "invalidPayload"): void {
+    this.telemetry.emit({
+      name: "ws.publish.rejected",
+      level: "error",
+      detail: { event, reason },
+    });
+  }
+
+  private emitRouteFailed(event: string, audience: WebSocketAudience, cause: unknown): void {
+    this.telemetry.emit({
+      name: "ws.fanout.route.failed",
+      level: "error",
+      detail: { event, audienceType: audience.type, errorType: describeError(cause) },
+    });
+  }
+
+  private emitFanOutResolved(
+    audience: WebSocketAudience,
+    localTargetCount: number,
+    remoteNodeCount: number,
   ): void {
+    this.telemetry.emit({
+      name: "ws.fanout.resolved",
+      level: "debug",
+      detail: { localTargetCount, remoteNodeCount },
+    });
+    this.telemetry.recordMetric({
+      name: "sonamu.ws.fanout.targets",
+      kind: "histogram",
+      value: localTargetCount + remoteNodeCount,
+      unit: "1",
+      tags: { audience_type: audience.type },
+    });
+  }
+
+  private enqueueFanOut(targets: FanOutTarget[], event: string): void {
     if (targets.length === 0) {
       return;
     }
@@ -196,7 +415,6 @@ export class WebSocketDeliveryEngine {
     this.pendingFanOutJobs.push({
       targets,
       event,
-      data,
       cursor: 0,
     });
     this.telemetry.emit({
@@ -230,7 +448,7 @@ export class WebSocketDeliveryEngine {
         const job = this.pendingFanOutJobs[0];
 
         while (job.cursor < job.targets.length && processed < FAN_OUT_BATCH_SIZE) {
-          this.safePublish(job.targets[job.cursor], job.event, job.data);
+          this.safeSend(job.targets[job.cursor], job.event);
           job.cursor += 1;
           processed += 1;
         }
@@ -241,7 +459,7 @@ export class WebSocketDeliveryEngine {
       }
     } catch (error) {
       status = "error";
-      errorType = error instanceof Error ? error.name : runtimeTypeOf(error);
+      errorType = describeError(error);
       throw error;
     } finally {
       const durationMs = performance.now() - startedAt;
@@ -265,14 +483,11 @@ export class WebSocketDeliveryEngine {
     }
   }
 
-  private safePublish<Data>(
-    connection: ManagedWebSocketConnection,
-    event: string,
-    data: Data,
-  ): void {
+  private safeSend(target: FanOutTarget, event: string): void {
+    const { connection, frame } = target;
     try {
       if (!connection.closed) {
-        connection.publishUntyped(event, data);
+        connection.sendFrame(event, frame);
       }
     } catch {
       this.telemetry.emit({
@@ -287,3 +502,12 @@ export class WebSocketDeliveryEngine {
     }
   }
 }
+
+// 원격에서 온 frames는 prototype 키를 무시하고 자기 속성만 읽는다
+function getOwnFrame(frames: Record<string, string>, routeKey: string): string | undefined {
+  return Object.hasOwn(frames, routeKey) ? frames[routeKey] : undefined;
+}
+
+function describeError(cause: unknown): string {
+  return cause instanceof Error ? cause.name : runtimeTypeOf(cause);
+}