feat: add first-class WebSocket support via ctx.upgrade() and app.ws()

Adds ctx.upgrade() to the Context class with two overloads:
- Bare mode returns { socket, response } for manual event wiring
- Managed mode accepts handlers object and returns Response directly

Adds app.ws() shorthand for registering WebSocket endpoints.
Throws HttpError(400) on non-WebSocket requests.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bartlomieju

packages/fresh/src/app.ts

@@ -3,7 +3,11 @@ import { trace } from "@opentelemetry/api";
 import { DENO_DEPLOYMENT_ID } from "@fresh/build-id";
 import * as colors from "@std/fmt/colors";
 import type { MaybeLazyMiddleware, Middleware } from "./middlewares/mod.ts";
-import { Context } from "./context.ts";
+import {
+  Context,
+  type WebSocketHandlers,
+  type WebSocketUpgradeOptions,
+} from "./context.ts";
 import { mergePath, type Method, UrlPatternRouter } from "./router.ts";
 import type { FreshConfig, ResolvedFreshConfig } from "./config.ts";
 import type { BuildCache } from "./build_cache.ts";
@@ -301,6 +305,24 @@ export class App<State> {
     return this;
   }
 
+  /**
+   * Register a WebSocket endpoint at the specified path.
+   *
+   * ```ts
+   * app.ws("/chat", {
+   *   open(socket) { console.log("connected"); },
+   *   message(socket, event) { socket.send(event.data); },
+   * });
+   * ```
+   */
+  ws(
+    path: string,
+    handlers: WebSocketHandlers,
+    options?: WebSocketUpgradeOptions,
+  ): this {
+    return this.get(path, (ctx) => ctx.upgrade(handlers, options));
+  }
+
   /**
    * Add middlewares for all HTTP verbs at the specified path.
    */

packages/fresh/src/context.ts

@@ -11,6 +11,7 @@ import { jsxTemplate } from "preact/jsx-runtime";
 import { SpanStatusCode } from "@opentelemetry/api";
 import type { ResolvedFreshConfig } from "./config.ts";
 import type { BuildCache } from "./build_cache.ts";
+import { HttpError } from "./error.ts";
 import type { LayoutConfig } from "./types.ts";
 import {
   FreshScripts,
@@ -31,6 +32,43 @@ import { renderToString } from "preact-render-to-string";
 
 const ENCODER = new TextEncoder();
 
+/**
+ * Event handlers for a WebSocket connection upgraded via
+ * {@linkcode Context.upgrade}.
+ */
+export interface WebSocketHandlers {
+  /** Called when the WebSocket connection is established. */
+  open?(socket: WebSocket): void;
+  /** Called when a message is received. */
+  message?(socket: WebSocket, event: MessageEvent): void;
+  /** Called when the connection is closed. */
+  close?(socket: WebSocket, code: number, reason: string): void;
+  /** Called when an error occurs. */
+  error?(socket: WebSocket, event: Event | ErrorEvent): void;
+}
+
+/**
+ * Options forwarded to `Deno.upgradeWebSocket()`.
+ */
+export interface WebSocketUpgradeOptions {
+  /** Automatically close the connection if no ping is received
+   * within this many seconds. Default: 120. */
+  idleTimeout?: number;
+  /** The WebSocket sub-protocol to negotiate. */
+  protocol?: string;
+}
+
+function isWebSocketHandlers(
+  value: unknown,
+): value is WebSocketHandlers {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.open === "function" ||
+    typeof v.message === "function" ||
+    typeof v.close === "function" ||
+    typeof v.error === "function";
+}
+
 export interface Island {
   file: string;
   name: string;
@@ -489,6 +527,85 @@ export class Context<State> {
 
     return new Response(body, init);
   }
+
+  /**
+   * Upgrade the request to a WebSocket connection.
+   *
+   * **Bare mode** — returns the socket and the upgrade response.
+   * Wire events yourself and return `response` from your handler:
+   *
+   * ```ts
+   * app.get("/ws", (ctx) => {
+   *   const { socket, response } = ctx.upgrade();
+   *   socket.onmessage = (e) => socket.send(e.data);
+   *   return response;
+   * });
+   * ```
+   *
+   * **Managed mode** — pass handlers and receive the response directly:
+   *
+   * ```ts
+   * app.get("/ws", (ctx) =>
+   *   ctx.upgrade({
+   *     message(socket, event) {
+   *       socket.send(event.data);
+   *     },
+   *   })
+   * );
+   * ```
+   */
+  upgrade(
+    options?: WebSocketUpgradeOptions,
+  ): { socket: WebSocket; response: Response };
+  upgrade(
+    handlers: WebSocketHandlers,
+    options?: WebSocketUpgradeOptions,
+  ): Response;
+  upgrade(
+    handlersOrOptions?: WebSocketHandlers | WebSocketUpgradeOptions,
+    maybeOptions?: WebSocketUpgradeOptions,
+  ): { socket: WebSocket; response: Response } | Response {
+    let handlers: WebSocketHandlers | undefined;
+    let options: WebSocketUpgradeOptions | undefined;
+
+    if (isWebSocketHandlers(handlersOrOptions)) {
+      handlers = handlersOrOptions;
+      options = maybeOptions;
+    } else {
+      options = handlersOrOptions;
+    }
+
+    if (this.req.headers.get("upgrade") !== "websocket") {
+      throw new HttpError(400, "Expected a WebSocket upgrade request");
+    }
+
+    const { socket, response } = Deno.upgradeWebSocket(this.req, options);
+
+    if (handlers === undefined) {
+      return { socket, response };
+    }
+
+    if (handlers.open) {
+      socket.addEventListener("open", () => handlers.open!(socket));
+    }
+    if (handlers.message) {
+      socket.addEventListener(
+        "message",
+        (ev) => handlers.message!(socket, ev),
+      );
+    }
+    if (handlers.close) {
+      socket.addEventListener(
+        "close",
+        (ev) => handlers.close!(socket, ev.code, ev.reason),
+      );
+    }
+    if (handlers.error) {
+      socket.addEventListener("error", (ev) => handlers.error!(socket, ev));
+    }
+
+    return response;
+  }
 }
 
 function getHeadersFromInit(init?: ResponseInit) {

packages/fresh/src/mod.ts

@@ -20,7 +20,13 @@ export {
 } from "./middlewares/ip_filter.ts";
 export { csp, type CSPOptions } from "./middlewares/csp.ts";
 export type { FreshConfig, ResolvedFreshConfig } from "./config.ts";
-export type { Context, FreshContext, Island } from "./context.ts";
+export type {
+  Context,
+  FreshContext,
+  Island,
+  WebSocketHandlers,
+  WebSocketUpgradeOptions,
+} from "./context.ts";
 export { createDefine, type Define } from "./define.ts";
 export type { Method } from "./router.ts";
 export { HttpError } from "./error.ts";

packages/fresh/src/websocket_test.ts

@@ -0,0 +1,180 @@
+import { expect } from "@std/expect";
+import { App } from "./app.ts";
+import { FakeServer } from "./test_utils.ts";
+
+Deno.test("ctx.upgrade() - throws 400 on non-WebSocket request", async () => {
+  const app = new App()
+    .get("/ws", (ctx) => ctx.upgrade({ message() {} }));
+
+  const server = new FakeServer(app.handler());
+  const res = await server.get("/ws");
+  expect(res.status).toEqual(400);
+});
+
+Deno.test("app.ws() - throws 400 on non-WebSocket request", async () => {
+  const app = new App()
+    .ws("/ws", { message() {} });
+
+  const server = new FakeServer(app.handler());
+  const res = await server.get("/ws");
+  expect(res.status).toEqual(400);
+});
+
+Deno.test({
+  name: "ctx.upgrade() - managed echo",
+  sanitizeOps: false,
+  sanitizeResources: false,
+  async fn() {
+    const app = new App()
+      .get("/ws", (ctx) =>
+        ctx.upgrade({
+          message(socket, event) {
+            socket.send(`echo: ${event.data}`);
+          },
+        }));
+
+    const ac = new AbortController();
+    const server = Deno.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      signal: ac.signal,
+      onListen: () => {},
+    }, app.handler());
+
+    const port = server.addr.port;
+
+    const ws = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+    const received = new Promise<string>((resolve, reject) => {
+      ws.onmessage = (e) => resolve(e.data);
+      ws.onerror = (e) => reject(e);
+    });
+    ws.onopen = () => ws.send("hello");
+
+    const msg = await received;
+    expect(msg).toEqual("echo: hello");
+
+    ws.close();
+    ac.abort();
+    await server.finished;
+  },
+});
+
+Deno.test({
+  name: "ctx.upgrade() - bare overload",
+  sanitizeOps: false,
+  sanitizeResources: false,
+  async fn() {
+    const app = new App()
+      .get("/ws", (ctx) => {
+        const { socket, response } = ctx.upgrade();
+        socket.onmessage = (e) => socket.send(`bare: ${e.data}`);
+        return response;
+      });
+
+    const ac = new AbortController();
+    const server = Deno.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      signal: ac.signal,
+      onListen: () => {},
+    }, app.handler());
+
+    const port = server.addr.port;
+
+    const ws = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+    const received = new Promise<string>((resolve, reject) => {
+      ws.onmessage = (e) => resolve(e.data);
+      ws.onerror = (e) => reject(e);
+    });
+    ws.onopen = () => ws.send("hello");
+
+    const msg = await received;
+    expect(msg).toEqual("bare: hello");
+
+    ws.close();
+    ac.abort();
+    await server.finished;
+  },
+});
+
+Deno.test({
+  name: "app.ws() - echo shorthand",
+  sanitizeOps: false,
+  sanitizeResources: false,
+  async fn() {
+    const app = new App()
+      .ws("/ws", {
+        message(socket, event) {
+          socket.send(`ws: ${event.data}`);
+        },
+      });
+
+    const ac = new AbortController();
+    const server = Deno.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      signal: ac.signal,
+      onListen: () => {},
+    }, app.handler());
+
+    const port = server.addr.port;
+
+    const ws = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+    const received = new Promise<string>((resolve, reject) => {
+      ws.onmessage = (e) => resolve(e.data);
+      ws.onerror = (e) => reject(e);
+    });
+    ws.onopen = () => ws.send("hello");
+
+    const msg = await received;
+    expect(msg).toEqual("ws: hello");
+
+    ws.close();
+    ac.abort();
+    await server.finished;
+  },
+});
+
+Deno.test({
+  name: "ctx.upgrade() - open and close handlers fire",
+  sanitizeOps: false,
+  sanitizeResources: false,
+  async fn() {
+    const events: string[] = [];
+    const closed = Promise.withResolvers<void>();
+
+    const app = new App()
+      .get("/ws", (ctx) =>
+        ctx.upgrade({
+          open() {
+            events.push("open");
+          },
+          close() {
+            events.push("close");
+            closed.resolve();
+          },
+        }));
+
+    const ac = new AbortController();
+    const server = Deno.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      signal: ac.signal,
+      onListen: () => {},
+    }, app.handler());
+
+    const port = server.addr.port;
+
+    const ws = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+    await new Promise<void>((resolve) => {
+      ws.onopen = () => resolve();
+    });
+    ws.close();
+
+    await closed.promise;
+    expect(events).toEqual(["open", "close"]);
+
+    ac.abort();
+    await server.finished;
+  },
+});