on-zero 0.7.10 → 0.8.0

package/src/createZeroClient.connection.test.tsx

@@ -95,7 +95,7 @@ async function mount(extraProps: Record<string, unknown> = {}, userID = 'conn')
         {...extraProps}
       >
         <span>ok</span>
-      </client.ProvideZero>,
+      </client.ProvideZero>
     )
     await Promise.resolve()
   })
@@ -119,7 +119,7 @@ test('waitForZero resolves when the provider publishes its active instance', asy
         userID="readiness"
       >
         <span>ok</span>
-      </readinessClient.ProvideZero>,
+      </readinessClient.ProvideZero>
     )
     await Promise.resolve()
   })
@@ -138,6 +138,10 @@ test('installs the supplied client transport for the provider server', async ()
 
 test('refreshAuth reconnects in place on needs-auth, once per transition', async () => {
   const refreshAuth = vi.fn(async () => 'fresh-token')
+  const events: Array<{ type: string; reasonKey?: string }> = []
+  const off = client.zeroEvents.listen((event) => {
+    if (event) events.push(event)
+  })
   const instance = await mount({ refreshAuth }, 'conn-auth')
 
   await act(async () => {
@@ -150,6 +154,12 @@ test('refreshAuth reconnects in place on needs-auth, once per transition', async
     await Promise.resolve()
   })
   expect(instance.connection.connect).toHaveBeenCalledWith({ auth: 'fresh-token' })
+  expect(events).toContainEqual({
+    type: 'error',
+    reasonKey: 'connection-needs-auth',
+    message: 'token expired',
+  })
+  off()
 })
 
 test('stale-poke error reconnects instead of surfacing a fatal error', async () => {
@@ -219,6 +229,7 @@ test('fatal error state stays terminal and reports the reason', async () => {
     expect(instance.connection.connect).not.toHaveBeenCalled()
     expect(events).toContainEqual({
       type: 'error',
+      reasonKey: 'connection-error',
       message: 'Got open event but connect start time is undefined',
     })
     off()

package/src/createZeroClient.recovery.test.tsx

@@ -23,7 +23,7 @@ const fakeZero = vi.hoisted(() => {
       complete: Promise.resolve(),
     }))
 
-    constructor() {
+    constructor(readonly options: Record<string, any>) {
       instances.push(this)
     }
   }
@@ -41,6 +41,7 @@ vi.mock('@rocicorp/zero', async (importOriginal) => {
 })
 
 import { createZeroClient } from './createZeroClient'
+import { resetRecoveryStateForTests } from './helpers/recoverZeroClient'
 
 declare global {
   // eslint-disable-next-line no-var
@@ -62,6 +63,8 @@ let container: HTMLDivElement
 let root: Root | null
 
 beforeEach(() => {
+  window.sessionStorage.clear()
+  resetRecoveryStateForTests()
   fakeZero.instances.length = 0
   container = document.createElement('div')
   root = null
@@ -77,7 +80,7 @@ async function mount() {
     root?.render(
       <client.ProvideZero cacheURL="http://127.0.0.1:7777/zero" userID="agentbus">
         <span>ok</span>
-      </client.ProvideZero>,
+      </client.ProvideZero>
     )
     await Promise.resolve()
   })
@@ -111,7 +114,7 @@ test('remint drops local state and reconstructs a fresh instance in place', asyn
     root?.render(
       <client.ProvideZero cacheURL="http://127.0.0.1:7777/zero" userID="remint-test">
         <span>ok</span>
-      </client.ProvideZero>,
+      </client.ProvideZero>
     )
     await Promise.resolve()
   })
@@ -156,7 +159,7 @@ test('remint with no provider mounted returns false without burning the guard bu
         userID="remint-unmounted"
       >
         <span>ok</span>
-      </isolated.ProvideZero>,
+      </isolated.ProvideZero>
     )
     await Promise.resolve()
   })
@@ -170,3 +173,96 @@ test('remint with no provider mounted returns false without burning the guard bu
   })
   expect(result).toBe(true)
 })
+
+test('two consecutive server acknowledgement timeouts enter normal recovery', async () => {
+  vi.useFakeTimers()
+  try {
+    const isolated = createZeroClient({
+      schema,
+      models: {},
+      groupedQueries: {},
+      instanceName: 'ack-timeout-recovery-test',
+    })
+    let scheduled:
+      | {
+          reasonKey: string
+          performReload: () => Promise<void>
+        }
+      | undefined
+
+    root = createRoot(container)
+    await act(async () => {
+      root?.render(
+        <isolated.ProvideZero
+          cacheURL="http://127.0.0.1:7777/zero"
+          userID="ack-timeout"
+          scheduleReload={(context) => {
+            scheduled = context
+          }}
+        >
+          <span>ok</span>
+        </isolated.ProvideZero>
+      )
+      await Promise.resolve()
+    })
+
+    const timeout = async (label: string) => {
+      const result = isolated.awaitMutationServer(
+        { client: Promise.resolve({}), server: new Promise(() => {}) },
+        label,
+        10
+      )
+      const timedOut = expect(result).rejects.toMatchObject({
+        name: 'MutationTimeoutError',
+        phase: 'server',
+      })
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(10)
+      })
+      await timedOut
+    }
+
+    await timeout('first write')
+    expect(scheduled).toBeUndefined()
+    await timeout('second write')
+    expect(scheduled).toMatchObject({ reasonKey: 'server-ack-timeout' })
+  } finally {
+    vi.useRealTimers()
+  }
+})
+
+test('transport and app benign log patterns suppress classified recovery', async () => {
+  const isolated = createZeroClient({
+    schema,
+    models: {},
+    groupedQueries: {},
+    instanceName: 'transport-log-classification-test',
+  })
+  const scheduleReload = vi.fn()
+  const install = vi.fn()
+  root = createRoot(container)
+  await act(async () => {
+    root?.render(
+      <isolated.ProvideZero
+        cacheURL="http://127.0.0.1:7777/zero"
+        userID="transport-log"
+        transport={{
+          install,
+          logClassifications: { benign: ['ClientNotFound'] },
+        }}
+        benignLogPatterns={[/sent mutation ID .* but expected/]}
+        scheduleReload={scheduleReload}
+      >
+        <span>ok</span>
+      </isolated.ProvideZero>
+    )
+    await Promise.resolve()
+  })
+
+  const instance = fakeZero.instances.at(-1)!
+  instance.options.logSink.log('error', undefined, 'ClientNotFound: cold boot')
+  instance.options.logSink.log('error', undefined, 'sent mutation ID 5 but expected 4')
+  await Promise.resolve()
+  expect(install).toHaveBeenCalledOnce()
+  expect(scheduleReload).not.toHaveBeenCalled()
+})

package/src/createZeroClient.tsx

@@ -10,7 +10,6 @@ import {
   ZeroContext,
   ZeroProvider,
 } from '@rocicorp/zero/react'
-import { createEmitter, IS_SERVER_RUNTIME, type Emitter } from '@take-out/helpers'
 import {
   createContext,
   memo,
@@ -23,6 +22,7 @@ import {
   type Context,
   type ReactNode,
 } from 'react'
+
 import { createPermissions } from './createPermissions'
 import {
   createUseQuery,
@@ -30,13 +30,17 @@ import {
   type UseQueryHook,
 } from './createUseQuery'
 import { createMutators } from './helpers/createMutators'
+import { createEmitter, type Emitter } from './helpers/emitter'
 import { getAuth } from './helpers/getAuth'
+import { createMutationLifecycle } from './helpers/mutationLifecycle'
+import { IS_SERVER_RUNTIME } from './helpers/platform'
 import {
   composeRecoveryLogSink,
   isRecoverableZeroStalePokeMessage,
   makeZeroRecovery,
   type RecoveryGuardStorage,
   type ScheduleReloadContext,
+  type ZeroLogPattern,
   type ZeroRecoveryDeps,
 } from './helpers/recoverZeroClient'
 import { registerClientInstance } from './instanceRegistry'
@@ -48,7 +52,14 @@ import { getEnvironment, setAuthData, setEnvironment, setSchema } from './state'
 import { getRawWhere, setEvaluatingPermission } from './where'
 import { setRunner, type ZeroRunner } from './zeroRunner'
 import { zql } from './zql'
-import type { AuthData, GenericModels, GetZeroMutators, ZeroEvent } from './types'
+
+import type {
+  AuthData,
+  GenericModels,
+  GetZeroMutators,
+  ZeroEvent,
+  ZeroEventsEmitter,
+} from './types'
 import type {
   AnyQueryRegistry,
   Query,
@@ -70,6 +81,9 @@ export type PermissionStrategy = 'optimistic' | 'optimistic-deny' | 'optimistic-
 
 export type ZeroProviderTransport = {
   install(serverURL: string): unknown
+  logClassifications?: {
+    benign?: readonly ZeroLogPattern[]
+  }
 }
 
 export type WaitForZeroOptions = {
@@ -84,6 +98,9 @@ export type CreateZeroClientOptions<
   models: Models
   groupedQueries: GroupedQueries
   permissionStrategy?: PermissionStrategy
+  // repeated server acknowledgement timeouts are a desync signal. one timeout
+  // remains a normal slow-server failure; recovery begins at this threshold.
+  serverAckTimeoutRecoveryThreshold?: number
   // names this client instance so multiple instances can coexist on one page.
   // each query/mutator namespace is claimed by exactly one instance, and the
   // ambient run() + the combineZeroClients facade dispatch by that claim.
@@ -119,7 +136,7 @@ function createUnavailableDirectUseQuery<
 >(): UseQueryHook<Schema> {
   function useQueryDirect(): never {
     throw new Error(
-      `[on-zero] direct queries are optional. Import createZeroClientWithDirectQueries from 'on-zero/multi' for clients used outside the innermost ZeroProvider.`,
+      `[on-zero] direct queries are optional. Import createZeroClientWithDirectQueries from 'on-zero/multi' for clients used outside the innermost ZeroProvider.`
     )
   }
 
@@ -127,7 +144,7 @@ function createUnavailableDirectUseQuery<
 }
 
 export function createZeroClient<Schema extends ZeroSchema, Models extends GenericModels>(
-  options: CreateZeroClientOptions<Schema, Models>,
+  options: CreateZeroClientOptions<Schema, Models>
 ) {
   return createZeroClientInternal(options)
 }
@@ -141,6 +158,7 @@ export function createZeroClientInternal<
   groupedQueries,
   permissionStrategy = 'optimistic',
   instanceName = 'default',
+  serverAckTimeoutRecoveryThreshold = 2,
   createDirectUseQuery,
 }: CreateZeroClientOptions<Schema, Models> & {
   createDirectUseQuery?: DirectQueryAdapter<Schema>
@@ -175,7 +193,7 @@ export function createZeroClientInternal<
       registerQuery(fn, `${namespace}.${name}`)
       // wrap each plain function in defineQuery
       wrappedNamespaces[namespace][name] = defineQuery(({ args }: { args: any }) =>
-        fn(args),
+        fn(args)
       )
     }
   }
@@ -210,7 +228,7 @@ export function createZeroClientInternal<
                 eb,
                 rawPerm || ((e: any) => e.and()),
                 args.objOrId,
-                table,
+                table
               )
             } finally {
               setEvaluatingPermission(false)
@@ -234,7 +252,7 @@ export function createZeroClientInternal<
             eb,
             perm || ((e: any) => e.and()),
             args.objOrId,
-            table,
+            table
           )
         })
         .one()
@@ -261,7 +279,7 @@ export function createZeroClientInternal<
     namespaces: Object.keys(models),
     customQueries,
     queryNames: Object.entries(groupedQueries).flatMap(([namespace, queries]) =>
-      Object.keys(queries).map((name) => `${namespace}.${name}`),
+      Object.keys(queries).map((name) => `${namespace}.${name}`)
     ),
   })
 
@@ -277,7 +295,7 @@ export function createZeroClientInternal<
     if (latestZeroInstance) return Promise.resolve(latestZeroInstance)
     if (signal?.aborted) {
       return Promise.reject(
-        signal.reason ?? new Error('Waiting for the Zero instance was aborted'),
+        signal.reason ?? new Error('Waiting for the Zero instance was aborted')
       )
     }
 
@@ -305,7 +323,7 @@ export function createZeroClientInternal<
     const resolve = () => {
       if (latestZeroInstance === null) {
         throw new Error(
-          `Zero instance not initialized. Ensure ZeroProvider is mounted before accessing 'zero'.`,
+          `Zero instance not initialized. Ensure ZeroProvider is mounted before accessing 'zero'.`
         )
       }
       let target: any = (latestZeroInstance as any).mutate
@@ -330,7 +348,7 @@ export function createZeroClientInternal<
       if (latestZeroInstance === null) {
         if (key === 'mutate') return lazyMutatePath([])
         throw new Error(
-          `Zero instance not initialized. Ensure ZeroProvider is mounted before accessing 'zero'.`,
+          `Zero instance not initialized. Ensure ZeroProvider is mounted before accessing 'zero'.`
         )
       }
       if (key === 'delete') {
@@ -346,7 +364,25 @@ export function createZeroClientInternal<
   // unchanged for single-instance back-compat.
   const emitterScope = instanceName === 'default' ? '' : `:${instanceName}`
 
-  const zeroEvents = createEmitter<ZeroEvent | null>(`zero${emitterScope}`, null)
+  const zeroEvents: ZeroEventsEmitter = createEmitter<ZeroEvent | null>(
+    `zero${emitterScope}`,
+    null
+  )
+
+  let recoverFromAckTimeout: (input: {
+    label: string
+    timeoutMs: number
+    consecutiveTimeouts: number
+  }) => void = () => {}
+  const ackTimeoutRecoveryThreshold =
+    Number.isFinite(serverAckTimeoutRecoveryThreshold) &&
+    serverAckTimeoutRecoveryThreshold >= 2
+      ? Math.floor(serverAckTimeoutRecoveryThreshold)
+      : 2
+  const mutationLifecycle = createMutationLifecycle({
+    ackTimeoutRecoveryThreshold,
+    recoverFromAckTimeout: (input) => recoverFromAckTimeout(input),
+  })
 
   const zeroInstanceVersion = createDirectUseQuery
     ? createEmitter<number>(`zero-instance-version${emitterScope}`, 0)
@@ -381,14 +417,14 @@ export function createZeroClientInternal<
         table: TableName | (string & {}),
         objOrId: string | Partial<Row<any>> | undefined,
         enabled?: boolean,
-        debug?: boolean,
+        debug?: boolean
       ) => boolean | null
     }
     return function usePermission(
       table: TableName | (string & {}),
       objOrId: string | Partial<Row<any>> | undefined,
       enabled = typeof objOrId !== 'undefined',
-      debug = false,
+      debug = false
     ): boolean | null {
       const disableMode = useContext(DisabledContext)
       const lastRef = useRef<boolean | null>(null)
@@ -403,7 +439,7 @@ export function createZeroClientInternal<
       const [data, status] = useQueryImpl(
         checkFn as any,
         { objOrId: objOrId as any, _uid },
-        { enabled: Boolean(!disableMode && enabled && objOrId && checkFn) },
+        { enabled: Boolean(!disableMode && enabled && objOrId && checkFn) }
       )
 
       if (debug) {
@@ -478,6 +514,7 @@ export function createZeroClientInternal<
   function invalidateZeroInstance(instanceToInvalidate: ZeroInstance | null): void {
     if (!instanceToInvalidate) return
 
+    mutationLifecycle.fence()
     if (clearZeroInstanceReferences(instanceToInvalidate)) {
       zeroInstanceVersion?.emit(zeroInstanceVersion.value + 1)
     }
@@ -489,8 +526,9 @@ export function createZeroClientInternal<
   }
 
   async function deleteZeroInstance(
-    instanceToDelete: ZeroInstance | null,
+    instanceToDelete: ZeroInstance | null
   ): Promise<unknown> {
+    mutationLifecycle.fence()
     try {
       return await instanceToDelete?.delete()
     } finally {
@@ -588,9 +626,9 @@ export function createZeroClientInternal<
     // cross-reload loop-guard backing store; defaults to sessionStorage on web.
     // inject a native KV so Hermes gets real cross-reload protection.
     guardStorage?: RecoveryGuardStorage
-    // return true for a classified recovery log the app wants treated as benign
-    // (its own cold-boot timeout, say) so it does NOT trigger recovery.
-    benignLogFilter?: (message: string) => boolean
+    // expected recovery signatures supplied as data. transport patterns and app
+    // patterns are combined; neither replaces the built-in classification.
+    benignLogPatterns?: readonly ZeroLogPattern[]
     // called when the connection needs auth; return a fresh token to reconnect
     // in place. lets an expired token auto-recover without a reload.
     refreshAuth?: () => Promise<string | undefined>
@@ -633,7 +671,7 @@ export function createZeroClientInternal<
     beforeReload,
     scheduleReload,
     guardStorage,
-    benignLogFilter,
+    benignLogPatterns,
     refreshAuth,
     connectionDataset,
     disable,
@@ -696,11 +734,14 @@ export function createZeroClientInternal<
       Object.entries({ kvStore: 'mem', ...props })
         .filter(
           ([key, value]) =>
-            key !== 'auth' && typeof value !== 'function' && value !== undefined,
+            key !== 'auth' && typeof value !== 'function' && value !== undefined
         )
         .sort(([a], [b]) => (a < b ? -1 : 1)),
       hasAuth,
       transport,
+      benignLogPatterns?.map((pattern) =>
+        typeof pattern === 'string' ? pattern : `/${pattern.source}/${pattern.flags}`
+      ),
       remintGeneration,
     ])
 
@@ -717,6 +758,7 @@ export function createZeroClientInternal<
     // until the commit-safe rotation effect below closes or reuses it.
     useLayoutEffect(() => {
       if (latestZeroInstance && (disable || cachedZero?.key !== instanceKey)) {
+        mutationLifecycle.fence()
         unpublishZeroInstance(latestZeroInstance)
       }
     }, [disable, instanceKey])
@@ -754,6 +796,7 @@ export function createZeroClientInternal<
           // the replacement's SetZeroInstance effect publishes one version
           // change; clearing the old references here must not emit a second.
           clearZeroInstanceReferences(cached.instance)
+          mutationLifecycle.fence()
           cached.instance.close()
         }
         // recovery closures reach the instance through this ref so they always
@@ -766,9 +809,14 @@ export function createZeroClientInternal<
           beforeReload,
           scheduleReload,
           guardStorage,
-          benignLogFilter,
+          benignLogPatterns: [
+            ...(transport?.logClassifications?.benign ?? []),
+            ...(benignLogPatterns ?? []),
+          ],
+          onRecovery: () => mutationLifecycle.fence(),
         }
         const recovery = makeZeroRecovery(recoveryDeps)
+        recoverFromAckTimeout = recovery.onServerAckTimeout
         const createdInstance = new ZeroClient<Schema, ZeroMutators>({
           kvStore: 'mem',
           ...options,
@@ -860,6 +908,7 @@ export function createZeroClientInternal<
     // runner before descendant effects perform imperative work.
     if (zeroInstance !== latestZeroInstance) {
       latestZeroInstance = zeroInstance
+      mutationLifecycle.activate()
       const runner: ZeroRunner = (query, options) =>
         zeroInstance.run(query as any, options)
       // the instance-keyed runner is what run() dispatches owned namespaces
@@ -889,7 +938,7 @@ export function createZeroClientInternal<
       exposeDataset,
       datasetCacheUrl,
     }: {
-      zeroEvents: ReturnType<typeof createEmitter<ZeroEvent | null>>
+      zeroEvents: ZeroEventsEmitter
       refreshAuth?: () => Promise<string | undefined>
       exposeDataset?: boolean
       datasetCacheUrl?: string
@@ -947,13 +996,18 @@ export function createZeroClientInternal<
         if (name !== prevState.current) {
           prevState.current = name
           if (name === 'error' || name === 'needs-auth') {
-            zeroEvents.emit({ type: 'error', message: reason || name })
+            zeroEvents.emit({
+              type: 'error',
+              reasonKey:
+                name === 'needs-auth' ? 'connection-needs-auth' : 'connection-error',
+              message: reason || name,
+            })
           }
         }
       }, [state, zeroEvents, zeroInstance, refreshAuth, exposeDataset, datasetCacheUrl])
 
       return null
-    },
+    }
   )
 
   // preload data for a query into cache without materializing
@@ -961,16 +1015,16 @@ export function createZeroClientInternal<
   function preload<TArg, TTable extends keyof Schema['tables'] & string, TReturn>(
     fn: PlainQueryFn<TArg, Query<TTable, Schema, TReturn>>,
     params: TArg,
-    options?: PreloadOptions,
+    options?: PreloadOptions
   ): { cleanup: () => void; complete: Promise<void> }
   function preload<TTable extends keyof Schema['tables'] & string, TReturn>(
     fn: PlainQueryFn<void, Query<TTable, Schema, TReturn>>,
-    options?: PreloadOptions,
+    options?: PreloadOptions
   ): { cleanup: () => void; complete: Promise<void> }
   function preload(
     fnArg: any,
     paramsOrOptions?: any,
-    optionsArg?: PreloadOptions,
+    optionsArg?: PreloadOptions
   ): { cleanup: () => void; complete: Promise<void> } {
     const hasParams =
       optionsArg !== undefined || (paramsOrOptions && !('ttl' in paramsOrOptions))
@@ -983,10 +1037,10 @@ export function createZeroClientInternal<
 
   function getQuery<TArg, TTable extends keyof Schema['tables'] & string, TReturn>(
     fn: PlainQueryFn<TArg, Query<TTable, Schema, TReturn>>,
-    params: TArg,
+    params: TArg
   ): ReturnType<typeof resolveQuery<Schema>>
   function getQuery<TTable extends keyof Schema['tables'] & string, TReturn>(
-    fn: PlainQueryFn<void, Query<TTable, Schema, TReturn>>,
+    fn: PlainQueryFn<void, Query<TTable, Schema, TReturn>>
   ): ReturnType<typeof resolveQuery<Schema>>
   function getQuery(fn: any, params?: any) {
     return resolveQuery({ customQueries, fn, params })
@@ -1019,5 +1073,8 @@ export function createZeroClientInternal<
     getQuery,
     waitForZero,
     remint,
+    enqueueBackgroundMutation: mutationLifecycle.enqueueBackgroundMutation,
+    awaitMutationClient: mutationLifecycle.awaitMutationClient,
+    awaitMutationServer: mutationLifecycle.awaitMutationServer,
   }
 }