on-zero 0.6.6 → 0.6.8

package/src/httpPullTransport.ts

@@ -25,16 +25,36 @@ type DesiredQueryPatchOp =
 
 type GotQueryPatchOp = { op: 'clear' } | { op: 'put' | 'del'; hash: string }
 
+// a shipped desired-query put carries an AST (client-resolved by a
+// queryTransform, or an ad-hoc query's inline ast) OR name+args for the server
+// to resolve. name+args is the auth-sensitive path: the permission transform
+// stays server-side, so a client cannot forge the AST.
+type QueryPatchOp =
+  | { op: 'put'; hash: string; ast: unknown }
+  | { op: 'put'; hash: string; name: string; args: readonly unknown[] }
+  | { op: 'del'; hash: string }
+  | { op: 'clear' }
+
+// transforms a named query's (name, args) into its Zero v51 AST. providing one
+// turns the query-aware extension on and resolves desired queries CLIENT-side
+// (ship the AST). use for a native host with no query registry, or a trusted
+// harness. omit it (with queryForward) to ship name+args and resolve SERVER-side.
+export type QueryTransform = (name: string, args: readonly unknown[]) => unknown
+
+type ServerGotQueries = { version: number; patch: GotQueryPatchOp[] }
+
 type PullResponse =
   | {
       cookie: number
       lastMutationIDChanges: Record<string, number>
       rowsPatch: unknown[]
       unchanged?: false
+      gotQueries?: ServerGotQueries
     }
   | {
       cookie: number | null
       unchanged: true
+      gotQueries?: ServerGotQueries
     }
 
 type TransportState = {
@@ -44,6 +64,10 @@ type TransportState = {
   readonly nativeWebSocket: WebSocketConstructor | undefined
   readonly sockets: Set<ZeroHttpSocket>
   readonly pullIntervalMs: number | undefined
+  readonly wakeEnabled: boolean
+  readonly queryTransform: QueryTransform | undefined
+  readonly queryForward: boolean
+  readonly queryAware: boolean
   nextPokeID: number
   transientFailureCount: number
 }
@@ -64,6 +88,20 @@ export type HttpPullTransportOptions = {
   // when set, every open connection also pulls on this interval so
   // server-initiated changes arrive without a client-side trigger
   pullIntervalMs?: number
+  // when true, each connection also opens a notification-only wake socket to
+  // <origin>/wake and pulls immediately on any wake, demoting the interval
+  // poll to a safety net. the wake channel carries no data ("pull now" only)
+  // and zero correctness weight: a lost or duplicated wake can never cause
+  // missed or wrong data because convergence comes from the pull protocol.
+  wake?: boolean
+  // when provided, the query-aware extension is on and desired queries are
+  // resolved client-side to an AST before shipping (native host / trusted
+  // harness). omit for the baseline dialect (client-local got-query synthesis).
+  queryTransform?: QueryTransform
+  // turns the query-aware extension on WITHOUT a client-side transform: desired
+  // queries ship as name+args for the SERVER (consumer worker) to resolve with
+  // auth. the production path for permission-transformed queries.
+  queryForward?: boolean
 }
 
 export function installHttpPullTransport(
@@ -85,6 +123,10 @@ export function installHttpPullTransport(
     nativeWebSocket: previousWebSocket,
     sockets: new Set(),
     pullIntervalMs: opts.pullIntervalMs,
+    wakeEnabled: opts.wake ?? false,
+    queryTransform: opts.queryTransform,
+    queryForward: opts.queryForward === true,
+    queryAware: opts.queryTransform !== undefined || opts.queryForward === true,
     nextPokeID: 0,
     transientFailureCount: 0,
   }
@@ -161,12 +203,22 @@ class ZeroHttpSocket {
   private readonly wsid: string
   private cookie: string | null
   private pendingGotQueriesPatch: GotQueryPatchOp[] = []
+  // query-aware extension state: the accumulated un-acked desired-query delta
+  // to ship, a client-side query-state version that bumps on each change, and
+  // the version/length of the delta the in-flight pull sent (to clear the
+  // acked prefix on the server's ack).
+  private desiredQueryPatch: QueryPatchOp[] = []
+  private queryVersion = 0
+  private sentQueryVersion: number | undefined
+  private sentQueryPatchLen = 0
   private pullInFlight: Promise<void> | undefined
   private pullAfterCurrent = false
   private pushChain: Promise<void> = Promise.resolve()
   private nextLocalCookieID: number
   private openTimer: ReturnType<typeof setTimeout> | undefined
   private pullTimer: ReturnType<typeof setInterval> | undefined
+  private wakeSocket: { close(): void } | undefined
+  private wakeReconnectTimer: ReturnType<typeof setTimeout> | undefined
 
   constructor(
     private readonly state: TransportState,
@@ -245,6 +297,7 @@ class ZeroHttpSocket {
     if (this.readyState === this.CLOSED) return
     if (this.openTimer) clearTimeout(this.openTimer)
     if (this.pullTimer) clearInterval(this.pullTimer)
+    this.closeWakeChannel()
     this.readyState = this.CLOSED
     this.state.sockets.delete(this)
     this.emit('close', { code, reason, wasClean: code <= 1001 })
@@ -253,8 +306,9 @@ class ZeroHttpSocket {
   pull(): Promise<void> {
     if (this.readyState !== this.OPEN) return Promise.resolve()
     if (this.pullInFlight) return this.pullInFlight
-    this.pullInFlight = this.fetchPull(this.clientGroupID, this.cookie)
+    this.pullInFlight = this.fetchPull(this.clientGroupID, this.cookie, true)
       .then((response) => {
+        if (this.state.queryAware) this.applyServerGotQueries(response)
         if (response.unchanged) {
           this.emitGotQueriesPatch(response.cookie)
           return
@@ -285,13 +339,104 @@ class ZeroHttpSocket {
         this.run(this.pull())
       }, this.state.pullIntervalMs)
     }
+    if (this.state.wakeEnabled) this.openWakeChannel()
+  }
+
+  // notification-only wake channel: a real WebSocket to <origin>/wake that
+  // carries no data. any frame means "pull now", so a wake triggers an
+  // immediate (coalesced) pull — push-shaped propagation without waiting on
+  // the poll interval. advisory only: if it drops we reconnect, and the
+  // interval poll remains the safety net that guarantees convergence.
+  private openWakeChannel() {
+    const Native = this.state.nativeWebSocket
+    if (!Native || this.wakeSocket || this.readyState !== this.OPEN) return
+    const wsBase = this.state.originString.replace(/^http/, 'ws')
+    const url = `${wsBase}/wake?clientID=${encodeURIComponent(this.clientID)}`
+    let socket: {
+      onmessage: (() => void) | null
+      onclose: (() => void) | null
+      onerror: (() => void) | null
+      close(): void
+    }
+    try {
+      socket = new Native(url) as unknown as typeof socket
+    } catch {
+      return
+    }
+    this.wakeSocket = socket
+    const reconnect = () => {
+      if (this.wakeSocket !== socket) return
+      this.wakeSocket = undefined
+      if (this.readyState !== this.OPEN || this.wakeReconnectTimer) return
+      this.wakeReconnectTimer = setTimeout(() => {
+        this.wakeReconnectTimer = undefined
+        this.openWakeChannel()
+      }, 500)
+    }
+    // route through requestPullAfterCurrent, NOT pull() directly: a wake that
+    // lands while a pull is already in flight must set pullAfterCurrent so the
+    // in-flight pull re-runs and picks up the woken change. calling pull()
+    // directly would return the existing promise and silently drop the wake,
+    // leaving convergence to the safety poll (a burst-storm latency bug).
+    socket.onmessage = () => this.requestPullAfterCurrent()
+    socket.onclose = reconnect
+    socket.onerror = reconnect
+  }
+
+  private closeWakeChannel() {
+    if (this.wakeReconnectTimer) {
+      clearTimeout(this.wakeReconnectTimer)
+      this.wakeReconnectTimer = undefined
+    }
+    const socket = this.wakeSocket
+    this.wakeSocket = undefined
+    if (socket) {
+      try {
+        socket.close()
+      } catch {
+        // best effort: an already-closing wake socket is harmless
+      }
+    }
   }
 
   private queueDesiredQueries(body: unknown) {
     const desiredQueriesPatch = (body as { desiredQueriesPatch?: unknown })
       ?.desiredQueriesPatch
     if (!Array.isArray(desiredQueriesPatch)) return
-    this.pendingGotQueriesPatch.push(...gotQueriesPatch(desiredQueriesPatch))
+    if (!this.state.queryAware) {
+      // baseline dialect: synthesize the got-query ack locally
+      this.pendingGotQueriesPatch.push(...gotQueriesPatch(desiredQueriesPatch))
+      return
+    }
+    // query-aware: accumulate the desired-query delta to ship to the server. a
+    // put ships its inline ast, or a client-resolved ast (queryTransform), or
+    // name+args for the server to resolve (queryForward). the server owns the
+    // got-query ack.
+    const transform = this.state.queryTransform
+    for (const op of desiredQueriesPatch as DesiredQueryPatchOp[]) {
+      if (op.op === 'clear') {
+        this.desiredQueryPatch.push({ op: 'clear' })
+      } else if (op.op === 'del') {
+        this.desiredQueryPatch.push({ op: 'del', hash: op.hash })
+      } else if (op.op === 'put') {
+        const inline = (op as { ast?: unknown }).ast
+        const name = (op as { name?: string }).name ?? ''
+        const args = ((op as { args?: readonly unknown[] }).args ??
+          []) as readonly unknown[]
+        if (this.state.queryForward) {
+          this.desiredQueryPatch.push({ op: 'put', hash: op.hash, name, args })
+        } else if (inline !== undefined) {
+          this.desiredQueryPatch.push({ op: 'put', hash: op.hash, ast: inline })
+        } else if (transform) {
+          this.desiredQueryPatch.push({
+            op: 'put',
+            hash: op.hash,
+            ast: transform(name, args),
+          })
+        }
+      }
+    }
+    this.queryVersion++
   }
 
   private async push(body: unknown) {
@@ -328,12 +473,30 @@ class ZeroHttpSocket {
     this.run(this.pull())
   }
 
+  // in query-aware mode the got-query ack is authoritative from the server:
+  // take the server's gotQueries.patch as the got patch to emit (replacing
+  // local synthesis), and clear the acked prefix of the shipped desired delta
+  // once the server acks that version (the ack never leads its row effects —
+  // invariant 13 — so the client marks a query got only after its rows land).
+  private applyServerGotQueries(response: PullResponse) {
+    const got = response.gotQueries
+    this.pendingGotQueriesPatch = got ? got.patch : []
+    if (
+      got &&
+      this.sentQueryVersion !== undefined &&
+      got.version >= this.sentQueryVersion
+    ) {
+      this.desiredQueryPatch.splice(0, this.sentQueryPatchLen)
+      this.sentQueryVersion = undefined
+    }
+  }
+
   private async answerMutationRecoveryPull(body: {
     clientGroupID: string
     cookie: string | null
     requestID: string
   }) {
-    const response = await this.fetchPull(body.clientGroupID, body.cookie)
+    const response = await this.fetchPull(body.clientGroupID, body.cookie, false)
     const cookie = toWebSocketCookie(response.cookie)
     this.emitMessage([
       'pull',
@@ -345,12 +508,27 @@ class ZeroHttpSocket {
     ])
   }
 
-  private async fetchPull(clientGroupID: string, cookie: string | null) {
-    return (await this.postJSON('/pull', {
+  private async fetchPull(
+    clientGroupID: string,
+    cookie: string | null,
+    includeQueries: boolean,
+  ) {
+    const body: Record<string, unknown> = {
       clientID: this.clientID,
       clientGroupID,
       cookie: toHttpCookie(cookie),
-    })) as PullResponse
+    }
+    // ship the un-acked desired-query delta with the pull; remember what we
+    // sent so the server ack can clear exactly that prefix. a recovery pull
+    // (includeQueries=false) never carries desires.
+    if (includeQueries && this.state.queryAware && this.desiredQueryPatch.length > 0) {
+      this.sentQueryVersion = this.queryVersion
+      this.sentQueryPatchLen = this.desiredQueryPatch.length
+      body.queries = { version: this.queryVersion, patch: [...this.desiredQueryPatch] }
+    } else {
+      this.sentQueryVersion = undefined
+    }
+    return (await this.postJSON('/pull', body)) as PullResponse
   }
 
   private async postJSON(path: '/pull' | '/push', body: unknown) {
@@ -410,11 +588,23 @@ class ZeroHttpSocket {
   }
 
   private emitPoke(response: Exclude<PullResponse, { unchanged: true }>) {
-    const nextCookie = toWebSocketCookie(response.cookie)
-    if (isStaleCookie(this.cookie, response.cookie)) {
+    const currentServer = toHttpCookie(this.cookie)
+    let nextCookie: string
+    if (currentServer !== null && response.cookie < currentServer) {
+      // the server watermark is BEHIND the client: a real reset/restore. mirror
+      // the 409 stale path instead of poking the client backwards.
       throw new Error(
         `zero-http pull returned stale cookie ${response.cookie} for ${this.cookie}`,
       )
+    } else if (currentServer !== null && response.cookie === currentServer) {
+      // same server watermark but a non-empty patch: a query-aware membership
+      // delta (a desired-query change recomputes rows without advancing the
+      // change log). bump a client-local cookie id so replicache sees a changed
+      // cookie — otherwise it trips "cookie did not change, but patch is not
+      // empty" and drops the patch.
+      nextCookie = toLocalWebSocketCookie(response.cookie, ++this.nextLocalCookieID)
+    } else {
+      nextCookie = toWebSocketCookie(response.cookie) as string
     }
 
     const pokeID = `zero-http-${++this.state.nextPokeID}`
@@ -576,11 +766,6 @@ function toLocalWebSocketCookie(cookie: number, localID: number): string {
   )}`
 }
 
-function isStaleCookie(current: string | null, next: number) {
-  const currentNumber = toHttpCookie(current)
-  return currentNumber !== null && next <= currentNumber
-}
-
 function errorMessage(error: unknown) {
   return error instanceof Error ? error.message : String(error)
 }

package/types/helpers/createMutators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createMutators.d.ts","sourceRoot":"","sources":["../../src/helpers/createMutators.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,QAAQ,EACR,GAAG,EACH,aAAa,EACb,eAAe,EAGhB,MAAM,UAAU,CAAA;AAEjB,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;CACd,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1B,YAAY,EAAE,kBAAkB,IAAI,wBAAwB,EAAE,CAAA;AAE9D,wBAAgB,cAAc,CAAC,MAAM,SAAS,aAAa,EAAE,EAC3D,WAAW,EACX,QAAQ,EACR,mBAAmB,EACnB,UAAe,EACf,GAAG,EACH,MAAM,EACN,gBAAgB,EAChB,kBAAkB,GACnB,EAAE;IACD,WAAW,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAChC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;IACzB,GAAG,EAAE,GAAG,CAAA;IACR,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;IACvC,mBAAmB,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC/C,gBAAgB,CAAC,EAAE,kBAAkB,CAAA;IACrC,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAA;CACzD,GAAG,eAAe,CAAC,MAAM,CAAC,CAkK1B"}
+{"version":3,"file":"createMutators.d.ts","sourceRoot":"","sources":["../../src/helpers/createMutators.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,QAAQ,EACR,GAAG,EACH,aAAa,EACb,eAAe,EAGhB,MAAM,UAAU,CAAA;AAEjB,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;CACd,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1B,YAAY,EAAE,kBAAkB,IAAI,wBAAwB,EAAE,CAAA;AAE9D,wBAAgB,cAAc,CAAC,MAAM,SAAS,aAAa,EAAE,EAC3D,WAAW,EACX,QAAQ,EACR,mBAAmB,EACnB,UAAe,EACf,GAAG,EACH,MAAM,EACN,gBAAgB,EAChB,kBAAkB,GACnB,EAAE;IACD,WAAW,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAChC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;IACzB,GAAG,EAAE,GAAG,CAAA;IACR,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;IACvC,mBAAmB,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC/C,gBAAgB,CAAC,EAAE,kBAAkB,CAAA;IACrC,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAA;CACzD,GAAG,eAAe,CAAC,MAAM,CAAC,CAuK1B"}

package/types/helpers/createMutators.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=createMutators.test.d.ts.map

package/types/helpers/createMutators.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createMutators.test.d.ts","sourceRoot":"","sources":["../../src/helpers/createMutators.test.ts"],"names":[],"mappings":""}

package/types/httpPull/completeAck.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=completeAck.test.d.ts.map

package/types/httpPull/completeAck.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completeAck.test.d.ts","sourceRoot":"","sources":["../../src/httpPull/completeAck.test.ts"],"names":[],"mappings":""}

package/types/httpPullTransport.d.ts

@@ -1,3 +1,4 @@
+export type QueryTransform = (name: string, args: readonly unknown[]) => unknown;
 export type HttpPullTransport = {
     pull(): Promise<void>;
     readonly connections: number;
@@ -7,6 +8,9 @@ export type HttpPullTransportOptions = {
     origin: string;
     fetch?: typeof fetch;
     pullIntervalMs?: number;
+    wake?: boolean;
+    queryTransform?: QueryTransform;
+    queryForward?: boolean;
 };
 export declare function installHttpPullTransport(opts: HttpPullTransportOptions): HttpPullTransport;
 export declare function ensureHttpPullTransport(opts: HttpPullTransportOptions): HttpPullTransport;

package/types/httpPullTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"httpPullTransport.d.ts","sourceRoot":"","sources":["../src/httpPullTransport.ts"],"names":[],"mappings":"AAsDA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,SAAS,IAAI,IAAI,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IAGpB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,wBAAwB,GAC7B,iBAAiB,CAqDnB;AAOD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,iBAAiB,CAOnB"}
+{"version":3,"file":"httpPullTransport.d.ts","sourceRoot":"","sources":["../src/httpPullTransport.ts"],"names":[],"mappings":"AAyCA,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,CAAA;AAqChF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,SAAS,IAAI,IAAI,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IAGpB,cAAc,CAAC,EAAE,MAAM,CAAA;IAMvB,IAAI,CAAC,EAAE,OAAO,CAAA;IAId,cAAc,CAAC,EAAE,cAAc,CAAA;IAI/B,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,wBAAwB,GAC7B,iBAAiB,CAyDnB;AAOD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,iBAAiB,CAOnB"}