orez-sync-cf-host 0.4.52

package/src/index.ts

@@ -0,0 +1,22 @@
+export { createSyncDurableObject, createSyncWorker } from './host.js'
+export { MutationApplicationError, registerMutators } from './types.js'
+export type {
+  DeferredEffect,
+  JsonPrimitive,
+  JsonValue,
+  MutatorContext,
+  MutatorRegistry,
+  MutatorSql,
+  NormalizedClaims,
+  PullCaps,
+  QueryResolver,
+  RegisteredMutator,
+  SyncHostConfig,
+  SyncHostEnv,
+  ServiceBinding,
+  SyncSql,
+  UpstreamConfig,
+  VisibilityConfig,
+  VisibilityFilter,
+  ZeroSchemaConfig,
+} from './types.js'

package/src/ingest-harness-worker.ts

@@ -0,0 +1,119 @@
+import { WorkerEntrypoint } from 'cloudflare:workers'
+
+import { ZeroDO } from '../../../src/cf-do/worker.js'
+import { createSyncDurableObject, createSyncWorker } from './index.js'
+
+import type { SyncHostConfig, SyncHostEnv, ZeroSchemaConfig } from './index.js'
+
+const schema = {
+  tables: {
+    item: {
+      columns: {
+        id: { type: 'string' },
+        label: { type: 'string' },
+        rank: { type: 'number' },
+        done: { type: 'boolean' },
+        meta: { type: 'json' },
+      },
+      primaryKey: ['id'],
+    },
+  },
+} as const satisfies ZeroSchemaConfig
+
+type Fetcher = { fetch(input: string | Request, init?: RequestInit): Promise<Response> }
+interface Env extends SyncHostEnv {
+  DATA: Fetcher
+  APP: Fetcher
+  UPSTREAM_DO: DurableObjectNamespace
+}
+
+const config: SyncHostConfig<Env> = {
+  hostVersion: 'upstream-ingest-harness',
+  schema,
+  mutateUrl: '/api/zero/push',
+  mutateBinding: 'APP',
+  upstream: {
+    binding: 'DATA',
+    namespacePath: (namespace) => `/${namespace}`,
+    changeLimit: 2,
+    intervalMs: 1_000,
+  },
+  initialize(sql) {
+    sql.exec(
+      'CREATE TABLE IF NOT EXISTS item (id TEXT PRIMARY KEY, label TEXT NOT NULL, rank REAL NOT NULL, done INTEGER NOT NULL, meta TEXT)'
+    )
+  },
+  authenticate(request) {
+    const userID = request.headers.get('authorization')?.match(/^Bearer token-(.+)$/)?.[1]
+    return userID ? { userID } : null
+  },
+  namespace(request) {
+    return new URL(request.url).pathname.split('/')[1] || null
+  },
+}
+
+export const SyncDurableObject = createSyncDurableObject(config)
+export { ZeroDO }
+
+async function upstreamFetch(request: Request, env: Env): Promise<Response> {
+  const url = new URL(request.url)
+  const [, namespace, ...rest] = url.pathname.split('/')
+  if (!namespace) return new Response('namespace required', { status: 400 })
+  const stub = env.UPSTREAM_DO.get(env.UPSTREAM_DO.idFromName(namespace))
+  const exec = async (sql: string, params: unknown[] = []) => {
+    const response = await stub.fetch('https://upstream.invalid/exec', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ sql, params }),
+    })
+    if (!response.ok) throw new Error(`upstream init failed: ${await response.text()}`)
+  }
+  await exec(
+    'CREATE TABLE IF NOT EXISTS item (id TEXT PRIMARY KEY, label TEXT NOT NULL, rank REAL NOT NULL, done INTEGER NOT NULL, meta TEXT)'
+  )
+  await exec(
+    'CREATE TABLE IF NOT EXISTS _zero_schema_tables (name TEXT PRIMARY KEY, schema_json TEXT NOT NULL)'
+  )
+  await exec(
+    'INSERT OR IGNORE INTO _zero_schema_tables (name, schema_json) VALUES (?, ?)',
+    ['item', JSON.stringify(schema.tables.item)]
+  )
+  url.pathname = `/${rest.join('/')}`
+  return stub.fetch(new Request(url, request))
+}
+
+/** Self service-binding target backed by the real ZeroSqlDO. */
+export class DataService extends WorkerEntrypoint<Env> {
+  fetch(request: Request): Promise<Response> {
+    const pathname = new URL(request.url).pathname
+    if (!pathname.endsWith('/changes') && !pathname.endsWith('/snapshot')) {
+      return Promise.resolve(
+        new Response('DATA route rejected non-feed request', { status: 418 })
+      )
+    }
+    return upstreamFetch(request, this.env)
+  }
+}
+
+export class AppService extends WorkerEntrypoint<Env> {
+  fetch(request: Request): Promise<Response> {
+    if (!new URL(request.url).pathname.endsWith('/api/zero/push')) {
+      return Promise.resolve(
+        new Response('APP route rejected non-push request', { status: 418 })
+      )
+    }
+    return upstreamFetch(request, this.env)
+  }
+}
+
+const syncWorker = createSyncWorker(config)
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url)
+    if (url.pathname.startsWith('/upstream/')) {
+      url.pathname = url.pathname.slice('/upstream'.length)
+      return upstreamFetch(new Request(url, request), env)
+    }
+    return syncWorker.fetch!(request as never, env, ctx) as Promise<Response>
+  },
+}

package/src/platform-probe-worker.ts

@@ -0,0 +1,304 @@
+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 scheduler.wait(1)
+      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 scheduler.wait(1)
+      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 scheduler.wait(1)
+    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
+
+        // This await is deliberately inside the storage transaction and before
+        // the remaining SQL operations. M0 exists to prove this contract.
+        await scheduler.wait(1)
+        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 scheduler.wait(1)
+          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

@@ -0,0 +1,168 @@
+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) {}
+
+  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()
+    this.sql.exec(sql, ...params.map(decodeBinding))
+    this.stats.execCalls++
+    this.stats.sqlMs += performance.now() - start
+  }
+
+  query(sql: string, params: WireValue[]): WireRow[] {
+    assertHostSql(sql)
+    const start = performance.now()
+    const cursor = this.sql.exec(sql, ...params.map(decodeBinding))
+    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) {}
+
+  exec(sql: string, params: readonly unknown[] = []): void {
+    assertHostSql(sql)
+    this.sql.exec(sql, ...params)
+  }
+
+  query<Row extends Record<string, unknown> = Record<string, unknown>>(
+    sql: string,
+    params: readonly unknown[] = []
+  ): Row[] {
+    assertHostSql(sql)
+    return this.sql.exec(sql, ...params).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))
+  }
+}