fix: stabilize local auth session exchange

apps/api/scripts/dev-with-local-hyperdrive.mjs

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import net from 'node:net';
 
 const parseEnvFile = (contents) => {
   const values = {};
@@ -34,6 +35,36 @@ const parseEnvFile = (contents) => {
 
 const ROOT_ENV_PATH = resolve(process.cwd(), '..', '..', '.env');
 const API_DEV_VARS_PATH = resolve(process.cwd(), '.dev.vars');
+const API_DEV_PORT = 8787;
+
+const assertPortAvailable = async (port, label) => {
+  await new Promise((resolvePromise, rejectPromise) => {
+    const server = net.createServer();
+
+    server.once('error', (error) => {
+      server.close();
+      rejectPromise(error);
+    });
+
+    server.listen(port, () => {
+      server.close((closeError) => {
+        if (closeError) {
+          rejectPromise(closeError);
+          return;
+        }
+        resolvePromise();
+      });
+    });
+  }).catch((error) => {
+    if ((error && typeof error === 'object' && 'code' in error && error.code) === 'EADDRINUSE') {
+      console.error(`${label} is already in use. Stop the existing process before starting local dev.`);
+      process.exit(1);
+    }
+
+    console.error(`Unable to verify ${label}: ${error instanceof Error ? error.message : 'unknown error'}`);
+    process.exit(1);
+  });
+};
 
 const loadRootEnv = () => {
   if (!existsSync(ROOT_ENV_PATH)) {
@@ -49,6 +80,7 @@ const loadRootEnv = () => {
 };
 
 loadRootEnv();
+await assertPortAvailable(API_DEV_PORT, 'api-dev-port');
 
 if (!process.env.CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE) {
   const databaseUrl = process.env.DATABASE_URL?.trim();
@@ -65,7 +97,7 @@ if (!process.env.CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE) {
 }
 
 const wranglerCommand = process.platform === 'win32' ? 'wrangler.cmd' : 'wrangler';
-const wranglerArgs = ['dev', '--config', 'wrangler.toml'];
+const wranglerArgs = ['dev', '--config', 'wrangler.toml', '--port', String(API_DEV_PORT)];
 
 if (existsSync(API_DEV_VARS_PATH)) {
   wranglerArgs.push('--env-file', API_DEV_VARS_PATH);

apps/api/src/server/database.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { shouldUsePerRequestDatabase } from './database';
+
+describe('shouldUsePerRequestDatabase', () => {
+  it('uses a short-lived database client for localhost requests', () => {
+    expect(
+      shouldUsePerRequestDatabase({
+        env: { APP_BASE_URL: 'https://opencalendly.com' },
+        req: { url: 'http://localhost:8787/v0/auth/me' },
+      }),
+    ).toBe(true);
+  });
+
+  it('uses a short-lived database client for localhost app configuration', () => {
+    expect(
+      shouldUsePerRequestDatabase({
+        env: { APP_BASE_URL: 'http://localhost:3000' },
+      }),
+    ).toBe(true);
+  });
+
+  it('keeps runtime database reuse enabled for non-local environments', () => {
+    expect(
+      shouldUsePerRequestDatabase({
+        env: { APP_BASE_URL: 'https://opencalendly.com' },
+        req: { url: 'https://api.opencalendly.com/v0/auth/me' },
+      }),
+    ).toBe(false);
+  });
+});

apps/api/src/server/database.ts

@@ -1,9 +1,39 @@
-import { createRuntimeDb } from '@opencalendly/db';
+import { createDb, createRuntimeDb } from '@opencalendly/db';
 
 import { jsonError } from './core';
 import { isNeonDatabaseUrl, resolveConnectionString } from './env';
 import type { ContextLike, Database } from './types';
 
+const LOCAL_DATABASE_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
+
+const normalizeHostname = (value: string): string => {
+  return value.trim().toLowerCase().replace(/^\[(.*)\]$/, '$1');
+};
+
+export const shouldUsePerRequestDatabase = (context: Pick<ContextLike, 'env'> & { req?: { url: string } }): boolean => {
+  if (context.req?.url) {
+    try {
+      const requestUrl = new URL(context.req.url);
+      if (LOCAL_DATABASE_HOSTS.has(normalizeHostname(requestUrl.hostname))) {
+        return true;
+      }
+    } catch {
+      // Ignore malformed request URLs and fall back to APP_BASE_URL detection.
+    }
+  }
+
+  const configuredAppUrl = context.env.APP_BASE_URL?.trim();
+  if (!configuredAppUrl) {
+    return false;
+  }
+
+  try {
+    return LOCAL_DATABASE_HOSTS.has(normalizeHostname(new URL(configuredAppUrl).hostname));
+  } catch {
+    return false;
+  }
+};
+
 export const isUniqueViolation = (error: unknown, constraint?: string): boolean => {
   if (!error || typeof error !== 'object') {
     return false;
@@ -33,6 +63,20 @@ export const withDatabase = async (
     return jsonError(context, 500, 'DATABASE_URL must point to Neon Postgres (*.neon.tech).');
   }
 
+  if (shouldUsePerRequestDatabase(context)) {
+    // Wrangler/workerd local dev can hang retained pg pools after auth/session requests.
+    // Use a short-lived client for localhost flows and keep pooled reuse for deployed runtimes.
+    const { client, db } = createDb(connection.connectionString, {
+      enforceNeon: connection.source === 'database_url',
+    });
+    await client.connect();
+    try {
+      return await handler(db);
+    } finally {
+      await client.end().catch(() => undefined);
+    }
+  }
+
   const { db } = createRuntimeDb(connection.connectionString, {
     enforceNeon: connection.source === 'database_url',
   });

apps/web/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "node -e \"require('node:fs').rmSync('.next', { recursive: true, force: true })\" && next dev",
+    "dev": "node ../../scripts/ensure-dev-port.mjs 3000 web-dev-port && node -e \"require('node:fs').rmSync('.next', { recursive: true, force: true })\" && next dev -p 3000",
     "build": "next build",
     "start": "next start",
     "typecheck": "tsc --project tsconfig.json --noEmit",

docs/BACKLOG.md

@@ -1532,3 +1532,23 @@ Acceptance criteria:
 - Validation passes:
   - `git diff --check`
   - workflow YAML remains syntactically valid
+
+### Feature 59: Local auth safety on fixed dev ports
+
+Scope:
+- Prevent local auth and OAuth flows from silently breaking when the web or API dev server starts on an unexpected fallback port.
+- Keep local development pinned to `localhost:3000` for web and `localhost:8787` for API.
+- Fail fast with a clear error when either expected port is already occupied.
+- Keep the pooled local API database runtime compatible with wrangler/workerd timer behavior so auth session exchange does not fail under local development.
+
+Acceptance criteria:
+
+- `npm run dev:web` checks port `3000` first and exits with a clear message instead of silently switching to another port.
+- `npm run dev:api` checks port `8787` first and exits with a clear message instead of silently switching to another port.
+- Local auth/OAuth assumptions remain aligned with `.env` defaults for `APP_BASE_URL` and `NEXT_PUBLIC_API_BASE_URL`.
+- Local API auth/session requests do not fail with `tid.unref is not a function` from pooled database cleanup.
+- Local localhost auth/session requests remain stable under wrangler/workerd instead of hanging after `POST /v0/auth/clerk/exchange`.
+- Validation passes:
+  - `npm run lint`
+  - `npm run test`
+  - `npm run typecheck`

packages/db/src/client.test.ts

@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { runtimeSupportsTimerUnref } from './client';
+
+describe('runtimeSupportsTimerUnref', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('returns true when timers expose unref', () => {
+    const unref = vi.fn();
+    const timer = { unref };
+    const clearTimeoutMock = vi.fn();
+
+    vi.stubGlobal('setTimeout', vi.fn(() => timer) as unknown as typeof setTimeout);
+    vi.stubGlobal('clearTimeout', clearTimeoutMock as unknown as typeof clearTimeout);
+
+    expect(runtimeSupportsTimerUnref()).toBe(true);
+    expect(clearTimeoutMock).toHaveBeenCalledWith(timer);
+  });
+
+  it('returns false when timers do not expose unref', () => {
+    const clearTimeoutMock = vi.fn();
+
+    vi.stubGlobal('setTimeout', vi.fn(() => 1) as unknown as typeof setTimeout);
+    vi.stubGlobal('clearTimeout', clearTimeoutMock as unknown as typeof clearTimeout);
+
+    expect(runtimeSupportsTimerUnref()).toBe(false);
+    expect(clearTimeoutMock).toHaveBeenCalledWith(1);
+  });
+});

packages/db/src/client.ts

@@ -33,6 +33,14 @@ type RuntimeDbEntry = {
   db: ReturnType<typeof drizzle<typeof schema>>;
 };
 
+export const runtimeSupportsTimerUnref = (): boolean => {
+  const timer = setTimeout(() => undefined, 0) as ReturnType<typeof setTimeout> & {
+    unref?: () => unknown;
+  };
+  clearTimeout(timer);
+  return typeof timer === 'object' && timer !== null && typeof timer.unref === 'function';
+};
+
 const getRuntimeDbCache = (): Map<string, RuntimeDbEntry> => {
   const globalCache = globalThis as typeof globalThis & {
     __opencalendlyRuntimeDbCache__?: Map<string, RuntimeDbEntry>;
@@ -69,14 +77,19 @@ export const createPgPool = (
     assertNeonDatabaseUrl(databaseUrl);
   }
 
-  return new Pool({
+  const poolOptions: ConstructorParameters<typeof Pool>[0] = {
     connectionString: databaseUrl,
     ssl: { rejectUnauthorized: false },
     max: 20,
     idleTimeoutMillis: 30_000,
     connectionTimeoutMillis: 5_000,
-    allowExitOnIdle: true,
-  });
+  };
+
+  if (runtimeSupportsTimerUnref()) {
+    poolOptions.allowExitOnIdle = true;
+  }
+
+  return new Pool(poolOptions);
 };
 
 export const createDb = (databaseUrl = getDatabaseUrl(), options: CreatePgClientOptions = {}) => {

scripts/ensure-dev-port.mjs

@@ -0,0 +1,26 @@
+import net from 'node:net';
+
+const [rawPort, ...labelParts] = process.argv.slice(2);
+const port = Number.parseInt(rawPort ?? '', 10);
+const label = labelParts.join(' ').trim() || `port ${rawPort ?? 'unknown'}`;
+
+if (!Number.isInteger(port) || port <= 0) {
+  console.error('Usage: node scripts/ensure-dev-port.mjs <port> [label]');
+  process.exit(1);
+}
+
+const server = net.createServer();
+
+server.once('error', (error) => {
+  if ((error && typeof error === 'object' && 'code' in error && error.code) === 'EADDRINUSE') {
+    console.error(`${label} is already in use. Stop the existing process before starting local dev.`);
+    process.exit(1);
+  }
+
+  console.error(`Unable to verify ${label}: ${error instanceof Error ? error.message : 'unknown error'}`);
+  process.exit(1);
+});
+
+server.listen(port, () => {
+  server.close(() => process.exit(0));
+});