@webjsdev/server 0.7.2

package/src/forwarded.js

@@ -0,0 +1,59 @@
+/**
+ * Build a full URL from a Node IncomingMessage, respecting standard
+ * reverse-proxy headers (`X-Forwarded-Proto`, `X-Forwarded-Host`).
+ *
+ * Why: webjs apps are almost always deployed behind a reverse proxy
+ * (Railway, Fly, Render, Vercel, Cloudflare, nginx, Caddy, Traefik -
+ * see the no-build architecture docs). The proxy terminates TLS and
+ * speaks plain HTTP/1.1 to the container, so `req.url` inside the
+ * container reflects the internal "http" view. Without honoring the
+ * forwarded headers, `ctx.url.origin` returns `http://container-host`
+ * even though the browser is on `https://your-domain.com`: which
+ * breaks OG / og:image tags, OAuth callback URLs, and any user code
+ * that builds absolute URLs.
+ *
+ * Threat model: in webjs's typical deployment topology, the
+ * container's HTTP port is only reachable through the trusted edge
+ * proxy. There's no path for an attacker to inject these headers
+ * without going through that proxy. For self-hosted bare-VM deploys
+ * where the container is somehow directly exposed, set
+ * `WEBJS_NO_TRUST_PROXY=1` to fall back to the raw `Host` header and
+ * `http://` default.
+ *
+ * Header semantics:
+ * - `X-Forwarded-Host` / `X-Forwarded-Proto` can be a comma-separated
+ *   chain if multiple proxies are in front (e.g. CDN -> load balancer
+ *   -> container). The first entry is the value closest to the
+ *   original client: that's what we want.
+ * - Node sometimes returns headers as an array (when the same header
+ *   appears multiple times); handle both string and array shapes.
+ *
+ * @param {{ url?: string, headers: Record<string, string | string[] | undefined> }} req
+ * @returns {URL}
+ */
+export function urlFromRequest(req) {
+  const trust = process.env.WEBJS_NO_TRUST_PROXY !== '1';
+  let host = null;
+  let proto = null;
+  if (trust) {
+    host = firstHeaderValue(req.headers['x-forwarded-host']);
+    proto = firstHeaderValue(req.headers['x-forwarded-proto']);
+  }
+  const finalHost = host || /** @type {string|undefined} */ (req.headers.host) || 'localhost';
+  const finalProto = proto || 'http';
+  return new URL(req.url || '/', `${finalProto}://${finalHost}`);
+}
+
+/**
+ * Pick the first comma-separated value from a header that may be a
+ * string, an array of strings, or undefined.
+ *
+ * @param {string | string[] | undefined} h
+ * @returns {string | null}
+ */
+function firstHeaderValue(h) {
+  const v = Array.isArray(h) ? h[0] : h;
+  if (!v) return null;
+  const first = v.split(',')[0].trim();
+  return first || null;
+}

package/src/fs-walk.js

@@ -0,0 +1,28 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Recursively walk a directory, yielding absolute file paths.
+ *
+ * @param {string} dir
+ * @param {(path: string) => boolean} [filter]
+ * @returns {AsyncGenerator<string>}
+ */
+export async function* walk(dir, filter) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    if (entry.name === 'node_modules') continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(full, filter);
+    } else if (entry.isFile()) {
+      if (!filter || filter(full)) yield full;
+    }
+  }
+}

package/src/importmap.js

@@ -0,0 +1,40 @@
+/**
+ * Build the import map JSON injected into every SSR HTML document.
+ *
+ * Additional vendor entries are added automatically when the bare-import
+ * scanner discovers npm packages used by client code (Vite-style
+ * optimizeDeps).
+ */
+
+/** @type {Record<string, string>} */
+let _extraEntries = {};
+
+/**
+ * Merge additional vendor entries into the import map.
+ * Called by the server after scanning for bare imports.
+ * @param {Record<string, string>} entries
+ */
+export function setVendorEntries(entries) {
+  _extraEntries = entries;
+}
+
+export function buildImportMap() {
+  return {
+    imports: {
+      '@webjsdev/core':               '/__webjs/core/index.js',
+      '@webjsdev/core/':              '/__webjs/core/src/',
+      '@webjsdev/core/client-router': '/__webjs/core/src/router-client.js',
+      '@webjsdev/core/lazy-loader':   '/__webjs/core/src/lazy-loader.js',
+      '@webjsdev/core/directives':    '/__webjs/core/src/directives.js',
+      '@webjsdev/core/context':       '/__webjs/core/src/context.js',
+      '@webjsdev/core/testing':       '/__webjs/core/src/testing.js',
+      '@webjsdev/core/task':          '/__webjs/core/src/task.js',
+      ..._extraEntries,
+    },
+  };
+}
+
+/** Serialise the import map to an HTML script tag string. */
+export function importMapTag() {
+  return `<script type="importmap">${JSON.stringify(buildImportMap())}</script>`;
+}

package/src/json.js

@@ -0,0 +1,64 @@
+import { stringify as wjStringify, parse as wjParse } from '@webjsdev/core';
+import { getRequest } from './context.js';
+import { RPC_CONTENT_TYPE } from './actions.js';
+
+/**
+ * Content-negotiated JSON helper for API routes (`route.js` handlers).
+ *
+ *   // GET /api/posts
+ *   import { json } from '@webjsdev/server';
+ *   export async function GET() {
+ *     return json(await listPosts());   // plain Prisma rows with Date columns
+ *   }
+ *
+ * The helper reads the in-flight Request from the AsyncLocalStorage
+ * request context. If the caller sent `Accept: application/vnd.webjs+json`
+ * (e.g. via the `richFetch` client helper), the response body is
+ * encoded with the webjs serializer so rich types (Date, Map, Set,
+ * BigInt, TypedArrays, Blob, File, FormData, cycles) survive. Otherwise
+ * the response is plain `application/json`, unchanged behaviour for
+ * curl / external consumers.
+ *
+ * Passing an options object with `{ status, headers }` mirrors
+ * `Response.json(data, init)`.
+ *
+ * @template T
+ * @param {T} data
+ * @param {ResponseInit} [init]
+ * @returns {Promise<Response>} async because the rich path may need to
+ *   read bytes from Blob/File/FormData; plain-JSON path resolves
+ *   immediately.
+ */
+export async function json(data, init = {}) {
+  const req = getRequest();
+  const accept = req?.headers.get('accept') || '';
+  const wantsRich = accept.includes(RPC_CONTENT_TYPE);
+
+  const headers = new Headers(init.headers || {});
+  if (wantsRich) {
+    headers.set('content-type', RPC_CONTENT_TYPE);
+    headers.append('vary', 'Accept');
+    return new Response(await wjStringify(data), { ...init, headers });
+  }
+  headers.set('content-type', 'application/json; charset=utf-8');
+  headers.append('vary', 'Accept');
+  return new Response(JSON.stringify(data), { ...init, headers });
+}
+
+/**
+ * Parse a request body using the webjs serializer when the client sent
+ * our content type, otherwise as plain JSON. Handy for route handlers
+ * that accept rich bodies from the `richFetch` helper but plain JSON
+ * from everyone else.
+ *
+ * @param {Request} req
+ */
+export async function readBody(req) {
+  const ct = req.headers.get('content-type') || '';
+  const text = await req.text();
+  if (!text) return null;
+  if (ct.includes(RPC_CONTENT_TYPE)) return wjParse(text);
+  return JSON.parse(text);
+}
+
+export { RPC_CONTENT_TYPE };

package/src/logger.js

@@ -0,0 +1,39 @@
+/**
+ * Minimal pluggable logger.
+ *
+ * webjs doesn't pick pino/winston/bunyan for you. The default in prod emits
+ * one JSON object per line to stdout: trivially ingestable by any log
+ * aggregator. In dev, lines are plain text for readability.
+ *
+ * Apps can pass their own logger to `createRequestHandler({ logger })`.
+ * Any object that implements `{ info, warn, error }` works.
+ *
+ * @typedef {{
+ *   info: (msg: string, meta?: Record<string, unknown>) => void,
+ *   warn: (msg: string, meta?: Record<string, unknown>) => void,
+ *   error: (msg: string, meta?: Record<string, unknown>) => void,
+ * }} Logger
+ */
+
+/**
+ * @param {{ dev?: boolean }} [opts]
+ * @returns {Logger}
+ */
+export function defaultLogger(opts = {}) {
+  if (opts.dev) {
+    return {
+      info: (msg, meta) => console.log(meta ? `[webjs] ${msg}` : `[webjs] ${msg}`, meta ?? ''),
+      warn: (msg, meta) => console.warn(`[webjs] ${msg}`, meta ?? ''),
+      error: (msg, meta) => console.error(`[webjs] ${msg}`, meta ?? ''),
+    };
+  }
+  const emit = (level, stream) => (msg, meta) => {
+    const line = JSON.stringify({ level, msg, time: new Date().toISOString(), ...(meta || {}) });
+    stream.write(line + '\n');
+  };
+  return {
+    info: emit('info', process.stdout),
+    warn: emit('warn', process.stderr),
+    error: emit('error', process.stderr),
+  };
+}

package/src/module-graph.js

@@ -0,0 +1,141 @@
+/**
+ * Lightweight module dependency graph.
+ *
+ * At startup, scans the app directory and builds an in-memory map of
+ * `file → Set<imported files>`. The SSR pipeline queries this graph to
+ * emit *complete* modulepreload hints: including transitive dependencies
+ * of components: so the browser can fetch the entire tree in parallel
+ * rather than discovering imports one waterfall at a time.
+ *
+ * The graph is file-path-based (absolute paths). URLs are derived when
+ * emitting preload hints.
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, resolve, dirname, extname } from 'node:path';
+
+/** @type {RegExp} match static `import … from '…'` and `import '…'` */
+const IMPORT_RE = /\bimport\s+(?:(?:[\w*{}\s,]+)\s+from\s+)?['"]([^'"]+)['"]/g;
+
+/**
+ * @typedef {Map<string, Set<string>>} ModuleGraph
+ * A map of absolute file path → Set of absolute file paths it imports.
+ */
+
+/**
+ * Build the module graph for all source files under `appDir`.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ModuleGraph>}
+ */
+export async function buildModuleGraph(appDir) {
+  /** @type {ModuleGraph} */
+  const graph = new Map();
+  await walk(appDir, appDir, graph);
+  return graph;
+}
+
+/**
+ * Given a set of entry files, return all transitive dependencies (deduplicated).
+ * Entry files themselves are NOT included (they're already preloaded by the
+ * boot script).
+ *
+ * @param {ModuleGraph} graph
+ * @param {string[]} entryFiles  absolute paths
+ * @param {string} appDir
+ * @returns {string[]}  absolute paths of transitive deps
+ */
+export function transitiveDeps(graph, entryFiles, appDir) {
+  /** @type {Set<string>} */
+  const visited = new Set(entryFiles);
+  /** @type {string[]} */
+  const result = [];
+  /** @type {string[]} */
+  const queue = [...entryFiles];
+
+  while (queue.length) {
+    const file = /** @type {string} */ (queue.shift());
+    const deps = graph.get(file);
+    if (!deps) continue;
+    for (const dep of deps) {
+      if (visited.has(dep)) continue;
+      visited.add(dep);
+      // Only include files within the app dir (skip node_modules, core, etc.)
+      if (dep.startsWith(appDir)) {
+        result.push(dep);
+      }
+      queue.push(dep);
+    }
+  }
+  return result;
+}
+
+/**
+ * Recursively walk a directory, parse imports, and populate the graph.
+ * @param {string} dir
+ * @param {string} appDir
+ * @param {ModuleGraph} graph
+ */
+async function walk(dir, appDir, graph) {
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); }
+  catch { return; }
+  for (const e of entries) {
+    if (e.name === 'node_modules' || e.name === '.webjs' || e.name === 'public' || e.name.startsWith('_')) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      await walk(full, appDir, graph);
+    } else if (/\.(js|ts|mjs|mts)$/.test(e.name)) {
+      await parseFile(full, appDir, graph);
+    }
+  }
+}
+
+/**
+ * Parse a single file's imports and add them to the graph.
+ * Only resolves relative imports (bare specifiers are npm deps, not in the graph).
+ *
+ * @param {string} file
+ * @param {string} appDir
+ * @param {ModuleGraph} graph
+ */
+async function parseFile(file, appDir, graph) {
+  let src;
+  try { src = await readFile(file, 'utf8'); }
+  catch { return; }
+
+  const deps = new Set();
+  for (const m of src.matchAll(IMPORT_RE)) {
+    const spec = m[1];
+    // Only resolve relative imports within the project
+    if (!spec.startsWith('.') && !spec.startsWith('/')) continue;
+    const resolved = resolveImport(spec, file, appDir);
+    if (resolved) deps.add(resolved);
+  }
+  if (deps.size) graph.set(file, deps);
+}
+
+/**
+ * Resolve a relative import specifier to an absolute file path.
+ * Handles: exact match, .ts/.js extension fallback, /index.ts fallback.
+ *
+ * @param {string} spec  e.g. `'../components/theme-toggle.ts'`
+ * @param {string} fromFile  absolute path of the importing file
+ * @param {string} appDir
+ * @returns {string | null}
+ */
+function resolveImport(spec, fromFile, appDir) {
+  const base = dirname(fromFile);
+  let target;
+  if (spec.startsWith('/')) {
+    // Absolute from app root (how browser sees it)
+    target = join(appDir, spec);
+  } else {
+    target = resolve(base, spec);
+  }
+  // Exact match check: we can't use async `stat` in a sync resolver, so we
+  // store the resolved path optimistically. The graph is advisory (for preload
+  // hints), not load-bearing, so a wrong entry is harmless: the browser will
+  // just get a redundant preload that 404s and is ignored.
+  return target;
+}

package/src/rate-limit.js

@@ -0,0 +1,105 @@
+/**
+ * Fixed-window rate limiter backed by the pluggable cache store.
+ *
+ * Uses the global cache store (`getStore()`) by default, which is
+ * in-memory unless the app calls `setStore(redisStore(...))` at
+ * startup. Passing `opts.store` lets a single middleware target a
+ * different store than the default.
+ *
+ * ```js
+ * import { rateLimit } from '@webjsdev/server';
+ * export default rateLimit({ window: '1m', max: 60 });
+ * ```
+ *
+ * For horizontal scaling across multiple instances, switch the global
+ * store to Redis once at app startup:
+ *
+ * ```js
+ * import { setStore, redisStore } from '@webjsdev/server';
+ * setStore(redisStore({ url: process.env.REDIS_URL }));
+ * ```
+ *
+ * @module rate-limit
+ */
+
+import { getStore } from './cache.js';
+
+/**
+ * @param {{
+ *   window?: number | string,
+ *   max?: number,
+ *   key?: string | ((req: Request) => string | Promise<string>),
+ *   message?: string,
+ *   store?: import('./cache.js').CacheStore,
+ * }} opts
+ * @returns {(req: Request, next: () => Promise<Response>) => Promise<Response>}
+ */
+export function rateLimit(opts = {}) {
+  const windowMs = parseWindow(opts.window ?? '1m');
+  const max = opts.max ?? 60;
+  const keyFn = typeof opts.key === 'function' ? opts.key : defaultKey;
+  const keyPrefix = typeof opts.key === 'string' ? opts.key : '';
+  const message = opts.message ?? 'Too Many Requests';
+  // Use the provided store, or fall back to the global cache store -
+  // whatever was set via `setStore()` at app startup (in-memory by default).
+  const store = opts.store || null;
+
+  return async function rateLimitMiddleware(req, next) {
+    const s = store || getStore();
+    const raw = typeof opts.key === 'function' ? await keyFn(req) : defaultKey(req);
+    const key = `rl:${keyPrefix}${raw}`;
+
+    const count = await s.increment(key, windowMs);
+    const resetAt = Date.now() + windowMs;
+
+    if (count > max) {
+      return new Response(JSON.stringify({ error: message }), {
+        status: 429,
+        headers: {
+          'content-type': 'application/json; charset=utf-8',
+          'retry-after': String(Math.ceil(windowMs / 1000)),
+          'x-ratelimit-limit': String(max),
+          'x-ratelimit-remaining': '0',
+          'x-ratelimit-reset': String(Math.floor(resetAt / 1000)),
+        },
+      });
+    }
+
+    const resp = await next();
+    try {
+      resp.headers.set('x-ratelimit-limit', String(max));
+      resp.headers.set('x-ratelimit-remaining', String(Math.max(0, max - count)));
+      resp.headers.set('x-ratelimit-reset', String(Math.floor(resetAt / 1000)));
+    } catch {
+      // Headers may be immutable on some synthetic Responses.
+    }
+    return resp;
+  };
+}
+
+/** @param {Request} req */
+function defaultKey(req) {
+  return (
+    req.headers.get('x-forwarded-for')?.split(',')[0].trim() ||
+    req.headers.get('cf-connecting-ip') ||
+    req.headers.get('x-real-ip') ||
+    '_anon_'
+  );
+}
+
+/** @param {number | string} w @returns {number} milliseconds */
+export function parseWindow(w) {
+  if (typeof w === 'number') return w;
+  const m = /^(\d+)\s*(ms|s|m|h)?$/.exec(String(w));
+  if (!m) return 60_000;
+  const n = Number(m[1]);
+  const unit = m[2] || 'ms';
+  const mult = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[unit];
+  return n * (mult || 1);
+}
+
+/** Testing hook: reset the default store (for unit tests). */
+export function _resetRateLimits() {
+  // With the cache store, there's nothing to reset here: the store
+  // handles its own state. This function exists for API compatibility.
+}