@statorjs/stator 1.1.0 → 1.2.0

package/README.md

@@ -96,7 +96,7 @@ const [counter] = Stator.reads([Counter])
 </html>
 ```
 
-Run with `tsx server.ts`. See the repo's `apps/example` for the full wiring
+Run with `tsx server.ts`. See the repo's `examples/desksmith` for the full wiring
 (type sync, production build, deploy).
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Server-canonical web framework: business logic in composable state machines, UI as a thin renderer binding machine outputs to DOM positions. Ships TypeScript source (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -88,7 +88,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "1.1.0"
+    "@statorjs/stator": "1.2.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/server/api-route.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto'
 import type { Context } from 'hono'
 import { setCookie } from 'hono/cookie'
 import { scheduleSessionEffects } from './effects.ts'
@@ -13,7 +14,7 @@ import type {
   Directive,
   RouteRequest,
 } from './routing.ts'
-import { getOrCreateSessionId } from './session.ts'
+import { getOrCreateSessionId, setSessionCookie } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 import { fanOut } from './sse.ts'
@@ -42,6 +43,7 @@ export async function runApiRoute(
   params?: Record<string, string>,
 ): Promise<Response> {
   const { sessionId } = getOrCreateSessionId(c)
+  let rotation: { clear: boolean } | null = null
   const request = params
     ? { ...buildRouteRequest(c, discovered.paramNames), params }
     : buildRouteRequest(c, discovered.paramNames)
@@ -63,6 +65,12 @@ export async function runApiRoute(
           // The target machine is addressed by its def; read the name off it.
           const dispatchedTouched = runtime.processEvent(machine.name, event)
           for (const name of dispatchedTouched) touched.add(name)
+          // Same honesty as client dispatch: a guard-dropped event commits
+          // nothing, and handlers (login flows especially) need to know.
+          return { committed: dispatchedTouched.size > 0 }
+        },
+        rotateSession: (opts) => {
+          rotation = { clear: opts?.clear === true }
         },
       }
 
@@ -78,9 +86,32 @@ export async function runApiRoute(
         await runtime.persistTouched(touched)
         await fanOut(touched, { sessionId })
       }
+
+      // Session rotation (fixation defense). Order matters: the runtime has
+      // already persisted under the OLD id and fan-out has reached the old
+      // id's connections (about to be navigated away) — now the whole
+      // session moves (or, for logout, dies) and the response carries the
+      // new cookie. Effect completions must chase the NEW id.
+      let effectsSessionId = sessionId
+      if (rotation !== null) {
+        const newSessionId = randomUUID()
+        if ((rotation as { clear: boolean }).clear) {
+          await store.persistence.deleteSession(sessionId)
+        } else {
+          if (!store.persistence.renameSession) {
+            throw new Error(
+              'stator: rotateSession requires a store with renameSession — ' +
+                'the configured custom store does not implement it.',
+            )
+          }
+          await store.persistence.renameSession(sessionId, newSessionId)
+        }
+        setSessionCookie(c, newSessionId)
+        effectsSessionId = newSessionId
+      }
       // Effects queued by dispatched events run after this callback returns
       // (never under the session lock); see server/effects.ts.
-      scheduleSessionEffects(runtime, store, sessionId)
+      scheduleSessionEffects(runtime, store, effectsSessionId)
 
       // Escape hatch: handler returned a real Response. Pass through.
       if (result instanceof Response) return result

package/src/server/app-dispatch.ts

@@ -18,7 +18,7 @@ export async function dispatchToApp<D extends AnyMachineDef>(
   store: MachineStore,
   machine: D,
   event: EventOf<D>,
-): Promise<void> {
+): Promise<{ committed: boolean }> {
   const name = machine.name
   const handle = store.appInstance(name)
   if (!handle) {
@@ -46,6 +46,10 @@ export async function dispatchToApp<D extends AnyMachineDef>(
       await store.persistAppMachine(touchedName)
     }
     await fanOut(touched)
+    // Same contract as client and API-route dispatch: did the TARGET machine
+    // actually commit a transition? Webhook receivers use this to tell a
+    // processed event from a guard-dropped duplicate.
+    return { committed: touched.has(name) }
   } finally {
     runtime.dispose()
   }

package/src/server/banner.ts

@@ -40,12 +40,18 @@ function lanAddress(): string | undefined {
 
 export function printDevBanner(info: {
   port: number
+  /** The port originally asked for, when the server had to shift off it. */
+  requestedPort?: number
   machines: number
   routes: number
   inspector?: boolean
 }): void {
   const v = statorVersion()
   const lan = lanAddress()
+  const shifted =
+    info.requestedPort !== undefined && info.requestedPort !== info.port
+      ? [`  ${c.dim(`port ${info.requestedPort} was busy — using ${info.port}`)}`]
+      : []
   const lines = [
     '',
     `  ${c.copper(c.bold('stator'))}${v ? c.dim(` v${v}`) : ''}  ${c.dim('dev server')}`,
@@ -58,6 +64,7 @@ export function printDevBanner(info: {
         info.routes === 1 ? '' : 's'
       }${info.inspector ? ' · inspector on' : ''} — Ctrl+C to stop`,
     )}`,
+    ...shifted,
     '',
   ]
   process.stdout.write(`${lines.join('\n')}\n`)
@@ -88,3 +95,20 @@ export function installGracefulShutdown(close: () => Promise<void> | void, quiet
   process.on('SIGINT', handler)
   process.on('SIGTERM', handler)
 }
+
+/** First free TCP port at or above `start` (bounded probe). The dev plane
+ *  auto-shifts off busy ports like every modern dev server; production
+ *  never calls this — a taken port there is a deploy error to surface. */
+export async function findFreePort(start: number, attempts = 10): Promise<number> {
+  const { createServer } = await import('node:net')
+  for (let port = start; port < start + attempts; port++) {
+    const free = await new Promise<boolean>((resolve) => {
+      const probe = createServer()
+      probe.once('error', () => resolve(false))
+      probe.once('listening', () => probe.close(() => resolve(true)))
+      probe.listen(port)
+    })
+    if (free) return port
+  }
+  throw new Error(`stator: no free port found in ${start}–${start + attempts - 1}`)
+}

package/src/server/cached-store.ts

@@ -99,6 +99,20 @@ export class CachedStore implements Store {
     await this.backing.deleteSession(sid)
   }
 
+  async renameSession(oldSid: string, newSid: string): Promise<void> {
+    // Drop (don't move) cache entries — the next read repopulates from the
+    // backing under the new id. Simpler than key surgery, and rotation is
+    // rare (login/logout).
+    const prefix = `${oldSid}:`
+    for (const k of [...this.cache.keys()]) {
+      if (k.startsWith(prefix)) this.cache.delete(k)
+    }
+    if (!this.backing.renameSession) {
+      throw new Error('stator: CachedStore backing store does not support renameSession')
+    }
+    await this.backing.renameSession(oldSid, newSid)
+  }
+
   /** Insert / refresh an entry at LRU-end and evict oldest if over capacity. */
   private populate(key: string, snapshot: unknown, ttlMs: number): void {
     this.cache.delete(key)

package/src/server/create-app.ts

@@ -76,6 +76,18 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
           logger.info({ port, machines: defs.length, routes: routes.length }, 'listening')
           resolveFn()
         })
+        // Production is strict about its port (a collision is a deploy
+        // error) — but says so in one line, not a stack trace.
+        server.on('error', (err: NodeJS.ErrnoException) => {
+          if (err.code === 'EADDRINUSE') {
+            logger.error(
+              { port },
+              `port ${port} is already in use — is another instance running? (set PORT to change it)`,
+            )
+            process.exit(1)
+          }
+          throw err
+        })
         // Ctrl+C / SIGTERM (deploy rollover) exits 0, not 130 — quiet in
         // prod: the structured logs are the record.
         installGracefulShutdown(() => new Promise<void>((done) => server.close(() => done())), true)

package/src/server/dev.ts

@@ -7,7 +7,7 @@ import { createServer as createViteServer, type ViteDevServer } from 'vite'
 import { compile } from '../compiler/index.ts'
 import { machineStub, stator } from '../vite/index.ts'
 import type { AppStore } from './app-store.ts'
-import { installGracefulShutdown, printDevBanner } from './banner.ts'
+import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.ts'
 import { logger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
@@ -52,10 +52,14 @@ export interface DevApp {
 }
 
 export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
+  // Vite's HMR websocket defaults to 24678 for EVERY dev server — two
+  // stator apps side by side would fight over it (the loser's live reload
+  // silently dies). Probe a free one instead.
+  const hmrPort = await findFreePort(24678)
   const vite = await createViteServer({
     root: resolve(config.root),
     appType: 'custom',
-    server: { middlewareMode: true },
+    server: { middlewareMode: true, hmr: { port: hmrPort } },
     // machineStub keeps server machines out of browser module graphs: island
     // imports of a machine resolve to a `{ name }` stub (SSR loads are
     // untouched — `options.ssr` gates it).
@@ -199,12 +203,23 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
         await vite.close()
         await new Promise<void>((done) => server.close(() => done()))
       })
-      return new Promise((resolveFn) => {
-        server.listen(port, () => {
-          printDevBanner({ port, machines: machineCount, routes: routes.length, inspector: true })
-          resolveFn()
-        })
-      })
+      // Busy port? Shift up like every modern dev server (the requested
+      // port is someone's other project, not an error).
+      return findFreePort(port).then(
+        (freePort) =>
+          new Promise((resolveFn) => {
+            server.listen(freePort, () => {
+              printDevBanner({
+                port: freePort,
+                requestedPort: port,
+                machines: machineCount,
+                routes: routes.length,
+                inspector: true,
+              })
+              resolveFn()
+            })
+          }),
+      )
     },
     close: () => vite.close(),
   }

package/src/server/redis-store.ts

@@ -69,6 +69,14 @@ export class RedisStore implements Store {
     await this.client.del(this.key(sid))
   }
 
+  async renameSession(oldSid: string, newSid: string): Promise<void> {
+    // RENAME is atomic and carries the hash's TTL; it throws when the source
+    // is missing (an empty session has nothing to move — fine).
+    if ((await this.client.exists(this.key(oldSid))) === 1) {
+      await this.client.rename(this.key(oldSid), this.key(newSid))
+    }
+  }
+
   /** Close the connection. Call on graceful shutdown. */
   async close(): Promise<void> {
     await this.client.quit()

package/src/server/routing.ts

@@ -136,7 +136,18 @@ export interface ApiRouteHelpers {
    *  Processes the event under the dispatch context, persists touched machines,
    *  fires cross-machine subscriptions. The machine must be in the route's
    *  loaded graph (its `reads`, transitively). */
-  dispatch: <D extends AnyMachineDef>(machine: D, event: EventOf<D>) => Promise<void>
+  dispatch: <D extends AnyMachineDef>(
+    machine: D,
+    event: EventOf<D>,
+  ) => Promise<{ committed: boolean }>
+  /** Rotate the session id — the fixation defense for privilege changes.
+   *  Call on login (state moves to a fresh id; the old id becomes worthless
+   *  to anyone who captured it) and on logout with `{ clear: true }` (the
+   *  old session's state is DELETED and the browser starts anonymous).
+   *  Applied after the handler returns: state persists under the new id and
+   *  the response carries the new cookie. Requires a store with
+   *  `renameSession` (all built-in stores have it). */
+  rotateSession: (opts?: { clear?: boolean }) => void
 }
 
 export interface ApiRouteDefinition {

package/src/server/session.ts

@@ -12,6 +12,17 @@ function shouldUseSecureCookie(): boolean {
   return process.env.NODE_ENV === 'production'
 }
 
+/** Write the session cookie — shared by session creation and rotation so
+ *  the flags can never drift apart. */
+export function setSessionCookie(c: Context, sessionId: string): void {
+  setCookie(c, SESSION_COOKIE, sessionId, {
+    httpOnly: true,
+    sameSite: 'Lax',
+    path: '/',
+    secure: shouldUseSecureCookie(),
+  })
+}
+
 export function getOrCreateSessionId(c: Context): {
   sessionId: string
   isNew: boolean
@@ -19,11 +30,6 @@ export function getOrCreateSessionId(c: Context): {
   const existing = getCookie(c, SESSION_COOKIE)
   if (existing) return { sessionId: existing, isNew: false }
   const sessionId = randomUUID()
-  setCookie(c, SESSION_COOKIE, sessionId, {
-    httpOnly: true,
-    sameSite: 'Lax',
-    path: '/',
-    secure: shouldUseSecureCookie(),
-  })
+  setSessionCookie(c, sessionId)
   return { sessionId, isNew: true }
 }

package/src/server/store.ts

@@ -29,6 +29,10 @@ export interface Store {
   ): Promise<void>
   has(sessionId: string, machineName: string): Promise<boolean>
   deleteSession(sessionId: string): Promise<void>
+  /** Move EVERY machine snapshot from one session id to another (used by
+   *  session rotation on privilege change). Optional for custom adapters;
+   *  rotation fails loudly when the configured store lacks it. */
+  renameSession?(oldSessionId: string, newSessionId: string): Promise<void>
 }
 
 /**
@@ -92,4 +96,16 @@ export class InMemoryStore implements Store {
   async deleteSession(sid: string): Promise<void> {
     this.dropSession(sid)
   }
+
+  async renameSession(oldSid: string, newSid: string): Promise<void> {
+    if (this.isExpired(oldSid)) {
+      this.dropSession(oldSid)
+      return
+    }
+    const session = this.data.get(oldSid)
+    const expiry = this.expiryAt.get(oldSid)
+    this.dropSession(oldSid)
+    if (session) this.data.set(newSid, session)
+    if (expiry !== undefined) this.expiryAt.set(newSid, expiry)
+  }
 }