@webjsdev/server 0.7.2

package/src/router.js

@@ -0,0 +1,280 @@
+import { join, relative, sep, posix } from 'node:path';
+import { walk } from './fs-walk.js';
+
+/**
+ * @typedef {{
+ *   pattern: RegExp,
+ *   paramNames: string[],
+ *   file: string,
+ *   routeDir: string,
+ *   layouts: string[],
+ *   errors: string[],
+ *   loadings: string[],
+ *   metadataFiles: string[],
+ *   middlewares: string[],
+ *   isCatchAll: boolean
+ * }} PageRoute
+ *
+ * @typedef {{
+ *   pattern: RegExp,
+ *   paramNames: string[],
+ *   file: string,
+ *   middlewares: string[],
+ * }} ApiRoute
+ *
+ * @typedef {{ stem: string, file: string, urlPath: string }} MetadataRoute
+ *
+ * @typedef {{
+ *   pages: PageRoute[],
+ *   apis: ApiRoute[],
+ *   notFound: string | null,
+ *   notFounds: Map<string, string>,
+ *   metadataRoutes: MetadataRoute[],
+ *   appDir: string
+ * }} RouteTable
+ */
+
+/**
+ * Scan `<appDir>/app` and build a route table.
+ *
+ * Supported file conventions (NextJs App Router–compatible):
+ *   app/page.js                     → /
+ *   app/about/page.js               → /about
+ *   app/blog/[slug]/page.js         → /blog/:slug
+ *   app/files/[...rest]/page.js     → /files/*
+ *   app/(marketing)/about/page.js   → /about   (folders in parens are route groups; not in URL)
+ *   app/_internal/page.js           → ignored  (folders starting with _ are private)
+ *   app/api/hello/route.js          → /api/hello
+ *   app/layout.js                   → wraps every page
+ *   app/error.js                    → error boundary (nested)
+ *   app/loading.js                  → loading UI (auto-wraps page in Suspense)
+ *   app/not-found.js                → 404 fallback (nested: nearest wins)
+ *   app/[[...slug]]/page.js         → optional catch-all (matches / AND /a/b)
+ *   app/sitemap.js                  → serves /sitemap.xml
+ *   app/robots.js                   → serves /robots.txt
+ *   app/icon.js                     → serves /icon (dynamic)
+ *   app/opengraph-image.js          → serves /opengraph-image (dynamic)
+ *
+ * @param {string} appDir
+ * @returns {Promise<RouteTable>}
+ */
+export async function buildRouteTable(appDir) {
+  const root = join(appDir, 'app');
+  /** @type {PageRoute[]} */
+  const pages = [];
+  /** @type {ApiRoute[]} */
+  const apis = [];
+  /** @type {Map<string,string>} */
+  const layouts = new Map();
+  /** @type {Map<string,string>} */
+  const errors = new Map();
+  /** @type {Map<string,string>} */
+  const loadings = new Map();
+  /** @type {Map<string,string>} */
+  const middlewares = new Map();
+  /** @type {Map<string, string>} */
+  const notFounds = new Map();
+  let notFound = null;
+  /** @type {MetadataRoute[]} */
+  const metadataRoutes = [];
+
+  /** @type {Set<string>} */
+  const METADATA_STEMS = new Set(['sitemap', 'robots', 'manifest', 'icon', 'apple-icon', 'opengraph-image', 'twitter-image']);
+  /** @type {Record<string,string>} */
+  const METADATA_URL_MAP = {
+    'sitemap': '/sitemap.xml',
+    'robots': '/robots.txt',
+    'manifest': '/manifest.json',
+    'icon': '/icon',
+    'apple-icon': '/apple-icon',
+    'opengraph-image': '/opengraph-image',
+    'twitter-image': '/twitter-image',
+  };
+
+  for await (const file of walk(root)) {
+    const rel = relative(root, file).split(sep).join('/');
+    const base = posix.basename(rel);
+    const dir = posix.dirname(rel);
+
+    // Private folders (any segment starting with _) are excluded from routing.
+    if (dir !== '.' && dir.split('/').some((s) => s.startsWith('_'))) continue;
+
+    // Match `<name>.<js|mjs|ts|mts>` conventions. Stem is the name without ext.
+    const stem = stemOf(base);
+    if (!stem) continue;
+
+    if (stem === 'page') {
+      const segs = dir === '.' ? [] : dir.split('/');
+      const { pattern, paramNames, isCatchAll } = segmentsToPattern(segs);
+      pages.push({
+        pattern,
+        paramNames,
+        file,
+        routeDir: dir,
+        layouts: [],
+        errors: [],
+        loadings: [],
+        metadataFiles: [],
+        middlewares: [],
+        isCatchAll,
+      });
+    } else if (stem === 'layout') {
+      layouts.set(dir, file);
+    } else if (stem === 'error') {
+      errors.set(dir, file);
+    } else if (stem === 'loading') {
+      loadings.set(dir, file);
+    } else if (stem === 'middleware') {
+      middlewares.set(dir, file);
+    } else if (stem === 'not-found') {
+      notFounds.set(dir, file);
+      if (dir === '.') notFound = file;
+    } else if (METADATA_STEMS.has(stem) && (dir === '.' || dir.split('/').every(s => !s.startsWith('[')))) {
+      // Metadata route: sitemap.ts, robots.ts, icon.ts, etc.
+      // Only at root or static segments (no dynamic params in metadata routes).
+      const urlPath = METADATA_URL_MAP[stem] || `/${stem}`;
+      metadataRoutes.push({ stem, file, urlPath });
+    } else if (stem === 'route') {
+      // route.js / route.ts can live anywhere under app/ (matches NextJs).
+      const segs = dir === '.' ? [] : dir.split('/');
+      const { pattern, paramNames } = segmentsToPattern(segs);
+      apis.push({ pattern, paramNames, file, routeDir: dir, middlewares: [] });
+    }
+  }
+
+  // Attach nested layouts / error / loading / middleware files (outermost first).
+  for (const page of pages) {
+    const chainDirs = chainOf(page.routeDir);
+    page.layouts = chainDirs.map((d) => layouts.get(d)).filter(Boolean);
+    page.errors = chainDirs.map((d) => errors.get(d)).filter(Boolean);
+    page.loadings = chainDirs.map((d) => loadings.get(d)).filter(Boolean);
+    page.middlewares = chainDirs.map((d) => middlewares.get(d)).filter(Boolean);
+    page.metadataFiles = [...page.layouts, page.file];
+  }
+  for (const api of apis) {
+    /** @type any */
+    const a = api;
+    const chainDirs = chainOf(a.routeDir);
+    a.middlewares = chainDirs.map((d) => middlewares.get(d)).filter(Boolean);
+  }
+
+  pages.sort((a, b) => dynScore(a) - dynScore(b));
+  return { pages, apis, notFound, notFounds, metadataRoutes, appDir };
+}
+
+/**
+ * Return the bare name of a file without the accepted JS/TS extension.
+ * `page.js` / `page.mjs` / `page.ts` / `page.mts` → `page`.
+ * Returns null for anything else (images, CSS, etc. don't participate in routing).
+ *
+ * @param {string} base
+ * @returns {string | null}
+ */
+function stemOf(base) {
+  const m = /^([A-Za-z0-9_.-]+)\.(?:m?[jt]s)$/.exec(base);
+  return m ? m[1] : null;
+}
+
+/** @param {string} routeDir */
+function chainOf(routeDir) {
+  const segs = routeDir === '.' ? [] : routeDir.split('/');
+  /** @type {string[]} */
+  const dirs = ['.'];
+  for (let i = 1; i <= segs.length; i++) dirs.push(segs.slice(0, i).join('/'));
+  return dirs;
+}
+
+/** @param {string} seg */
+function isUrlSegment(seg) {
+  if (seg.startsWith('(') && seg.endsWith(')')) return false; // route group
+  if (seg.startsWith('_')) return false; // private
+  return true;
+}
+
+/** @param {PageRoute} r */
+function dynScore(r) {
+  if (r.isCatchAll) return 3;
+  if (r.paramNames.length) return 2;
+  return 1;
+}
+
+/**
+ * @param {string[]} segments
+ * @param {string} [prefix]
+ */
+function segmentsToPattern(segments, prefix = '') {
+  const paramNames = [];
+  let isCatchAll = false;
+  let isOptionalCatchAll = false;
+  const parts = segments
+    .filter(isUrlSegment)
+    .map((seg) => {
+      // Optional catch-all: [[...slug]] matches with AND without params
+      if (seg.startsWith('[[...') && seg.endsWith(']]')) {
+        paramNames.push(seg.slice(5, -2));
+        isCatchAll = true;
+        isOptionalCatchAll = true;
+        return '(.*)';
+      }
+      if (seg.startsWith('[...') && seg.endsWith(']')) {
+        paramNames.push(seg.slice(4, -1));
+        isCatchAll = true;
+        return '(.*)';
+      }
+      if (seg.startsWith('[') && seg.endsWith(']')) {
+        paramNames.push(seg.slice(1, -1));
+        return '([^/]+)';
+      }
+      return escapeRe(seg);
+    });
+  const body = parts.length ? '/' + parts.join('/') : '';
+  // Optional catch-all: also matches the base path without any trailing segments.
+  // e.g., /docs/[[...slug]] matches both /docs and /docs/a/b/c
+  const suffix = isOptionalCatchAll ? '(?:/(.*))?/?' : '/?';
+  const regexBody = isOptionalCatchAll
+    ? body.replace(/\/\(\.\*\)$/, '')  // remove the trailing (.*): we add it as optional
+    : body;
+  const pattern = new RegExp(`^${escapeRe(prefix)}${regexBody}${isOptionalCatchAll ? suffix : '/?$'}`);
+  if (!isOptionalCatchAll) {
+    // Standard pattern needs end anchor
+    return { pattern: new RegExp(`^${escapeRe(prefix)}${body}/?$`), paramNames, isCatchAll };
+  }
+  return { pattern, paramNames, isCatchAll };
+}
+
+/** @param {string} s */
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * @param {RouteTable} table
+ * @param {string} pathname
+ */
+export function matchPage(table, pathname) {
+  for (const route of table.pages) {
+    const m = route.pattern.exec(pathname);
+    if (!m) continue;
+    /** @type {Record<string,string>} */
+    const params = {};
+    route.paramNames.forEach((n, i) => (params[n] = decodeURIComponent(m[i + 1] || '')));
+    return { route, params };
+  }
+  return null;
+}
+
+/**
+ * @param {RouteTable} table
+ * @param {string} pathname
+ */
+export function matchApi(table, pathname) {
+  for (const route of table.apis) {
+    const m = route.pattern.exec(pathname);
+    if (!m) continue;
+    /** @type {Record<string,string>} */
+    const params = {};
+    route.paramNames.forEach((n, i) => (params[n] = decodeURIComponent(m[i + 1] || '')));
+    return { route, params };
+  }
+  return null;
+}

package/src/serializer.js

@@ -0,0 +1,86 @@
+import { stringify, parse } from '@webjsdev/core';
+
+/**
+ * @typedef {Object} Serializer
+ * A pluggable serializer that controls how webjs server actions encode and
+ * decode values on the RPC wire.
+ *
+ * **AI hint:** The default serializer uses webjs's built-in
+ * (`@webjsdev/core` `stringify` / `parse`) so rich types: Date, Map, Set,
+ * BigInt, TypedArrays, Blob/File/FormData, cycles: survive the
+ * client/server round-trip. To swap in a different wire format (e.g.
+ * plain JSON, msgpack), call `setSerializer()` with an object that
+ * implements `serialize`, `deserialize`, and `contentType`.
+ *
+ * @property {(value: unknown) => Promise<string>} serialize
+ *   Encode a value to a string suitable for an HTTP response body.
+ *   Async to support binary types (Blob/File/FormData) which require
+ *   an `await arrayBuffer()` step.
+ * @property {(str: string) => unknown} deserialize
+ *   Decode a string produced by `serialize` back to the original value.
+ *   Sync: binary is already inlined as base64 in the wire format.
+ * @property {string} contentType
+ *   The MIME content-type header value to use for RPC responses.
+ */
+
+/**
+ * Default serializer backed by webjs's built-in `stringify` / `parse`.
+ *
+ * Handles Date, Map, Set, BigInt, TypedArrays, ArrayBuffer, DataView,
+ * Blob, File, FormData, registered Symbols, undefined, NaN/Infinity/-0,
+ * Error, and cycles / shared references.
+ *
+ * @type {Serializer}
+ */
+export const defaultSerializer = {
+  async serialize(value) {
+    return stringify(value);
+  },
+  deserialize(str) {
+    return parse(str);
+  },
+  contentType: 'application/vnd.webjs+json',
+};
+
+/** @type {Serializer} */
+let current = defaultSerializer;
+
+/**
+ * Return the active serializer.
+ *
+ * **AI hint:** Use this in server-side code that needs to encode or decode
+ * RPC payloads. It returns whatever serializer was set via `setSerializer`,
+ * or the default webjs serializer if none was set.
+ *
+ * @returns {Serializer}
+ */
+export function getSerializer() {
+  return current;
+}
+
+/**
+ * Replace the active serializer with a custom implementation.
+ *
+ * **AI hint:** Call this at application startup (before any requests are
+ * handled) to swap the wire format for server actions. The serializer
+ * must implement `serialize(value) => Promise<string>`,
+ * `deserialize(str) => unknown`, and expose a `contentType` string.
+ *
+ * ```js
+ * import { setSerializer } from '@webjsdev/server';
+ *
+ * setSerializer({
+ *   serialize: async (v) => JSON.stringify(v),
+ *   deserialize: JSON.parse,
+ *   contentType: 'application/json',
+ * });
+ * ```
+ *
+ * @param {Serializer} serializer
+ */
+export function setSerializer(serializer) {
+  if (!serializer || typeof serializer.serialize !== 'function' || typeof serializer.deserialize !== 'function') {
+    throw new Error('setSerializer: serializer must have serialize() and deserialize() methods');
+  }
+  current = serializer;
+}

package/src/session.js

@@ -0,0 +1,336 @@
+/**
+ * Session middleware with Remix-style Session class and SessionStorage interface.
+ *
+ * Storage owns the Session lifecycle:
+ *   `storage.read(cookie) → Session`
+ *   `storage.save(session) → cookie | null | ''`
+ *
+ * ```js
+ * // middleware.ts
+ * import { session } from '@webjsdev/server';
+ * export default session({ secret: process.env.SESSION_SECRET });
+ *
+ * // In any handler:
+ * import { getSession } from '@webjsdev/server';
+ * const s = getSession(req);
+ * s.set('userId', user.id);
+ * s.flash('message', 'Welcome back!');
+ * ```
+ *
+ * @module session
+ */
+
+import { getStore } from './cache.js';
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Session class
+// ---------------------------------------------------------------------------
+
+/**
+ * A session holds data for a specific user across multiple requests.
+ *
+ * Modeled after Remix's Session: get, set, has, unset, flash, destroy,
+ * regenerateId.
+ */
+export class Session {
+  #id;
+  #data;
+  #flash;
+  #dirty = false;
+  #destroyed = false;
+  #deleteId;
+
+  /**
+   * @param {string} [id]
+   * @param {{ data?: Record<string, unknown>, flash?: Record<string, unknown> }} [initial]
+   */
+  constructor(id, initial) {
+    this.#id = id || randomBytes(24).toString('base64url');
+    this.#data = new Map(Object.entries(initial?.data || {}));
+    this.#flash = new Map(Object.entries(initial?.flash || {}));
+    if (this.#flash.size > 0) this.#dirty = true;
+  }
+
+  get id() { return this.#id; }
+  get dirty() { return this.#dirty; }
+  get destroyed() { return this.#destroyed; }
+  get deleteId() { return this.#deleteId; }
+
+  /** Serialized data for storage. */
+  get data() {
+    return {
+      data: Object.fromEntries(this.#data),
+      flash: Object.fromEntries(this.#flash),
+    };
+  }
+
+  /** @param {string} key @returns {unknown} */
+  get(key) {
+    if (this.#destroyed) return undefined;
+    return this.#data.get(key) ?? this.#flash.get(key);
+  }
+
+  /** @param {string} key @param {unknown} value */
+  set(key, value) {
+    if (this.#destroyed) throw new Error('Session has been destroyed');
+    if (value == null) this.#data.delete(key);
+    else this.#data.set(key, value);
+    this.#dirty = true;
+  }
+
+  /** @param {string} key @returns {boolean} */
+  has(key) {
+    if (this.#destroyed) return false;
+    return this.#data.has(key) || this.#flash.has(key);
+  }
+
+  /** @param {string} key */
+  unset(key) {
+    if (this.#destroyed) throw new Error('Session has been destroyed');
+    this.#data.delete(key);
+    this.#dirty = true;
+  }
+
+  /**
+   * Set a value that exists for one request only.
+   * @param {string} key @param {unknown} value
+   */
+  flash(key, value) {
+    if (this.#destroyed) throw new Error('Session has been destroyed');
+    this.#flash.set(key, value);
+    this.#dirty = true;
+  }
+
+  /** Destroy the session. Use for logout. */
+  destroy() {
+    this.#destroyed = true;
+    this.#data.clear();
+    this.#flash.clear();
+    this.#dirty = true;
+  }
+
+  /**
+   * Regenerate the session ID. Call after login to prevent session fixation.
+   * @param {boolean} [deleteOld=false]
+   */
+  regenerateId(deleteOld = false) {
+    if (this.#destroyed) throw new Error('Session has been destroyed');
+    if (deleteOld) this.#deleteId = this.#id;
+    this.#id = randomBytes(24).toString('base64url');
+    this.#dirty = true;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SessionStorage interface
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} SessionStorage
+ * @property {(cookie: string | null) => Promise<Session>} read
+ *   Create or restore a Session from the raw (unsigned) cookie value.
+ * @property {(session: Session) => Promise<string | null>} save
+ *   Persist session and return the raw cookie value to sign and set.
+ *   Returns `null` if no cookie change needed, `''` to clear the cookie.
+ */
+
+/**
+ * Cookie-based session storage. All data lives in the cookie itself.
+ * Stateless: no server storage needed.
+ *
+ * @returns {SessionStorage}
+ */
+export function cookieSessionStorage() {
+  return {
+    async read(cookie) {
+      if (cookie) {
+        try {
+          const parsed = JSON.parse(cookie);
+          return new Session(parsed.id, { data: parsed.data, flash: parsed.flash });
+        } catch {}
+      }
+      return new Session();
+    },
+    async save(session) {
+      if (session.destroyed) return '';
+      if (!session.dirty) return null;
+      return JSON.stringify({ id: session.id, ...session.data });
+    },
+  };
+}
+
+/**
+ * Server-side session storage. Session ID in cookie, data in cache store.
+ *
+ * @param {{ store?: import('./cache.js').CacheStore, maxAge?: number }} [opts]
+ * @returns {SessionStorage}
+ */
+export function storeSessionStorage(opts = {}) {
+  const store = opts.store || getStore();
+  const maxAge = opts.maxAge || 86400_000;
+
+  return {
+    async read(cookie) {
+      if (cookie) {
+        const raw = await store.get(`session:${cookie}`);
+        if (raw) {
+          try {
+            const parsed = JSON.parse(raw);
+            return new Session(cookie, { data: parsed.data, flash: parsed.flash });
+          } catch {}
+        }
+      }
+      return new Session();
+    },
+    async save(session) {
+      if (session.deleteId) await store.delete(`session:${session.deleteId}`);
+      if (session.destroyed) {
+        await store.delete(`session:${session.id}`);
+        return '';
+      }
+      if (!session.dirty) return null;
+      await store.set(`session:${session.id}`, JSON.stringify(session.data), maxAge);
+      return session.id;
+    },
+  };
+}
+
+// Backwards-compatible aliases
+export const cookieSession = cookieSessionStorage;
+export const storeSession = storeSessionStorage;
+
+// ---------------------------------------------------------------------------
+// Cookie helpers
+// ---------------------------------------------------------------------------
+
+function sign(value, secret) {
+  return `${value}.${createHmac('sha256', secret).update(value).digest('base64url')}`;
+}
+
+function unsign(input, secret) {
+  const idx = input.lastIndexOf('.');
+  if (idx < 1) return null;
+  const value = input.slice(0, idx);
+  const expected = createHmac('sha256', secret).update(value).digest('base64url');
+  const sigBuf = Buffer.from(input.slice(idx + 1));
+  const expBuf = Buffer.from(expected);
+  if (sigBuf.length !== expBuf.length) return null;
+  if (!timingSafeEqual(sigBuf, expBuf)) return null;
+  return value;
+}
+
+function parseCookies(header) {
+  const out = {};
+  if (!header) return out;
+  for (const pair of header.split(';')) {
+    const eq = pair.indexOf('=');
+    if (eq < 0) continue;
+    out[pair.slice(0, eq).trim()] = decodeURIComponent(pair.slice(eq + 1).trim());
+  }
+  return out;
+}
+
+function serializeCookie(name, value, opts) {
+  let str = `${name}=${encodeURIComponent(value)}`;
+  str += `; Max-Age=${Math.floor(opts.maxAge / 1000)}`;
+  str += `; Path=${opts.path || '/'}`;
+  if (opts.httpOnly !== false) str += '; HttpOnly';
+  if (opts.secure !== false) str += '; Secure';
+  str += `; SameSite=${opts.sameSite || 'Lax'}`;
+  return str;
+}
+
+// ---------------------------------------------------------------------------
+// WeakMap for attaching Session to Request
+// ---------------------------------------------------------------------------
+
+/** @type {WeakMap<Request, Session>} */
+const sessionMap = new WeakMap();
+
+// ---------------------------------------------------------------------------
+// Session middleware
+// ---------------------------------------------------------------------------
+
+/**
+ * Session middleware. Storage owns the Session lifecycle:
+ * `storage.read(cookie) → Session`, `storage.save(session) → cookie`.
+ *
+ * @param {{
+ *   storage?: SessionStorage,
+ *   cookieName?: string,
+ *   secret?: string,
+ *   maxAge?: number,
+ *   path?: string,
+ *   httpOnly?: boolean,
+ *   secure?: boolean,
+ *   sameSite?: string,
+ * }} [opts]
+ */
+export function session(opts = {}) {
+  const secret = opts.secret || process.env.SESSION_SECRET;
+  if (!secret) throw new Error('session() requires secret option or SESSION_SECRET env var');
+
+  const storage = opts.storage || cookieSessionStorage();
+  const cookieName = opts.cookieName || 'webjs.sid';
+  const cookieOpts = {
+    maxAge: opts.maxAge || 86400_000,
+    path: opts.path || '/',
+    httpOnly: opts.httpOnly,
+    secure: opts.secure,
+    sameSite: opts.sameSite,
+  };
+
+  return async function sessionMiddleware(req, next) {
+    const cookies = parseCookies(req.headers.get('cookie') || '');
+    const rawCookie = cookies[cookieName] || '';
+    const unsigned = rawCookie ? unsign(rawCookie, secret) : null;
+
+    // Storage creates the Session
+    const s = await storage.read(unsigned);
+    sessionMap.set(req, s);
+
+    const resp = await next();
+
+    // Storage serializes the Session
+    const cookieValue = await storage.save(s);
+
+    if (cookieValue === '') {
+      // Destroyed: clear the cookie
+      try {
+        resp.headers.append('set-cookie', `${cookieName}=; Max-Age=0; Path=${cookieOpts.path}`);
+      } catch {}
+    } else if (cookieValue !== null) {
+      // Changed: sign and set
+      try {
+        resp.headers.append('set-cookie', serializeCookie(cookieName, sign(cookieValue, secret), cookieOpts));
+      } catch {}
+    }
+    // null = no change
+
+    return resp;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Read session from request
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the Session for the current request.
+ *
+ * ```js
+ * const s = getSession(req);
+ * s.get('userId');
+ * s.set('userId', user.id);
+ * s.flash('message', 'Saved!');
+ * ```
+ *
+ * @param {Request} req
+ * @returns {Session}
+ */
+export function getSession(req) {
+  const s = sessionMap.get(req);
+  if (!s) throw new Error('getSession() called outside of session middleware');
+  return s;
+}