on-zero 0.6.3 → 0.6.4

package/lint/ssr-guards.js

@@ -0,0 +1,164 @@
+/**
+ * canonical oxlint plugin for zero model SSR guards — shipped WITH on-zero so
+ * every consumer references ONE source instead of copying it. add it as a
+ * jsPlugins entry in the consumer's .oxlintrc.json.
+ *
+ * it enforces on-zero's own footgun contract: run() and
+ * server.asyncTasks.push() must appear only inside a tree-shakeable
+ * `if (process.env.VITE_ENVIRONMENT === 'ssr')` block, never in the
+ * non-tree-shakeable `!== 'ssr'` early-return form.
+ *
+ * valid guards (tree-shakeable):
+ * - if (isSSR) { ... }              — `typeof window === 'undefined'` constant
+ * - if (process.env.VITE_ENVIRONMENT === 'ssr') { ... }  — legacy
+ *
+ * `if (server)` is NOT valid because it doesn't tree-shake.
+ */
+
+function isEnvSSRCheck(node) {
+  if (!node) return false
+
+  // process.env.VITE_ENVIRONMENT === 'ssr'
+  if (node.type === 'BinaryExpression' && node.operator === '===') {
+    const left = node.left
+    const right = node.right
+    if (
+      left.type === 'MemberExpression' &&
+      left.object?.type === 'MemberExpression' &&
+      left.object?.object?.name === 'process' &&
+      left.object?.property?.name === 'env' &&
+      left.property?.name === 'VITE_ENVIRONMENT' &&
+      right.type === 'Literal' &&
+      right.value === 'ssr'
+    ) {
+      return true
+    }
+  }
+
+  // check compound conditions: if (x && isSSR)
+  if (node.type === 'LogicalExpression' && node.operator === '&&') {
+    return isEnvSSRCheck(node.left) || isEnvSSRCheck(node.right)
+  }
+
+  return false
+}
+
+function isSSRGuard(node) {
+  if (node.type !== 'IfStatement') return false
+  return isEnvSSRCheck(node.test)
+}
+
+function isModelFile(filename) {
+  return (
+    filename.includes('/data/mutations/') &&
+    !filename.includes('/data/mutations/helpers/')
+  )
+}
+
+// detect: if (process.env.VITE_ENVIRONMENT !== 'ssr') return
+function isSSREarlyReturn(node) {
+  if (node.type !== 'IfStatement') return false
+  const test = node.test
+  if (
+    test.type === 'BinaryExpression' &&
+    test.operator === '!==' &&
+    test.left?.type === 'MemberExpression' &&
+    test.left?.object?.type === 'MemberExpression' &&
+    test.left?.object?.object?.name === 'process' &&
+    test.left?.object?.property?.name === 'env' &&
+    test.left?.property?.name === 'VITE_ENVIRONMENT' &&
+    test.right?.type === 'Literal' &&
+    test.right?.value === 'ssr'
+  ) {
+    const body =
+      node.consequent.type === 'BlockStatement' ? node.consequent.body : [node.consequent]
+    return body.some((s) => s.type === 'ReturnStatement')
+  }
+  return false
+}
+
+function createSSRGuardRule(matchCallee, messageId, message) {
+  return {
+    meta: {
+      type: 'problem',
+      messages: { [messageId]: message },
+    },
+    create(context) {
+      const filename = context.filename || context.getFilename()
+      if (!isModelFile(filename)) return {}
+
+      let isServerOnly = false
+      let guardDepth = 0
+
+      return {
+        ImportDeclaration(node) {
+          if (node.source.value === 'server-only') {
+            isServerOnly = true
+          }
+        },
+        IfStatement(node) {
+          if (isSSRGuard(node)) guardDepth++
+        },
+        'IfStatement:exit'(node) {
+          if (isSSRGuard(node)) guardDepth--
+        },
+        CallExpression(node) {
+          if (isServerOnly) return
+          if (matchCallee(node) && guardDepth === 0) {
+            context.report({ node, messageId })
+          }
+        },
+      }
+    },
+  }
+}
+
+const runCallRule = createSSRGuardRule(
+  (node) => node.callee.type === 'Identifier' && node.callee.name === 'run',
+  'missingGuard',
+  'run() is a footgun on client, must be inside `if (process.env.VITE_ENVIRONMENT === "ssr")`',
+)
+
+const asyncTasksRule = createSSRGuardRule(
+  (node) => {
+    const callee = node.callee
+    return (
+      callee.type === 'MemberExpression' &&
+      callee.property?.name === 'push' &&
+      callee.object?.type === 'MemberExpression' &&
+      callee.object?.property?.name === 'asyncTasks'
+    )
+  },
+  'missingGuard',
+  'server.asyncTasks.push must be inside `if (process.env.VITE_ENVIRONMENT === "ssr")`',
+)
+
+const noEarlyReturnRule = {
+  meta: {
+    type: 'problem',
+    messages: {
+      noEarlyReturn:
+        'Use `if (process.env.VITE_ENVIRONMENT === "ssr") { ... }` block, not `!== "ssr"` early return',
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (!isModelFile(filename)) return {}
+    return {
+      IfStatement(node) {
+        if (isSSREarlyReturn(node)) {
+          context.report({ node, messageId: 'noEarlyReturn' })
+        }
+      },
+    }
+  },
+}
+
+export default {
+  meta: { name: 'ssr-guards' },
+  rules: {
+    'run-call': runCallRule,
+    'async-tasks': asyncTasksRule,
+    'no-early-return': noEarlyReturnRule,
+  },
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "on-zero",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "A typed layer over @rocicorp/zero with queries, mutations, and permissions",
   "sideEffects": false,
   "source": "src/index.ts",
@@ -83,7 +83,7 @@
     }
   },
   "dependencies": {
-    "@take-out/helpers": "0.6.3",
+    "@take-out/helpers": "0.6.4",
     "chokidar": "^4.0.3",
     "citty": "^0.1.6",
     "valibot": "^1.1.0"

package/readme.md

@@ -578,6 +578,26 @@ constraints:
 - the server stays single: one `createZeroServer` per backend process.
 - omitting `instanceName` keeps the exact single-instance behavior.
 
+**guarding the partition against drift.** a generated namespace that ends up in
+NEITHER instance's split silently un-registers its queries (a `useQuery` then
+throws "query not registered" at runtime, error-boundarying a whole screen). run
+`assertZeroInstancePartition` at module eval over each split so the drift is a
+boot throw instead — it also catches a namespace listed in more than one
+partition:
+
+```ts
+import { assertZeroInstancePartition } from 'on-zero/multi'
+
+assertZeroInstancePartition('query namespace', groupedQueries, {
+  control: controlQueries,
+  project: projectQueries,
+})
+assertZeroInstancePartition('model namespace', models, {
+  control: controlModels,
+  project: projectModels,
+})
+```
+
 ### server validation hooks
 
 add custom validation for all queries and mutations:
@@ -748,6 +768,112 @@ import { ensureAuth } from 'on-zero'
 const auth = ensureAuth() // AuthData (throws if not authenticated)
 ```
 
+## recovery
+
+on-zero self-heals a client whose local sync state is lost or rejected. this is
+**on by default** — a consumer that passes nothing gets the full behavior. the
+hooks below let you compose ONE extra behavior (gate the reload, reload
+natively, drop a benign log, refresh auth) without re-implementing the stack.
+
+### what's on by default
+
+`ProvideZero` installs Zero's `onUpdateNeeded` / `onClientStateNotFound` and a
+log sink that watches for the fatal store-loss / desync signatures. on a match it
+drops the affected instance's local store and reloads the page ONCE. this covers:
+
+- **update-needed** — `SchemaVersionNotSupported` (drops local state, the rows
+  are now incompatible), `NewClientGroup` / `VersionNotSupported` (reload
+  without dropping, so a sibling tab's shared IndexedDB survives).
+- **client-state-not-found** — the store is unusable; drop it and reload.
+- **log-only fatals** — `Expected IndexedDB not found`, native sqlite
+  `This statement has been finalized`, and repeated `Store is closed`.
+- **the mutation/connection desync class** — `sent mutation ID … but expected`,
+  `oooMutation`, `already processed`, `InvalidConnectionRequestBaseCookie` /
+  `…LastMutationID`, `ClientNotFound`, `connection userID mismatch`. these
+  surface only through the error log, so the log sink recovers on them too.
+
+genuinely app-infra signatures (your own synthesized ack-timeout marker, a
+cold-boot connect timeout) are NOT in this list — keep those app-side and use
+`benignLogFilter` to stop them from tripping recovery.
+
+### the hooks (all optional props on `ProvideZero`)
+
+- **`scheduleReload?: (ctx) => void`** — take over WHEN/HOW the recovery reload
+  happens. `ctx = { reason, reasonKey, dropLocalState, performReload }`. the
+  default is an immediate reload; inject this to gate it (only reload when the
+  user is on a safe surface), show a countdown toast, or reload natively —
+  then call `ctx.performReload()` to run the real deletes-then-reload work. the
+  store delete is deferred until `performReload` runs, so a gated reload never
+  leaves the app on an already-deleted store. `performReload` is idempotent.
+
+  ```tsx
+  // native (expo): reload the bundle instead of location.reload()
+  <ProvideZero
+    scheduleReload={(ctx) => {
+      void ctx
+        .performReload()
+        .then(() => Updates.reloadAsync())
+        .catch(() => DevSettings.reload())
+    }}
+    …
+  />
+  ```
+
+- **`beforeReload?: () => Promise<void>`** — awaited right before the reload
+  (e.g. wait for the dev origin to come back so the reload doesn't hit a
+  restarting server). composes with `scheduleReload`.
+
+- **`benignLogFilter?: (message) => boolean`** — return `true` for a classified
+  recovery log you want treated as benign so it does NOT recover (your app's
+  cold-boot timeout, say). only affects recovery; the log still reaches the sink.
+
+- **`refreshAuth?: () => Promise<string | undefined>`** — called when the
+  connection enters `needs-auth` (an expired token). return a fresh token and
+  on-zero reconnects in place — no reload. fires once per needs-auth transition.
+
+- **`guardStorage?: { getItem, setItem }`** — the loop-guard's cross-reload
+  backing store. defaults to `sessionStorage` on web; inject a native KV
+  (MMKV/sqlite) on Hermes so native gets real cross-reload loop protection.
+
+- **`connectionDataset?: boolean`** — mirror this instance's connection state
+  onto `document.body.dataset.zero*` (`zeroState`, `zeroConnected`,
+  `zeroReason`, `zeroCacheUrl`) for e2e/diagnostics. enable on ONE instance so
+  multiple instances don't clobber the dataset.
+
+### guard + latch semantics
+
+- a **per-reason guard** (60s window) means the SAME reason re-failing right
+  after its reload is surfaced as `fatal` instead of reload-storming; distinct
+  reasons never suppress each other. it's two-tier: an in-memory map (real loop
+  protection within a page-load, works on Hermes) plus the cross-reload
+  `guardStorage` (survives the reload to catch an immediate re-fire).
+- a **one-reload latch** means every affected instance of a combined client
+  drops its own store but only ONE reload fires. the latch **times out** (15s)
+  so a reload that never lands (a gated/native reload, a failed `reload()`)
+  can't kill recovery for the rest of the page's life.
+
+### remint — in-place recovery without a reload
+
+`createZeroClient` returns **`remint(opts?)`** — the supported, native-safe
+recovery path (a reload may never land on prod native, wedging the latch).
+it drops the current instance's local store (unless `dropLocalState: false`) and
+reconstructs a fresh Zero client in place, no page reload. it is rate-guarded
+in-memory (12s between mints, 5 attempts before backing off, reset after 60s
+stable) and returns `false` when suppressed. route your own
+`onClientStateNotFound` to it if you need in-place recovery:
+
+```tsx
+const { remint, ProvideZero } = createZeroClient({ … })
+<ProvideZero onClientStateNotFound={() => { void remint() }} … />
+```
+
+### stale-poke resume (automatic)
+
+a recoverable stale-cookie / stale-poke error (`Server returned unexpected base
+cookie during sync`; `Received cookie … is < than last snapshot cookie … ignoring
+client view`) is generic Zero behavior — on-zero's connection monitor reconnects
+instead of surfacing a fatal error, deduped per reason. no configuration.
+
 ## patterns
 
 **server-only mutations:**

package/src/createZeroClient.connection.test.tsx

@@ -0,0 +1,162 @@
+// @vitest-environment jsdom
+
+import { createSchema, string, table } from '@rocicorp/zero'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, expect, test, vi } from 'vitest'
+
+// a controllable connection whose state useConnectionState (useSyncExternalStore)
+// subscribes to — set() notifies listeners so ConnectionMonitor's effect re-runs.
+const fakeZero = vi.hoisted(() => {
+  class FakeConnectionState {
+    current: { name: string; reason?: string }
+    listeners = new Set<() => void>()
+    constructor(initial: { name: string; reason?: string }) {
+      this.current = initial
+    }
+    subscribe = (cb: () => void) => {
+      this.listeners.add(cb)
+      return () => {
+        this.listeners.delete(cb)
+      }
+    }
+    set(next: { name: string; reason?: string }) {
+      this.current = next
+      for (const cb of this.listeners) cb()
+    }
+  }
+
+  class FakeZero {
+    readonly context = {}
+    readonly connection = {
+      state: new FakeConnectionState({ name: 'connecting' }),
+      connect: vi.fn(async () => {}),
+    }
+    readonly delete = vi.fn(async () => ({ errors: [] }))
+    readonly close = vi.fn()
+    readonly run = vi.fn(async () => [])
+    readonly preload = vi.fn(() => ({ cleanup: () => {}, complete: Promise.resolve() }))
+
+    constructor() {
+      instances.push(this)
+    }
+  }
+
+  const instances: FakeZero[] = []
+  return { FakeZero, FakeConnectionState, instances }
+})
+
+vi.mock('@rocicorp/zero', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@rocicorp/zero')>()
+  return { ...actual, Zero: fakeZero.FakeZero }
+})
+
+import { createZeroClient } from './createZeroClient'
+
+declare global {
+  // eslint-disable-next-line no-var
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined
+}
+globalThis.IS_REACT_ACT_ENVIRONMENT = true
+
+const noteTable = table('note').columns({ id: string(), body: string() }).primaryKey('id')
+const schema = createSchema({ tables: [noteTable] })
+
+const client = createZeroClient({
+  schema,
+  models: {},
+  groupedQueries: {},
+  instanceName: 'connection-test',
+})
+
+let container: HTMLDivElement
+let root: Root | null
+
+beforeEach(() => {
+  fakeZero.instances.length = 0
+  container = document.createElement('div')
+  root = null
+  delete document.body.dataset.zeroState
+  delete document.body.dataset.zeroConnected
+  delete document.body.dataset.zeroReason
+})
+
+afterEach(() => {
+  if (root) act(() => root?.unmount())
+})
+
+async function mount(extraProps: Record<string, unknown> = {}, userID = 'conn') {
+  root = createRoot(container)
+  await act(async () => {
+    root?.render(
+      <client.ProvideZero
+        cacheURL="http://127.0.0.1:7788/zero"
+        userID={userID}
+        {...extraProps}
+      >
+        <span>ok</span>
+      </client.ProvideZero>,
+    )
+    await Promise.resolve()
+  })
+  return fakeZero.instances.at(-1)!
+}
+
+test('refreshAuth reconnects in place on needs-auth, once per transition', async () => {
+  const refreshAuth = vi.fn(async () => 'fresh-token')
+  const instance = await mount({ refreshAuth }, 'conn-auth')
+
+  await act(async () => {
+    instance.connection.state.set({ name: 'needs-auth', reason: 'token expired' })
+    await Promise.resolve()
+  })
+
+  expect(refreshAuth).toHaveBeenCalledTimes(1)
+  await act(async () => {
+    await Promise.resolve()
+  })
+  expect(instance.connection.connect).toHaveBeenCalledWith({ auth: 'fresh-token' })
+})
+
+test('stale-poke error reconnects instead of surfacing a fatal error', async () => {
+  const events: Array<{ type: string }> = []
+  const off = client.zeroEvents.listen((event) => {
+    if (event) events.push(event)
+  })
+  const instance = await mount({}, 'conn-stale')
+
+  await act(async () => {
+    instance.connection.state.set({
+      name: 'error',
+      reason: 'Server returned unexpected base cookie during sync',
+    })
+    await Promise.resolve()
+  })
+
+  // reconnect issued, no auth arg (plain resume)
+  expect(instance.connection.connect).toHaveBeenCalledTimes(1)
+  expect(instance.connection.connect).toHaveBeenCalledWith()
+  // the stale-poke reason must NOT be emitted as an error event
+  expect(events.some((event) => event.type === 'error')).toBe(false)
+  off()
+})
+
+test('connectionDataset mirrors connection state onto the body dataset', async () => {
+  const instance = await mount({ connectionDataset: true }, 'conn-dataset')
+
+  await act(async () => {
+    instance.connection.state.set({ name: 'connected' })
+    await Promise.resolve()
+  })
+  expect(document.body.dataset.zeroState).toBe('connected')
+  expect(document.body.dataset.zeroConnected).toBe('true')
+  expect(document.body.dataset.zeroCacheUrl).toBe('http://127.0.0.1:7788/zero')
+
+  await act(async () => {
+    instance.connection.state.set({ name: 'error', reason: 'boom' })
+    await Promise.resolve()
+  })
+  expect(document.body.dataset.zeroState).toBe('error')
+  expect(document.body.dataset.zeroConnected).toBeUndefined()
+  expect(document.body.dataset.zeroReason).toBe('boom')
+})

package/src/createZeroClient.recovery.test.tsx

@@ -102,3 +102,71 @@ test('zero.delete invalidates cached instance before a remount recovery', async
   expect(fakeZero.instances).toHaveLength(2)
   expect(fakeZero.instances[1]).not.toBe(first)
 })
+
+test('remint drops local state and reconstructs a fresh instance in place', async () => {
+  // unique userID so instanceKey misses the module-level cache from prior tests
+  // and a fresh instance is genuinely constructed here.
+  root = createRoot(container)
+  await act(async () => {
+    root?.render(
+      <client.ProvideZero cacheURL="http://127.0.0.1:7777/zero" userID="remint-test">
+        <span>ok</span>
+      </client.ProvideZero>,
+    )
+    await Promise.resolve()
+  })
+  const first = fakeZero.instances.at(-1)
+  expect(first).toBeDefined()
+  const countBefore = fakeZero.instances.length
+
+  let result: boolean | undefined
+  await act(async () => {
+    result = await client.remint()
+    // let the generation bump re-render and the rotate effect mint the fresh one
+    await Promise.resolve()
+  })
+
+  expect(result).toBe(true)
+  // dropped the rejected store + closed it, then minted a genuinely new client
+  // without unmounting the provider (no page reload).
+  expect(first?.delete).toHaveBeenCalledTimes(1)
+  expect(fakeZero.instances.length).toBe(countBefore + 1)
+  expect(fakeZero.instances.at(-1)).not.toBe(first)
+})
+
+test('remint with no provider mounted returns false without burning the guard budget', async () => {
+  // own client so the shared remint guard state is fresh for this assertion.
+  const isolated = createZeroClient({
+    schema,
+    models: {},
+    groupedQueries: {},
+    instanceName: 'remint-unmounted-test',
+  })
+
+  // nothing mounted → remintControl.bump is null. these must NOT start the 12s
+  // cooldown or consume the attempt budget.
+  expect(await isolated.remint()).toBe(false)
+  expect(await isolated.remint()).toBe(false)
+
+  root = createRoot(container)
+  await act(async () => {
+    root?.render(
+      <isolated.ProvideZero
+        cacheURL="http://127.0.0.1:7777/zero"
+        userID="remint-unmounted"
+      >
+        <span>ok</span>
+      </isolated.ProvideZero>,
+    )
+    await Promise.resolve()
+  })
+
+  // a mounted remint immediately after is still allowed — proof the unmounted
+  // calls didn't burn the guard (old code set lastRemintAt before this check).
+  let result: boolean | undefined
+  await act(async () => {
+    result = await isolated.remint()
+    await Promise.resolve()
+  })
+  expect(result).toBe(true)
+})