fix(worker): terminal WebSocket path matches Cloudflare container demo

- Move DO stub.fetch out of Effect so upgrade Response reaches the browser intact.
- Split prepareTerminalForWebSocketContext (auth + readiness) from raw stub.fetch.
- Strip ticket from container-bound URL; copy WS handshake headers explicitly.
- Log DO fetch results and container errors; expose toErrorResponse for non-Hono paths.

Made-with: Cursor

Author: acoyfellow

worker/effect/programs.ts

@@ -22,7 +22,8 @@ export const requireAuthorizedUsername = (input: {
     return yield* auth.requireUsername(input);
   });
 
-export const connectTerminal = (input: {
+/** Auth, workspace, container readiness — no DO stub.fetch. Cloudflare terminal demo returns stub.fetch outside any framework; Effect breaks WS Responses. */
+export const prepareTerminalForWebSocketContext = (input: {
   readonly request: Request;
   readonly upgrade?: string;
   readonly userIdHeader?: string | null;
@@ -75,11 +76,31 @@ export const connectTerminal = (input: {
       tabs: selection.tabs,
     });
 
-    return yield* runtime.proxyTerminalRequest(ready, {
-      request: input.request,
+    return {
+      ready,
       username,
       sessionId: selection.session.id,
       tabId: selection.tab.id,
+    };
+  });
+
+/** Tests / legacy: full path including proxy inside Effect (WS Response may not survive). */
+export const connectTerminal = (input: {
+  readonly request: Request;
+  readonly upgrade?: string;
+  readonly userIdHeader?: string | null;
+  readonly ticket?: string | null;
+  readonly requestedSessionId?: string | null;
+  readonly requestedTabId?: string | null;
+}) =>
+  Effect.gen(function* () {
+    const ctx = yield* prepareTerminalForWebSocketContext(input);
+    const runtime = yield* ContainerRuntime;
+    return yield* runtime.proxyTerminalRequest(ctx.ready, {
+      request: input.request,
+      username: ctx.username,
+      sessionId: ctx.sessionId,
+      tabId: ctx.tabId,
     });
   });
 

worker/effect/runtime.ts

@@ -72,7 +72,7 @@ export async function runRequestEffect<A>(
   return value;
 }
 
-export function toRouteErrorResponse(c: WorkerContext, error: unknown): Response {
+export function toErrorResponse(error: unknown): Response {
   const normalized = normalizeRouteError(error);
   const appError = isAppError(normalized)
     ? normalized
@@ -96,6 +96,10 @@ export function toRouteErrorResponse(c: WorkerContext, error: unknown): Response
   });
 }
 
+export function toRouteErrorResponse(_c: WorkerContext, error: unknown): Response {
+  return toErrorResponse(error);
+}
+
 function tryGetExecutionCtx(c: WorkerContext): ExecutionContext | undefined {
   try {
     return c.executionCtx;

worker/effect/services.ts

@@ -177,7 +177,41 @@ function toPersistenceFailure(message: string) {
 }
 
 function toContainerFailure(message: string, retryable: boolean) {
-  return () => new ContainerUnavailable({ message, retryable });
+  return (cause: unknown) => {
+    console.error('[container]', message, { retryable, cause });
+    return new ContainerUnavailable({ message, retryable });
+  };
+}
+
+/** DO → container: minimal path, no ticket query (JWT length breaks some internal hops). Session/tab come from X-* headers (main.go). */
+export function buildContainerWebSocketRequest(
+  clientRequest: Request,
+  username: string,
+  sessionId: string,
+  tabId: string
+): Request {
+  const internal = new URL('/ws/terminal', 'http://127.0.0.1:8080');
+  const h = new Headers();
+  for (const name of [
+    'upgrade',
+    'connection',
+    'sec-websocket-key',
+    'sec-websocket-version',
+    'sec-websocket-protocol',
+    'sec-websocket-extensions',
+  ]) {
+    const v = clientRequest.headers.get(name);
+    if (v) {
+      h.set(name, v);
+    }
+  }
+  h.set('X-User', username);
+  h.set('X-Session-Id', sessionId);
+  h.set('X-Tab-Id', tabId);
+  if (!h.has('sec-websocket-key') || !h.has('sec-websocket-version')) {
+    console.error('[ws/terminal] missing WS handshake headers on container request');
+  }
+  return new Request(internal, { method: 'GET', headers: h });
 }
 
 function runtimeAnnotations(context: RuntimeLogContext, containerId: string) {
@@ -871,14 +905,37 @@ const ContainerRuntimeLive = Layer.effect(
           ready.containerId,
           Effect.tryPromise({
             try: async () => {
-              const headers = new Headers(input.request.headers);
-              headers.set('X-User', input.username);
-              headers.set('X-Session-Id', input.sessionId);
-              headers.set('X-Tab-Id', input.tabId);
-              // Match @cloudflare/containers: Container.fetch → containerFetch uses getTcpPort + request.url (https→http).
-              // containers-demos/terminal uses containerFetch(request, defaultPort); WebSockets need that path, not a manual localhost URL.
-              const proxied = new Request(input.request, { headers });
-              return ready.container.fetch(switchPort(proxied, 8080));
+              const t0 = Date.now();
+              const containerReq = buildContainerWebSocketRequest(
+                input.request,
+                input.username,
+                input.sessionId,
+                input.tabId
+              );
+              const switched = switchPort(containerReq, 8080);
+              let res: Response;
+              try {
+                res = await ready.container.fetch(switched);
+              } catch (err) {
+                console.error('[ws/terminal] DO stub.fetch threw', {
+                  containerId: ready.containerId,
+                  ms: Date.now() - t0,
+                  err,
+                });
+                throw err;
+              }
+              const ws = (res as { webSocket?: WebSocket }).webSocket;
+              console.log('[ws/terminal] DO stub.fetch result', {
+                containerId: ready.containerId,
+                status: res.status,
+                hasWebSocket: ws != null,
+                ms: Date.now() - t0,
+              });
+              if (res.status >= 400 || (res.status !== 101 && ws == null)) {
+                const peek = await res.clone().text().catch(() => '');
+                console.log('[ws/terminal] non-upgrade response body', peek.slice(0, 400));
+              }
+              return res;
             },
             catch: toContainerFailure('Container error, please retry in a moment.', true),
           })

worker/index.ts

@@ -1,10 +1,9 @@
 import { Hono } from 'hono';
-import type { Context } from 'hono';
-import { Container, getContainer } from '@cloudflare/containers';
+import type { Context, ExecutionContext } from 'hono';
+import { Container, getContainer, switchPort } from '@cloudflare/containers';
 import {
   backupWorkspace,
   checkpointSession,
-  connectTerminal,
   createLegacyTab,
   createSession,
   createTab,
@@ -21,8 +20,17 @@ import {
   requireAuthorizedUsername,
   updateTab,
   updateSession,
+  prepareTerminalForWebSocketContext,
 } from './effect/programs';
-import { runJsonRoute, runRequestEffect, runRouteEffect, toRouteErrorResponse } from './effect/runtime';
+import { buildContainerWebSocketRequest } from './effect/services';
+import {
+  runJsonRoute,
+  runRequestEffect,
+  runRouteEffect,
+  toErrorResponse,
+  toRouteErrorResponse,
+} from './effect/runtime';
+import { UnexpectedFailure } from './effect/errors';
 import { getUserSessionContainerId, readWorkerIdentity } from './auth';
 import { isContainerActiveStatus } from './tabs';
 import type { Env } from './types';
@@ -154,35 +162,6 @@ function createApp() {
   // Health check
   app.get('/health', (c) => c.json({ status: 'ok' }));
 
-  // WebSocket terminal with Effect orchestration
-  app.get('/ws/terminal', (c) => {
-    const upgrade = c.req.header('Upgrade');
-    if (upgrade?.toLowerCase() !== 'websocket') {
-      return c.text('expected websocket', 426);
-    }
-
-    // Workers Logs (not Container stdout): confirms the request reached this worker before DO/container.
-    console.log('[ws/terminal] incoming', {
-      hasTicket: Boolean(c.req.query('ticket')),
-      querySessionId: c.req.query('sessionId') ?? null,
-      queryTabId: c.req.query('tabId') ?? null,
-      hasUserHeader: Boolean(c.req.header('X-User-Id')),
-    });
-
-    return runRouteEffect(
-      c,
-      connectTerminal({
-        request: c.req.raw,
-        upgrade,
-        userIdHeader: c.req.header('X-User-Id'),
-        ticket: c.req.query('ticket'),
-        requestedSessionId: c.req.query('sessionId'),
-        requestedTabId: c.req.query('tabId'),
-      }),
-      (response) => response
-    );
-  });
-
   // Session APIs
   app.get('/api/sessions', (c) => runJsonRoute(c, listSessions(c.req.header('X-User-Id'))));
   app.post('/api/sessions', (c) =>
@@ -514,5 +493,74 @@ function createApp() {
 
 const app = createApp();
 
+async function handleTerminalWebSocket(request: Request, env: Env): Promise<Response> {
+  const url = new URL(request.url);
+  console.log('[ws/terminal] incoming (raw)', {
+    hasTicket: Boolean(url.searchParams.get('ticket')),
+    querySessionId: url.searchParams.get('sessionId'),
+    queryTabId: url.searchParams.get('tabId'),
+    hasUserHeader: Boolean(request.headers.get('X-User-Id')),
+  });
+
+  try {
+    // containers-demos/terminal: `return await getContainer(env.TERMINAL).fetch(request)` — no Effect around stub.fetch.
+    const prep = await runRequestEffect(
+      env,
+      prepareTerminalForWebSocketContext({
+        request,
+        upgrade: request.headers.get('Upgrade') ?? undefined,
+        userIdHeader: request.headers.get('X-User-Id'),
+        ticket: url.searchParams.get('ticket'),
+        requestedSessionId: url.searchParams.get('sessionId'),
+        requestedTabId: url.searchParams.get('tabId'),
+      })
+    );
+
+    const t0 = Date.now();
+    const inner = buildContainerWebSocketRequest(request, prep.username, prep.sessionId, prep.tabId);
+    let res: Response;
+    try {
+      res = await prep.ready.container.fetch(switchPort(inner, 8080));
+    } catch (err) {
+      console.error('[ws/terminal] DO stub.fetch threw', { ms: Date.now() - t0, err });
+      return toErrorResponse(
+        new UnexpectedFailure({
+          message: 'Container error, please retry in a moment.',
+          cause: err,
+        })
+      );
+    }
+
+    const ws = (res as { webSocket?: WebSocket }).webSocket;
+    console.log('[ws/terminal] direct stub.fetch', {
+      status: res.status,
+      hasWebSocket: ws != null,
+      ms: Date.now() - t0,
+      containerId: prep.ready.containerId,
+    });
+    if (res.status >= 400 || (res.status !== 101 && ws == null)) {
+      const peek = await res.clone().text().catch(() => '');
+      console.log('[ws/terminal] non-upgrade response body', peek.slice(0, 400));
+    }
+    return res;
+  } catch (error) {
+    return toErrorResponse(error);
+  }
+}
+
 export { createApp };
-export default app;
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname === '/ws/terminal' && request.method === 'GET') {
+      if (request.headers.get('Upgrade')?.toLowerCase() !== 'websocket') {
+        return new Response('expected websocket', {
+          status: 426,
+          headers: { 'Content-Type': 'text/plain; charset=UTF-8' },
+        });
+      }
+      return handleTerminalWebSocket(request, env);
+    }
+    return app.fetch(request, env, ctx);
+  },
+};