@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/dist/runtime/session.js

@@ -0,0 +1,396 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { attachSessionRuntimeState, cloneSessionRuntimeState, coerceSessionRuntimeFormState, hasSessionRuntimeState, mergeSessionRuntimeState, readSessionRuntimeState, } from './session-runtime.js';
+import { attachSessionMetadata, readSessionMetadata, stripSessionMetadataFields, } from './session-metadata.js';
+const SESSION_STORE_KEY = Symbol.for('webstir.webstir-backend.session-store');
+const LEGACY_FORM_RUNTIME_KEY = '__webstir_form_runtime';
+export function prepareSessionState(options) {
+    const now = options.now ?? (() => new Date());
+    const cookies = normalizeCookies(options.cookies);
+    const store = options.store ?? getDefaultSessionStore();
+    const sessionCookie = cookies[options.config.cookieName];
+    const initialId = verifySignedSessionCookie(sessionCookie, options.config.secret);
+    const invalidCookie = Boolean(sessionCookie) && !initialId;
+    const initialRecord = initialId ? loadSessionRecord(store, initialId, now) : undefined;
+    const staleCookie = Boolean(initialId) && !initialRecord;
+    const delivered = resolveConsumedFlash(readStoredFlash(initialRecord), options.route);
+    const initialState = initialRecord ? restoreStoredSessionState(initialRecord) : undefined;
+    const initialSession = initialState?.session
+        ? attachSessionRuntimeState(attachSessionMetadata(initialState.session, initialState.metadata), initialState.runtime)
+        : null;
+    const hasPendingConsumption = delivered.flash.length > 0;
+    return {
+        session: initialSession,
+        flash: delivered.flash,
+        commit({ session, route, result }) {
+            const publishFlash = resolvePublishedFlash(route ?? options.route, result, now);
+            const normalized = normalizeSessionValue(session);
+            if (initialRecord) {
+                store.delete(initialRecord.id);
+            }
+            const shouldPersist = normalized.session !== null ||
+                publishFlash.length > 0 ||
+                (initialRecord !== undefined && delivered.remaining.length > 0) ||
+                hasPendingConsumption ||
+                hasSessionRuntimeState(normalized.runtime);
+            if (!shouldPersist) {
+                return {
+                    session: null,
+                    setCookie: initialRecord || invalidCookie || staleCookie
+                        ? serializeExpiredCookie(options.config)
+                        : undefined,
+                };
+            }
+            const record = createStoredSessionRecord({
+                session: normalized.session,
+                runtime: normalized.runtime,
+                metadata: normalized.metadata,
+                fallbackId: normalized.metadata?.id ?? (publishFlash.length > 0 ? undefined : initialRecord?.id),
+                initialRecord,
+                flash: [...delivered.remaining, ...publishFlash],
+                config: options.config,
+                now,
+            });
+            store.set(record);
+            return {
+                session: attachSessionRuntimeState(attachSessionMetadata(cloneValue(record.value), {
+                    id: record.id,
+                    createdAt: record.createdAt,
+                    expiresAt: record.expiresAt,
+                }), record.runtime),
+                setCookie: initialRecord?.id === record.id && !invalidCookie && !staleCookie
+                    ? undefined
+                    : serializeSessionCookie(record.id, options.config),
+            };
+        },
+    };
+}
+export function parseCookieHeader(header) {
+    return normalizeCookies(header);
+}
+export function createInMemorySessionStore() {
+    const records = new Map();
+    return {
+        get(sessionId) {
+            const record = records.get(sessionId);
+            return record ? cloneStoredSessionRecord(record) : undefined;
+        },
+        set(record) {
+            records.set(record.id, cloneStoredSessionRecord(record));
+        },
+        delete(sessionId) {
+            records.delete(sessionId);
+        },
+        clear() {
+            records.clear();
+        },
+    };
+}
+export function resetInMemorySessionStore(store = getDefaultInMemorySessionStore()) {
+    store.clear();
+}
+function getDefaultSessionStore() {
+    return getDefaultInMemorySessionStore();
+}
+function getDefaultInMemorySessionStore() {
+    const globalStore = globalThis;
+    const existing = globalStore[SESSION_STORE_KEY];
+    if (isInMemorySessionStore(existing)) {
+        return existing;
+    }
+    const store = createInMemorySessionStore();
+    globalStore[SESSION_STORE_KEY] = store;
+    return store;
+}
+function normalizeCookies(input) {
+    if (!input) {
+        return {};
+    }
+    if (typeof input === 'object' && !Array.isArray(input)) {
+        return { ...input };
+    }
+    const raw = Array.isArray(input) ? input.join('; ') : input;
+    const cookies = {};
+    for (const part of raw.split(';')) {
+        const trimmed = part.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const separatorIndex = trimmed.indexOf('=');
+        if (separatorIndex === -1) {
+            continue;
+        }
+        const name = trimmed.slice(0, separatorIndex).trim();
+        const value = trimmed.slice(separatorIndex + 1).trim();
+        if (!name) {
+            continue;
+        }
+        cookies[name] = decodeCookieValue(value);
+    }
+    return cookies;
+}
+function decodeCookieValue(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function verifySignedSessionCookie(cookieValue, secret) {
+    if (!cookieValue) {
+        return undefined;
+    }
+    const separatorIndex = cookieValue.indexOf('.');
+    if (separatorIndex <= 0) {
+        return undefined;
+    }
+    const sessionId = cookieValue.slice(0, separatorIndex);
+    const signature = cookieValue.slice(separatorIndex + 1);
+    const expected = signSessionId(sessionId, secret);
+    const signatureBuffer = Buffer.from(signature);
+    const expectedBuffer = Buffer.from(expected);
+    if (signatureBuffer.length !== expectedBuffer.length) {
+        return undefined;
+    }
+    return timingSafeEqual(signatureBuffer, expectedBuffer) ? sessionId : undefined;
+}
+function signSessionId(sessionId, secret) {
+    return createHmac('sha256', secret).update(sessionId).digest('base64url');
+}
+function loadSessionRecord(store, sessionId, now) {
+    const record = store.get(sessionId);
+    if (!record) {
+        return undefined;
+    }
+    const expiresAt = Date.parse(record.expiresAt);
+    if (Number.isFinite(expiresAt) && expiresAt <= now().getTime()) {
+        store.delete(sessionId);
+        return undefined;
+    }
+    return record;
+}
+function resolveConsumedFlash(flash, route) {
+    const consume = new Set([
+        ...(route?.flash?.consume ?? []),
+        ...(route?.form?.flash?.consume ?? []),
+    ]);
+    if (consume.size === 0) {
+        return {
+            flash: [],
+            remaining: flash.map((message) => ({ ...message })),
+        };
+    }
+    const delivered = [];
+    const remaining = [];
+    for (const message of flash) {
+        if (consume.has(message.key)) {
+            delivered.push({ ...message });
+            continue;
+        }
+        remaining.push({ ...message });
+    }
+    return { flash: delivered, remaining };
+}
+function resolvePublishedFlash(route, result, now) {
+    const definitions = [...(route?.flash?.publish ?? []), ...(route?.form?.flash?.publish ?? [])];
+    if (definitions.length === 0) {
+        return [];
+    }
+    const condition = resolveFlashCondition(result);
+    return definitions
+        .filter((definition) => shouldPublishFlash(definition.when, condition))
+        .filter((definition) => typeof definition.key === 'string' && definition.key.length > 0)
+        .map((definition) => ({
+        key: definition.key,
+        level: definition.level ?? (condition === 'error' ? 'error' : 'info'),
+        createdAt: now().toISOString(),
+    }));
+}
+function resolveFlashCondition(result) {
+    if (result?.errors) {
+        return 'error';
+    }
+    if ((result?.status ?? 200) >= 400) {
+        return 'error';
+    }
+    return 'success';
+}
+function shouldPublishFlash(when, condition) {
+    if (!when || when === 'always') {
+        return true;
+    }
+    return when === condition;
+}
+function normalizeSessionValue(session) {
+    if (session === null) {
+        return { session: null };
+    }
+    const metadata = readSessionMetadata(session);
+    const cloned = cloneValue(session);
+    stripSessionMetadataFields(cloned);
+    delete cloned[LEGACY_FORM_RUNTIME_KEY];
+    return {
+        session: cloned,
+        metadata,
+        runtime: readSessionRuntimeState(session),
+    };
+}
+function createStoredSessionRecord(options) {
+    const sessionValue = (options.session ?? {});
+    const sessionId = options.metadata?.id ?? options.fallbackId ?? randomUUID();
+    const createdAt = options.metadata?.createdAt ?? options.initialRecord?.createdAt ?? options.now().toISOString();
+    const expiresAt = options.metadata?.expiresAt ??
+        options.initialRecord?.expiresAt ??
+        new Date(options.now().getTime() + options.config.maxAgeSeconds * 1000).toISOString();
+    return {
+        id: sessionId,
+        value: { ...sessionValue },
+        runtime: createSessionStoreRuntime(options.runtime, options.flash),
+        createdAt,
+        expiresAt,
+    };
+}
+function serializeSessionCookie(sessionId, config) {
+    const value = `${encodeURIComponent(sessionId)}.${signSessionId(sessionId, config.secret)}`;
+    return serializeCookie(config, value, config.maxAgeSeconds);
+}
+function serializeExpiredCookie(config) {
+    return serializeCookie(config, '', 0);
+}
+function serializeCookie(config, value, maxAgeSeconds) {
+    const parts = [`${config.cookieName}=${value}`];
+    parts.push(`Path=${config.path ?? '/'}`);
+    parts.push(`Max-Age=${Math.max(0, Math.floor(maxAgeSeconds))}`);
+    parts.push(`SameSite=${config.sameSite ?? 'Lax'}`);
+    parts.push('HttpOnly');
+    if (config.secure) {
+        parts.push('Secure');
+    }
+    return parts.join('; ');
+}
+function normalizeText(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function normalizeDate(value) {
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString();
+    }
+    if (typeof value === 'string') {
+        const timestamp = Date.parse(value);
+        if (!Number.isNaN(timestamp)) {
+            return new Date(timestamp).toISOString();
+        }
+    }
+    return undefined;
+}
+function cloneValue(value) {
+    if (typeof structuredClone === 'function') {
+        return structuredClone(value);
+    }
+    return JSON.parse(JSON.stringify(value));
+}
+function cloneStoredSessionRecord(record) {
+    const flash = cloneFlashMessages(record.flash);
+    const runtime = cloneSessionStoreRuntime(record.runtime);
+    return {
+        id: record.id,
+        value: cloneValue(record.value),
+        ...(flash.length > 0 ? { flash } : {}),
+        ...(runtime ? { runtime } : {}),
+        createdAt: record.createdAt,
+        expiresAt: record.expiresAt,
+    };
+}
+function restoreStoredSessionState(record) {
+    const session = cloneValue(record.value);
+    const legacyRuntime = restoreLegacyFormRuntime(session);
+    const legacyMetadata = readSessionMetadata(session);
+    stripSessionMetadataFields(session);
+    return {
+        session: session,
+        metadata: {
+            id: normalizeText(record.id) ?? legacyMetadata?.id ?? randomUUID(),
+            createdAt: normalizeDate(record.createdAt) ?? legacyMetadata?.createdAt ?? new Date(0).toISOString(),
+            expiresAt: normalizeDate(record.expiresAt) ?? legacyMetadata?.expiresAt ?? new Date(0).toISOString(),
+        },
+        runtime: mergeSessionRuntimeState(readStoredRuntimeState(record), legacyRuntime),
+    };
+}
+function restoreLegacyFormRuntime(session) {
+    const legacy = coerceSessionRuntimeFormState(session[LEGACY_FORM_RUNTIME_KEY]);
+    delete session[LEGACY_FORM_RUNTIME_KEY];
+    return legacy ? { form: legacy } : undefined;
+}
+function isInMemorySessionStore(value) {
+    return Boolean(value &&
+        typeof value === 'object' &&
+        typeof value.get === 'function' &&
+        typeof value.set === 'function' &&
+        typeof value.delete === 'function' &&
+        typeof value.clear === 'function');
+}
+function readStoredFlash(record) {
+    if (!record) {
+        return [];
+    }
+    return cloneFlashMessages(record.runtime?.flash ?? record.flash);
+}
+function readStoredRuntimeState(record) {
+    return cloneSessionRuntimeState(record.runtime);
+}
+function createSessionStoreRuntime(runtime, flash) {
+    const form = cloneSessionRuntimeState(runtime)?.form;
+    const storedFlash = cloneFlashMessages(flash);
+    if (!form && storedFlash.length === 0) {
+        return undefined;
+    }
+    return {
+        ...(form ? { form } : {}),
+        ...(storedFlash.length > 0 ? { flash: storedFlash } : {}),
+    };
+}
+function cloneSessionStoreRuntime(runtime) {
+    if (!runtime) {
+        return undefined;
+    }
+    const form = cloneSessionRuntimeState(runtime)?.form;
+    const flash = cloneFlashMessages(runtime.flash);
+    if (!form && flash.length === 0) {
+        return undefined;
+    }
+    return {
+        ...(form ? { form } : {}),
+        ...(flash.length > 0 ? { flash } : {}),
+    };
+}
+function cloneFlashMessages(flash) {
+    if (!Array.isArray(flash)) {
+        return [];
+    }
+    return flash.flatMap((message) => {
+        if (!isRecord(message) ||
+            typeof message.key !== 'string' ||
+            typeof message.createdAt !== 'string') {
+            return [];
+        }
+        const level = normalizeFlashLevel(message.level);
+        if (!level) {
+            return [];
+        }
+        return [
+            {
+                key: message.key,
+                level,
+                createdAt: message.createdAt,
+            },
+        ];
+    });
+}
+function normalizeFlashLevel(value) {
+    return value === 'info' || value === 'success' || value === 'warning' || value === 'error'
+        ? value
+        : undefined;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}

package/dist/runtime/views.d.ts

@@ -0,0 +1,74 @@
+export interface EnvAccessorLike {
+    get(name: string): string | undefined;
+    require(name: string): string;
+    entries(): Record<string, string | undefined>;
+}
+export interface LoggerLike {
+    readonly level?: string;
+    log?(level: string, message: string, metadata?: Record<string, unknown>): void;
+    debug?(message: string, metadata?: Record<string, unknown>): void;
+    info?(message: string, metadata?: Record<string, unknown>): void;
+    warn?(message: string, metadata?: Record<string, unknown>): void;
+    error?(message: string, metadata?: Record<string, unknown>): void;
+    with?(bindings: Record<string, unknown>): LoggerLike;
+}
+export interface ViewDefinitionLike {
+    name?: string;
+    path?: string;
+    renderMode?: 'ssg' | 'ssr' | 'spa';
+}
+export type RequestTimeDocumentCacheStatus = 'miss' | 'hit' | 'stale';
+export interface RequestTimeDocumentCacheMetadata {
+    readonly status: RequestTimeDocumentCacheStatus;
+    readonly documentPath: string;
+}
+export interface RenderedRequestTimeView {
+    readonly html: string;
+    readonly documentCache: RequestTimeDocumentCacheMetadata;
+}
+export interface SSRContextLike {
+    readonly url: URL;
+    readonly params: Record<string, string>;
+    readonly cookies: Record<string, string>;
+    readonly headers: Record<string, string>;
+    readonly auth: unknown;
+    readonly session: Record<string, unknown> | null;
+    readonly env: EnvAccessorLike;
+    readonly logger: LoggerLike;
+    readonly requestId?: string;
+    readonly now: () => Date;
+}
+export interface ModuleViewLike {
+    readonly definition?: ViewDefinitionLike;
+    readonly load?: (context: SSRContextLike) => Promise<unknown> | unknown;
+}
+export interface CompiledView {
+    readonly name: string;
+    readonly pathPattern: string;
+    readonly definition?: ViewDefinitionLike;
+    readonly load?: ModuleViewLike['load'];
+    readonly match: (pathname: string) => {
+        matched: boolean;
+        params: Record<string, string>;
+    };
+}
+export declare function compileViews(views: readonly ModuleViewLike[]): CompiledView[];
+export declare function matchView(views: readonly CompiledView[], pathname: string): {
+    view: CompiledView;
+    params: Record<string, string>;
+} | undefined;
+export declare function renderRequestTimeView(options: {
+    workspaceRoot?: string;
+    url: URL;
+    view: CompiledView;
+    params: Record<string, string>;
+    cookies: Record<string, string>;
+    headers: Record<string, string>;
+    auth: unknown;
+    session: Record<string, unknown> | null;
+    env: EnvAccessorLike;
+    logger: LoggerLike;
+    requestId?: string;
+    now?: () => Date;
+}): Promise<RenderedRequestTimeView>;
+export declare function toHeaderRecord(headers: Record<string, string | string[] | undefined>): Record<string, string>;

package/dist/runtime/views.js

@@ -0,0 +1,221 @@
+import path from 'node:path';
+import { access, stat } from 'node:fs/promises';
+import { resolveWorkspaceRoot } from '../workspace.js';
+import { readTextFile } from '../utils/bun.js';
+export function compileViews(views) {
+    const compiled = [];
+    for (const view of views) {
+        const pathPattern = normalizePath(view.definition?.path ?? '/');
+        compiled.push({
+            name: view.definition?.name ?? pathPattern,
+            pathPattern,
+            definition: view.definition,
+            load: view.load,
+            match: createPathMatcher(pathPattern),
+        });
+    }
+    return compiled;
+}
+export function matchView(views, pathname) {
+    for (const view of views) {
+        const matched = view.match(pathname);
+        if (matched.matched) {
+            return {
+                view,
+                params: matched.params,
+            };
+        }
+    }
+    return undefined;
+}
+export async function renderRequestTimeView(options) {
+    const { workspaceRoot, url, view, params, cookies, headers, auth, session, env, logger, requestId, } = options;
+    const now = options.now ?? (() => new Date());
+    const document = await loadFrontendDocument(resolveWorkspaceRoot(workspaceRoot), url.pathname);
+    const viewData = view.load
+        ? await view.load({
+            url,
+            params,
+            cookies,
+            headers,
+            auth,
+            session,
+            env,
+            logger,
+            requestId,
+            now,
+        })
+        : null;
+    return {
+        html: injectViewState(document.html, {
+            name: view.name,
+            templatePath: view.pathPattern,
+            pathname: normalizePath(url.pathname),
+            params,
+            data: viewData ?? null,
+            requestId,
+        }),
+        documentCache: {
+            status: document.cacheStatus,
+            documentPath: document.path,
+        },
+    };
+}
+export function toHeaderRecord(headers) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (typeof value === 'string') {
+            normalized[key] = value;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            normalized[key] = value.join(', ');
+        }
+    }
+    return normalized;
+}
+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 ?? {}),
+        };
+    };
+}
+function normalizePath(value) {
+    if (!value || value === '/') {
+        return '/';
+    }
+    const trimmed = value.endsWith('/') ? value.slice(0, -1) : value;
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+function firstPathSegment(pathname) {
+    const normalized = normalizePath(pathname);
+    if (normalized === '/') {
+        return undefined;
+    }
+    const parts = normalized.split('/').filter(Boolean);
+    return parts[0];
+}
+const documentTemplateCache = new Map();
+async function loadFrontendDocument(workspaceRoot, pathname) {
+    const documentPath = await resolveFrontendDocumentPath(workspaceRoot, pathname);
+    const documentStats = await stat(documentPath);
+    const cached = documentTemplateCache.get(documentPath);
+    if (cached &&
+        cached.ctimeMs === documentStats.ctimeMs &&
+        cached.mtimeMs === documentStats.mtimeMs &&
+        cached.size === documentStats.size) {
+        return {
+            path: documentPath,
+            html: cached.html,
+            cacheStatus: 'hit',
+        };
+    }
+    const html = await readTextFile(documentPath);
+    documentTemplateCache.set(documentPath, {
+        html,
+        ctimeMs: documentStats.ctimeMs,
+        mtimeMs: documentStats.mtimeMs,
+        size: documentStats.size,
+    });
+    return {
+        path: documentPath,
+        html,
+        cacheStatus: cached ? 'stale' : 'miss',
+    };
+}
+async function resolveFrontendDocumentPath(workspaceRoot, pathname) {
+    const candidates = getFrontendDocumentCandidates(workspaceRoot, pathname);
+    for (const candidate of candidates) {
+        if (await fileExists(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`Frontend document for ${normalizePath(pathname)} was not found. Checked ${candidates.join(', ')}.`);
+}
+function getFrontendDocumentCandidates(workspaceRoot, pathname) {
+    const pageName = firstPathSegment(pathname) ?? 'home';
+    const relativeCandidates = pageName === 'home'
+        ? [
+            path.join('pages', 'home', 'index.html'),
+            path.join('home', 'index.html'),
+            'home.html',
+            'index.html',
+        ]
+        : [
+            path.join('pages', pageName, 'index.html'),
+            path.join(pageName, 'index.html'),
+            `${pageName}.html`,
+        ];
+    const candidates = [
+        ...relativeCandidates.map((relativePath) => path.join(workspaceRoot, 'build', 'frontend', relativePath)),
+        ...relativeCandidates.map((relativePath) => path.join(workspaceRoot, 'dist', 'frontend', relativePath)),
+    ];
+    return Array.from(new Set(candidates));
+}
+async function fileExists(targetPath) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function injectViewState(documentHtml, state) {
+    const payload = serializeJsonForHtml({
+        view: {
+            name: state.name,
+            path: state.templatePath,
+            pathname: state.pathname,
+            params: state.params,
+        },
+        data: state.data,
+        requestId: state.requestId ?? null,
+    });
+    const scriptTag = `<script type="application/json" id="webstir-view-state">${payload}</script>`;
+    const htmlWithBodyAttributes = documentHtml.replace(/<body\b([^>]*)>/i, (_match, existingAttributes) => {
+        const attrs = [
+            `data-webstir-view-name="${escapeHtmlAttribute(state.name)}"`,
+            `data-webstir-view-pathname="${escapeHtmlAttribute(state.pathname)}"`,
+            `data-webstir-view-template="${escapeHtmlAttribute(state.templatePath)}"`,
+        ];
+        return `<body${existingAttributes} ${attrs.join(' ')}>`;
+    });
+    if (/<\/body>/i.test(htmlWithBodyAttributes)) {
+        return htmlWithBodyAttributes.replace(/<\/body>/i, `${scriptTag}\n</body>`);
+    }
+    if (/<\/html>/i.test(htmlWithBodyAttributes)) {
+        return htmlWithBodyAttributes.replace(/<\/html>/i, `${scriptTag}\n</html>`);
+    }
+    return `${htmlWithBodyAttributes}\n${scriptTag}`;
+}
+function serializeJsonForHtml(value) {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+function escapeHtmlAttribute(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}