@statorjs/stator 2.10.0-next.0 → 2.10.0

package/src/server/route-discovery.ts

@@ -35,6 +35,14 @@ export interface DiscoveredRoute {
   PUT?: ApiRouteDefinition
   PATCH?: ApiRouteDefinition
   DELETE?: ApiRouteDefinition
+  /** True for a `404.stator`/`404.ts` file — sugar for a `[...name]`
+   *  catch-all (same synthesized pattern, same matcher), except
+   *  `sortRoutes` forces it to the absolute lowest priority: below even a
+   *  real `[...name]` at the same depth. It's the last resort, only ever
+   *  reached once nothing else — including a genuine catch-all a request
+   *  matched first — could actually serve the request (a 404 cascades by
+   *  default; see the GET dispatch loop in http.ts). */
+  isNotFoundFallback?: boolean
 }
 
 /**
@@ -47,6 +55,11 @@ export interface DiscoveredRoute {
  *   - `routes/[a]/[b].ts`       → `/:a/:b`
  *   - `routes/foo/[...rest].ts` → `/foo/*rest` (catch-all: terminal, matches
  *     zero+ segments, param is the raw remainder incl. slashes)
+ *   - `routes/foo/404.ts`       → sugar for `routes/foo/[...___].ts` — a
+ *     catch-all without needing to know the bracket-rest convention, EXCEPT
+ *     `sortRoutes` also forces it to the absolute lowest match priority,
+ *     below even a real `[...rest]` at the same depth — see
+ *     `DiscoveredRoute.isNotFoundFallback`.
  *
  * Files may export any combination of `GET`/`POST`/`PUT`/`PATCH`/`DELETE`.
  * GET is a `defineRoute` (page renderer) or a `defineApiRoute` declaring
@@ -123,11 +136,12 @@ export async function discoverRoutes(
       continue
     }
 
-    const { urlPath, paramNames } = filePathToRoute(absDir, filePath)
+    const { urlPath, paramNames, isNotFoundFallback } = filePathToRoute(absDir, filePath)
     routes.push({
       urlPath,
       paramNames,
       filePath,
+      ...(isNotFoundFallback ? { isNotFoundFallback } : {}),
       GET: get,
       POST: post,
       PUT: put,
@@ -169,6 +183,10 @@ function mergeByUrlPath(routes: DiscoveredRoute[]): DiscoveredRoute[] {
 /**
  * Sort routes most-specific-first (Astro's model). At match time the first
  * matcher that matches wins, so order encodes priority:
+ *   - a `404.stator`/`404.ts` file (`isNotFoundFallback`) ranks absolute
+ *     last, below even a real `[...name]` at the same depth — it's the
+ *     final resort, only reached once nothing else (a genuine catch-all
+ *     included) could serve the request
  *   - routes without a rest/catch-all segment rank before those with one
  *   - per segment, left to right: static (0) > suffixed param `:id.json` (1)
  *     > bare param (2) > rest (3) — a suffixed param outranks a bare one so
@@ -186,6 +204,10 @@ export function sortRoutes(routes: DiscoveredRoute[]): DiscoveredRoute[] {
       )
 
   return [...routes].sort((a, b) => {
+    const aFallback = !!a.isNotFoundFallback
+    const bFallback = !!b.isNotFoundFallback
+    if (aFallback !== bFallback) return aFallback ? 1 : -1 // 404 fallback always last
+
     const ka = kinds(a.urlPath)
     const kb = kinds(b.urlPath)
     const aRest = ka.includes(3)
@@ -230,7 +252,7 @@ async function walkRouteFiles(dir: string): Promise<string[]> {
 export function filePathToRoute(
   absDir: string,
   filePath: string,
-): { urlPath: string; paramNames: string[] } {
+): { urlPath: string; paramNames: string[]; isNotFoundFallback: boolean } {
   const ext = extname(filePath)
   const rel = relative(absDir, filePath)
   const dirSegments = dirname(rel)
@@ -240,9 +262,18 @@ export function filePathToRoute(
   // sibling `<name>.stator.ts` files, which must map to the same URL as the
   // `<name>.stator` source did in dev.
   const fileBase = basename(rel, ext).replace(/\.stator$/, '')
-  const segments = fileBase === 'index' ? dirSegments : [...dirSegments, fileBase]
+  // `404` is sugar for a synthesized `[...name]` at this exact position —
+  // reuses the rest-segment branch below verbatim, so it gets the same
+  // matcher/regex a real catch-all would. `sortRoutes` is what actually
+  // forces it below a real `[...name]` at the same depth; this alone would
+  // just be an ordinary (if oddly-named) catch-all.
+  const isNotFoundFallback = fileBase === '404'
+  const segments =
+    fileBase === 'index'
+      ? dirSegments
+      : [...dirSegments, isNotFoundFallback ? '[...__stator_notfound__]' : fileBase]
 
-  if (segments.length === 0) return { urlPath: '/', paramNames: [] }
+  if (segments.length === 0) return { urlPath: '/', paramNames: [], isNotFoundFallback }
 
   const paramNames: string[] = []
   const urlSegments = segments.map((seg) => {
@@ -272,5 +303,5 @@ export function filePathToRoute(
     return seg
   })
 
-  return { urlPath: `/${urlSegments.join('/')}`, paramNames }
+  return { urlPath: `/${urlSegments.join('/')}`, paramNames, isNotFoundFallback }
 }

package/src/server/routing.ts

@@ -198,6 +198,7 @@ export function defineApiRoute<TReads extends ReadonlyArray<AnyMachineDef>>(
       __isStatorQueryRoute: true,
       reads: config.reads ? [...config.reads] : [],
       handler: config.handler,
+      revision: config.revision,
     }
   }
   return {
@@ -248,6 +249,7 @@ export interface QueryRouteDefinition {
     request: RouteRequest,
     helpers: QueryRouteHelpers,
   ) => Promise<QueryRouteResult> | QueryRouteResult
+  revision?: () => string | number | Promise<string | number>
 }
 
 export interface DefineQueryRouteConfig<TReads extends ReadonlyArray<AnyMachineDef> = readonly []> {
@@ -259,6 +261,12 @@ export interface DefineQueryRouteConfig<TReads extends ReadonlyArray<AnyMachineD
     request: RouteRequest,
     helpers: QueryRouteHelpers<TReads>,
   ) => Promise<QueryRouteResult> | QueryRouteResult
+  /** The revision ledger: a CHEAP fingerprint of everything the body depends
+   *  on (e.g. `() => String(maxUpdatedAt())` — one indexed SELECT). When
+   *  present, the ETag derives from it and a matching `If-None-Match`
+   *  answers 304 WITHOUT invoking the handler — a polling crawler costs the
+   *  fingerprint, not the render. Must change whenever the body could. */
+  revision?: () => string | number | Promise<string | number>
 }
 
 export function isStatorQueryRoute(v: unknown): v is QueryRouteDefinition {

package/src/server/session.ts

@@ -23,9 +23,18 @@ export interface SessionState {
   claimsDirty: boolean
 }
 
+/** Layer-3 provability tracking: did this request USE the session plane
+ *  (establish/dispatch/session-read) or READ claims? Either makes the
+ *  response unprovable as anonymous-identical, so no derived Cache-Control. */
+export interface SessionUse {
+  used: boolean
+  claimsRead: boolean
+}
+
 declare module 'hono' {
   interface ContextVariableMap {
     statorSession: SessionState
+    statorSessionUse: SessionUse
   }
 }
 
@@ -34,6 +43,40 @@ export function getSessionState(c: Context): SessionState | undefined {
   return c.get('statorSession')
 }
 
+/** The request's session-use flags (created on first access). */
+export function sessionUse(c: Context): SessionUse {
+  let use = c.get('statorSessionUse')
+  if (!use) {
+    use = { used: false, claimsRead: false }
+    c.set('statorSessionUse', use)
+  }
+  return use
+}
+
+/** The session id this request WOULD have — established state or the arriving
+ *  cookie — without creating anything. Null for a first-contact visitor. */
+export function peekSessionId(c: Context): string | null {
+  return getSessionState(c)?.sid ?? getCookie(c, SESSION_COOKIE) ?? null
+}
+
+/** Resume an EXISTING session from the arriving cookie (populate the shared
+ *  state, no cookie write) — or return null for first contact. Resuming is
+ *  not establishment: laziness governs CREATION only. */
+export function resumeSession(c: Context): SessionState | null {
+  const established = getSessionState(c)
+  if (established) return established
+  const cookieSid = getCookie(c, SESSION_COOKIE)
+  if (cookieSid === undefined) return null
+  const state: SessionState = {
+    sid: cookieSid,
+    isNew: false,
+    claims: undefined,
+    claimsDirty: false,
+  }
+  c.set('statorSession', state)
+  return state
+}
+
 /** Secure cookie flag — set when running behind HTTPS. Enabled by
  *  NODE_ENV=production; can be overridden via STATOR_SECURE_COOKIE. */
 function shouldUseSecureCookie(): boolean {
@@ -65,22 +108,26 @@ export function setSessionCookie(c: Context, sessionId: string): void {
   })
 }
 
+/**
+ * ESTABLISH the session — the lazy-creation trigger (dispatches, session-
+ * machine reads, SSE connects, explicit session ops call this; anonymous
+ * page/data GETs never do). Idempotent per request: the first caller
+ * establishes, everyone after reads the same state. A first-contact visitor
+ * gets a fresh sid + Set-Cookie HERE and nowhere earlier — the whole
+ * cacheable-read-path layer 1.
+ */
 export function getOrCreateSessionId(c: Context): {
   sessionId: string
   isNew: boolean
 } {
-  // Idempotent per request: the first caller (middleware or handler) establishes
-  // the session; everyone after reads the same one. Closes the double-create bug.
-  const established = c.get('statorSession')
-  if (established) return { sessionId: established.sid, isNew: established.isNew }
-
-  const cookieSid = getCookie(c, SESSION_COOKIE)
-  const sessionId = cookieSid ?? randomUUID()
-  const isNew = cookieSid === undefined
-  if (isNew) setSessionCookie(c, sessionId)
+  sessionUse(c).used = true
+  const resumed = resumeSession(c)
+  if (resumed) return { sessionId: resumed.sid, isNew: resumed.isNew }
 
-  c.set('statorSession', { sid: sessionId, isNew, claims: undefined, claimsDirty: false })
-  return { sessionId, isNew }
+  const sessionId = randomUUID()
+  setSessionCookie(c, sessionId)
+  c.set('statorSession', { sid: sessionId, isNew: true, claims: undefined, claimsDirty: false })
+  return { sessionId, isNew: true }
 }
 
 /**

package/src/server/sse.ts

@@ -17,13 +17,21 @@ const sseLog = scopedLogger('sse')
  * recompute will diff against when fan-out fires. Each push updates
  * `lastValue` for the bindings touched by the push, so subsequent pushes
  * only emit deltas.
+ *
+ * Writes never happen inline. Everything outbound — fan-out patches, the
+ * initial sync, the heartbeat, the dev broadcast — goes through `enqueue`,
+ * and one drain loop per connection owns the socket. A request or a lock is
+ * therefore never held across a socket write, and per-connection order is a
+ * property of the queue rather than of who awaited what.
  */
 export interface Connection {
   id: string
   sessionId: string
   /** The browser page-load identity (client-generated). Lets fan-out
-   *  recognize a dispatch's OWN connection: its baseline is advanced but
-   *  nothing is sent — the POST response already delivered those patches. */
+   *  recognize a dispatch's OWN connection: its baseline is advanced and,
+   *  when nothing is queued for it, nothing is sent — the POST response
+   *  delivers those patches. With a backlog they ride the queue instead, so
+   *  the two channels cannot reorder a positional list op. */
   clientId?: string
   routeKey: string
   route: RouteDefinition
@@ -39,14 +47,29 @@ export interface Connection {
    *  transport; absent in tests that register a bare connection. */
   close?: () => void
   closed: boolean
+  /** Outbound writes waiting for the drain loop, oldest first. */
+  queue: string[]
+  /** Bytes waiting in `queue`. The item being written is not counted. */
+  queuedBytes: number
+  /** True while the drain loop owns the socket — an item is in flight. */
+  draining: boolean
 }
 
+type ConnectionInit = Omit<Connection, 'id' | 'closed' | 'queue' | 'queuedBytes' | 'draining'>
+
 const connections = new Map<string, Connection>()
 let nextId = 0
 
-export function registerConnection(init: Omit<Connection, 'id' | 'closed'>): Connection {
+export function registerConnection(init: ConnectionInit): Connection {
   const id = `sse${nextId++}`
-  const conn: Connection = { ...init, id, closed: false }
+  const conn: Connection = {
+    ...init,
+    id,
+    closed: false,
+    queue: [],
+    queuedBytes: 0,
+    draining: false,
+  }
   // A page-load holds at most one channel per route, so an existing
   // connection with the same (clientId, routeKey) is a corpse whose abort we
   // never observed — a half-open socket, or a reconnect that raced its own
@@ -73,21 +96,16 @@ export function registerConnection(init: Omit<Connection, 'id' | 'closed'>): Con
 }
 
 /**
- * Push a pre-serialized envelope to every open connection, bypassing the
+ * Queue a pre-serialized envelope for every open connection, bypassing the
  * recompute path. The dev server's rebuild/error signals ride this so a dev
  * page holds ONE event-stream instead of two — see `dev-native.ts`. Not a
  * fan-out: no diffing, no baseline advance, no per-connection filtering.
  */
-export async function broadcastEnvelope(payload: unknown): Promise<void> {
+export function broadcastEnvelope(payload: unknown): void {
   if (connections.size === 0) return
   const data = JSON.stringify(payload)
   for (const conn of connections.values()) {
-    if (conn.closed) continue
-    try {
-      await conn.send(data)
-    } catch (err) {
-      sseLog.warn({ id: conn.id, err: String(err) }, 'broadcast failed')
-    }
+    if (!conn.closed) enqueue(conn, data)
   }
 }
 
@@ -95,6 +113,10 @@ export function unregisterConnection(id: string): void {
   const conn = connections.get(id)
   if (!conn) return
   conn.closed = true
+  // Whatever was waiting is discarded with the socket: the client reconnects
+  // and resyncs. The drain loop, if mid-write, sees `closed` and exits.
+  conn.queue.length = 0
+  conn.queuedBytes = 0
   conn.runtime.dispose()
   connections.delete(id)
   sseLog.debug(
@@ -107,6 +129,133 @@ export function activeConnectionCount(): number {
   return connections.size
 }
 
+/** How long one write to one connection may take before the connection is
+ *  treated as dead. `STATOR_SSE_WRITE_TIMEOUT_MS` overrides it. */
+const DEFAULT_WRITE_TIMEOUT_MS = 5_000
+
+function writeTimeoutMs(): number {
+  const raw = process.env.STATOR_SSE_WRITE_TIMEOUT_MS
+  if (raw === undefined || raw === '') return DEFAULT_WRITE_TIMEOUT_MS
+  const ms = Number(raw)
+  return Number.isFinite(ms) && ms > 0 ? ms : DEFAULT_WRITE_TIMEOUT_MS
+}
+
+/** Bytes a connection may hold WAITING behind an in-flight write before it is
+ *  treated as dead. The item being written is covered by the write deadline,
+ *  not by this, and a single waiting item never trips it however large — an
+ *  initial sync of a big table is one item. `STATOR_SSE_QUEUE_MAX_BYTES`
+ *  overrides it. */
+const DEFAULT_QUEUE_MAX_BYTES = 1_048_576
+
+function queueMaxBytes(): number {
+  const raw = process.env.STATOR_SSE_QUEUE_MAX_BYTES
+  if (raw === undefined || raw === '') return DEFAULT_QUEUE_MAX_BYTES
+  const bytes = Number(raw)
+  return Number.isFinite(bytes) && bytes > 0 ? bytes : DEFAULT_QUEUE_MAX_BYTES
+}
+
+/** Whether anything is queued or in flight for this connection. */
+export function hasBacklog(conn: Connection): boolean {
+  return conn.draining || conn.queue.length > 0
+}
+
+/**
+ * Queue one envelope for a connection and return at once. The drain loop
+ * writes it when everything ahead of it has been written, so order per
+ * connection is FIFO by construction. Overflow drops the connection, the
+ * same policy as a write that times out: the client reconnects and resyncs.
+ */
+export function enqueue(conn: Connection, data: string): void {
+  if (conn.closed) return
+  conn.queue.push(data)
+  conn.queuedBytes += Buffer.byteLength(data)
+  if (conn.queue.length > 1 && conn.queuedBytes > queueMaxBytes()) {
+    sseLog.warn(
+      {
+        id: conn.id,
+        sid: conn.sessionId,
+        route: conn.routeKey,
+        waiting: conn.queue.length,
+        bytes: conn.queuedBytes,
+        max: queueMaxBytes(),
+      },
+      'sse queue overflowed — dropping the connection',
+    )
+    unregisterConnection(conn.id)
+    conn.close?.()
+    return
+  }
+  if (!conn.draining) void drain(conn)
+}
+
+/** The one writer per connection. Runs until the queue is empty or the
+ *  connection closes under it (a timed-out write, an overflow, an abort). */
+async function drain(conn: Connection): Promise<void> {
+  conn.draining = true
+  try {
+    while (!conn.closed && conn.queue.length > 0) {
+      const data = conn.queue.shift()!
+      conn.queuedBytes -= Buffer.byteLength(data)
+      await pushToConnection(conn, data)
+    }
+  } finally {
+    conn.draining = false
+  }
+}
+
+/**
+ * Write one envelope to one connection, bounded. The drain loop's single
+ * write; nothing else touches the socket.
+ *
+ * A write to a live socket resolves; a write to a closed one rejects. A write
+ * to a HALF-OPEN one does neither once its buffer is full — when a remote
+ * laptop sleeps or a NAT drops the mapping, no FIN ever arrives, the socket
+ * still looks writable, and the promise simply never settles. Fan-out used to
+ * await these serially with no deadline, so one such connection stalled the
+ * loop and every connection registered after it received nothing until the
+ * kernel gave up on the socket (minutes) or the same page reconnected and
+ * evicted it. Under the session lock the same stall ran into the lock's 30s
+ * backstop, failing the dispatching request each time.
+ *
+ * On a timeout the connection is dropped rather than retried: the client
+ * reconnects and gets a full resync, which is cheap by design. Note what the
+ * deadline measures: a write to a socket with buffer space resolves at once
+ * regardless of the peer, so this fires only when the buffer has stayed full
+ * for the whole window — not on a merely slow client. And because the clock
+ * starts when the drain loop issues the write, not when the item was queued,
+ * a burst behind a slow but healthy socket cannot trip it.
+ */
+export async function pushToConnection(conn: Connection, data: string): Promise<Outcome> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    const outcome = await Promise.race<Outcome>([
+      conn.send(data).then((): Outcome => 'sent'),
+      new Promise<Outcome>((settle) => {
+        timer = setTimeout(() => settle('timeout'), writeTimeoutMs())
+        timer.unref?.()
+      }),
+    ])
+    if (outcome === 'timeout') {
+      sseLog.warn(
+        { id: conn.id, sid: conn.sessionId, route: conn.routeKey, ms: writeTimeoutMs() },
+        'sse write timed out — dropping the connection',
+      )
+      unregisterConnection(conn.id)
+      conn.close?.()
+    }
+    return outcome
+  } catch (err) {
+    // Bumped from debug to warn — silent push failures were why "30-50%
+    // delivery" was invisible in production logs.
+    sseLog.warn({ id: conn.id, sid: conn.sessionId, err: String(err) }, 'sse push failed')
+    return 'failed'
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+type Outcome = 'sent' | 'timeout' | 'failed'
+
 /**
  * Hang up every open connection — the shutdown path. A live response never ends
  * on its own, so `server.close()` cannot complete until these do; see
@@ -125,24 +274,31 @@ export function closeLiveConnections(): number {
 /**
  * After a state-changing dispatch settles, iterate every open connection
  * whose route's `reads:` intersects `touched`, recompute against that
- * connection's slot map, and push any resulting patches over its event
+ * connection's slot map, and queue any resulting patches on its event
  * stream. Recompute mutates the connection's `renderState.lastValue`s so
- * the next push is correctly diffed.
+ * the next push is correctly diffed. Returns as soon as everything is
+ * queued: no socket is awaited here, so a dispatch never waits on another
+ * page's network.
  *
  * Connections from any session receive pushes — that's the point: an
  * admin tab on session C sees updates triggered by session A's POSTs.
+ *
+ * `originatorQueued` tells the dispatch path whether the acting page's own
+ * patches were queued on its channel (because it already had a backlog)
+ * rather than left to the POST response. When true, the response must carry
+ * none, or the same positional list op lands twice.
  */
 export async function fanOut(
   touched: ReadonlySet<string>,
   source?: { sessionId?: string; originClientId?: string },
-): Promise<void> {
-  if (touched.size === 0 || connections.size === 0) return
+): Promise<{ originatorQueued: boolean }> {
+  if (touched.size === 0 || connections.size === 0) return { originatorQueued: false }
 
-  let pushedCount = 0
+  let enqueued = 0
   let skippedNoIntersect = 0
   let skippedNoPatches = 0
   let skippedOriginator = 0
-  let failed = 0
+  let originatorQueued = false
 
   // Expand through the reverse-reads graph once per fan-out: machines whose
   // SELECTORS derive from a touched machine must re-diff even though their
@@ -188,42 +344,43 @@ export async function fanOut(
       continue
     }
 
-    // The dispatching page's own connection: the POST response already
-    // delivered this diff. The recompute above advanced the baseline (so the
-    // NEXT push diffs correctly); sending would double-apply — and keyed
-    // insert/remove/move ops are not idempotent.
-    if (
+    // The dispatching page's own connection. With nothing queued for it, the
+    // POST response delivers this diff: the recompute above advanced the
+    // baseline (so the NEXT push diffs correctly) and sending would
+    // double-apply — keyed insert/remove/move ops are not idempotent. With a
+    // backlog, the response would overtake what is still queued, and a
+    // positional op applied out of order corrupts a list rather than merely
+    // staling it — so the diff rides the queue and the response carries none.
+    const isOriginator =
       source?.originClientId !== undefined &&
       conn.clientId !== undefined &&
       conn.clientId === source.originClientId
-    ) {
-      skippedOriginator++
-      continue
+    if (isOriginator) {
+      if (!hasBacklog(conn)) {
+        skippedOriginator++
+        continue
+      }
+      originatorQueued = true
     }
 
-    try {
-      await conn.send(JSON.stringify({ patches }))
-      pushedCount++
-    } catch (err) {
-      // Bumped from debug to warn — silent push failures were why "30-50%
-      // delivery" was invisible in production logs.
-      failed++
-      sseLog.warn({ id: conn.id, sid: conn.sessionId, err: String(err) }, 'sse push failed')
-    }
+    enqueue(conn, JSON.stringify({ patches }))
+    enqueued++
   }
 
   // Log every fan-out at debug so the user can see touched-machines flow and
-  // correlate against client-side inspector entries — noisy for prod, so debug.
+  // correlate against client-side inspector entries — noisy for prod, so
+  // debug. Write outcomes are logged by the drain loop as they happen.
   sseLog.debug(
     {
       touched: [...touched],
       total: connections.size,
-      pushed: pushedCount,
+      enqueued,
       skippedNoIntersect,
       skippedNoPatches,
       skippedOriginator,
-      failed,
+      originatorQueued,
     },
     'fan-out',
   )
+  return { originatorQueued }
 }

package/src/template/html-attributes.ts

@@ -94,6 +94,11 @@ export interface ElementSpecificAttributes {
     autofocus?: boolean
     accept?: string
     multiple?: boolean
+    /** Associates this element with a `<form>` elsewhere in the document by
+     *  id — the standard way to submit an element that can't live inside
+     *  the form's own DOM subtree (e.g. a per-row control alongside a
+     *  page-wide bulk-action form). `button` already carries this. */
+    form?: string
   }
   label: { for?: string }
   form: {
@@ -101,6 +106,11 @@ export interface ElementSpecificAttributes {
     method?: 'get' | 'post' | 'GET' | 'POST' | 'dialog'
     enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'
     novalidate?: boolean
+    /** Native inline event-handler attribute — a literal JS source string
+     *  (`"return confirm(...)"`), distinct from the `on:submit={...}`
+     *  Stator directive. Useful for a plain, no-hydration `confirm()`
+     *  guard that doesn't otherwise need an island. */
+    onsubmit?: string
   }
   select: {
     name?: string