overmux 0.0.1 → 0.0.2

package/src/internal/server/websocket-server.ts

@@ -0,0 +1,311 @@
+import type { ServerType as NodeServer } from "@hono/node-server";
+import {
+  encodeProtocolFrame,
+  notificationEventSchema,
+  serverProtocolMessageSchema,
+  webSocketCloseCode,
+  type ServerProtocolMessage,
+} from "../shared/index";
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import { WebSocket, WebSocketServer } from "ws";
+
+import { runtimeWebSocketPath, viteHmrPath } from "../shared/routes";
+import { attachWebSocketConnection } from "./websocket-connection";
+import type { AuthBoundary, RequestSession } from "./auth/auth-http";
+import {
+  errorDetails as diagnosticErrorDetails,
+  type ServerLogger,
+} from "./server-logger";
+import type { Runtime } from "./runtime/create-runtime";
+import { createViteWebSocketProxy } from "./vite-websocket-proxy";
+import { maxWebSocketBufferedBytes } from "./websocket-limits";
+
+const maxWebSocketPayloadBytes = 1_048_576;
+
+// Upgrade requests bypass Hono routing, so rejected paths need a raw HTTP response.
+const rejectUpgrade = (socket: Duplex, status: number, message: string) => {
+  socket.end(
+    `HTTP/1.1 ${status} ${message}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`,
+  );
+};
+
+const requestPath = (request: IncomingMessage) => {
+  try {
+    return new URL(request.url ?? "", "http://localhost").pathname;
+  } catch {
+    return undefined;
+  }
+};
+
+const requestAuthenticationInput = (request: IncomingMessage) => {
+  const host = request.headers.host;
+  if (!host) {
+    return;
+  }
+  const headers = new Headers();
+  Object.entries(request.headers).forEach(([name, value]) => {
+    if (Array.isArray(value)) {
+      value.forEach((entry) => headers.append(name, entry));
+    } else if (value !== undefined) {
+      headers.set(name, value);
+    }
+  });
+  const encrypted = Boolean(
+    (request.socket as typeof request.socket & { encrypted?: boolean })
+      .encrypted,
+  );
+  try {
+    return new Request(
+      `${encrypted ? "https" : "http"}://${host}${request.url ?? "/"}`,
+      { headers },
+    );
+  } catch {
+    return;
+  }
+};
+
+// Tie a WebSocket to its session, periodically revalidating it and cleaning up
+// the session mapping when the connection closes.
+export const attachSessionLifecycle = ({
+  auth,
+  serverLogger,
+  session,
+  sessionSockets,
+  socket,
+}: {
+  auth: AuthBoundary;
+  serverLogger?: ServerLogger;
+  session: RequestSession;
+  sessionSockets: Map<WebSocket, string>;
+  socket: WebSocket;
+}) => {
+  sessionSockets.set(socket, session.id);
+  let revalidationPending = false;
+  const revalidationTimer = setInterval(() => {
+    if (revalidationPending) {
+      return;
+    }
+    revalidationPending = true;
+    void auth.service
+      .authenticateToken(session.token, session.origin)
+      .then(
+        (authenticated) => {
+          if (!authenticated) {
+            socket.close(
+              webSocketCloseCode.authenticationRevoked,
+              "authentication revoked",
+            );
+          }
+        },
+        (cause: unknown) => {
+          serverLogger?.log({
+            details: diagnosticErrorDetails(cause),
+            event: "websocket-session-revalidation-failure",
+            level: "error",
+          });
+          socket.close(
+            webSocketCloseCode.authenticationUnavailable,
+            "authentication unavailable",
+          );
+        },
+      )
+      .finally(() => {
+        revalidationPending = false;
+      });
+  }, 1_000);
+  socket.once("close", () => {
+    clearInterval(revalidationTimer);
+    sessionSockets.delete(socket);
+  });
+};
+
+// WebSocket upgrades bypass Hono but share its credential parser. Browser
+// sessions additionally require the exact canonical Origin; local bearer clients
+// are not browser-origin credentials. Each socket remains tied to its session so
+// explicit revocation closes it immediately, while periodic revalidation covers
+// expiration and changes made by another server process.
+export const createWebSocketServer = ({
+  auth,
+  developmentWebTarget,
+  runtime,
+  server,
+  serverLogger,
+}: {
+  auth: AuthBoundary;
+  developmentWebTarget?: string;
+  runtime: Runtime;
+  server: NodeServer;
+  serverLogger?: ServerLogger;
+}) => {
+  const webSocketServer = new WebSocketServer({
+    maxPayload: maxWebSocketPayloadBytes,
+    noServer: true,
+  });
+  let updateAvailable = false;
+  const sessionSockets = new Map<WebSocket, string>();
+  const viteProxy = developmentWebTarget
+    ? createViteWebSocketProxy({
+        auth,
+        serverLogger,
+        target: developmentWebTarget,
+      })
+    : undefined;
+  const removeRevocationListener = auth.service.onSessionsRevoked((ids) => {
+    sessionSockets.forEach((sessionId, socket) => {
+      if (ids.has(sessionId)) {
+        socket.close(
+          webSocketCloseCode.authenticationRevoked,
+          "authentication revoked",
+        );
+      }
+    });
+    viteProxy?.revoke(ids);
+  });
+  const onUpgrade = async (
+    request: IncomingMessage,
+    socket: Duplex,
+    head: Buffer,
+  ) => {
+    const correlationId = serverLogger?.id();
+    serverLogger?.log({ correlationId, event: "websocket-connect" });
+    const path = requestPath(request);
+    const isRuntimeSocket = path === runtimeWebSocketPath;
+    const isViteSocket =
+      path === viteHmrPath && developmentWebTarget !== undefined;
+    if (!isRuntimeSocket && !isViteSocket) {
+      serverLogger?.log({
+        correlationId,
+        details: { status: 404 },
+        event: "websocket-connect-rejected",
+        level: "warn",
+      });
+      rejectUpgrade(socket, 404, "Not Found");
+      return;
+    }
+    const authenticationInput = requestAuthenticationInput(request);
+    if (!authenticationInput) {
+      rejectUpgrade(socket, 400, "Bad Request");
+      return;
+    }
+    const origin = auth.resolveOrigin({
+      remoteAddress: request.socket.remoteAddress,
+      request: authenticationInput,
+    });
+    let session: RequestSession | undefined;
+    try {
+      session = await auth.requests.authenticate(authenticationInput, origin);
+    } catch (cause) {
+      serverLogger?.log({
+        correlationId,
+        details: diagnosticErrorDetails(cause),
+        event: "websocket-authentication-failure",
+        level: "error",
+      });
+      rejectUpgrade(socket, 503, "Service Unavailable");
+      return;
+    }
+    if (!session) {
+      rejectUpgrade(socket, 401, "Unauthorized");
+      return;
+    }
+    if (
+      session.kind === "browser" &&
+      (!origin || request.headers.origin !== origin)
+    ) {
+      rejectUpgrade(socket, 403, "Forbidden");
+      return;
+    }
+    if (isViteSocket) {
+      if (
+        session.kind !== "browser" ||
+        session.credential !== "cookie" ||
+        !origin
+      ) {
+        rejectUpgrade(socket, 401, "Unauthorized");
+        return;
+      }
+      if (!viteProxy) {
+        rejectUpgrade(socket, 503, "Service Unavailable");
+        return;
+      }
+      viteProxy.connect({
+        correlationId,
+        head,
+        origin,
+        request,
+        session,
+        socket,
+      });
+      return;
+    }
+    webSocketServer.handleUpgrade(request, socket, head, (webSocket) => {
+      attachSessionLifecycle({
+        auth,
+        serverLogger,
+        session,
+        sessionSockets,
+        socket: webSocket,
+      });
+      webSocketServer.emit("connection", webSocket, request);
+      attachWebSocketConnection({ runtime, serverLogger, socket: webSocket });
+      if (updateAvailable) {
+        webSocket.send(encodeProtocolFrame({ type: "update-available" }));
+      }
+    });
+  };
+  server.on("upgrade", onUpgrade);
+
+  const broadcast = (message: ServerProtocolMessage) => {
+    const frame = encodeProtocolFrame(
+      serverProtocolMessageSchema.parse(message),
+    );
+    let delivered = 0;
+    webSocketServer.clients.forEach((socket) => {
+      if (socket.readyState !== WebSocket.OPEN) {
+        return;
+      }
+      // Apply outbound backpressure by dropping slow clients before queued broadcasts consume unbounded memory.
+      if (socket.bufferedAmount > maxWebSocketBufferedBytes) {
+        socket.close(1013, "client could not keep up");
+        return;
+      }
+      try {
+        socket.send(frame);
+        delivered += 1;
+      } catch (cause) {
+        socket.terminate();
+        serverLogger?.log({
+          details: diagnosticErrorDetails(cause),
+          event: "websocket-broadcast-failure",
+          level: "error",
+        });
+      }
+    });
+    return delivered;
+  };
+
+  return {
+    announceRestarting: () => broadcast({ type: "restarting" }),
+    announceUpdateAvailable: () => {
+      updateAvailable = true;
+      return broadcast({ type: "update-available" });
+    },
+    broadcastNotification: (notification: unknown) =>
+      broadcast(
+        notificationEventSchema.parse({
+          notification,
+          type: "notification",
+        }),
+      ),
+    close: async () => {
+      server.off("upgrade", onUpgrade);
+      removeRevocationListener();
+      viteProxy?.close();
+      webSocketServer.clients.forEach((socket) => socket.terminate());
+      await new Promise<void>((resolve) =>
+        webSocketServer.close(() => resolve()),
+      );
+    },
+  };
+};

package/src/internal/shared/background-notifications.ts

@@ -0,0 +1,37 @@
+// Validates browser subscription data exchanged by background-notification delivery.
+// Browser-standard key and endpoint details stay behind this internal boundary.
+import { z } from "zod";
+
+const deliveryKeySchema = z
+  .string()
+  .min(1)
+  .max(1_024)
+  .regex(/^[\w-]+$/u);
+
+export const backgroundNotificationSubscriptionSchema = z
+  .object({
+    endpoint: z
+      .url()
+      .max(4_096)
+      .refine((endpoint) => {
+        const url = new URL(endpoint);
+        return url.protocol === "https:" && !url.username && !url.password;
+      }),
+    expirationTime: z.number().int().nonnegative().nullable(),
+    keys: z
+      .object({ auth: deliveryKeySchema, p256dh: deliveryKeySchema })
+      .strict(),
+  })
+  .strict();
+
+export const backgroundNotificationPublicKeyResponseSchema = z
+  .object({ publicKey: deliveryKeySchema })
+  .strict();
+
+export const backgroundNotificationDisableRequestSchema = z
+  .object({ endpoint: backgroundNotificationSubscriptionSchema.shape.endpoint })
+  .strict();
+
+export type BackgroundNotificationSubscription = z.infer<
+  typeof backgroundNotificationSubscriptionSchema
+>;

package/src/internal/shared/index.ts

@@ -0,0 +1,2 @@
+export * from "./background-notifications";
+export * from "./protocol";

package/src/internal/shared/protocol.ts

@@ -0,0 +1,317 @@
+import { z } from "zod";
+
+import { notificationSchema } from "../../public/notifications";
+
+// Compatibility gate, not negotiation: open tabs may still run older client assets.
+// The exact version rejects incompatible runtime manifest and wire formats before later traffic.
+export const protocolVersion = 9 as const;
+
+// Application-defined WebSocket close codes shared by server and browser transports.
+export const webSocketCloseCode = {
+  authenticationRevoked: 4001,
+  authenticationUnavailable: 4002,
+} as const;
+
+export const runtimeManifestSchema = z.object({
+  debug: z.boolean(),
+  operations: z.array(z.string().min(1)),
+  protocolVersion: z.literal(protocolVersion),
+  resources: z.array(z.string().min(1)),
+  streams: z.array(z.string().min(1)),
+});
+
+export const updateAvailableEventSchema = z.object({
+  type: z.literal("update-available"),
+});
+
+export const restartingEventSchema = z.object({
+  type: z.literal("restarting"),
+});
+
+export const serverLifecycleEventSchema = z.discriminatedUnion("type", [
+  updateAvailableEventSchema,
+  restartingEventSchema,
+]);
+
+export const notificationEventSchema = z
+  .object({
+    notification: notificationSchema,
+    type: z.literal("notification"),
+  })
+  .strict();
+
+const operationIdSchema = z.string().min(1).max(256);
+const registrationNameSchema = z.string().min(1).max(256);
+
+export const resourceReadMessageSchema = z.object({
+  input: z.unknown().optional(),
+  operationId: operationIdSchema,
+  resourceName: registrationNameSchema,
+  type: z.literal("resource-read"),
+});
+
+export const resourceSubscribeMessageSchema = z.object({
+  input: z.unknown().optional(),
+  operationId: operationIdSchema,
+  resourceName: registrationNameSchema,
+  subscriptionId: operationIdSchema,
+  type: z.literal("resource-subscribe"),
+});
+
+export const resourceUnsubscribeMessageSchema = z.object({
+  subscriptionId: operationIdSchema,
+  type: z.literal("resource-unsubscribe"),
+});
+
+export const streamOpenMessageSchema = z.object({
+  input: z.unknown().optional(),
+  operationId: operationIdSchema,
+  streamId: operationIdSchema,
+  streamName: registrationNameSchema,
+  type: z.literal("stream-open"),
+});
+
+export const streamMessageSchema = z.object({
+  message: z.unknown(),
+  streamId: operationIdSchema,
+  type: z.literal("stream-message"),
+});
+
+export const streamCloseMessageSchema = z.object({
+  streamId: operationIdSchema,
+  type: z.literal("stream-close"),
+});
+
+export const clientDiagnosticEventSchema = z.object({
+  arguments: z.string().max(16_100),
+  level: z.enum(["log", "info", "warn", "error", "debug"]),
+  message: z.string().max(4_100),
+  stack: z.string().max(8_100).optional(),
+  timestamp: z.iso.datetime(),
+  type: z.literal("client-diagnostic"),
+  url: z.string().max(2_100).optional(),
+});
+
+export const clientProtocolMessageSchema = z.discriminatedUnion("type", [
+  resourceReadMessageSchema,
+  resourceSubscribeMessageSchema,
+  resourceUnsubscribeMessageSchema,
+  streamOpenMessageSchema,
+  streamMessageSchema,
+  streamCloseMessageSchema,
+  clientDiagnosticEventSchema,
+]);
+
+export const resourceResultMessageSchema = z.object({
+  operationId: operationIdSchema,
+  output: z.unknown(),
+  type: z.literal("resource-result"),
+});
+
+export const resourceInvalidatedMessageSchema = z.object({
+  subscriptionId: operationIdSchema,
+  type: z.literal("resource-invalidated"),
+});
+
+export const streamOpenedMessageSchema = z.object({
+  operationId: operationIdSchema,
+  streamId: operationIdSchema,
+  type: z.literal("stream-opened"),
+});
+
+export const streamOutputMessageSchema = z.object({
+  message: z.unknown(),
+  streamId: operationIdSchema,
+  type: z.literal("stream-output"),
+});
+
+export const streamClosedMessageSchema = z.object({
+  streamId: operationIdSchema,
+  type: z.literal("stream-closed"),
+});
+
+export const protocolErrorMessageSchema = z.object({
+  code: z.enum(["bad-request", "conflict", "internal", "not-found"]),
+  message: z.string(),
+  operationId: operationIdSchema.optional(),
+  streamId: operationIdSchema.optional(),
+  subscriptionId: operationIdSchema.optional(),
+  type: z.literal("error"),
+});
+
+export const serverProtocolMessageSchema = z.discriminatedUnion("type", [
+  resourceResultMessageSchema,
+  resourceInvalidatedMessageSchema,
+  streamOpenedMessageSchema,
+  streamOutputMessageSchema,
+  streamClosedMessageSchema,
+  protocolErrorMessageSchema,
+  updateAvailableEventSchema,
+  restartingEventSchema,
+  notificationEventSchema,
+]);
+
+const byteMarker = "$overmuxBytes";
+
+type EncodedBytes = { [byteMarker]: number[] };
+
+const encodeValue = (value: unknown): unknown => {
+  if (value instanceof Uint8Array) {
+    return { [byteMarker]: Array.from(value) } satisfies EncodedBytes;
+  }
+  if (Array.isArray(value)) {
+    return value.map(encodeValue);
+  }
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, encodeValue(item)]),
+    );
+  }
+  return value;
+};
+
+const decodeValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(decodeValue);
+  }
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    Object.keys(record).length === 1 &&
+    Array.isArray(record[byteMarker]) &&
+    record[byteMarker].every(
+      (item) => Number.isInteger(item) && item >= 0 && item <= 255,
+    )
+  ) {
+    return Uint8Array.from(record[byteMarker] as number[]);
+  }
+  return Object.fromEntries(
+    Object.entries(record).map(([key, item]) => [key, decodeValue(item)]),
+  );
+};
+
+const binaryMarker = "$overmuxBinary";
+const binaryMagic = 0x4f4d5801;
+
+type EncodedBinary = { [binaryMarker]: [number, number] };
+
+const encodeBinaryValue = (
+  value: unknown,
+  payloads: Uint8Array[],
+  offset: { value: number },
+): unknown => {
+  if (value instanceof Uint8Array) {
+    const marker = {
+      [binaryMarker]: [offset.value, value.byteLength],
+    } satisfies EncodedBinary;
+    payloads.push(value);
+    offset.value += value.byteLength;
+    return marker;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => encodeBinaryValue(item, payloads, offset));
+  }
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        encodeBinaryValue(item, payloads, offset),
+      ]),
+    );
+  }
+  return value;
+};
+
+const decodeBinaryValue = (value: unknown, payload: Uint8Array): unknown => {
+  if (Array.isArray(value)) {
+    return value.map((item) => decodeBinaryValue(item, payload));
+  }
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  const record = value as Record<string, unknown>;
+  const marker = record[binaryMarker];
+  if (
+    Object.keys(record).length === 1 &&
+    Array.isArray(marker) &&
+    marker.length === 2 &&
+    marker.every((item) => Number.isInteger(item) && item >= 0)
+  ) {
+    const [offset, length] = marker as [number, number];
+    if (offset + length > payload.byteLength) {
+      throw new Error("Invalid Overmux binary payload range");
+    }
+    return payload.slice(offset, offset + length);
+  }
+  return Object.fromEntries(
+    Object.entries(record).map(([key, item]) => [
+      key,
+      decodeBinaryValue(item, payload),
+    ]),
+  );
+};
+
+export const encodeProtocolMessage = (message: unknown): string =>
+  JSON.stringify(encodeValue(message));
+
+export const decodeProtocolMessage = (message: string): unknown =>
+  decodeValue(JSON.parse(message));
+
+export const encodeProtocolFrame = (message: unknown): string | Uint8Array => {
+  const payloads: Uint8Array[] = [];
+  const encoded = encodeBinaryValue(message, payloads, { value: 0 });
+  if (!payloads.length) {
+    return JSON.stringify(encoded);
+  }
+  const header = new TextEncoder().encode(JSON.stringify(encoded));
+  const payloadLength = payloads.reduce(
+    (total, payload) => total + payload.byteLength,
+    0,
+  );
+  const frame = new Uint8Array(8 + header.byteLength + payloadLength);
+  const view = new DataView(frame.buffer);
+  view.setUint32(0, binaryMagic);
+  view.setUint32(4, header.byteLength);
+  frame.set(header, 8);
+  let offset = 8 + header.byteLength;
+  payloads.forEach((payload) => {
+    frame.set(payload, offset);
+    offset += payload.byteLength;
+  });
+  return frame;
+};
+
+export const decodeProtocolFrame = (
+  frame: string | ArrayBuffer | Uint8Array,
+): unknown => {
+  if (typeof frame === "string") {
+    return decodeProtocolMessage(frame);
+  }
+  const bytes =
+    frame instanceof Uint8Array
+      ? frame
+      : new Uint8Array(frame, 0, frame.byteLength);
+  if (bytes.byteLength < 8) {
+    throw new Error("Invalid Overmux binary frame");
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint32(0) !== binaryMagic) {
+    throw new Error("Invalid Overmux binary frame magic");
+  }
+  const headerLength = view.getUint32(4);
+  if (8 + headerLength > bytes.byteLength) {
+    throw new Error("Invalid Overmux binary frame header");
+  }
+  const header = JSON.parse(
+    new TextDecoder().decode(bytes.subarray(8, 8 + headerLength)),
+  ) as unknown;
+  return decodeBinaryValue(header, bytes.subarray(8 + headerLength));
+};
+
+export type RuntimeManifest = z.infer<typeof runtimeManifestSchema>;
+export type ClientDiagnosticEvent = z.infer<typeof clientDiagnosticEventSchema>;
+export type ClientProtocolMessage = z.infer<typeof clientProtocolMessageSchema>;
+export type ServerLifecycleEvent = z.infer<typeof serverLifecycleEventSchema>;
+export type ServerProtocolMessage = z.infer<typeof serverProtocolMessageSchema>;

package/src/internal/shared/routes.ts

@@ -0,0 +1,3 @@
+export const runtimeWebSocketPath = "/api/socket";
+export const viteHmrPath = "/_overmux/vite/hmr";
+export const viteInfrastructurePath = "/_overmux/vite/*";