fix: improve ws close diagnostics

src/gateway/server.ts

@@ -1202,10 +1202,17 @@ export async function startGatewayServer(
   wss.on("connection", (socket, upgradeReq) => {
     let client: Client | null = null;
     let closed = false;
+    const openedAt = Date.now();
     const connId = randomUUID();
     const remoteAddr = (
       socket as WebSocket & { _socket?: { remoteAddress?: string } }
     )._socket?.remoteAddress;
+    const headerValue = (value: string | string[] | undefined) =>
+      Array.isArray(value) ? value[0] : value;
+    const requestHost = headerValue(upgradeReq.headers.host);
+    const requestOrigin = headerValue(upgradeReq.headers.origin);
+    const requestUserAgent = headerValue(upgradeReq.headers["user-agent"]);
+    const forwardedFor = headerValue(upgradeReq.headers["x-forwarded-for"]);
     const canvasHostPortForWs =
       canvasHostServer?.port ?? (canvasHost ? port : undefined);
     const canvasHostOverride =
@@ -1223,6 +1230,19 @@ export async function startGatewayServer(
     const isWebchatConnect = (params: ConnectParams | null | undefined) =>
       params?.client?.mode === "webchat" ||
       params?.client?.name === "webchat-ui";
+    let handshakeState: "pending" | "connected" | "failed" = "pending";
+    let closeCause: string | undefined;
+    let closeMeta: Record<string, unknown> = {};
+    let lastFrameType: string | undefined;
+    let lastFrameMethod: string | undefined;
+    let lastFrameId: string | undefined;
+
+    const setCloseCause = (cause: string, meta?: Record<string, unknown>) => {
+      if (!closeCause) closeCause = cause;
+      if (meta && Object.keys(meta).length > 0) {
+        closeMeta = { ...closeMeta, ...meta };
+      }
+    };
 
     const send = (obj: unknown) => {
       try {
@@ -1251,9 +1271,24 @@ export async function startGatewayServer(
       close();
     });
     socket.once("close", (code, reason) => {
+      const durationMs = Date.now() - openedAt;
+      const closeContext = {
+        cause: closeCause,
+        handshake: handshakeState,
+        durationMs,
+        lastFrameType,
+        lastFrameMethod,
+        lastFrameId,
+        host: requestHost,
+        origin: requestOrigin,
+        userAgent: requestUserAgent,
+        forwardedFor,
+        ...closeMeta,
+      };
       if (!client) {
         logWsControl.warn(
           `closed before connect conn=${connId} remote=${remoteAddr ?? "?"} code=${code ?? "n/a"} reason=${reason?.toString() || "n/a"}`,
+          closeContext,
         );
       }
       if (client && isWebchatConnect(client.connect)) {
@@ -1280,12 +1315,22 @@ export async function startGatewayServer(
         connId,
         code,
         reason: reason?.toString(),
+        durationMs,
+        cause: closeCause,
+        handshake: handshakeState,
+        lastFrameType,
+        lastFrameMethod,
+        lastFrameId,
       });
       close();
     });
 
     const handshakeTimer = setTimeout(() => {
       if (!client) {
+        handshakeState = "failed";
+        setCloseCause("handshake-timeout", {
+          handshakeMs: Date.now() - openedAt,
+        });
         logWsControl.warn(
           `handshake timeout conn=${connId} remote=${remoteAddr ?? "?"}`,
         );
@@ -1298,6 +1343,29 @@ export async function startGatewayServer(
       const text = rawDataToString(data);
       try {
         const parsed = JSON.parse(text);
+        const frameType =
+          parsed && typeof parsed === "object" && "type" in parsed
+            ? typeof (parsed as { type?: unknown }).type === "string"
+              ? String((parsed as { type?: unknown }).type)
+              : undefined
+            : undefined;
+        const frameMethod =
+          parsed && typeof parsed === "object" && "method" in parsed
+            ? typeof (parsed as { method?: unknown }).method === "string"
+              ? String((parsed as { method?: unknown }).method)
+              : undefined
+            : undefined;
+        const frameId =
+          parsed && typeof parsed === "object" && "id" in parsed
+            ? typeof (parsed as { id?: unknown }).id === "string"
+              ? String((parsed as { id?: unknown }).id)
+              : undefined
+            : undefined;
+        if (frameType || frameMethod || frameId) {
+          lastFrameType = frameType;
+          lastFrameMethod = frameMethod;
+          lastFrameId = frameId;
+        }
         if (!client) {
           // Handshake must be a normal request:
           // { type:"req", method:"connect", params: ConnectParams }.
@@ -1324,6 +1392,18 @@ export async function startGatewayServer(
                 `invalid handshake conn=${connId} remote=${remoteAddr ?? "?"}`,
               );
             }
+            handshakeState = "failed";
+            const handshakeError = validateRequestFrame(parsed)
+              ? (parsed as RequestFrame).method === "connect"
+                ? `invalid connect params: ${formatValidationErrors(validateConnectParams.errors)}`
+                : "invalid handshake: first request must be connect"
+              : "invalid request frame";
+            setCloseCause("invalid-handshake", {
+              frameType,
+              frameMethod,
+              frameId,
+              handshakeError,
+            });
             socket.close(1008, "invalid handshake");
             close();
             return;
@@ -1338,9 +1418,18 @@ export async function startGatewayServer(
             maxProtocol < PROTOCOL_VERSION ||
             minProtocol > PROTOCOL_VERSION
           ) {
+            handshakeState = "failed";
             logWsControl.warn(
               `protocol mismatch conn=${connId} remote=${remoteAddr ?? "?"} client=${connectParams.client.name} ${connectParams.client.mode} v${connectParams.client.version}`,
             );
+            setCloseCause("protocol-mismatch", {
+              minProtocol,
+              maxProtocol,
+              expectedProtocol: PROTOCOL_VERSION,
+              client: connectParams.client.name,
+              mode: connectParams.client.mode,
+              version: connectParams.client.version,
+            });
             send({
               type: "res",
               id: frame.id,
@@ -1364,9 +1453,24 @@ export async function startGatewayServer(
             req: upgradeReq,
           });
           if (!authResult.ok) {
+            handshakeState = "failed";
             logWsControl.warn(
               `unauthorized conn=${connId} remote=${remoteAddr ?? "?"} client=${connectParams.client.name} ${connectParams.client.mode} v${connectParams.client.version}`,
             );
+            const authProvided = connectParams.auth?.token
+              ? "token"
+              : connectParams.auth?.password
+                ? "password"
+                : "none";
+            setCloseCause("unauthorized", {
+              authMode: resolvedAuth.mode,
+              authProvided,
+              authReason: authResult.reason,
+              allowTailscale: resolvedAuth.allowTailscale,
+              client: connectParams.client.name,
+              mode: connectParams.client.mode,
+              version: connectParams.client.version,
+            });
             send({
               type: "res",
               id: frame.id,
@@ -1444,6 +1548,7 @@ export async function startGatewayServer(
 
           clearTimeout(handshakeTimer);
           client = { socket, connect: connectParams, connId, presenceKey };
+          handshakeState = "connected";
 
           logWs("out", "hello-ok", {
             connId,