@statorjs/stator 2.10.0-next.1 → 2.11.0-next.0

package/src/server/dev-vite.ts

@@ -13,6 +13,7 @@ import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.
 import { resolveAppConfig } from './config-compat.ts'
 import type { DevApp, DevAppConfig } from './dev.ts'
 import { loadDotenv } from './env.ts'
+import { resolveImagesConfig } from './images.ts'
 import { logger, setLogLevel } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
@@ -73,6 +74,7 @@ export async function createViteDevApp(config: DevAppConfig): Promise<DevApp> {
   const loader = (file: string) => vite.ssrLoadModule(file) as Promise<Record<string, unknown>>
 
   const root = resolve(config.root)
+  const images = config.images ? resolveImagesConfig(config.images) : undefined
   const machinesDir = resolve(config.machinesDir)
   const routesDir = resolve(config.routesDir)
   const resolved = resolveAppConfig(config)
@@ -201,6 +203,7 @@ export async function createViteDevApp(config: DevAppConfig): Promise<DevApp> {
       routes,
       store,
       staticDir: config.staticDir,
+      images,
       headExtras,
       inspector: inspectorOn,
       inspect: true,

package/src/server/dev.ts

@@ -41,6 +41,20 @@ export interface DevAppConfig {
     cookie?: { sameSite?: 'Lax' | 'Strict' }
   }
   /** Dev-only tooling. */
+  /** Image serving — mirrors `StatorConfig.images`. */
+  images?: {
+    dir: string
+    path?: string
+    widths?: number[]
+    aspectRatios?: number[]
+    transformer?: import('./images.ts').ImageTransformer
+    concurrency?: number
+    threads?: number
+    encodeTimeoutMs?: number
+    maxAge?: number
+    staleWhileRevalidate?: number
+    immutable?: boolean
+  }
   dev?: {
     /** Auto-inject the dev inspector toolbar. On by default; set false to disable. */
     inspector?: boolean

package/src/server/http.ts

@@ -9,6 +9,7 @@ import { applyRenderedEffects, runApiRoute } from './api-route.ts'
 import { crossSiteGuard } from './csrf.ts'
 import { scheduleSessionEffects } from './effects.ts'
 import { record, replayFor } from './event-dedupe.ts'
+import { type ImagesRenderInfo, type ResolvedImagesConfig, serveImage } from './images.ts'
 import { buildInspectPayload } from './inspect.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
@@ -19,7 +20,14 @@ import { renderRoute } from './render.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
 import { buildRouteRequest } from './route-request.ts'
 import { isStatorQueryRoute, type RouteDefinition } from './routing.ts'
-import { CLAIMS_KEY, getOrCreateSessionId, getSessionState } from './session.ts'
+import {
+  CLAIMS_KEY,
+  getOrCreateSessionId,
+  getSessionState,
+  peekSessionId,
+  resumeSession,
+  sessionUse,
+} from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 import { enqueue, fanOut, registerConnection, unregisterConnection } from './sse.ts'
@@ -30,6 +38,9 @@ export interface HttpConfig {
   routes: DiscoveredRoute[]
   store: MachineStore
   staticDir?: string
+  /** Resolved image-serving config — present mounts the endpoint at
+   *  `images.path` (see server/images.ts). */
+  images?: ResolvedImagesConfig
   /** Optional hook to inject extra `<head>` HTML for a GET route, keyed by the
    *  route's file path. The dev server uses this to inline collected scoped CSS
    *  (SSR head injection). Inserted at the `</head>` boundary. */
@@ -64,8 +75,18 @@ export interface HttpConfig {
   /** The app's discovered `middleware.ts` definition (if any). `withDefaults`
    *  controls whether the framework security stack is prepended. */
   middleware?: MiddlewareDefinition
+  /** Layer-3 derived Cache-Control: emitted on GET responses the framework can
+   *  PROVE anonymous-identical (no session reads declared, no session use or
+   *  claims read while handling, nothing hand-set). Absent → never emitted
+   *  (the dev servers leave it off so editing always re-renders). */
+  caching?: { sMaxAge: number; staleWhileRevalidate: number }
 }
 
+/** Placeholder sid for session-free page renders — `loadGraph` loads only
+ *  session-lifecycle machines, so on app-only routes this never reaches the
+ *  store; it exists to keep SessionRuntime's signature honest. */
+const ANONYMOUS_SID = '@anonymous'
+
 const eventSchema = z.object({
   machine: z.string(),
   event: z
@@ -113,14 +134,20 @@ function compileMatcher(route: DiscoveredRoute): RouteMatcher {
   return { route, regex: new RegExp(`^${pattern}$`) }
 }
 
+/** One matcher's result against a literal path: the route plus its
+ *  extracted path params. */
+interface PathMatch {
+  route: DiscoveredRoute
+  params: Record<string, string>
+}
+
 /**
- * Match a literal URL path against compiled matchers. Returns the matched
- * route + extracted params, or null if nothing matches.
+ * Match a literal URL path against every compiled matcher that matches it,
+ * in `matchers`' own (priority-sorted) order — every candidate a 404-
+ * cascading GET dispatch might need to try, not just the first.
  */
-function matchPath(
-  matchers: RouteMatcher[],
-  literalPath: string,
-): { route: DiscoveredRoute; params: Record<string, string> } | null {
+function matchAllPaths(matchers: RouteMatcher[], literalPath: string): PathMatch[] {
+  const matches: PathMatch[] = []
   for (const m of matchers) {
     const result = m.regex.exec(literalPath)
     if (!result) continue
@@ -128,9 +155,65 @@ function matchPath(
     m.route.paramNames.forEach((name, i) => {
       params[name] = decodeURIComponent(result[i + 1] ?? '')
     })
-    return { route: m.route, params }
+    matches.push({ route: m.route, params })
   }
-  return null
+  return matches
+}
+
+/**
+ * Match a literal URL path against compiled matchers. Returns the FIRST
+ * matched route + extracted params, or null if nothing matches — for call
+ * sites resolving an already-known route key (the SSE/event endpoints),
+ * where there is exactly one right answer and no cascading question.
+ */
+function matchPath(matchers: RouteMatcher[], literalPath: string): PathMatch | null {
+  return matchAllPaths(matchers, literalPath)[0] ?? null
+}
+
+/** True when any segment of a urlPath is a rest/catch-all (`*name`). */
+function isRestPattern(urlPath: string): boolean {
+  return urlPath.split('/').some((seg) => seg.startsWith('*'))
+}
+
+/** True when any segment of a urlPath is a suffixed param (`:name.ext`) —
+ *  the file-extension-routing pattern (`[id].json.ts` → `/p/:id.json`). */
+function isSuffixedParamPattern(urlPath: string): boolean {
+  return urlPath.split('/').some((seg) => seg.startsWith(':') && seg.includes('.'))
+}
+
+/**
+ * Candidates a 404-cascading GET dispatch may actually try, in priority
+ * order.
+ *
+ * Two matches can structurally overlap for one literal URL in ways that
+ * were never meant to form a "try something more general" chain:
+ *
+ *   - A suffixed param (`/p/:id.json`, from `[id].json.ts`) and its bare
+ *     sibling (`/p/:id`) — `compileMatcher`'s bare `:id` regex doesn't
+ *     exclude dots, so both structurally match `/p/abc.json`. The suffix
+ *     is the author's own explicit, dedicated handler for exactly that
+ *     extension (`sortRoutes`'s own doc comment: "so `/p/:id.json` wins
+ *     `/p/abc.json` before `/p/:id` can swallow it") — nothing ranked
+ *     below it, bare OR rest, is a MORE correct answer than what was
+ *     written on purpose for this exact case. (A rest/catch-all can't
+ *     even carry a suffix of its own — `filePathToRoute` rejects
+ *     `[...name].ext` outright — so it's exactly as wrong a fallback here
+ *     as bare is: confirmed against a real app, examples/live-poll's
+ *     `/p/:id.json` data route + `/p/:id` HTML page pair, where a 404
+ *     from the JSON route cascading into the page handed back HTML for a
+ *     request that explicitly asked for JSON.) So a winning suffixed
+ *     match is unconditionally terminal — no cascading at all, into
+ *     anything, once it's the one that matched.
+ *   - Anything bare/static vs. a rest/catch-all IS a legitimate fallback
+ *     chain (`routes/media/[...path].ts`, this feature's original
+ *     motivating case) — a catch-all stays cascade-eligible unless the
+ *     winning match was itself suffixed.
+ */
+function cascadeCandidates<T extends PathMatch>(all: T[]): T[] {
+  if (all.length === 0) return all
+  const winner = all[0]!
+  if (isSuffixedParamPattern(winner.route.urlPath)) return [winner]
+  return [winner, ...all.slice(1).filter((m) => isRestPattern(m.route.urlPath))]
 }
 
 /** Parse a route key like "GET /p/abc-123" into method + literal path. */
@@ -154,6 +237,11 @@ function parseRouteKey(
 
 export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
   const app = new Hono()
+  // Render-side view of the images config: `<Image>`/`<Picture>` read this
+  // from the render state so their URLs can't drift from the endpoint.
+  const imagesInfo = config.images
+    ? { widths: config.images.widths, aspectRatios: config.images.aspectRatios }
+    : undefined
   const clientJs = await bundleClient()
 
   // Request logger: one line per request with method, path, status, duration.
@@ -179,10 +267,13 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
   })
 
   // Context bridge — expose resolved config to every middleware (cors, app
-  // middleware) that follows, off `stator(c)`. Runs first. Also establishes the
-  // session once and eager-loads its claims (for a returning session), so the
-  // whole request shares one sid + claims snapshot; dirty claims persist at the
-  // end, to the current (possibly rotated) sid.
+  // middleware) that follows, off `stator(c)`. Runs first. Sessions are LAZY
+  // (the cacheable-read-path layer 1): an arriving cookie RESUMES its session
+  // (claims eager-loaded, no cookie write), but first contact establishes
+  // nothing — creation happens only at a dispatch, a session-machine read, an
+  // SSE connect, or an explicit session op. Anonymous reads therefore carry
+  // no Set-Cookie and stay CDN-cacheable. Dirty claims persist at the end,
+  // to the current (possibly rotated or just-established) sid.
   app.use('*', async (c, next) => {
     c.set('stator', {
       origin: config.origin,
@@ -194,14 +285,15 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     c.set('statorStore', config.store)
     // Stash the signing key so the cookie jar's signed methods can reach it.
     if (config.secret !== undefined) c.set('statorSecret', config.secret)
-    const { sessionId, isNew } = getOrCreateSessionId(c)
-    const session = getSessionState(c)
-    if (!isNew && session) {
-      session.claims = (await config.store.persistence.get(sessionId, CLAIMS_KEY)) ?? undefined
+    sessionUse(c)
+    const resumed = resumeSession(c)
+    if (resumed) {
+      resumed.claims = (await config.store.persistence.get(resumed.sid, CLAIMS_KEY)) ?? undefined
     }
     await next()
-    // Same session object (rotation mutates `.sid` in place), so persist to the
-    // current — possibly rotated — id.
+    // Re-read: the session may have been established mid-request. Rotation
+    // mutates `.sid` in place, so this persists to the current id.
+    const session = getSessionState(c)
     if (session?.claimsDirty) {
       await config.store.persistence.set(session.sid, CLAIMS_KEY, session.claims, {
         ttlSeconds: config.store.sessionTtlSeconds,
@@ -260,7 +352,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       const payload = await buildInspectPayload({
         store: config.store,
         routes: config.routes,
-        sessionId: getSessionState(c)?.sid,
+        // Inspecting IS session use — the route shows the caller's own
+        // session, so establish one for a first-contact dev visit.
+        sessionId: getOrCreateSessionId(c).sessionId,
         buildId: config.buildId,
       })
       c.header('Cache-Control', 'no-cache')
@@ -323,6 +417,25 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     })
   }
 
+  if (config.images) {
+    const images = config.images
+    app.get(`${images.path}/*`, (c) => {
+      let rel: string
+      try {
+        rel = decodeURIComponent(c.req.path.slice(images.path.length + 1))
+      } catch {
+        return c.text('not found', 404) // malformed percent-encoding is a 404, not a 500
+      }
+      return serveImage(
+        images,
+        rel,
+        c.req.query('w'),
+        c.req.query('h'),
+        c.req.header('if-none-match') ?? null,
+      )
+    })
+  }
+
   // SSE endpoint. The connection's runtime + renderState stay alive for
   // the connection's lifetime — this is the one place per-session state
   // outlives a request, because the connection *is* one (very long) request.
@@ -375,7 +488,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
 
       const runtime = new SessionRuntime(sessionId, config.store)
       await runtime.loadGraph(route.reads)
-      const { renderState } = await renderRoute(route, routeKey, sessionId, runtime, request)
+      const { renderState } = await renderRoute(route, routeKey, sessionId, runtime, request, {
+        images: imagesInfo,
+      })
 
       // The handler parks on `finished` until the connection ends. Both ways
       // out resolve it: the client aborting, and the server hanging up on a
@@ -531,6 +646,7 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         // resolve defer slots here (that would kick their I/O under the lock).
         const { renderState } = await renderRoute(route, routeKey, sessionId, runtime, request, {
           resolveDeferred: false,
+          images: imagesInfo,
         })
 
         const touched = runtime.processEvent(body.machine, body.event)
@@ -591,24 +707,62 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     })
   }
 
+  // 404 cascades by default: a matched GET route that 404s doesn't
+  // permanently claim the path — a lower-priority `[...name]`/`404`
+  // catch-all (if one exists) gets a turn, same priority order `matchers`
+  // is already sorted in. Only once every candidate 404s does the LAST
+  // (lowest-priority) one's response actually go out — so a route's own
+  // not-found body/headers/status still reach the client, this just stops
+  // the FIRST match from being final when a catch-all could actually
+  // serve it. `cascadeCandidates` (not the full `matchAllPaths` list) is
+  // what narrows "the next matching route" to specifically mean a
+  // catch-all — see its own doc comment for why that boundary matters.
   app.get('*', async (c, next) => {
-    const matched = matchPath(matchers, c.req.path)
-    if (!matched?.route.GET) return next()
-    const getRoute = matched.route.GET
-    // Brand decides the GET plane: data routes never touch the HTML path
-    // (no client-runtime injection, no live meta — a raw Response out).
-    if (isStatorQueryRoute(getRoute)) {
-      return runQueryRoute(c, matched.route, getRoute, config.store, matched.params)
-    }
-    return handleGet(
-      c,
-      matched.route,
-      getRoute,
-      matched.params,
-      config.store,
-      config.headExtras,
-      config.buildId,
+    const candidates = cascadeCandidates(
+      matchAllPaths(matchers, c.req.path).filter(
+        (
+          m,
+        ): m is PathMatch & {
+          route: DiscoveredRoute & { GET: NonNullable<DiscoveredRoute['GET']> }
+        } => !!m.route.GET,
+      ),
     )
+    if (candidates.length === 0) return next()
+
+    let lastNotFound: (() => Response) | undefined
+    for (const matched of candidates) {
+      const getRoute = matched.route.GET
+      // Brand decides the GET plane: data routes never touch the HTML path
+      // (no client-runtime injection, no live meta — a raw Response out).
+      if (isStatorQueryRoute(getRoute)) {
+        const response = await runQueryRoute(
+          c,
+          matched.route,
+          getRoute,
+          config.store,
+          matched.params,
+          config.caching,
+        )
+        if (response.status !== 404) return response
+        lastNotFound = () => response
+        continue
+      }
+
+      const candidate = await renderGetCandidate(
+        c,
+        matched.route,
+        getRoute,
+        matched.params,
+        config.store,
+        config.headExtras,
+        config.buildId,
+        config.caching,
+        imagesInfo,
+      )
+      if (candidate.status !== 404) return candidate.commit()
+      lastNotFound = candidate.commit
+    }
+    return lastNotFound ? lastNotFound() : next()
   })
 
   return app
@@ -672,7 +826,24 @@ function injectIntoDocument(html: string, parts: { head?: string; bodyEnd?: stri
   return out
 }
 
-async function handleGet(
+/** A rendered GET candidate, not yet committed to the shared Hono `Context`.
+ *  Cascading (see `matchAllPaths`/the GET dispatch loop) speculatively tries
+ *  several routes for one path — `applyRenderedEffects` writes headers,
+ *  cookies, and status directly onto `c`, cumulatively, so calling it for a
+ *  candidate that turns out to 404 would leak into whatever candidate wins
+ *  next (worse: `applyRenderedEffects` only calls `c.status(...)` when the
+ *  status isn't 200, so a losing 404 candidate followed by a winning 200 one
+ *  would ship 200 content under a stale 404 status — confirmed the hard way
+ *  designing this). Splitting render (safe to call speculatively, side-effect
+ *  free on `c`) from commit (writes to `c`, only ever called once, for
+ *  whichever candidate the dispatch loop actually decided to serve) is what
+ *  makes cascading safe. */
+interface GetCandidate {
+  status: number
+  commit: () => Response
+}
+
+async function renderGetCandidate(
   c: Context,
   discovered: DiscoveredRoute,
   route: RouteDefinition,
@@ -680,64 +851,101 @@ async function handleGet(
   store: MachineStore,
   headExtras?: (filePath: string) => string | Promise<string>,
   buildId?: string,
-): Promise<Response> {
-  {
-    const { sessionId } = getOrCreateSessionId(c)
-    const literalPath = c.req.path
-    const routeKey = `GET ${literalPath}`
-    const request = { ...buildRouteRequest(c, discovered.paramNames), params }
-
-    const runtime = new SessionRuntime(sessionId, store)
-    try {
-      await runtime.loadGraph(route.reads)
-      const result = await renderRoute(route, routeKey, sessionId, runtime, request)
-      let html = result.html
-
-      const headHtml: string[] = []
-      if (headExtras) {
-        const extra = await headExtras(discovered.filePath)
-        if (extra) headHtml.push(extra)
-      }
-      if (route.live) {
-        headHtml.push('<meta name="stator-live" content="true">')
-        // The build this page was rendered against — the client echoes it on
-        // /__sse connect so the server can reload a page from a stale build.
-        // `buildId` is a framework-generated UUID (no HTML-special chars).
-        if (buildId) {
-          headHtml.push(`<meta name="stator-build" content="${buildId}">`)
-        }
+  caching?: { sMaxAge: number; staleWhileRevalidate: number },
+  images?: ImagesRenderInfo,
+): Promise<GetCandidate> {
+  // Lazy layer 1: only a session-machine read forces establishment. An
+  // app-only (or read-free) page renders against the resumed sid when a
+  // cookie arrived, or an inert placeholder — loadGraph loads session
+  // machines only, so the placeholder never reaches the store.
+  const needsSession = route.reads.some((def) => def.lifecycle === 'session')
+  const sessionId = needsSession
+    ? getOrCreateSessionId(c).sessionId
+    : (peekSessionId(c) ?? ANONYMOUS_SID)
+  const literalPath = c.req.path
+  const routeKey = `GET ${literalPath}`
+  const request = { ...buildRouteRequest(c, discovered.paramNames), params }
+
+  const runtime = new SessionRuntime(sessionId, store)
+  try {
+    await runtime.loadGraph(route.reads)
+    const result = await renderRoute(route, routeKey, sessionId, runtime, request, { images })
+    let html = result.html
+
+    const headHtml: string[] = []
+    if (headExtras) {
+      const extra = await headExtras(discovered.filePath)
+      if (extra) headHtml.push(extra)
+    }
+    if (route.live) {
+      headHtml.push('<meta name="stator-live" content="true">')
+      // The build this page was rendered against — the client echoes it on
+      // /__sse connect so the server can reload a page from a stale build.
+      // `buildId` is a framework-generated UUID (no HTML-special chars).
+      if (buildId) {
+        headHtml.push(`<meta name="stator-build" content="${buildId}">`)
       }
+    }
 
-      // Auto-inject the client runtime (delegated events + patch application).
-      // Apps never hand-include it — a forgotten <script> is a silently dead
-      // page (events fire nothing, no patches apply). Idempotent: skipped if the
-      // document already references it, so a layout that still carries the tag
-      // (or two passes sharing a doc) never loads it twice.
-      const bodyHtml: string[] = []
-      if (!html.includes('/static/client.js')) {
-        bodyHtml.push('<script src="/static/client.js"></script>')
-      }
+    // Auto-inject the client runtime (delegated events + patch application).
+    // Apps never hand-include it — a forgotten <script> is a silently dead
+    // page (events fire nothing, no patches apply). Idempotent: skipped if the
+    // document already references it, so a layout that still carries the tag
+    // (or two passes sharing a doc) never loads it twice.
+    const bodyHtml: string[] = []
+    if (!html.includes('/static/client.js')) {
+      bodyHtml.push('<script src="/static/client.js"></script>')
+    }
 
-      html = injectIntoDocument(html, {
-        head: headHtml.join(''),
-        bodyEnd: bodyHtml.join(''),
-      })
-      applyRenderedEffects(c, result.response)
-
-      // A fresh machine that fired its initial entry effect on load must be
-      // persisted (so the next request hydrates instead of re-firing) and its
-      // effect scheduled off-lock, after the response. The common GET (no entry
-      // effect) skips both and stays a pure read.
-      const entryFired = runtime.entryFiredMachines()
-      if (entryFired.size > 0) {
-        await runtime.persistTouched(entryFired)
-        scheduleSessionEffects(runtime, store, sessionId)
-      }
+    html = injectIntoDocument(html, {
+      head: headHtml.join(''),
+      bodyEnd: bodyHtml.join(''),
+    })
+
+    // Fired regardless of whether this candidate ends up winning: an entry
+    // effect firing is a fact about the MACHINE having been loaded for the
+    // first time (shared, cross-cutting state), not about which route's
+    // response the caller ultimately serves — a discarded losing candidate
+    // still genuinely loaded whatever it read.
+    const entryFired = runtime.entryFiredMachines()
+    if (entryFired.size > 0) {
+      await runtime.persistTouched(entryFired)
+      scheduleSessionEffects(runtime, store, sessionId)
+    }
 
-      return c.html(html)
-    } finally {
-      runtime.dispose()
+    // Layer 3 — derived Cache-Control: the page is PROVABLY anonymous-
+    // identical (no session reads declared, no session use or claims read
+    // during handling) and the route didn't hand-set the header. The
+    // framework says what it can prove; hand-set always wins. Computed here
+    // but only ever WRITTEN from `commit`, below — this render may be a
+    // losing, discarded candidate under cascading, and only the winner's
+    // headers may reach `c` (the same reason `applyRenderedEffects` is
+    // deferred to `commit` rather than called here).
+    const use = sessionUse(c)
+    const deriveCacheControl =
+      !!caching &&
+      !needsSession &&
+      !use.used &&
+      !use.claimsRead &&
+      result.response.status < 300 &&
+      result.response.cookies.length === 0 &&
+      !result.response.headers.has('cache-control')
+
+    return {
+      status: result.response.status,
+      commit: () => {
+        applyRenderedEffects(c, result.response)
+        if (deriveCacheControl) {
+          c.header(
+            'Cache-Control',
+            `public, max-age=0, s-maxage=${caching!.sMaxAge}, stale-while-revalidate=${caching!.staleWhileRevalidate}`,
+          )
+        }
+        return c.html(html)
+      },
     }
+  } finally {
+    runtime.dispose()
   }
 }