rosefc 0.0.0-stage → 0.2.0

package/src/cli/validator.ts

@@ -0,0 +1,53 @@
+// The conditional-request validator a dynamic response answers with.
+//
+// A server-side cache key can name a representation perfectly and still hand
+// the client the wrong answer, because the client does not compare keys - it
+// compares validators. The prod server used to derive a non-HTML entry's
+// validator from `raw.length` plus the cookie (BUG.md AM): an anonymous
+// reader's cookie is the empty string, so the validator only moved when the
+// byte count moved. Two equal-length representations with different bytes - a
+// same-length typo fix, a re-rendered feed of the same size - therefore shared
+// one validator, and every conditional request against the newer entry answered
+// 304 with the older bytes: a false 304 that survives until the length changes.
+//
+// The rule that closes it is content-derived and cheap: hash what is about to
+// go on the wire. sha1 is not a collision-resistant signature any more, but a
+// validator only needs the property that a byte change flips it, and RFC 9110
+// lets a weak validator (`W/"..."`) be answered with 200 whenever the client's
+// copy is not byte-equivalent. sha1 over a render that already cost a route
+// lookup and a serialization is noise on the budget.
+//
+// Ownership still belongs to the origin server: an app that publishes its own
+// `ETag` keeps it. The framework only synthesizes one where the response has
+// none, so an application-side validator (a database version stamp, a content
+// hash of the pre-serialized row) is never silently replaced underneath a
+// client that cached it.
+import { createHash } from 'node:crypto';
+
+/** A weak, content-derived validator for the exact bytes going on the wire. */
+export function contentEtag(raw: Buffer): string {
+  return 'W/"' + createHash('sha1').update(raw).digest('base64url').slice(0, 24) + '"';
+}
+
+/** The validator this response carries: the app's own if it published one,
+ *  otherwise the hash of its body. Both the exit that answers the request and
+ *  the cache entry that replays it must agree, or a hot replay would mint a
+ *  validator the cold render never showed. */
+export function responseEtag(response: { headers: Headers }, raw: Buffer): string {
+  return response.headers.get('etag') ?? contentEtag(raw);
+}
+
+/** RFC 9110 §13.1.2: `If-None-Match` is a list, `*` matches any current
+ *  representation, and the comparison is weak - the `W/` prefix is not part of
+ *  the identity, so a client that echoed a strong tag still revalidates. */
+export function ifNoneMatch(header: string | string[] | undefined | null, etag: string): boolean {
+  if (!header) return false;
+  const bare = etag.startsWith('W/') ? etag.slice(2) : etag;
+  for (const part of (Array.isArray(header) ? header.join(',') : header).split(',')) {
+    const token = part.trim();
+    if (!token) continue;
+    if (token === '*') return true;
+    if ((token.startsWith('W/') ? token.slice(2) : token) === bare) return true;
+  }
+  return false;
+}

package/src/hash.ts

@@ -0,0 +1,9 @@
+export function fnv1a32(input: Uint8Array | string): string {
+  let h = 0x811c9dc5;
+  const bytes = typeof input === 'string' ? new TextEncoder().encode(input) : input;
+  for (let i = 0; i < bytes.length; i++) {
+    h ^= bytes[i];
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(36);
+}

package/src/runtime/db.ts

@@ -0,0 +1,166 @@
+// src/runtime/db.ts - the database helper tier for pages/api/*.rose handlers.
+//
+// Rose ships no database driver: pg, mysql2 and node:sqlite are three
+// incompatible shapes, and none of them belongs in a runtime whose entire
+// published dependency list is esbuild. So the app supplies ONE object that
+// can run a query - the `Driver` below - and every handler talks to the typed
+// helpers in this file. Swapping SQLite for Postgres is then a one-file
+// change (the driver), not a rewrite of twenty routes.
+//
+// WIRING (once, at boot, in a server-only place - src/pages/_middleware.rose,
+// or a module that file imports; never a page: a page script ships to the
+// browser). Register there, and handlers call q()/q1()/tx() with no driver
+// import at all.
+//
+//   // Postgres. connect() is what makes tx() correct: a pool hands out a
+//   // different connection per query, so BEGIN/COMMIT on `pool.query` would
+//   // run on different sockets. One connection for the whole transaction.
+//   import { Pool } from 'pg';
+//   import { registerDb } from '../../src/runtime/db';   // flat-build-relative
+//   const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+//   registerDb({
+//     query: (sql, params) => pool.query(sql, params as any[]),
+//     async connect() {
+//       const c = await pool.connect();
+//       return { query: (sql, params) => c.query(sql, params as any[]), release: () => c.release() };
+//     },
+//   });
+//
+//   // mysql2/promise is the same two lines over `pool.execute`.
+//
+//   // SQLite via node:sqlite: no connect() - one connection IS the pool, so
+//   // tx() sends BEGIN/COMMIT/ROLLBACK through query() on it.
+//   const sqlite = new DatabaseSync('blog.db');
+//   registerDb({ query: async (sql, params) => ({ rows: sqlite.prepare(sql).all(...(params ?? [])) }) });
+//
+// Then, in any handler:
+//
+//   const posts = await q<PostRow>('SELECT * FROM posts ORDER BY id DESC');
+//   const post  = await q1<PostRow>('SELECT * FROM posts WHERE id = ?', [id]);   // null when absent
+//   await tx(async (t) => {                                                     // all or nothing
+//     await t.q1('INSERT INTO posts (title) VALUES (?) RETURNING id', [title]);
+//     await t.q('UPDATE counters SET n = n + 1 WHERE k = ?', ['posts']);
+//   });
+//
+// A handler that returns q()'s rows is enough on its own: an exported API
+// function's plain object return value is serialized as JSON.
+//
+// The driver lives on globalThis, not in a module-level `let`, because the
+// runtime is bundled once per page (sliced and per-page inline bundles each
+// carry their own copy of this module) - a module-level variable would be
+// per-copy, so a route would see "no driver registered" from a different
+// bundle's registration. Same reason the rest of the server runtime publishes
+// itself through __rosefdAuth / __rosefdKvApi / __rosefdExtras.
+//
+// Zero dependencies: no import statement in this file at all.
+
+/** The one thing an app must supply. `query` is async even for a sync driver. */
+export interface Driver {
+  query(sql: string, params?: readonly unknown[]): Promise<{ rows: any[] }>;
+  /**
+   * Optional: a dedicated connection for a transaction, released when tx()
+   * ends. Required for a POOL (pg, mysql2) - without it tx() runs BEGIN and
+   * COMMIT through query() and two different sockets would each hold half a
+   * transaction.
+   */
+  connect?(): Promise<Conn>;
+}
+
+/** What connect() returns: the connection, plus the release that returns it. */
+export interface Conn extends Driver {
+  release(): void | Promise<void>;
+}
+
+/** The query helpers. What tx() hands its callback, so it cannot nest. */
+export interface Queries {
+  /** Every matching row. `[]` when none match. */
+  q<T = any>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+  /** The first matching row, or null. Rows are untyped - you name the shape. */
+  q1<T = any>(sql: string, params?: readonly unknown[]): Promise<T | null>;
+}
+
+/** The registered database: the query helpers plus transactions. */
+export interface Db extends Queries {
+  tx<T>(fn: (t: Queries) => Promise<T> | T): Promise<T>;
+}
+
+const KEY = '__rosefdDb';
+
+const slot = () => globalThis as unknown as Record<string, Driver | undefined>;
+
+/**
+ * Publish the app's driver. Call once at boot, before the first request;
+ * calling again (a dev hot reload) simply replaces it.
+ */
+export function registerDb(driver: Driver): void {
+  slot()[KEY] = driver;
+}
+
+function requireDriver(): Driver {
+  const driver = slot()[KEY];
+  if (!driver) {
+    throw new Error(
+      'rosefd/db: no database driver registered - call registerDb({ query }) once at boot ' +
+      '(src/pages/_middleware.rose, or a module it imports) before any handler queries',
+    );
+  }
+  return driver;
+}
+
+const on = (run: Driver): Queries => ({
+  q: async <T>(sql: string, params?: readonly unknown[]): Promise<T[]> => (await run.query(sql, params)).rows as T[],
+  q1: async <T>(sql: string, params?: readonly unknown[]): Promise<T | null> => {
+    const { rows } = await run.query(sql, params);
+    return (rows[0] ?? null) as T | null;
+  },
+});
+
+// q/q1 are `async` rather than plain `Promise`-returning wrappers so a missing
+// driver surfaces as a REJECTED promise: a handler written `export function
+// GET()` (not async) can still await/.catch it instead of crashing at call
+// time on a synchronous throw.
+/** Every matching row, on the registered driver. */
+export async function q<T = any>(sql: string, params?: readonly unknown[]): Promise<T[]> {
+  return on(requireDriver()).q<T>(sql, params);
+}
+
+/** The first matching row, or null, on the registered driver. */
+export async function q1<T = any>(sql: string, params?: readonly unknown[]): Promise<T | null> {
+  return on(requireDriver()).q1<T>(sql, params);
+}
+
+/**
+ * Run `fn` inside one transaction: BEGIN, then COMMIT on success, ROLLBACK and
+ * rethrow on failure. The callback's handle is connection-scoped (queries go
+ * to the same connection the BEGIN went to) and deliberately has no tx(), so a
+ * nested transaction cannot deadlock two connections against each other.
+ */
+export async function tx<T>(fn: (t: Queries) => Promise<T> | T): Promise<T> {
+  const driver = requireDriver();
+  const conn = driver.connect ? await driver.connect() : null;
+  const run = conn ?? driver;
+  try {
+    await run.query('BEGIN');
+    const out = await fn(on(run));
+    await run.query('COMMIT');
+    return out;
+  } catch (err) {
+    // The original failure is the one worth reporting; a rollback that also
+    // fails (a dropped socket) must not replace it.
+    try {
+      await run.query('ROLLBACK');
+    } catch { /* the error thrown below is the truth */ }
+    throw err;
+  } finally {
+    if (conn) await conn.release();
+  }
+}
+
+/** The registered database, for handlers that would rather hold an object. */
+export function db(): Db {
+  return {
+    q: (sql, params) => q(sql, params),
+    q1: (sql, params) => q1(sql, params),
+    tx: (fn) => tx(fn),
+  };
+}