@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/dist/runtime/core.js

@@ -0,0 +1,316 @@
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolveRequestHooks, } from './request-hooks.js';
+import { compileViews, } from './views.js';
+export class RequestBodyTooLargeError extends Error {
+    statusCode = 413;
+    code = 'payload_too_large';
+    constructor(maxBytes) {
+        super(`Request body exceeded ${maxBytes} bytes.`);
+    }
+}
+export function createProcessEnvAccessor() {
+    return {
+        get: (name) => process.env[name],
+        require: (name) => {
+            const value = process.env[name];
+            if (value === undefined) {
+                throw new Error(`Missing required env var ${name}`);
+            }
+            return value;
+        },
+        entries: () => ({ ...process.env }),
+    };
+}
+export function createReadinessTracker() {
+    let status = 'booting';
+    let message;
+    return {
+        booting() {
+            status = 'booting';
+            message = undefined;
+        },
+        ready() {
+            status = 'ready';
+            message = undefined;
+        },
+        error(reason) {
+            status = 'error';
+            message = reason;
+        },
+        snapshot() {
+            return { status, message };
+        },
+    };
+}
+export function normalizePath(value) {
+    if (!value || value === '/') {
+        return '/';
+    }
+    const trimmed = value.endsWith('/') ? value.slice(0, -1) : value;
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function matchRoute(routes, method, pathname) {
+    const normalizedMethod = (method ?? 'GET').toUpperCase();
+    for (const route of routes) {
+        if (route.method !== normalizedMethod) {
+            continue;
+        }
+        const { matched, params } = route.match(pathname);
+        if (matched) {
+            return { route, params };
+        }
+    }
+    return undefined;
+}
+export async function loadModuleRuntime(options) {
+    const loaded = await tryLoadModuleDefinition(options);
+    if (!loaded) {
+        return { routes: [], views: [] };
+    }
+    const manifest = sanitizeManifest(loaded.definition.manifest);
+    const compiled = compileRoutes(loaded.definition.routes ?? [], {
+        manifestRequestHooks: manifest?.requestHooks,
+        requestHookImplementations: loaded.definition.requestHooks,
+    });
+    const views = compileViews(resolveModuleViews(loaded.definition, manifest));
+    return {
+        definition: loaded.definition,
+        manifest,
+        routes: compiled.routes,
+        views,
+        source: loaded.source,
+        warnings: compiled.warnings,
+    };
+}
+export function summarizeManifest(manifest) {
+    if (!manifest) {
+        return undefined;
+    }
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        routes: Array.isArray(manifest.routes) ? manifest.routes.length : 0,
+        views: Array.isArray(manifest.views) ? manifest.views.length : 0,
+        capabilities: manifest.capabilities && manifest.capabilities.length > 0 ? manifest.capabilities : undefined,
+    };
+}
+export function logManifestSummary(logger, manifest, routeCount, viewCount) {
+    if (!manifest) {
+        logger.info(`[webstir-backend] manifest routes=${routeCount} views=${viewCount} (no manifest metadata found)`);
+        return;
+    }
+    const caps = manifest.capabilities?.length ? ` [${manifest.capabilities.join(', ')}]` : '';
+    const routes = Array.isArray(manifest.routes) ? manifest.routes.length : routeCount;
+    const views = Array.isArray(manifest.views) ? manifest.views.length : viewCount;
+    logger.info(`[webstir-backend] manifest name=${manifest.name ?? 'unknown'} routes=${routes} views=${views}${caps}`);
+}
+export function normalizeRouteHandlerResult(result) {
+    const validatedFragment = validateFragmentResult(result.fragment);
+    if (!validatedFragment.valid) {
+        return {
+            status: result.status && result.status >= 400 ? result.status : 500,
+            headers: result.headers,
+            errors: [
+                {
+                    code: 'invalid_fragment_response',
+                    message: 'Fragment responses require a non-empty target, supported mode, and body.',
+                    details: validatedFragment.issues,
+                },
+            ],
+        };
+    }
+    if (!validatedFragment.fragment) {
+        return result;
+    }
+    return {
+        ...result,
+        fragment: validatedFragment.fragment,
+    };
+}
+export function resolveResponseHeaders(result) {
+    const headers = { ...(result.headers ?? {}) };
+    const lowerCaseHeaders = lowerCaseHeaderMap(headers);
+    if (result.redirect) {
+        headers.location = result.redirect.location;
+    }
+    if (result.fragment) {
+        headers['x-webstir-fragment-cache'] = 'bypass';
+        headers['x-webstir-fragment-target'] = result.fragment.target;
+        if (result.fragment.selector) {
+            headers['x-webstir-fragment-selector'] = result.fragment.selector;
+        }
+        if (result.fragment.mode) {
+            headers['x-webstir-fragment-mode'] = result.fragment.mode;
+        }
+        if (!('cache-control' in lowerCaseHeaders)) {
+            headers['cache-control'] = 'no-store';
+        }
+    }
+    if (!('content-type' in lowerCaseHeaders)) {
+        const payload = result.fragment ? result.fragment.body : result.body;
+        if (payload !== undefined && payload !== null) {
+            headers['content-type'] = resolveContentType(payload);
+        }
+    }
+    return headers;
+}
+function lowerCaseHeaderMap(headers) {
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+}
+function resolveContentType(payload) {
+    if (typeof payload === 'string') {
+        return 'text/html; charset=utf-8';
+    }
+    if (Buffer.isBuffer(payload)) {
+        return 'application/octet-stream';
+    }
+    return 'application/json';
+}
+function validateFragmentResult(fragment) {
+    if (!fragment) {
+        return { valid: true };
+    }
+    const issues = [];
+    const target = typeof fragment.target === 'string' ? fragment.target.trim() : '';
+    if (!target) {
+        issues.push('target');
+    }
+    let selector;
+    if (fragment.selector !== undefined) {
+        if (typeof fragment.selector !== 'string' || !fragment.selector.trim()) {
+            issues.push('selector');
+        }
+        else {
+            selector = fragment.selector.trim();
+        }
+    }
+    let mode;
+    if (fragment.mode !== undefined) {
+        if (fragment.mode === 'replace' || fragment.mode === 'append' || fragment.mode === 'prepend') {
+            mode = fragment.mode;
+        }
+        else {
+            issues.push('mode');
+        }
+    }
+    if (fragment.body === undefined || fragment.body === null) {
+        issues.push('body');
+    }
+    if (issues.length > 0) {
+        return { valid: false, issues };
+    }
+    return {
+        valid: true,
+        fragment: {
+            target,
+            selector,
+            mode,
+            body: fragment.body,
+        },
+    };
+}
+function sanitizeManifest(manifest) {
+    if (!manifest || typeof manifest !== 'object') {
+        return undefined;
+    }
+    return {
+        ...manifest,
+        routes: Array.isArray(manifest.routes) ? manifest.routes : [],
+        views: Array.isArray(manifest.views) ? manifest.views : [],
+        requestHooks: Array.isArray(manifest.requestHooks) ? manifest.requestHooks : [],
+        capabilities: Array.isArray(manifest.capabilities) ? manifest.capabilities : undefined,
+    };
+}
+function compileRoutes(routes, options) {
+    const compiled = [];
+    const warnings = [];
+    for (const route of routes) {
+        if (typeof route.handler !== 'function') {
+            continue;
+        }
+        const method = (route.definition?.method ?? 'GET').toUpperCase();
+        const pathPattern = normalizePath(route.definition?.path ?? '/');
+        const routeName = route.definition?.name ?? pathPattern;
+        const resolvedHooks = resolveRequestHooks({
+            routeName,
+            routeReferences: route.definition?.requestHooks,
+            manifestDefinitions: options.manifestRequestHooks,
+            registrations: options.requestHookImplementations,
+        });
+        compiled.push({
+            method,
+            name: routeName,
+            match: createPathMatcher(pathPattern),
+            handler: route.handler,
+            requestHooks: resolvedHooks.hooks,
+            definition: route.definition,
+        });
+        warnings.push(...resolvedHooks.warnings);
+    }
+    return { routes: compiled, warnings };
+}
+function resolveModuleViews(definition, manifest) {
+    if (Array.isArray(definition.views) && definition.views.length > 0) {
+        return definition.views;
+    }
+    if (Array.isArray(manifest?.views) && manifest.views.length > 0) {
+        return manifest.views.map((view) => ({ definition: view }));
+    }
+    return [];
+}
+function createPathMatcher(pattern) {
+    const normalized = normalizePath(pattern);
+    const paramRegex = /:([A-Za-z0-9_]+)/g;
+    const regex = new RegExp('^' +
+        normalized
+            .replace(/\//g, '\\/')
+            .replace(paramRegex, (_segment, name) => `(?<${name}>[^/]+)`) +
+        '$');
+    return (pathname) => {
+        const pathToTest = normalizePath(pathname);
+        const match = regex.exec(pathToTest);
+        if (!match) {
+            return { matched: false, params: {} };
+        }
+        return {
+            matched: true,
+            params: (match.groups ?? {}),
+        };
+    };
+}
+async function tryLoadModuleDefinition(options) {
+    const here = path.dirname(fileURLToPath(options.importMetaUrl));
+    const candidates = options.candidates ?? [
+        'module.js',
+        'module.mjs',
+        'module/index.js',
+        'module/index.mjs',
+    ];
+    for (const rel of candidates) {
+        const full = path.join(here, rel);
+        try {
+            const imported = await import(`${pathToFileURL(full).href}?t=${Date.now()}`);
+            const definition = extractModuleDefinition(imported);
+            if (definition) {
+                return { definition, source: rel };
+            }
+        }
+        catch {
+            // ignore and continue
+        }
+    }
+    return undefined;
+}
+function extractModuleDefinition(exports) {
+    const keys = ['module', 'moduleDefinition', 'default', 'backendModule'];
+    for (const key of keys) {
+        if (key in exports) {
+            const value = exports[key];
+            if (value && typeof value === 'object') {
+                return value;
+            }
+        }
+    }
+    return undefined;
+}

package/dist/runtime/deploy-backend.d.ts

@@ -0,0 +1,20 @@
+import { type ChildProcessByStdio } from 'node:child_process';
+import type { Readable } from 'node:stream';
+import type { DeploymentIo, PublishedWorkspaceMode } from './deploy-shared.js';
+interface RuntimeProcessRecord {
+    readonly child: ChildProcessByStdio<null, Readable, Readable>;
+    readonly exitPromise: Promise<number | null>;
+    expectedExit: boolean;
+}
+export declare function startBackendProcess(options: {
+    readonly workspaceRoot: string;
+    readonly backendEntry: string;
+    readonly port: number;
+    readonly env?: Record<string, string | undefined>;
+    readonly io: DeploymentIo;
+}): RuntimeProcessRecord;
+export declare function waitForRuntimeReady(port: number, exitPromise: Promise<number | null>): Promise<void>;
+export declare function proxyRequest(request: Request, requestUrl: URL, proxyPath: string, backendOrigin: string, mode: PublishedWorkspaceMode): Promise<Response>;
+export declare function shouldProxyToBackend(request: Request, pathname: string): boolean;
+export declare function getFullWorkspaceProxyPath(pathname: string): string;
+export {};

package/dist/runtime/deploy-backend.js

@@ -0,0 +1,175 @@
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { resolveRuntimeCommand, textResponse } from './deploy-shared.js';
+const READY_TIMEOUT_MS = 15_000;
+const READY_POLL_MS = 100;
+const SOCKET_TIMEOUT_MS = 200;
+export function startBackendProcess(options) {
+    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) => {
+        options.io.stdout.write(`[backend] ${chunk}`);
+    });
+    child.stderr.on('data', (chunk) => {
+        options.io.stderr.write(`[backend] ${chunk}`);
+    });
+    const exitPromise = new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code) => resolve(code));
+    });
+    return {
+        child,
+        exitPromise,
+        expectedExit: false,
+    };
+}
+export async function waitForRuntimeReady(port, exitPromise) {
+    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, requestUrl, proxyPath, backendOrigin, mode) {
+    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, pathname) {
+    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) {
+    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, signal) {
+    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) {
+    return await new Promise((resolve) => {
+        const socket = net.createConnection({ host: '127.0.0.1', port });
+        let settled = false;
+        const finish = (value) => {
+            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, targetUrl, mode) {
+    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, targetUrl, mode) {
+    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) {
+    if (pathname === '/api' || pathname.startsWith('/api/')) {
+        return pathname;
+    }
+    return pathname === '/' ? '/api' : `/api${pathname}`;
+}
+function createProxyRequestInit(request, targetUrl) {
+    const headers = new Headers(request.headers);
+    headers.set('host', targetUrl.host);
+    headers.set('connection', 'close');
+    const requestInit = {
+        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/dist/runtime/deploy-shared.d.ts

@@ -0,0 +1,43 @@
+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 declare const DEFAULT_PUBLIC_PORT = 8080;
+export declare function readPublishedWorkspaceMode(workspaceRoot: string): Promise<PublishedWorkspaceMode>;
+export declare function assertExists(targetPath: string, label: string): Promise<void>;
+export declare function getOpenPort(): Promise<number>;
+export declare function textResponse(statusCode: number, body: string): Response;
+export declare function resolveRuntimeCommand(): string;
+export declare function requireBunRuntime(): BunLike;
+export declare const defaultIo: DeploymentIo;

package/dist/runtime/deploy-shared.js

@@ -0,0 +1,75 @@
+import net from 'node:net';
+import path from 'node:path';
+import { access, readFile } from 'node:fs/promises';
+export const DEFAULT_PUBLIC_PORT = 8080;
+export async function readPublishedWorkspaceMode(workspaceRoot) {
+    const packageJsonPath = path.join(workspaceRoot, 'package.json');
+    const source = await readFile(packageJsonPath, 'utf8');
+    const packageJson = JSON.parse(source);
+    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, label) {
+    try {
+        await access(targetPath);
+    }
+    catch {
+        throw new Error(`Expected ${label} at ${targetPath}.`);
+    }
+}
+export async function getOpenPort() {
+    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, body) {
+    return new Response(body, {
+        status: statusCode,
+        headers: {
+            'Content-Type': 'text/plain; charset=utf-8',
+        },
+    });
+}
+export function resolveRuntimeCommand() {
+    if (typeof process.versions.bun === 'string') {
+        return process.execPath;
+    }
+    return 'bun';
+}
+export function requireBunRuntime() {
+    const bun = globalThis.Bun;
+    if (!bun?.serve || !bun.file) {
+        throw new Error('Published Webstir deploy requires Bun at runtime.');
+    }
+    return bun;
+}
+export const defaultIo = {
+    stdout: {
+        write(message) {
+            process.stdout.write(message);
+        },
+    },
+    stderr: {
+        write(message) {
+            process.stderr.write(message);
+        },
+    },
+};

package/dist/runtime/deploy-static.d.ts

@@ -0,0 +1,2 @@
+export declare function servePublishedStaticFile(request: Request, frontendRoot: string): Promise<Response>;
+export declare function getStaticCandidatePaths(pathname: string): readonly string[];