@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/dist/runtime/bun.js

@@ -0,0 +1,499 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { executeRequestHookPhase } from './request-hooks.js';
+import { createProcessEnvAccessor, createReadinessTracker, loadModuleRuntime, logManifestSummary, matchRoute, normalizePath, normalizeRouteHandlerResult, RequestBodyTooLargeError, resolveResponseHeaders, summarizeManifest, } from './core.js';
+import { parseCookieHeader, prepareSessionState, createInMemorySessionStore, } from './session.js';
+import { matchView, renderRequestTimeView } from './views.js';
+export async function startBunBackend(options) {
+    const bun = requireBunRuntime();
+    const env = options.loadEnv();
+    const logger = options.createBaseLogger(env);
+    const metrics = options.createMetricsTracker(env.metrics);
+    const readiness = createReadinessTracker();
+    readiness.booting();
+    let runtime;
+    let loadError;
+    try {
+        runtime = await loadModuleRuntime({
+            importMetaUrl: options.importMetaUrl,
+            candidates: options.moduleCandidates,
+        });
+    }
+    catch (error) {
+        loadError = error.message ?? 'Failed to load module definition';
+        logger.error({ err: error }, '[webstir-backend] module load failed');
+        readiness.error(loadError);
+        runtime = { routes: [], views: [] };
+    }
+    if (runtime.source) {
+        logger.info(`[webstir-backend] loaded module definition from ${runtime.source}`);
+    }
+    else {
+        logger.warn('[webstir-backend] no module definition found. Add src/backend/module.ts to describe routes.');
+    }
+    logManifestSummary(logger, runtime.manifest, runtime.routes.length, runtime.views.length);
+    for (const warning of runtime.warnings ?? []) {
+        logger.warn({ warning }, '[webstir-backend] request hook configuration warning');
+    }
+    const manifestSummary = summarizeManifest(runtime.manifest);
+    bun.serve({
+        port: env.PORT,
+        hostname: '0.0.0.0',
+        fetch: async (request) => {
+            return await handleRequest({
+                request,
+                runtime,
+                readiness,
+                manifestSummary,
+                env,
+                logger,
+                metrics,
+                options,
+            });
+        },
+        error: (error) => {
+            logger.error({ err: error }, '[webstir-backend] Bun server request failed');
+            return jsonResponse(500, { error: 'internal_error', message: error.message });
+        },
+    });
+    if (!loadError) {
+        readiness.ready();
+    }
+    logger.info({ port: env.PORT, mode: env.NODE_ENV, runtime: 'bun' }, 'API server running');
+}
+export function createDefaultBunBackendBootstrap(options) {
+    return {
+        importMetaUrl: options.importMetaUrl,
+        moduleCandidates: options.moduleCandidates,
+        loadEnv: options.loadEnv,
+        resolveWorkspaceRoot: options.resolveWorkspaceRoot ??
+            (() => resolveWorkspaceRootFromImportMetaUrl(options.importMetaUrl)),
+        resolveRequestAuth: options.resolveRequestAuth ?? (async () => undefined),
+        createBaseLogger: options.createBaseLogger ?? (() => createDefaultBaseLogger()),
+        createMetricsTracker: options.createMetricsTracker ?? (() => createDefaultMetricsTracker()),
+        sessionStore: options.sessionStore ?? createInMemorySessionStore(),
+    };
+}
+function createDefaultBaseLogger() {
+    return {
+        child() {
+            return this;
+        },
+        info(value, message) {
+            writeDefaultLog('info', value, message);
+        },
+        warn(value, message) {
+            writeDefaultLog('warn', value, message);
+        },
+        error(value, message) {
+            writeDefaultLog('error', value, message);
+        },
+    };
+}
+function createDefaultMetricsTracker() {
+    return {
+        record() { },
+        snapshot() {
+            return { enabled: false };
+        },
+    };
+}
+function writeDefaultLog(level, value, message) {
+    const line = typeof value === 'string' && !message ? value : message;
+    const detail = typeof value === 'string' && !message ? undefined : value;
+    const output = [line, detail ? JSON.stringify(detail) : undefined].filter(Boolean).join(' ');
+    if (level === 'error') {
+        console.error(output);
+        return;
+    }
+    if (level === 'warn') {
+        console.warn(output);
+        return;
+    }
+    console.log(output);
+}
+function resolveWorkspaceRootFromImportMetaUrl(importMetaUrl) {
+    return path.resolve(path.dirname(fileURLToPath(importMetaUrl)), '..', '..');
+}
+async function handleRequest(args) {
+    const { request, runtime, readiness, manifestSummary, env, logger, metrics, options } = args;
+    try {
+        const url = new URL(request.url);
+        const pathname = normalizePath(url.pathname);
+        const method = (request.method ?? 'GET').toUpperCase();
+        if (isHealthPath(pathname)) {
+            return jsonResponse(200, { ok: true, uptime: process.uptime() });
+        }
+        if (isReadyPath(pathname)) {
+            const snapshot = readiness.snapshot();
+            const statusCode = snapshot.status === 'ready' ? 200 : 503;
+            return jsonResponse(statusCode, {
+                status: snapshot.status,
+                message: snapshot.message,
+                manifest: manifestSummary,
+                metrics: metrics.snapshot(),
+            });
+        }
+        if (isMetricsPath(pathname)) {
+            const snapshot = metrics.snapshot();
+            return jsonResponse(200, snapshot ?? { enabled: false });
+        }
+        if (method === 'OPTIONS') {
+            const requestOrigin = request.headers.get('origin');
+            const allowOrigin = env.NODE_ENV === 'development' ? requestOrigin : undefined;
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    ...(allowOrigin ? { 'Access-Control-Allow-Origin': allowOrigin } : {}),
+                    'Access-Control-Allow-Methods': 'GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS',
+                    'Access-Control-Allow-Headers': request.headers.get('access-control-request-headers') ?? 'content-type',
+                },
+            });
+        }
+        const matchedRoute = matchRoute(runtime.routes, method, pathname);
+        const matchedView = !matchedRoute && (method === 'GET' || method === 'HEAD')
+            ? matchView(runtime.views, pathname)
+            : undefined;
+        if (!matchedRoute && !matchedView) {
+            metrics.record({ method, route: pathname, status: 404, durationMs: 0 });
+            return jsonResponse(404, { error: 'not_found', path: pathname });
+        }
+        const routeName = matchedRoute
+            ? (matchedRoute.route.name ?? matchedRoute.route.definition?.path ?? pathname)
+            : (matchedView?.view.name ?? pathname);
+        const startTime = performance.now();
+        const requestId = extractRequestId(request);
+        const requestLogger = createBunRequestLogger(logger, request, routeName, requestId);
+        const structuredLogger = createStructuredLogger(requestLogger);
+        const envAccessor = createProcessEnvAccessor();
+        const now = () => new Date();
+        let responseStatus = 200;
+        try {
+            if (matchedView) {
+                const response = await handleViewRequest({
+                    request,
+                    method,
+                    url,
+                    matchedView,
+                    env,
+                    envAccessor,
+                    requestLogger,
+                    structuredLogger,
+                    requestId,
+                    now,
+                    options,
+                });
+                responseStatus = response.status;
+                return response;
+            }
+            const routeMatch = matchedRoute;
+            if (!routeMatch) {
+                throw new Error('Expected a matched backend route.');
+            }
+            const body = await readRequestBody(request, env.http.bodyLimitBytes);
+            const sessionState = prepareSessionState({
+                cookies: parseCookieHeader(request.headers.get('cookie') ?? undefined),
+                route: routeMatch.route.definition,
+                config: env.sessions,
+                store: options.sessionStore,
+                now,
+            });
+            const ctx = {
+                request,
+                reply: new Response(null),
+                params: routeMatch.params,
+                query: Object.fromEntries(url.searchParams.entries()),
+                body,
+                auth: undefined,
+                session: sessionState.session,
+                flash: sessionState.flash,
+                db: Object.create(null),
+                env: envAccessor,
+                logger: requestLogger,
+                requestId,
+                now,
+            };
+            const routeDefinition = routeMatch.route.definition ?? {
+                name: routeMatch.route.name,
+                path: pathname,
+                method,
+            };
+            const beforeAuth = await executeRequestHookPhase({
+                hooks: routeMatch.route.requestHooks,
+                phase: 'beforeAuth',
+                context: ctx,
+                route: routeDefinition,
+                logger: structuredLogger,
+            });
+            if (beforeAuth.shortCircuited && beforeAuth.result) {
+                const response = createCommittedResponse(beforeAuth.result, {
+                    method,
+                    sessionState,
+                    session: ctx.session,
+                    route: routeMatch.route.definition,
+                    requestId,
+                });
+                responseStatus = response.status;
+                return response;
+            }
+            if (ctx.auth === undefined) {
+                ctx.auth = await options.resolveRequestAuth(request, env.auth, structuredLogger);
+            }
+            const beforeHandler = await executeRequestHookPhase({
+                hooks: routeMatch.route.requestHooks,
+                phase: 'beforeHandler',
+                context: ctx,
+                route: routeDefinition,
+                logger: structuredLogger,
+            });
+            if (beforeHandler.shortCircuited && beforeHandler.result) {
+                const response = createCommittedResponse(beforeHandler.result, {
+                    method,
+                    sessionState,
+                    session: ctx.session,
+                    route: routeMatch.route.definition,
+                    requestId,
+                });
+                responseStatus = response.status;
+                return response;
+            }
+            const handlerResult = await routeMatch.route.handler(ctx);
+            const afterHandler = await executeRequestHookPhase({
+                hooks: routeMatch.route.requestHooks,
+                phase: 'afterHandler',
+                context: ctx,
+                route: routeDefinition,
+                logger: structuredLogger,
+                result: handlerResult,
+            });
+            const response = createCommittedResponse(afterHandler.result ?? handlerResult, {
+                method,
+                sessionState,
+                session: ctx.session,
+                route: routeMatch.route.definition,
+                requestId,
+            });
+            responseStatus = response.status;
+            return response;
+        }
+        catch (error) {
+            requestLogger.error({ err: error }, 'request handler failed');
+            if (error instanceof RequestBodyTooLargeError) {
+                responseStatus = error.statusCode;
+                return jsonResponse(error.statusCode, { error: error.code, message: error.message }, requestId);
+            }
+            responseStatus = 500;
+            return jsonResponse(500, {
+                error: 'internal_error',
+                message: error.message,
+            }, requestId);
+        }
+        finally {
+            const durationMs = performance.now() - startTime;
+            metrics.record({
+                method,
+                route: routeName,
+                status: responseStatus,
+                durationMs,
+            });
+            requestLogger.info({ status: responseStatus, durationMs }, 'request.completed');
+        }
+    }
+    catch (error) {
+        logger.error({ err: error }, '[webstir-backend] request failed');
+        if (error instanceof RequestBodyTooLargeError) {
+            return jsonResponse(error.statusCode, { error: error.code, message: error.message });
+        }
+        return jsonResponse(500, { error: 'internal_error', message: error.message });
+    }
+}
+async function handleViewRequest(args) {
+    const { request, method, url, matchedView, env, envAccessor, structuredLogger, requestId, now, options, } = args;
+    const sessionState = prepareSessionState({
+        cookies: parseCookieHeader(request.headers.get('cookie') ?? undefined),
+        config: env.sessions,
+        store: options.sessionStore,
+        now,
+    });
+    const rendered = await renderRequestTimeView({
+        workspaceRoot: options.resolveWorkspaceRoot(),
+        url,
+        view: matchedView.view,
+        params: matchedView.params,
+        cookies: parseCookieHeader(request.headers.get('cookie') ?? undefined),
+        headers: toRequestHeadersRecord(request.headers),
+        auth: await options.resolveRequestAuth(request, env.auth, structuredLogger),
+        session: sessionState.session,
+        env: envAccessor,
+        logger: structuredLogger,
+        requestId,
+        now,
+    });
+    const commit = sessionState.commit({
+        session: sessionState.session,
+        result: { status: 200 },
+    });
+    const headers = new Headers({
+        'cache-control': 'no-store',
+        'content-type': 'text/html; charset=utf-8',
+        'x-request-id': requestId,
+        'x-webstir-document-cache': rendered.documentCache.status,
+    });
+    if (commit.setCookie) {
+        headers.append('set-cookie', commit.setCookie);
+    }
+    return new Response(method === 'HEAD' ? null : rendered.html, {
+        status: 200,
+        headers,
+    });
+}
+function createCommittedResponse(result, options) {
+    const normalizedResult = normalizeRouteHandlerResult(result);
+    const commit = options.sessionState.commit({
+        session: options.session,
+        route: options.route,
+        result: normalizedResult,
+    });
+    const status = resolveResponseStatus(normalizedResult);
+    const headers = new Headers(resolveResponseHeaders(normalizedResult));
+    headers.set('x-request-id', options.requestId);
+    if (commit.setCookie) {
+        headers.append('set-cookie', commit.setCookie);
+    }
+    if (normalizedResult.errors) {
+        return jsonResponse(status, { errors: normalizedResult.errors }, options.requestId, headers);
+    }
+    if (normalizedResult.redirect) {
+        return new Response(null, { status, headers });
+    }
+    const payload = normalizedResult.fragment
+        ? normalizedResult.fragment.body
+        : normalizedResult.body;
+    if (payload === undefined || payload === null || options.method === 'HEAD') {
+        return new Response(null, { status, headers });
+    }
+    if (typeof payload === 'string' || payload instanceof ArrayBuffer) {
+        return new Response(payload, { status, headers });
+    }
+    if (payload instanceof Uint8Array) {
+        return new Response(Buffer.from(payload), { status, headers });
+    }
+    return jsonResponse(status, payload, options.requestId, headers);
+}
+async function readRequestBody(request, maxBodyBytes) {
+    const method = (request.method ?? 'GET').toUpperCase();
+    if (method === 'GET' || method === 'HEAD') {
+        return undefined;
+    }
+    const declaredContentLength = Number(request.headers.get('content-length') ?? '');
+    if (Number.isFinite(declaredContentLength) && declaredContentLength > maxBodyBytes) {
+        throw new RequestBodyTooLargeError(maxBodyBytes);
+    }
+    const bodyBuffer = await request.arrayBuffer();
+    if (bodyBuffer.byteLength === 0) {
+        return undefined;
+    }
+    if (bodyBuffer.byteLength > maxBodyBytes) {
+        throw new RequestBodyTooLargeError(maxBodyBytes);
+    }
+    const bodyText = Buffer.from(bodyBuffer).toString('utf8');
+    const contentType = request.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+        try {
+            return JSON.parse(bodyText);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (contentType.includes('application/x-www-form-urlencoded')) {
+        return Object.fromEntries(new URLSearchParams(bodyText).entries());
+    }
+    if (contentType.includes('text/plain')) {
+        return bodyText;
+    }
+    return bodyText;
+}
+function createBunRequestLogger(baseLogger, request, route, requestId) {
+    const url = new URL(request.url);
+    return baseLogger.child({
+        requestId,
+        method: request.method ?? 'GET',
+        path: url.pathname,
+        route,
+    });
+}
+function createStructuredLogger(logger) {
+    return {
+        info(message, metadata) {
+            logStructured(logger.info.bind(logger), message, metadata);
+        },
+        warn(message, metadata) {
+            logStructured(logger.warn.bind(logger), message, metadata);
+        },
+        error(message, metadata) {
+            logStructured(logger.error.bind(logger), message, metadata);
+        },
+        with(bindings) {
+            return createStructuredLogger(logger.child(bindings));
+        },
+    };
+}
+function logStructured(log, message, metadata) {
+    if (metadata && Object.keys(metadata).length > 0) {
+        log(metadata, message);
+        return;
+    }
+    log(message);
+}
+function extractRequestId(request) {
+    const header = request.headers.get('x-request-id');
+    if (header && header.length > 0) {
+        return header;
+    }
+    try {
+        return randomUUID();
+    }
+    catch {
+        return `${Date.now()}`;
+    }
+}
+function toRequestHeadersRecord(headers) {
+    return Object.fromEntries(headers.entries());
+}
+function resolveResponseStatus(result) {
+    if (result.redirect) {
+        return result.status ?? 303;
+    }
+    return result.status ?? (result.errors ? 400 : 200);
+}
+function jsonResponse(status, payload, requestId, headers) {
+    const responseHeaders = new Headers(headers);
+    if (!responseHeaders.has('content-type')) {
+        responseHeaders.set('content-type', 'application/json');
+    }
+    if (requestId && !responseHeaders.has('x-request-id')) {
+        responseHeaders.set('x-request-id', requestId);
+    }
+    return new Response(JSON.stringify(payload), {
+        status,
+        headers: responseHeaders,
+    });
+}
+function requireBunRuntime() {
+    const bun = globalThis.Bun;
+    if (!bun?.serve) {
+        throw new Error('The default Webstir backend runtime requires Bun at runtime.');
+    }
+    return bun;
+}
+function isHealthPath(pathname) {
+    return pathname === '/api/health' || pathname === '/healthz';
+}
+function isReadyPath(pathname) {
+    return pathname === '/readyz';
+}
+function isMetricsPath(pathname) {
+    return pathname === '/metrics';
+}

package/dist/runtime/core.d.ts

@@ -0,0 +1,141 @@
+import { type CompiledRequestHook, type RequestHookDefinitionLike, type RequestHookHandler, type RequestHookReferenceLike } from './request-hooks.js';
+import type { SessionAwareRouteDefinitionLike } from './session.js';
+import { type CompiledView, type ModuleViewLike, type ViewDefinitionLike } from './views.js';
+export interface EnvAccessor {
+    get(name: string): string | undefined;
+    require(name: string): string;
+    entries(): Record<string, string | undefined>;
+}
+export interface RouteHandlerResult {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+    redirect?: {
+        location: string;
+    };
+    fragment?: {
+        target: string;
+        selector?: string;
+        mode?: 'replace' | 'append' | 'prepend';
+        body: unknown;
+    };
+    errors?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    }[];
+}
+export type NormalizedRouteHandlerResult = RouteHandlerResult & {
+    fragment?: {
+        target: string;
+        selector?: string;
+        mode?: 'replace' | 'append' | 'prepend';
+        body: unknown;
+    };
+};
+export interface BackendRouteDefinitionLike extends SessionAwareRouteDefinitionLike {
+    name?: string;
+    method?: string;
+    path?: string;
+    requestHooks?: RequestHookReferenceLike[];
+    interaction?: 'navigation' | 'mutation';
+    form?: SessionAwareRouteDefinitionLike['form'] & {
+        contentType?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';
+        csrf?: boolean;
+    };
+    fragment?: {
+        target: string;
+        selector?: string;
+        mode?: 'replace' | 'append' | 'prepend';
+    };
+}
+export type RouteHandler<TContext, TResult extends RouteHandlerResult> = (ctx: TContext) => Promise<TResult> | TResult;
+export interface ModuleRouteLike<TContext, TResult extends RouteHandlerResult, TRouteDefinition extends BackendRouteDefinitionLike> {
+    definition?: TRouteDefinition;
+    handler?: RouteHandler<TContext, TResult>;
+}
+export interface ModuleManifestLike<TRouteDefinition extends BackendRouteDefinitionLike = BackendRouteDefinitionLike, TViewDefinition extends ViewDefinitionLike = ViewDefinitionLike> {
+    name?: string;
+    version?: string;
+    capabilities?: string[];
+    requestHooks?: RequestHookDefinitionLike[];
+    routes?: TRouteDefinition[];
+    views?: TViewDefinition[];
+}
+export type LifecycleHook = (context: {
+    env: EnvAccessor;
+    logger: {
+        info(message: string): void;
+    };
+}) => Promise<void> | void;
+export interface ModuleRequestHook<TContext, TResult extends RouteHandlerResult, TRouteDefinition extends BackendRouteDefinitionLike> {
+    id?: string;
+    handler?: RequestHookHandler<TContext, TResult, TRouteDefinition>;
+}
+export interface ModuleDefinitionLike<TContext, TResult extends RouteHandlerResult, TRouteDefinition extends BackendRouteDefinitionLike = BackendRouteDefinitionLike> {
+    manifest?: ModuleManifestLike<TRouteDefinition>;
+    routes?: ModuleRouteLike<TContext, TResult, TRouteDefinition>[];
+    views?: ModuleViewLike[];
+    requestHooks?: ModuleRequestHook<TContext, TResult, TRouteDefinition>[];
+    init?: LifecycleHook;
+    dispose?: LifecycleHook;
+}
+export interface CompiledRoute<TContext, TResult extends RouteHandlerResult, TRouteDefinition extends BackendRouteDefinitionLike> {
+    method: string;
+    name: string;
+    match: (pathname: string) => {
+        matched: boolean;
+        params: Record<string, string>;
+    };
+    handler: RouteHandler<TContext, TResult>;
+    requestHooks: CompiledRequestHook<TContext, TResult, TRouteDefinition>[];
+    definition?: TRouteDefinition;
+}
+export interface ModuleRuntime<TContext, TResult extends RouteHandlerResult, TRouteDefinition extends BackendRouteDefinitionLike = BackendRouteDefinitionLike> {
+    definition?: ModuleDefinitionLike<TContext, TResult, TRouteDefinition>;
+    manifest?: ModuleManifestLike<TRouteDefinition>;
+    routes: CompiledRoute<TContext, TResult, TRouteDefinition>[];
+    views: CompiledView[];
+    source?: string;
+    warnings?: string[];
+}
+export type ReadinessStatus = 'booting' | 'ready' | 'error';
+export interface ReadinessState {
+    status: ReadinessStatus;
+    message?: string;
+}
+export interface ReadinessTracker {
+    booting(): void;
+    ready(): void;
+    error(reason: string): void;
+    snapshot(): ReadinessState;
+}
+export interface ManifestSummary {
+    name?: string;
+    version?: string;
+    routes: number;
+    views: number;
+    capabilities?: string[];
+}
+export declare class RequestBodyTooLargeError extends Error {
+    readonly statusCode = 413;
+    readonly code = "payload_too_large";
+    constructor(maxBytes: number);
+}
+export declare function createProcessEnvAccessor(): EnvAccessor;
+export declare function createReadinessTracker(): ReadinessTracker;
+export declare function normalizePath(value: string | undefined): string;
+export declare function matchRoute<TContext, TResult extends RouteHandlerResult, TRouteDefinition extends BackendRouteDefinitionLike>(routes: readonly CompiledRoute<TContext, TResult, TRouteDefinition>[], method: string, pathname: string): {
+    route: CompiledRoute<TContext, TResult, TRouteDefinition>;
+    params: Record<string, string>;
+} | undefined;
+export declare function loadModuleRuntime<TContext, TResult extends RouteHandlerResult, TRouteDefinition extends BackendRouteDefinitionLike>(options: {
+    importMetaUrl: string;
+    candidates?: readonly string[];
+}): Promise<ModuleRuntime<TContext, TResult, TRouteDefinition>>;
+export declare function summarizeManifest<TRouteDefinition extends BackendRouteDefinitionLike>(manifest?: ModuleManifestLike<TRouteDefinition>): ManifestSummary | undefined;
+export declare function logManifestSummary(logger: {
+    info(message: string): void;
+}, manifest: ModuleManifestLike | undefined, routeCount: number, viewCount: number): void;
+export declare function normalizeRouteHandlerResult(result: RouteHandlerResult): NormalizedRouteHandlerResult;
+export declare function resolveResponseHeaders(result: NormalizedRouteHandlerResult): Record<string, string>;