@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/dist/runtime/deploy-static.js

@@ -0,0 +1,161 @@
+import path from 'node:path';
+import { access } from 'node:fs/promises';
+import { requireBunRuntime, textResponse } from './deploy-shared.js';
+const MIME_TYPES = {
+    '.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, frontendRoot) {
+    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) {
+    const relativePath = normalizeRequestPath(pathname);
+    const candidates = [];
+    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, relativePaths) {
+    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) {
+    if (!error || typeof error !== 'object' || !('code' in error)) {
+        return false;
+    }
+    return error.code === 'ENOENT' || error.code === 'ENOTDIR';
+}
+function normalizeRequestPath(pathname) {
+    const decoded = decodeURIComponent(pathname);
+    const normalized = path.posix.normalize(decoded);
+    const stripped = normalized.replace(/^(\.\.(\/|\\|$))+/, '').replace(/^\/+/, '');
+    return stripped.replace(/\/+$/, '');
+}
+function getGenericFileCandidates(relativePath) {
+    const hasExtension = path.posix.extname(relativePath) !== '';
+    const candidates = hasExtension
+        ? [relativePath]
+        : [relativePath, `${relativePath}.html`, path.posix.join(relativePath, 'index.html')];
+    return candidates;
+}
+function hasReservedPrefix(relativePath) {
+    return RESERVED_PREFIXES.some((prefix) => relativePath === prefix || relativePath.startsWith(`${prefix}/`));
+}
+function setCacheHeaders(headers, relativePath) {
+    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.set('Cache-Control', 'no-cache, no-store, must-revalidate');
+    headers.set('Pragma', 'no-cache');
+    headers.set('Expires', '0');
+}

package/dist/runtime/deploy.d.ts

@@ -0,0 +1,3 @@
+import { type DeploymentIo, type PublishedWorkspaceServer, type PublishedWorkspaceServerOptions } from './deploy-shared.js';
+export type { DeploymentIo, PublishedWorkspaceServer, PublishedWorkspaceServerOptions };
+export declare function startPublishedWorkspaceServer(options: PublishedWorkspaceServerOptions): Promise<PublishedWorkspaceServer>;

package/dist/runtime/deploy.js

@@ -0,0 +1,91 @@
+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, } from './deploy-shared.js';
+import { servePublishedStaticFile } from './deploy-static.js';
+export async function startPublishedWorkspaceServer(options) {
+    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) {
+    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);
+}

package/dist/runtime/forms.d.ts

@@ -0,0 +1,73 @@
+export type FormIssueCode = 'validation' | 'auth' | 'csrf';
+export type FormValue = string | string[];
+export type FormValues = Record<string, FormValue>;
+export interface FormIssue {
+    code?: FormIssueCode;
+    field?: string;
+    message: string;
+}
+export interface FormRouteDefinitionLike {
+    path?: string;
+    form?: {
+        csrf?: boolean;
+    };
+}
+export interface PreparedFormState<TSession extends Record<string, unknown>> {
+    session: TSession;
+    csrfToken?: string;
+    values: FormValues;
+    issues: FormIssue[];
+}
+interface RouteHandlerResultLike {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+    redirect?: {
+        location: string;
+    };
+    errors?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    }[];
+}
+export type FormSubmissionResult<TSession extends Record<string, unknown>, TAuth> = {
+    ok: true;
+    session: TSession;
+    values: FormValues;
+    auth: TAuth | undefined;
+} | {
+    ok: false;
+    session: TSession;
+    values: FormValues;
+    issues: FormIssue[];
+    result: RouteHandlerResultLike;
+};
+export declare function prepareFormState<TSession extends Record<string, unknown>>(options: {
+    session: TSession | null;
+    formId: string;
+    route?: FormRouteDefinitionLike;
+    csrf?: boolean;
+    now?: () => Date;
+}): PreparedFormState<TSession>;
+export declare function processFormSubmission<TSession extends Record<string, unknown>, TAuth>(options: {
+    session: TSession | null;
+    body: unknown;
+    auth?: TAuth;
+    formId: string;
+    route?: FormRouteDefinitionLike;
+    csrf?: boolean;
+    csrfFieldName?: string;
+    redirectTo?: string;
+    requireAuth?: boolean | {
+        redirectTo?: string;
+        message?: string;
+    };
+    validate?: (values: FormValues) => readonly FormIssue[] | FormIssue[] | undefined;
+    now?: () => Date;
+}): FormSubmissionResult<TSession, TAuth>;
+export declare function groupFormIssuesByField(issues: readonly FormIssue[] | undefined): {
+    form: string[];
+    fields: Record<string, string[]>;
+};
+export {};

package/dist/runtime/forms.js

@@ -0,0 +1,236 @@
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { getFormSessionRuntimeState, pruneSessionRuntimeState, } from './session-runtime.js';
+const DEFAULT_CSRF_FIELD_NAME = '_csrf';
+export function prepareFormState(options) {
+    const session = ensureSession(options.session);
+    const store = getFormRuntimeStore(session);
+    const stored = store.states[options.formId];
+    if (stored) {
+        delete store.states[options.formId];
+    }
+    let csrfToken;
+    if (isCsrfEnabled(options)) {
+        csrfToken = ensureCsrfToken(store, options.formId);
+    }
+    cleanupFormRuntimeStore(session);
+    return {
+        session,
+        csrfToken,
+        values: cloneFormValues(stored?.values),
+        issues: cloneIssues(stored?.issues),
+    };
+}
+export function processFormSubmission(options) {
+    const now = options.now ?? (() => new Date());
+    const session = ensureSession(options.session);
+    const store = getFormRuntimeStore(session);
+    const csrfFieldName = options.csrfFieldName ?? DEFAULT_CSRF_FIELD_NAME;
+    const values = normalizeFormValues(options.body, csrfFieldName);
+    const redirectTo = options.redirectTo;
+    if (isCsrfEnabled(options)) {
+        const expectedToken = ensureCsrfToken(store, options.formId);
+        const providedToken = readCsrfToken(options.body, csrfFieldName);
+        if (!providedToken || !tokensMatch(providedToken, expectedToken)) {
+            return failSubmission({
+                session,
+                store,
+                formId: options.formId,
+                values,
+                redirectTo,
+                now,
+                issues: [
+                    {
+                        code: 'csrf',
+                        message: 'Form session expired. Reload the page and try again.',
+                    },
+                ],
+            });
+        }
+        delete store.csrf[options.formId];
+    }
+    if (requiresAuth(options.requireAuth) && options.auth === undefined) {
+        return failSubmission({
+            session,
+            store,
+            formId: options.formId,
+            values,
+            redirectTo: resolveAuthRedirect(options.requireAuth, redirectTo),
+            now,
+            issues: [
+                {
+                    code: 'auth',
+                    message: typeof options.requireAuth === 'object' && options.requireAuth.message
+                        ? options.requireAuth.message
+                        : 'Sign-in required to submit this form.',
+                },
+            ],
+        });
+    }
+    const validationResult = options.validate?.(values);
+    const validationIssues = cloneIssues(Array.isArray(validationResult) ? validationResult : undefined);
+    if (validationIssues.length > 0) {
+        return failSubmission({
+            session,
+            store,
+            formId: options.formId,
+            values,
+            redirectTo,
+            now,
+            issues: validationIssues.map((issue) => ({
+                ...issue,
+                code: issue.code ?? 'validation',
+            })),
+        });
+    }
+    delete store.states[options.formId];
+    cleanupFormRuntimeStore(session);
+    return {
+        ok: true,
+        session,
+        values,
+        auth: options.auth,
+    };
+}
+export function groupFormIssuesByField(issues) {
+    const grouped = {
+        form: [],
+        fields: {},
+    };
+    for (const issue of issues ?? []) {
+        if (!issue?.message) {
+            continue;
+        }
+        if (!issue.field) {
+            grouped.form.push(issue.message);
+            continue;
+        }
+        grouped.fields[issue.field] ??= [];
+        grouped.fields[issue.field].push(issue.message);
+    }
+    return grouped;
+}
+function failSubmission(options) {
+    options.store.states[options.formId] = {
+        values: cloneFormValues(options.values),
+        issues: cloneIssues(options.issues),
+        createdAt: options.now().toISOString(),
+    };
+    cleanupFormRuntimeStore(options.session);
+    if (options.redirectTo) {
+        return {
+            ok: false,
+            session: options.session,
+            values: options.values,
+            issues: options.issues,
+            result: {
+                status: 303,
+                redirect: {
+                    location: options.redirectTo,
+                },
+            },
+        };
+    }
+    const status = options.issues.some((issue) => issue.code === 'auth')
+        ? 401
+        : options.issues.some((issue) => issue.code === 'csrf')
+            ? 403
+            : 422;
+    return {
+        ok: false,
+        session: options.session,
+        values: options.values,
+        issues: options.issues,
+        result: {
+            status,
+            errors: options.issues.map((issue) => ({
+                code: issue.code === 'auth' ? 'auth' : 'validation',
+                message: issue.message,
+                details: issue.field
+                    ? { field: issue.field, reason: issue.code ?? 'validation' }
+                    : { reason: issue.code ?? 'validation' },
+            })),
+        },
+    };
+}
+function ensureSession(session) {
+    if (session && typeof session === 'object' && !Array.isArray(session)) {
+        return session;
+    }
+    return {};
+}
+function getFormRuntimeStore(session) {
+    return getFormSessionRuntimeState(session);
+}
+function cleanupFormRuntimeStore(session) {
+    pruneSessionRuntimeState(session);
+}
+function ensureCsrfToken(store, formId) {
+    const existing = store.csrf[formId];
+    if (existing) {
+        return existing;
+    }
+    const generated = randomUUID();
+    store.csrf[formId] = generated;
+    return generated;
+}
+function readCsrfToken(body, fieldName) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return undefined;
+    }
+    const value = body[fieldName];
+    if (typeof value === 'string' && value.length > 0) {
+        return value;
+    }
+    if (Array.isArray(value) && typeof value[0] === 'string' && value[0].length > 0) {
+        return value[0];
+    }
+    return undefined;
+}
+function normalizeFormValues(body, csrfFieldName) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return {};
+    }
+    const values = {};
+    for (const [key, raw] of Object.entries(body)) {
+        if (key === csrfFieldName) {
+            continue;
+        }
+        if (typeof raw === 'string') {
+            values[key] = raw;
+            continue;
+        }
+        if (Array.isArray(raw) && raw.every((value) => typeof value === 'string')) {
+            values[key] = [...raw];
+        }
+    }
+    return values;
+}
+function cloneFormValues(values) {
+    if (!values) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, Array.isArray(value) ? [...value] : value]));
+}
+function cloneIssues(issues) {
+    return (issues ?? []).map((issue) => ({ ...issue }));
+}
+function tokensMatch(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    if (leftBuffer.length !== rightBuffer.length) {
+        return false;
+    }
+    return timingSafeEqual(leftBuffer, rightBuffer);
+}
+function isCsrfEnabled(options) {
+    return options.csrf ?? options.route?.form?.csrf ?? false;
+}
+function requiresAuth(option) {
+    return option === true || typeof option === 'object';
+}
+function resolveAuthRedirect(option, fallback) {
+    if (typeof option === 'object' && option.redirectTo) {
+        return option.redirectTo;
+    }
+    return fallback;
+}

package/dist/runtime/request-hooks.d.ts

@@ -0,0 +1,47 @@
+export type RequestHookPhase = 'beforeAuth' | 'beforeHandler' | 'afterHandler';
+export interface RequestHookDefinitionLike {
+    id?: string;
+    phase?: RequestHookPhase;
+    order?: number;
+}
+export interface RequestHookReferenceLike {
+    id?: string;
+}
+export type RequestHookHandler<TContext, TResult, TRoute> = (context: TContext, input: {
+    phase: RequestHookPhase;
+    route: TRoute;
+    result?: TResult;
+}) => Promise<TResult | undefined> | TResult | undefined;
+export interface RegisteredRequestHook<TContext, TResult, TRoute> {
+    id?: string;
+    handler?: RequestHookHandler<TContext, TResult, TRoute>;
+}
+export interface CompiledRequestHook<TContext, TResult, TRoute> {
+    id: string;
+    phase: RequestHookPhase;
+    order: number;
+    handler: RequestHookHandler<TContext, TResult, TRoute>;
+}
+export declare function resolveRequestHooks<TContext, TResult, TRoute>(options: {
+    routeName: string;
+    routeReferences?: readonly RequestHookReferenceLike[];
+    manifestDefinitions?: readonly RequestHookDefinitionLike[];
+    registrations?: readonly RegisteredRequestHook<TContext, TResult, TRoute>[];
+}): {
+    hooks: CompiledRequestHook<TContext, TResult, TRoute>[];
+    warnings: string[];
+};
+export declare function executeRequestHookPhase<TContext, TResult, TRoute>(options: {
+    hooks: readonly CompiledRequestHook<TContext, TResult, TRoute>[];
+    phase: RequestHookPhase;
+    context: TContext;
+    route: TRoute;
+    logger?: {
+        info?(message: string, metadata?: Record<string, unknown>): void;
+        error?(message: string, metadata?: Record<string, unknown>): void;
+    };
+    result?: TResult;
+}): Promise<{
+    result?: TResult;
+    shortCircuited: boolean;
+}>;