@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/src/runtime/deploy-backend.ts

@@ -0,0 +1,239 @@
+import net from 'node:net';
+import { spawn, type ChildProcessByStdio } from 'node:child_process';
+import type { Readable } from 'node:stream';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import type { DeploymentIo, PublishedWorkspaceMode } from './deploy-shared.js';
+import { resolveRuntimeCommand, textResponse } from './deploy-shared.js';
+
+interface RuntimeProcessRecord {
+  readonly child: ChildProcessByStdio<null, Readable, Readable>;
+  readonly exitPromise: Promise<number | null>;
+  expectedExit: boolean;
+}
+
+const READY_TIMEOUT_MS = 15_000;
+const READY_POLL_MS = 100;
+const SOCKET_TIMEOUT_MS = 200;
+
+export function startBackendProcess(options: {
+  readonly workspaceRoot: string;
+  readonly backendEntry: string;
+  readonly port: number;
+  readonly env?: Record<string, string | undefined>;
+  readonly io: DeploymentIo;
+}): RuntimeProcessRecord {
+  const child = spawn(resolveRuntimeCommand(), [options.backendEntry], {
+    cwd: options.workspaceRoot,
+    env: {
+      ...process.env,
+      ...options.env,
+      PORT: String(options.port),
+      NODE_ENV: options.env?.NODE_ENV ?? process.env.NODE_ENV ?? 'production',
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  child.stdout.setEncoding('utf8');
+  child.stderr.setEncoding('utf8');
+  child.stdout.on('data', (chunk: string) => {
+    options.io.stdout.write(`[backend] ${chunk}`);
+  });
+  child.stderr.on('data', (chunk: string) => {
+    options.io.stderr.write(`[backend] ${chunk}`);
+  });
+
+  const exitPromise = new Promise<number | null>((resolve, reject) => {
+    child.once('error', reject);
+    child.once('close', (code) => resolve(code));
+  });
+
+  return {
+    child,
+    exitPromise,
+    expectedExit: false,
+  };
+}
+
+export async function waitForRuntimeReady(
+  port: number,
+  exitPromise: Promise<number | null>,
+): Promise<void> {
+  const abortController = new AbortController();
+
+  try {
+    await Promise.race([
+      waitForPortOpen(port, abortController.signal),
+      exitPromise.then((code) => {
+        throw new Error(`Backend runtime exited before it became ready (code ${code ?? 'null'}).`);
+      }),
+      delay(READY_TIMEOUT_MS).then(() => {
+        throw new Error(`Backend runtime did not become ready within ${READY_TIMEOUT_MS}ms.`);
+      }),
+    ]);
+  } finally {
+    abortController.abort();
+  }
+}
+
+export async function proxyRequest(
+  request: Request,
+  requestUrl: URL,
+  proxyPath: string,
+  backendOrigin: string,
+  mode: PublishedWorkspaceMode,
+): Promise<Response> {
+  const targetUrl = new URL(proxyPath + requestUrl.search, backendOrigin);
+
+  try {
+    const requestInit = createProxyRequestInit(request, targetUrl);
+    const proxyResponse = await fetch(targetUrl, requestInit);
+    const headers = rewriteProxyResponseHeaders(proxyResponse.headers, targetUrl, mode);
+
+    return new Response(request.method !== 'HEAD' ? proxyResponse.body : null, {
+      status: proxyResponse.status,
+      headers,
+    });
+  } catch {
+    return textResponse(502, 'Backend proxy failed.');
+  }
+}
+
+export function shouldProxyToBackend(request: Request, pathname: string): boolean {
+  const method = (request.method ?? 'GET').toUpperCase();
+  if (method !== 'GET' && method !== 'HEAD') {
+    return true;
+  }
+
+  return (
+    pathname === '/api' ||
+    pathname === '/api/health' ||
+    pathname.startsWith('/api/') ||
+    pathname === '/healthz' ||
+    pathname === '/readyz' ||
+    pathname === '/metrics'
+  );
+}
+
+export function getFullWorkspaceProxyPath(pathname: string): string {
+  if (pathname === '/healthz' || pathname === '/readyz' || pathname === '/metrics') {
+    return pathname;
+  }
+
+  if (pathname === '/api') {
+    return '/';
+  }
+
+  if (pathname === '/api/health') {
+    return '/api/health';
+  }
+
+  if (pathname.startsWith('/api/')) {
+    const normalizedPath = pathname.slice('/api'.length);
+    return normalizedPath.startsWith('/') ? normalizedPath : `/${normalizedPath}`;
+  }
+
+  return pathname;
+}
+
+async function waitForPortOpen(port: number, signal: AbortSignal): Promise<void> {
+  while (!signal.aborted) {
+    if (await canConnectToPort(port)) {
+      return;
+    }
+
+    await delay(READY_POLL_MS, undefined, { signal }).catch(() => undefined);
+  }
+
+  throw new Error('Backend readiness check was aborted.');
+}
+
+async function canConnectToPort(port: number): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const socket = net.createConnection({ host: '127.0.0.1', port });
+    let settled = false;
+
+    const finish = (value: boolean) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      socket.destroy();
+      resolve(value);
+    };
+
+    socket.setTimeout(SOCKET_TIMEOUT_MS);
+    socket.once('connect', () => finish(true));
+    socket.once('timeout', () => finish(false));
+    socket.once('error', () => finish(false));
+  });
+}
+
+function rewriteProxyResponseHeaders(
+  headers: Headers,
+  targetUrl: URL,
+  mode: PublishedWorkspaceMode,
+): Headers {
+  const nextHeaders = new Headers(headers);
+  const location = headers.get('location');
+  if (!location) {
+    return nextHeaders;
+  }
+
+  nextHeaders.set('location', rewriteProxyLocation(location, targetUrl, mode));
+  return nextHeaders;
+}
+
+function rewriteProxyLocation(value: string, targetUrl: URL, mode: PublishedWorkspaceMode): string {
+  const trimmed = value.trim();
+  if (!trimmed || mode === 'api') {
+    return value;
+  }
+
+  if (trimmed.startsWith('/')) {
+    return prefixApiMount(trimmed);
+  }
+
+  try {
+    const resolved = new URL(trimmed, targetUrl.origin);
+    if (resolved.origin !== targetUrl.origin) {
+      return value;
+    }
+    return prefixApiMount(`${resolved.pathname}${resolved.search}${resolved.hash}`);
+  } catch {
+    return value;
+  }
+}
+
+function prefixApiMount(pathname: string): string {
+  if (pathname === '/api' || pathname.startsWith('/api/')) {
+    return pathname;
+  }
+
+  return pathname === '/' ? '/api' : `/api${pathname}`;
+}
+
+function createProxyRequestInit(
+  request: Request,
+  targetUrl: URL,
+): RequestInit & { duplex?: 'half' } {
+  const headers = new Headers(request.headers);
+  headers.set('host', targetUrl.host);
+  headers.set('connection', 'close');
+
+  const requestInit: RequestInit & { duplex?: 'half' } = {
+    method: request.method,
+    headers,
+    redirect: 'manual',
+    signal: request.signal,
+  };
+
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    requestInit.body = request.body;
+    if (request.body) {
+      requestInit.duplex = 'half';
+    }
+  }
+
+  return requestInit;
+}

package/src/runtime/deploy-shared.ts

@@ -0,0 +1,136 @@
+import net from 'node:net';
+import path from 'node:path';
+import { access, readFile } from 'node:fs/promises';
+
+export interface PublishedWorkspaceServerOptions {
+  readonly workspaceRoot: string;
+  readonly host?: string;
+  readonly port?: number;
+  readonly env?: Record<string, string | undefined>;
+  readonly io?: DeploymentIo;
+}
+
+export interface PublishedWorkspaceServer {
+  readonly origin: string;
+  readonly mode: PublishedWorkspaceMode;
+  stop(): Promise<void>;
+}
+
+export interface DeploymentIo {
+  readonly stdout: {
+    write(message: string): void;
+  };
+  readonly stderr: {
+    write(message: string): void;
+  };
+}
+
+export type PublishedWorkspaceMode = 'api' | 'full';
+
+export interface BunServerLike {
+  readonly port: number;
+  stop(closeActiveConnections?: boolean): void;
+}
+
+export interface BunLike {
+  serve(options: {
+    readonly port: number;
+    readonly hostname?: string;
+    readonly idleTimeout?: number;
+    fetch(request: Request): Response | Promise<Response>;
+    error?(error: Error): Response | Promise<Response>;
+  }): BunServerLike;
+  file(pathname: string): Blob;
+}
+
+export const DEFAULT_PUBLIC_PORT = 8080;
+
+export async function readPublishedWorkspaceMode(
+  workspaceRoot: string,
+): Promise<PublishedWorkspaceMode> {
+  const packageJsonPath = path.join(workspaceRoot, 'package.json');
+  const source = await readFile(packageJsonPath, 'utf8');
+  const packageJson = JSON.parse(source) as {
+    webstir?: {
+      mode?: string;
+    };
+  };
+  const mode = packageJson.webstir?.mode;
+  if (mode === 'api' || mode === 'full') {
+    return mode;
+  }
+
+  throw new Error(
+    `Published deploy only supports api and full workspaces. Received ${JSON.stringify(mode)} in ${packageJsonPath}.`,
+  );
+}
+
+export async function assertExists(targetPath: string, label: string): Promise<void> {
+  try {
+    await access(targetPath);
+  } catch {
+    throw new Error(`Expected ${label} at ${targetPath}.`);
+  }
+}
+
+export async function getOpenPort(): Promise<number> {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        reject(new Error('Failed to allocate an open port.'));
+        return;
+      }
+
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+
+        resolve(address.port);
+      });
+    });
+  });
+}
+
+export function textResponse(statusCode: number, body: string): Response {
+  return new Response(body, {
+    status: statusCode,
+    headers: {
+      'Content-Type': 'text/plain; charset=utf-8',
+    },
+  });
+}
+
+export function resolveRuntimeCommand(): string {
+  if (typeof process.versions.bun === 'string') {
+    return process.execPath;
+  }
+
+  return 'bun';
+}
+
+export function requireBunRuntime(): BunLike {
+  const bun = (globalThis as typeof globalThis & { Bun?: BunLike }).Bun;
+  if (!bun?.serve || !bun.file) {
+    throw new Error('Published Webstir deploy requires Bun at runtime.');
+  }
+
+  return bun;
+}
+
+export const defaultIo: DeploymentIo = {
+  stdout: {
+    write(message) {
+      process.stdout.write(message);
+    },
+  },
+  stderr: {
+    write(message) {
+      process.stderr.write(message);
+    },
+  },
+};

package/src/runtime/deploy-static.ts

@@ -0,0 +1,191 @@
+import path from 'node:path';
+import { access } from 'node:fs/promises';
+
+import { requireBunRuntime, textResponse } from './deploy-shared.js';
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.txt': 'text/plain; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+};
+const RESERVED_PREFIXES = ['__webstir', 'api', 'fonts', 'images', 'media', 'pages', 'sse'];
+const STATIC_EXTENSIONS = new Set([
+  '.css',
+  '.js',
+  '.mjs',
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.svg',
+  '.webp',
+  '.ico',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.otf',
+  '.eot',
+  '.mp3',
+  '.m4a',
+  '.wav',
+  '.ogg',
+  '.mp4',
+  '.webm',
+  '.mov',
+  '.json',
+  '.txt',
+  '.xml',
+  '.map',
+]);
+const CONTENT_HASH_PATTERN =
+  /\.[a-f0-9]{8,64}\.(css|js|png|jpg|jpeg|gif|svg|webp|ico|woff2?|ttf|otf|eot|mp3|m4a|wav|ogg|mp4|webm|mov)$/i;
+
+export async function servePublishedStaticFile(
+  request: Request,
+  frontendRoot: string,
+): Promise<Response> {
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    return textResponse(405, 'Method not allowed.');
+  }
+
+  const requestUrl = new URL(request.url);
+  const candidates = getStaticCandidatePaths(requestUrl.pathname);
+  const resolved = await resolveStaticFile(frontendRoot, candidates);
+  if (!resolved) {
+    return textResponse(404, 'Not found.');
+  }
+
+  const lowerRelativePath = resolved.relativePath.toLowerCase();
+  const extension = path.extname(lowerRelativePath).toLowerCase();
+  const headers = new Headers({
+    'Content-Type': MIME_TYPES[extension] ?? 'application/octet-stream',
+  });
+  setCacheHeaders(headers, lowerRelativePath);
+
+  if (request.method === 'HEAD') {
+    return new Response(null, {
+      status: 200,
+      headers,
+    });
+  }
+
+  return new Response(requireBunRuntime().file(resolved.absolutePath), {
+    status: 200,
+    headers,
+  });
+}
+
+export function getStaticCandidatePaths(pathname: string): readonly string[] {
+  const relativePath = normalizeRequestPath(pathname);
+  const candidates: string[] = [];
+
+  if (relativePath) {
+    candidates.push(...getGenericFileCandidates(relativePath));
+  }
+
+  if (relativePath === '') {
+    candidates.push('pages/home/index.html');
+  } else if (/^index\.(?!html$)[^/]+$/i.test(relativePath)) {
+    candidates.push(path.posix.join('pages', 'home', relativePath));
+  } else if (/^[^/]+\/index\.(js|css)$/i.test(relativePath)) {
+    const [pageName, fileName] = relativePath.split('/');
+    candidates.push(path.posix.join('pages', pageName, fileName));
+  } else if (!path.posix.extname(relativePath) && !hasReservedPrefix(relativePath)) {
+    candidates.push(path.posix.join('pages', relativePath, 'index.html'));
+  }
+
+  return Array.from(new Set(candidates.map((candidate) => candidate.replace(/^\/+/, ''))));
+}
+
+async function resolveStaticFile(
+  buildRoot: string,
+  relativePaths: readonly string[],
+): Promise<{ absolutePath: string; relativePath: string } | null> {
+  for (const relativePath of relativePaths) {
+    const absolutePath = path.resolve(buildRoot, relativePath);
+    if (!absolutePath.startsWith(buildRoot + path.sep) && absolutePath !== buildRoot) {
+      continue;
+    }
+
+    try {
+      await access(absolutePath);
+      return { absolutePath, relativePath };
+    } catch (error) {
+      if (isMissingStaticCandidate(error)) {
+        continue;
+      }
+
+      throw error;
+    }
+  }
+
+  return null;
+}
+
+function isMissingStaticCandidate(error: unknown): boolean {
+  if (!error || typeof error !== 'object' || !('code' in error)) {
+    return false;
+  }
+
+  return error.code === 'ENOENT' || error.code === 'ENOTDIR';
+}
+
+function normalizeRequestPath(pathname: string): string {
+  const decoded = decodeURIComponent(pathname);
+  const normalized = path.posix.normalize(decoded);
+  const stripped = normalized.replace(/^(\.\.(\/|\\|$))+/, '').replace(/^\/+/, '');
+  return stripped.replace(/\/+$/, '');
+}
+
+function getGenericFileCandidates(relativePath: string): readonly string[] {
+  const hasExtension = path.posix.extname(relativePath) !== '';
+  const candidates = hasExtension
+    ? [relativePath]
+    : [relativePath, `${relativePath}.html`, path.posix.join(relativePath, 'index.html')];
+
+  return candidates;
+}
+
+function hasReservedPrefix(relativePath: string): boolean {
+  return RESERVED_PREFIXES.some(
+    (prefix) => relativePath === prefix || relativePath.startsWith(`${prefix}/`),
+  );
+}
+
+function setCacheHeaders(headers: Headers, relativePath: string): void {
+  if (CONTENT_HASH_PATTERN.test(relativePath)) {
+    headers.set('Cache-Control', 'public, max-age=31536000, immutable');
+    return;
+  }
+
+  const extension = path.extname(relativePath).toLowerCase();
+  if (extension === '.html' || extension === '') {
+    setNoCacheHeaders(headers);
+    return;
+  }
+
+  if (STATIC_EXTENSIONS.has(extension)) {
+    headers.set('Cache-Control', 'no-cache, must-revalidate');
+  }
+}
+
+function setNoCacheHeaders(headers: Headers): void {
+  headers.set('Cache-Control', 'no-cache, no-store, must-revalidate');
+  headers.set('Pragma', 'no-cache');
+  headers.set('Expires', '0');
+}

package/src/runtime/deploy.ts

@@ -0,0 +1,143 @@
+import path from 'node:path';
+import {
+  getFullWorkspaceProxyPath,
+  proxyRequest,
+  shouldProxyToBackend,
+  startBackendProcess,
+  waitForRuntimeReady,
+} from './deploy-backend.js';
+import {
+  assertExists,
+  DEFAULT_PUBLIC_PORT,
+  defaultIo,
+  getOpenPort,
+  readPublishedWorkspaceMode,
+  requireBunRuntime,
+  textResponse,
+  type DeploymentIo,
+  type PublishedWorkspaceMode,
+  type PublishedWorkspaceServer,
+  type PublishedWorkspaceServerOptions,
+} from './deploy-shared.js';
+import { servePublishedStaticFile } from './deploy-static.js';
+
+export type { DeploymentIo, PublishedWorkspaceServer, PublishedWorkspaceServerOptions };
+
+export async function startPublishedWorkspaceServer(
+  options: PublishedWorkspaceServerOptions,
+): Promise<PublishedWorkspaceServer> {
+  const bun = requireBunRuntime();
+  const workspaceRoot = path.resolve(options.workspaceRoot);
+  const io = options.io ?? defaultIo;
+  const mode = await readPublishedWorkspaceMode(workspaceRoot);
+  const frontendRoot = mode === 'full' ? path.join(workspaceRoot, 'dist', 'frontend') : undefined;
+  const backendEntry = path.join(workspaceRoot, 'build', 'backend', 'index.js');
+
+  await assertExists(backendEntry, 'published backend entry');
+  if (frontendRoot) {
+    await assertExists(frontendRoot, 'published frontend output');
+  }
+
+  const internalPort = await getOpenPort();
+  const processRecord = startBackendProcess({
+    workspaceRoot,
+    backendEntry,
+    port: internalPort,
+    env: options.env,
+    io,
+  });
+  const backendOrigin = `http://127.0.0.1:${internalPort}`;
+  let stopping = false;
+
+  try {
+    await waitForRuntimeReady(internalPort, processRecord.exitPromise);
+  } catch (error) {
+    processRecord.expectedExit = true;
+    processRecord.child.kill('SIGTERM');
+    await processRecord.exitPromise.catch(() => undefined);
+    throw error;
+  }
+
+  const host = options.host ?? '0.0.0.0';
+  const requestedPort = options.port ?? DEFAULT_PUBLIC_PORT;
+  const server = bun.serve({
+    hostname: host,
+    idleTimeout: 0,
+    port: requestedPort,
+    fetch: async (request) =>
+      await handlePublishedWorkspaceRequest({
+        request,
+        mode,
+        frontendRoot,
+        backendOrigin,
+      }),
+    error: (error) => textResponse(500, error.message),
+  });
+
+  processRecord.exitPromise
+    .then((code) => {
+      if (stopping || processRecord.expectedExit) {
+        return;
+      }
+
+      io.stderr.write(
+        `[webstir-backend-deploy] backend runtime exited unexpectedly with code ${code ?? 'null'}.\n`,
+      );
+      server.stop(true);
+    })
+    .catch((error) => {
+      if (stopping) {
+        return;
+      }
+
+      io.stderr.write(
+        `[webstir-backend-deploy] backend runtime failed: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+      server.stop(true);
+    });
+
+  const displayHost = host === '0.0.0.0' ? '127.0.0.1' : host;
+
+  return {
+    origin: `http://${displayHost}:${server.port}`,
+    mode,
+    async stop() {
+      stopping = true;
+      server.stop(true);
+      processRecord.expectedExit = true;
+      processRecord.child.kill('SIGTERM');
+      await processRecord.exitPromise.catch(() => undefined);
+    },
+  };
+}
+
+async function handlePublishedWorkspaceRequest(options: {
+  readonly request: Request;
+  readonly mode: PublishedWorkspaceMode;
+  readonly frontendRoot?: string;
+  readonly backendOrigin: string;
+}): Promise<Response> {
+  const requestUrl = new URL(options.request.url);
+  const pathname = requestUrl.pathname;
+
+  if (options.mode === 'api') {
+    return await proxyRequest(options.request, requestUrl, pathname, options.backendOrigin, 'api');
+  }
+
+  if (shouldProxyToBackend(options.request, pathname)) {
+    const proxyPath = getFullWorkspaceProxyPath(pathname);
+    return await proxyRequest(
+      options.request,
+      requestUrl,
+      proxyPath,
+      options.backendOrigin,
+      'full',
+    );
+  }
+
+  if (!options.frontendRoot) {
+    return textResponse(500, 'Published frontend output is not available.');
+  }
+
+  return await servePublishedStaticFile(options.request, options.frontendRoot);
+}