orez-sync-cf-host 0.5.18 → 0.5.20

package/src/platform-probe-worker.ts

@@ -1,305 +0,0 @@
-import { DurableObject } from 'cloudflare:workers'
-
-import {
-  initSync,
-  init_probe_schema,
-  pull_snapshot,
-  push_finalize,
-  push_preflight,
-  rust_panic_after_writes,
-  value_round_trip,
-} from './generated/sync_wasm.js'
-import wasmModule from './generated/sync_wasm_bg.wasm'
-import { SqlStorageSyncDb } from './sql-storage-adapter.js'
-
-initSync({ module: wasmModule })
-
-interface Env {
-  PROBE_DO: DurableObjectNamespace<ProbeDurableObject>
-}
-
-type DeferredEffect = { mutationID: string; kind: string }
-type MutatorName = 'read-then-write' | 'multi-table' | 'application-error'
-
-// Deterministic local analogue of normal DO idle eviction, matching the
-// harness/cf probe: discard all in-memory state after an idle gap while SQL
-// storage remains intact. This keeps the test sub-second instead of waiting
-// for workerd/platform eviction heuristics.
-const IDLE_TEARDOWN_MS = 250
-
-const json = (value: unknown, status = 200) =>
-  Response.json(value, {
-    status,
-    headers: { 'cache-control': 'no-store' },
-  })
-
-export class ProbeDurableObject extends DurableObject<Env> {
-  readonly #db: SqlStorageSyncDb
-  #bootID = crypto.randomUUID()
-  #lastRequestAt = 0
-  #reinstantiations = 0
-  #effects: Array<DeferredEffect & { observedCommitted: boolean }> = []
-
-  constructor(ctx: DurableObjectState, env: Env) {
-    super(ctx, env)
-    this.#db = new SqlStorageSyncDb(ctx.storage.sql)
-    ctx.storage.transactionSync(() => init_probe_schema(this.#db))
-  }
-
-  #maybeReinstantiate(now: number): void {
-    if (this.#lastRequestAt > 0 && now - this.#lastRequestAt >= IDLE_TEARDOWN_MS) {
-      this.#bootID = crypto.randomUUID()
-      this.#effects = []
-      this.#reinstantiations++
-    }
-    this.#lastRequestAt = now
-  }
-
-  #state(): Record<string, unknown> {
-    const row = this.ctx.storage.sql
-      .exec(
-        `SELECT
-          CAST((SELECT lmid FROM probe_state WHERE singleton = 1) AS TEXT) AS lmid,
-          (SELECT balance FROM accounts WHERE id = 'primary') AS balance,
-          (SELECT COUNT(*) FROM ledger) AS ledgerCount,
-          (SELECT COUNT(*) FROM outbox) AS outboxCount,
-          (SELECT COUNT(*) FROM mutation_log) AS mutationCount,
-          (SELECT COUNT(*) FROM value_probe) AS valueCount`
-      )
-      .one()
-    return {
-      ...row,
-      sideEffectCount: this.#effects.length,
-      sideEffects: this.#effects,
-    }
-  }
-
-  async #mutate(name: MutatorName, deferred: DeferredEffect[]): Promise<void> {
-    if (name === 'read-then-write') {
-      const { balance } = this.ctx.storage.sql
-        .exec("SELECT balance FROM accounts WHERE id = 'primary'")
-        .one() as { balance: number }
-      await Promise.resolve()
-      this.ctx.storage.sql.exec(
-        "UPDATE accounts SET balance = ? WHERE id = 'primary'",
-        balance + 10
-      )
-      this.ctx.storage.sql.exec(
-        'INSERT INTO ledger (account_id, amount, note) VALUES (?, ?, ?)',
-        'primary',
-        10,
-        'read-then-write'
-      )
-      deferred.push({ mutationID: '', kind: 'balance-notification' })
-      return
-    }
-
-    if (name === 'multi-table') {
-      this.ctx.storage.sql.exec(
-        "UPDATE accounts SET balance = balance - 5 WHERE id = 'primary'"
-      )
-      await Promise.resolve()
-      this.ctx.storage.sql.exec(
-        'INSERT INTO ledger (account_id, amount, note) VALUES (?, ?, ?)',
-        'primary',
-        -5,
-        'multi-table'
-      )
-      this.ctx.storage.sql.exec(
-        'INSERT INTO outbox (topic, payload) VALUES (?, ?)',
-        'account.changed',
-        JSON.stringify({ id: 'primary', delta: -5 })
-      )
-      deferred.push({ mutationID: '', kind: 'outbox-notification' })
-      return
-    }
-
-    const { balance } = this.ctx.storage.sql
-      .exec("SELECT balance FROM accounts WHERE id = 'primary'")
-      .one() as { balance: number }
-    this.ctx.storage.sql.exec(
-      "UPDATE accounts SET balance = ? WHERE id = 'primary'",
-      balance + 777
-    )
-    await Promise.resolve()
-    this.ctx.storage.sql.exec(
-      'INSERT INTO ledger (account_id, amount, note) VALUES (?, ?, ?)',
-      'primary',
-      777,
-      'application-error'
-    )
-    deferred.push({ mutationID: '', kind: 'must-not-run' })
-    throw new Error('intentional application mutator error')
-  }
-
-  async #push(name: MutatorName, mutationID: string): Promise<Response> {
-    this.#db.resetStats()
-    const deferred: DeferredEffect[] = []
-    const started = performance.now()
-    let lmid: string | undefined
-    let wasmMs = 0
-    try {
-      await this.ctx.storage.transaction(async () => {
-        let wasmStarted = performance.now()
-        const expected = push_preflight(this.#db, mutationID)
-        wasmMs += performance.now() - wasmStarted
-
-        // MutatorSql methods resolve through the microtask queue. Cross that
-        // same boundary here without admitting timers or other external work
-        // into the storage transaction.
-        await Promise.resolve()
-        await this.#mutate(name, deferred)
-
-        wasmStarted = performance.now()
-        lmid = push_finalize(this.#db, mutationID, expected)
-        wasmMs += performance.now() - wasmStarted
-      })
-    } catch (error) {
-      return json(
-        {
-          ok: false,
-          error: String(error),
-          awaitedInsideTransaction: true,
-          state: this.#state(),
-          effectsDeferredButNotRun: deferred.length,
-        },
-        409
-      )
-    }
-
-    // External effects are not even inspected until the transaction promise
-    // resolves. Each effect independently verifies its mutation is durable.
-    for (const effect of deferred) {
-      effect.mutationID = mutationID
-      const committed =
-        this.ctx.storage.sql
-          .exec(
-            'SELECT 1 AS committed FROM mutation_log WHERE mutation_id = ?',
-            mutationID
-          )
-          .toArray().length === 1
-      this.#effects.push({ ...effect, observedCommitted: committed })
-    }
-
-    return json({
-      ok: true,
-      lmid,
-      awaitedInsideTransaction: true,
-      state: this.#state(),
-      timing: {
-        elapsedMs: performance.now() - started,
-        wasmMs,
-        ...this.#db.stats,
-      },
-    })
-  }
-
-  async fetch(request: Request): Promise<Response> {
-    this.#maybeReinstantiate(Date.now())
-    const url = new URL(request.url)
-    const [, , ...routeParts] = url.pathname.split('/')
-    const route = `/${routeParts.join('/')}`
-
-    if (route === '/status') {
-      return json({
-        bootID: this.#bootID,
-        idleTeardownMs: IDLE_TEARDOWN_MS,
-        reinstantiations: this.#reinstantiations,
-        state: this.#state(),
-      })
-    }
-
-    if (route === '/pull') {
-      this.#db.resetStats()
-      const started = performance.now()
-      const snapshot = this.ctx.storage.transactionSync(() => pull_snapshot(this.#db))
-      return json({
-        snapshot,
-        transaction: 'transactionSync',
-        timing: { elapsedMs: performance.now() - started, ...this.#db.stats },
-      })
-    }
-
-    if (route.startsWith('/push/')) {
-      const name = route.slice('/push/'.length) as MutatorName
-      if (!['read-then-write', 'multi-table', 'application-error'].includes(name)) {
-        return json({ error: 'unknown mutator' }, 404)
-      }
-      const body = (await request.json()) as { mutationID: string }
-      return this.#push(name, body.mutationID)
-    }
-
-    if (route === '/js-exception') {
-      const before = this.#state()
-      try {
-        await this.ctx.storage.transaction(async () => {
-          const expected = push_preflight(this.#db, 'js-exception')
-          this.ctx.storage.sql.exec(
-            "UPDATE accounts SET balance = balance + 123 WHERE id = 'primary'"
-          )
-          await Promise.resolve()
-          this.ctx.storage.sql.exec(
-            'INSERT INTO outbox (topic, payload) VALUES (?, ?)',
-            'must.rollback',
-            '{}'
-          )
-          push_finalize(this.#db, 'js-exception', expected)
-          throw new Error('intentional JS exception after finalization')
-        })
-      } catch (error) {
-        return json(
-          { ok: false, error: String(error), before, after: this.#state() },
-          409
-        )
-      }
-      return json({ error: 'JS exception did not escape transaction' }, 500)
-    }
-
-    if (route === '/rust-panic') {
-      const before = this.#state()
-      try {
-        this.ctx.storage.transactionSync(() => rust_panic_after_writes(this.#db))
-      } catch (error) {
-        return json(
-          { ok: false, error: String(error), before, after: this.#state() },
-          409
-        )
-      }
-      return json({ error: 'Rust panic did not escape transaction' }, 500)
-    }
-
-    if (route === '/values') {
-      const input = await request.json()
-      const output = this.ctx.storage.transactionSync(() =>
-        value_round_trip(this.#db, input)
-      )
-      return json(output)
-    }
-
-    if (route === '/adapter-guard') {
-      const errors: string[] = []
-      for (const [sql, params] of [
-        ['BEGIN TRANSACTION', []],
-        ['SELECT ?1', [{ kind: 'integer', value: '1' }]],
-      ] as const) {
-        try {
-          this.#db.exec(sql, [...params] as never)
-        } catch (error) {
-          errors.push(String(error))
-        }
-      }
-      return json({ errors })
-    }
-
-    return json({ error: 'not found', route }, 404)
-  }
-}
-
-export default {
-  fetch(request: Request, env: Env): Promise<Response> {
-    const url = new URL(request.url)
-    const [, namespace] = url.pathname.split('/')
-    if (!namespace) return Promise.resolve(new Response('orez rust sync M0 probe'))
-    return env.PROBE_DO.get(env.PROBE_DO.idFromName(namespace)).fetch(request)
-  },
-} satisfies ExportedHandler<Env>

package/src/sql-storage-adapter.ts

@@ -1,185 +0,0 @@
-import { trackBillableCursorRows } from './write-safeguards.js'
-
-import type { MutatorSql, SyncSql } from './types.js'
-
-type WireValue =
-  | { kind: 'null' }
-  | { kind: 'integer'; value: string }
-  | { kind: 'real'; value: number }
-  | { kind: 'text'; value: string }
-  | { kind: 'blob'; value: number[] }
-
-type WireRow = { columns: string[]; values: WireValue[] }
-
-interface JsSyncDb {
-  exec(sql: string, params: WireValue[]): void
-  query(sql: string, params: WireValue[]): WireRow[]
-}
-
-export type CompiledQuery = { sql: string; params: WireValue[] }
-
-export type AdapterStats = {
-  execCalls: number
-  queryCalls: number
-  sqlMs: number
-}
-
-// Match transaction control only as the statement itself. CREATE TRIGGER uses
-// `... BEGIN ... END` for its body, which is valid DO SQL and not a transaction.
-const TX_SQL = /^\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)(?=\s|;|$)/i
-const NUMBERED_PARAMETER = /\?[0-9]+/
-const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER)
-const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER)
-
-export function assertHostSql(sql: string): void {
-  if (TX_SQL.test(sql)) {
-    throw new TypeError('transaction SQL is host-owned and forbidden')
-  }
-  if (NUMBERED_PARAMETER.test(sql)) {
-    throw new TypeError('numbered parameters are forbidden; use positional ? bindings')
-  }
-}
-
-function decodeBinding(value: WireValue): unknown {
-  switch (value.kind) {
-    case 'null':
-      return null
-    case 'integer': {
-      const exact = BigInt(value.value)
-      // SqlStorage does not accept bigint. Safe values can use Number; unsafe
-      // values use decimal text and rely on the destination's INTEGER affinity.
-      return exact >= MIN_SAFE && exact <= MAX_SAFE ? Number(exact) : value.value
-    }
-    case 'real':
-    case 'text':
-      return value.value
-    case 'blob':
-      return Uint8Array.from(value.value).buffer
-  }
-}
-
-function encodeResult(value: unknown): WireValue {
-  if (value === null) return { kind: 'null' }
-  if (typeof value === 'number') {
-    return Number.isInteger(value)
-      ? { kind: 'integer', value: String(value) }
-      : { kind: 'real', value }
-  }
-  if (typeof value === 'string') return { kind: 'text', value }
-  if (value instanceof ArrayBuffer) {
-    return { kind: 'blob', value: Array.from(new Uint8Array(value)) }
-  }
-  if (ArrayBuffer.isView(value)) {
-    return {
-      kind: 'blob',
-      value: Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength)),
-    }
-  }
-  throw new TypeError(
-    `unsupported SqlStorage result: ${Object.prototype.toString.call(value)}`
-  )
-}
-
-/**
- * The sole JS SQL adapter used by wasm. It is synchronous, consumes every
- * cursor before returning, accepts positional `?` only, and never starts or
- * finishes a transaction.
- */
-export class SqlStorageSyncDb implements JsSyncDb {
-  readonly stats: AdapterStats = { execCalls: 0, queryCalls: 0, sqlMs: 0 }
-
-  constructor(
-    private readonly sql: SqlStorage,
-    private readonly recordRowsWritten: (rows: number) => void = () => {}
-  ) {}
-
-  resetStats(): void {
-    this.stats.execCalls = 0
-    this.stats.queryCalls = 0
-    this.stats.sqlMs = 0
-  }
-
-  exec(sql: string, params: WireValue[]): void {
-    assertHostSql(sql)
-    const start = performance.now()
-    trackBillableCursorRows(
-      this.sql.exec(sql, ...params.map(decodeBinding)),
-      this.recordRowsWritten
-    )
-    this.stats.execCalls++
-    this.stats.sqlMs += performance.now() - start
-  }
-
-  query(sql: string, params: WireValue[]): WireRow[] {
-    assertHostSql(sql)
-    const start = performance.now()
-    const cursor = trackBillableCursorRows(
-      this.sql.exec(sql, ...params.map(decodeBinding)),
-      this.recordRowsWritten
-    )
-    const columns = [...cursor.columnNames]
-    // A SqlStorage cursor must be fully consumed before any await. Returning a
-    // materialized array here makes that property structural.
-    const rows = Array.from(cursor.raw()).map((values) => ({
-      columns,
-      values: values.map(encodeResult),
-    }))
-    this.stats.queryCalls++
-    this.stats.sqlMs += performance.now() - start
-    return rows
-  }
-}
-
-/** Direct application SQL surface used for initialization and admin reads. */
-export class SqlStorageDirect implements SyncSql {
-  constructor(
-    private readonly sql: SqlStorage,
-    private readonly recordRowsWritten: (rows: number) => void = () => {}
-  ) {}
-
-  exec(sql: string, params: readonly unknown[] = []): void {
-    assertHostSql(sql)
-    trackBillableCursorRows(this.sql.exec(sql, ...params), this.recordRowsWritten)
-  }
-
-  query<Row extends Record<string, unknown> = Record<string, unknown>>(
-    sql: string,
-    params: readonly unknown[] = []
-  ): Row[] {
-    assertHostSql(sql)
-    return trackBillableCursorRows(
-      this.sql.exec(sql, ...params),
-      this.recordRowsWritten
-    ).toArray() as Row[]
-  }
-}
-
-/**
- * Async-compatible consumer mutator surface. Each method fully completes and
- * materializes its SqlStorage operation before its promise resolves, so an
- * existing `await tx.query(...)` cannot carry a cursor across an await.
- */
-export class SqlStorageMutatorTransaction implements MutatorSql {
-  constructor(
-    private readonly direct: SqlStorageDirect,
-    private readonly compileQuery: (ast: unknown) => CompiledQuery
-  ) {}
-
-  async exec(sql: string, params: readonly unknown[] = []): Promise<void> {
-    this.direct.exec(sql, params)
-  }
-
-  async query<Row extends Record<string, unknown> = Record<string, unknown>>(
-    sql: string,
-    params: readonly unknown[] = []
-  ): Promise<Row[]> {
-    return this.direct.query<Row>(sql, params)
-  }
-
-  async queryAst<Row extends Record<string, unknown> = Record<string, unknown>>(
-    ast: unknown
-  ): Promise<Row[]> {
-    const compiled = this.compileQuery(ast)
-    return this.direct.query<Row>(compiled.sql, compiled.params.map(decodeBinding))
-  }
-}

package/src/types.ts

@@ -1,181 +0,0 @@
-export type JsonPrimitive = string | number | boolean | null
-export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }
-
-export type NormalizedClaims = {
-  /** Stable consumer user id used for client-group ownership. */
-  userID: string
-  [claim: string]: JsonValue
-}
-
-export type ZeroSchemaConfig = {
-  readonly tables: Readonly<
-    Record<
-      string,
-      {
-        readonly columns: Readonly<Record<string, { readonly type: string }>>
-        readonly primaryKey: readonly string[]
-      }
-    >
-  >
-}
-
-export interface SyncSql {
-  exec(sql: string, params?: readonly unknown[]): void
-  query<Row extends Record<string, unknown> = Record<string, unknown>>(
-    sql: string,
-    params?: readonly unknown[]
-  ): Row[]
-}
-
-export interface MutatorSql {
-  exec(sql: string, params?: readonly unknown[]): Promise<void>
-  query<Row extends Record<string, unknown> = Record<string, unknown>>(
-    sql: string,
-    params?: readonly unknown[]
-  ): Promise<Row[]>
-  /** Execute a validated Zero AST inside the current application transaction. */
-  queryAst<Row extends Record<string, unknown> = Record<string, unknown>>(
-    ast: JsonValue
-  ): Promise<Row[]>
-}
-
-export type DeferredEffect = () => void | Promise<void>
-
-export type MutatorContext = {
-  claims: NormalizedClaims
-  /** Current Zero mutation identity, when invoked by the production host. */
-  clientID?: string
-  mutationID?: string | number
-  defer(effect: DeferredEffect): void
-}
-
-export type RegisteredMutator = (
-  tx: MutatorSql,
-  args: JsonValue,
-  context: MutatorContext
-) => void | Promise<void>
-
-export type MutatorRegistry = Readonly<Record<string, RegisteredMutator>>
-
-/** Preserve mutator names while making the host-facing registry immutable. */
-export function registerMutators<
-  const Registry extends Record<string, RegisteredMutator>,
->(registry: Registry): Readonly<Registry> {
-  return Object.freeze({ ...registry })
-}
-
-export class MutationApplicationError extends Error {
-  constructor(
-    readonly details: string,
-    message = details
-  ) {
-    super(message)
-    this.name = 'MutationApplicationError'
-  }
-}
-
-export type VisibilityFilter = {
-  /** SQL WHERE fragment only, without the WHERE keyword. */
-  sql: string
-  params?: readonly JsonPrimitive[]
-}
-
-export type VisibilityConfig = {
-  /** True only when every predicate depends on the selected row alone. */
-  rowLocal: boolean | ((claims: NormalizedClaims) => boolean)
-  filter(table: string, claims: NormalizedClaims): VisibilityFilter | undefined
-}
-
-export type QueryResolver = (
-  name: string,
-  args: readonly JsonValue[],
-  claims: NormalizedClaims,
-  env: SyncHostEnv
-) => JsonValue | Promise<JsonValue>
-
-export type PullCaps = {
-  maxChangeRows: number
-  maxChangeBytes: number
-}
-
-export interface SyncHostEnv {
-  SYNC_DO: DurableObjectNamespace
-  ADMIN_KEY?: string
-}
-
-export type ServiceBinding = {
-  fetch(input: string | Request, init?: RequestInit): Promise<Response>
-}
-
-export type UpstreamConfig = {
-  /** Env key for the service binding that owns the app write endpoint and feed. */
-  binding: string
-  /** Path to this namespace on the bound service (for example `/data/<id>`). */
-  namespacePath: string | ((namespace: string) => string)
-  /** Feed page size; the cursor loop continues until the reported head is reached. */
-  changeLimit?: number
-  /** Active wake-socket alarm safety net. Defaults to 15 seconds. */
-  intervalMs?: number
-  /** Billable SQLite rows written by ingest per rolling window. Defaults to 150,000. */
-  ingestBudgetRows?: number
-  /** Rolling ingest budget window. Defaults to five minutes. */
-  ingestBudgetWindowMs?: number
-  /** Initial breaker cooldown. Defaults to one second. */
-  ingestBackoffMs?: number
-  /** Maximum breaker cooldown. Defaults to one minute. */
-  ingestMaxBackoffMs?: number
-}
-
-export type DelegatedPushRetryConfig = {
-  /** Total attempts including the first request. Defaults to 3. */
-  maxAttempts?: number
-  /** Initial exponential delay. Defaults to 100ms. */
-  initialBackoffMs?: number
-  /** Delay cap. Defaults to 1,000ms. */
-  maxBackoffMs?: number
-  /** Per-attempt service-binding timeout. Defaults to 5,000ms. */
-  timeoutMs?: number
-}
-
-export type SyncHostConfig<Env extends SyncHostEnv = SyncHostEnv> = {
-  hostVersion: string
-  schema: ZeroSchemaConfig
-  mutators?: MutatorRegistry
-  /** Absolute app push path on the upstream service binding. */
-  mutateUrl?: string
-  /** Absolute origin used for delegated push requests through the service binding. */
-  mutateOrigin?: string
-  /** Env binding for delegated pushes; defaults to upstream.binding. */
-  mutateBinding?: string
-  delegatedPushRetry?: DelegatedPushRetryConfig
-  /** Required for delegated push; forbidden with local mutators (no dual apply). */
-  upstream?: UpstreamConfig
-  /** Application DDL and optional seed, called before sync-core schema init. */
-  initialize(sql: SyncSql): void
-  authenticate(
-    request: Request,
-    env: Env
-  ): NormalizedClaims | null | Promise<NormalizedClaims | null>
-  /** Authorize the advisory wake socket before selecting a namespace DO.
-   * Browser clients should present a short-lived, namespace-scoped capability
-   * in the query string because WebSocket cannot set request headers. */
-  authorizeWake(request: Request, env: Env): boolean | Promise<boolean>
-  /** Authorize upstream service notifications before selecting a namespace DO. */
-  authorizeNotify(request: Request, env: Env): boolean | Promise<boolean>
-  /** Resolve the first path component or another consumer-defined namespace. */
-  namespace(request: Request): string | null
-  visibility?: VisibilityConfig
-  /** Enable desired-query pulls for this namespace and resolve named queries
-   * into validated Zero ASTs before they reach sync-core. */
-  queryAware?: boolean | ((claims: NormalizedClaims) => boolean)
-  resolveQuery?: QueryResolver
-  /** Server-owned invalidation epoch for permission/schema transforms. */
-  queryTransformVersion?: number | ((claims: NormalizedClaims) => number)
-  /** Enable consumer visibility from the first request. Defaults to false for harnesses. */
-  visibilityEnabled?: boolean
-  retainChanges?: number
-  caps?: Partial<PullCaps>
-  idleTeardownMs?: number
-  wakeCoalesceMs?: number
-  authorizeAdmin?: (request: Request, env: Env) => boolean | Promise<boolean>
-}