on-zero 0.7.2-1784530701923 → 0.7.2

package/src/syncHost.test.ts

@@ -0,0 +1,223 @@
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite'
+
+import { defineQueries, defineQuery } from '@rocicorp/zero'
+import * as v from 'valibot'
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+
+import { getScopedAuthData } from './helpers/mutatorContext'
+import { zeroHttpFixtureSchema } from './httpPull/fixtureSchema'
+import { createZeroSyncHostAdapter } from './syncHost'
+import { zql } from './zql'
+
+import type { SqlStatementMetadata, SQLiteQueryFormat } from './createZeroSQLiteServer'
+import type {
+  SyncHostApplicationTransaction,
+  SyncHostMutatorContext,
+  SyncHostTransactionExecutor,
+} from './syncHost'
+
+const queries = defineQueries({
+  project: {
+    byOwner: defineQuery(v.object({ ownerId: v.string() }), ({ args }) =>
+      zql.project.where('ownerId', args.ownerId),
+    ),
+  },
+})
+
+describe('createZeroSyncHostAdapter', () => {
+  let db: DatabaseSync
+  let executor: SyncHostTransactionExecutor
+  let transaction: SyncHostApplicationTransaction
+  let lastQueryFormat: SQLiteQueryFormat | undefined
+  let statements: SqlStatementMetadata[]
+
+  beforeEach(() => {
+    db = new DatabaseSync(':memory:')
+    db.exec(
+      'CREATE TABLE project (id TEXT PRIMARY KEY, ownerId TEXT NOT NULL, name TEXT NOT NULL)',
+    )
+    statements = []
+    executor = {
+      exec(sql, params = [], metadata) {
+        if (metadata) statements.push(metadata)
+        const result = db.prepare(sql).run(...(params as SQLInputValue[]))
+        return { changes: Number(result.changes) }
+      },
+      query<Row extends Record<string, unknown>>(sql, params = []) {
+        return db.prepare(sql).all(...(params as SQLInputValue[])) as Row[]
+      },
+      queryAst<Result>(_ast, format) {
+        lastQueryFormat = format
+        const rows = db.prepare('SELECT * FROM project ORDER BY id').all()
+        return (format.singular ? rows[0] : rows) as Result
+      },
+    }
+    transaction = async (work) => {
+      const effects: Array<() => void | Promise<void>> = []
+      db.exec('BEGIN')
+      try {
+        const value = await work(executor, {
+          defer(effect) {
+            effects.push(effect)
+          },
+        })
+        db.exec('COMMIT')
+        for (const effect of effects) await effect()
+        return value
+      } catch (error) {
+        db.exec('ROLLBACK')
+        throw error
+      }
+    }
+  })
+
+  afterEach(() => {
+    db.close()
+  })
+
+  test('adapts pipe-named mutators, auth, validation, and deferred effects', async () => {
+    let effectAuthID: string | undefined
+    let validatedAuthID: string | undefined
+    const adapter = createZeroSyncHostAdapter({
+      schema: zeroHttpFixtureSchema,
+      models: {
+        project: {
+          mutate: {
+            create: async ({ authData, server, tx }, value: Record<string, unknown>) => {
+              expect(authData?.id).toBe('u1')
+              await tx.mutate.project.insert(value as never)
+              server?.enqueueTask(async () => {
+                effectAuthID = getScopedAuthData()?.id as string
+              })
+            },
+          },
+        },
+      },
+      createServerActions: () => ({}),
+      queries,
+      transaction,
+      validateMutation({ authData }) {
+        validatedAuthID = authData?.id as string
+      },
+    })
+
+    expect(Object.keys(adapter.mutators)).toEqual([
+      'project|create',
+      '_zero_cleanupResults',
+    ])
+    await transaction((tx, context) =>
+      adapter.mutators['project|create']!(
+        tx,
+        { id: 'p1', ownerId: 'u1', name: 'first' },
+        mutationContext(context),
+      ),
+    )
+
+    expect(db.prepare('SELECT * FROM project').all()).toEqual([
+      { id: 'p1', ownerId: 'u1', name: 'first' },
+    ])
+    expect(validatedAuthID).toBe('u1')
+    expect(effectAuthID).toBe('u1')
+    expect(statements).toEqual([
+      { table: 'project', publicTable: 'project', kind: 'insert' },
+    ])
+  })
+
+  test('returns a structural application error and drops rolled-back effects', async () => {
+    let effectRuns = 0
+    const adapter = createZeroSyncHostAdapter({
+      schema: zeroHttpFixtureSchema,
+      models: {
+        project: {
+          mutate: {
+            reject: async ({ server, tx }, value: Record<string, unknown>) => {
+              await tx.mutate.project.insert(value as never)
+              server?.enqueueTask(async () => {
+                effectRuns++
+              })
+              throw new Error('denied')
+            },
+          },
+        },
+      },
+      createServerActions: () => ({}),
+      transaction,
+    })
+
+    const error = await transaction((tx, context) =>
+      adapter.mutators['project|reject']!(
+        tx,
+        { id: 'p1', ownerId: 'u1', name: 'must roll back' },
+        mutationContext(context),
+      ),
+    ).catch((caught) => caught)
+
+    expect(error).toMatchObject({
+      name: 'MutationApplicationError',
+      message: 'denied',
+      details: 'denied',
+    })
+    expect(db.prepare('SELECT * FROM project').all()).toEqual([])
+    expect(effectRuns).toBe(0)
+  })
+
+  test('uses the host queryAst compiler surface for direct server queries', async () => {
+    db.prepare('INSERT INTO project (id, ownerId, name) VALUES (?, ?, ?)').run(
+      'p1',
+      'u1',
+      'first',
+    )
+    const adapter = createZeroSyncHostAdapter({
+      schema: zeroHttpFixtureSchema,
+      models: {},
+      createServerActions: () => ({}),
+      transaction,
+    })
+
+    await expect(adapter.server.query((q) => q.project.one())).resolves.toEqual({
+      id: 'p1',
+      ownerId: 'u1',
+      name: 'first',
+    })
+    expect(lastQueryFormat).toEqual({ relationships: {}, singular: true })
+  })
+
+  test('resolves auth-sensitive named queries and runs query validation', async () => {
+    let validation: unknown
+    const adapter = createZeroSyncHostAdapter({
+      schema: zeroHttpFixtureSchema,
+      models: {},
+      createServerActions: () => ({}),
+      queries,
+      transaction,
+      validateQuery(args) {
+        validation = args
+      },
+    })
+
+    const ast = await adapter.resolveQuery('project|byOwner', [{ ownerId: 'u1' }], {
+      userID: 'u1',
+      role: 'member',
+    })
+
+    expect(ast).toMatchObject({ table: 'project' })
+    expect(JSON.stringify(ast)).toContain('ownerId')
+    expect(JSON.stringify(ast)).toContain('u1')
+    expect(validation).toEqual({
+      authData: { id: 'u1', role: 'member', userID: 'u1' },
+      queryName: 'project|byOwner',
+      params: { ownerId: 'u1' },
+    })
+  })
+})
+
+function mutationContext(context: {
+  defer(effect: () => void | Promise<void>): void
+}): SyncHostMutatorContext {
+  return {
+    ...context,
+    claims: { userID: 'u1', role: 'member' },
+    clientID: 'client-a',
+    mutationID: '1',
+  }
+}

package/src/syncHost.ts

@@ -0,0 +1,294 @@
+import { asQueryInternals } from '@rocicorp/zero/bindings'
+import { createBuilder, type Schema as ZeroSchema } from '@rocicorp/zero'
+
+import { createPermissions } from './createPermissions'
+import {
+  createZeroDirectServer,
+  resolveServerQuery,
+  type ZeroDirectServer,
+  type ZeroServerCommonOptions,
+} from './createZeroDirectServer'
+import {
+  createSQLiteDatabase,
+  createZeroSQLiteTransaction,
+  defaultLedgerTables,
+  encodeSQLiteValue,
+  type SqlStatementMetadata,
+  type SQLiteExecResult,
+  type SQLiteTransactionExecutor,
+  type SQLiteTransactionProvider,
+  type ZeroSQLiteTransactionOptions,
+} from './sqliteRuntime'
+import { createMutators } from './helpers/createMutators'
+import { runWithAuthScope } from './helpers/mutatorContext'
+import { runWithQueryContext } from './helpers/queryContext'
+import { setEnvironment, setSchema } from './state'
+
+import type { AsyncTaskEntry, AuthData, GenericModels } from './types'
+
+export type SyncHostJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | SyncHostJsonValue[]
+  | { [key: string]: SyncHostJsonValue }
+
+export type SyncHostClaims = {
+  userID: string
+  [claim: string]: SyncHostJsonValue
+}
+
+export type SyncHostTransactionContext = {
+  defer(effect: () => void | Promise<void>): void
+}
+
+export type SyncHostTransactionExecutor = {
+  exec(
+    sql: string,
+    params?: readonly unknown[],
+    metadata?: SqlStatementMetadata,
+  ): SQLiteExecResult | Promise<SQLiteExecResult>
+  query<Row extends Record<string, unknown> = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Row[] | Promise<Row[]>
+  queryAst<Result = unknown>(
+    ast: SyncHostJsonValue,
+    format: import('./sqliteRuntime').SQLiteQueryFormat,
+    queryName?: string,
+  ): Result | Promise<Result>
+}
+
+export type SyncHostMutatorContext = SyncHostTransactionContext & {
+  claims: SyncHostClaims
+  clientID?: string
+  mutationID?: string | number
+}
+
+export type SyncHostRegisteredMutator = (
+  tx: SyncHostTransactionExecutor,
+  args: SyncHostJsonValue,
+  context: SyncHostMutatorContext,
+) => void | Promise<void>
+
+export type SyncHostApplicationTransaction = <Value>(
+  work: (
+    tx: SyncHostTransactionExecutor,
+    context: SyncHostTransactionContext,
+  ) => Value | Promise<Value>,
+) => Promise<Value>
+
+export type CreateZeroSyncHostAdapterOptions<
+  Schema extends ZeroSchema,
+  Models extends GenericModels,
+  ServerActions extends Record<string, unknown>,
+> = Omit<
+  ZeroServerCommonOptions<Schema, Models, ServerActions>,
+  'defaultMutateAuthData'
+> &
+  ZeroSQLiteTransactionOptions<Schema> & {
+    transaction: SyncHostApplicationTransaction
+    mapAuthData?: (claims: SyncHostClaims) => AuthData
+    defaultMutateAuthData?: Pick<AuthData, 'email' | 'id'> & Partial<AuthData>
+  }
+
+export type ZeroSyncHostAdapter<
+  Schema extends ZeroSchema,
+  Models extends GenericModels,
+> = {
+  mutators: Readonly<Record<string, SyncHostRegisteredMutator>>
+  resolveQuery(
+    name: string,
+    args: readonly SyncHostJsonValue[],
+    claims: SyncHostClaims,
+  ): Promise<SyncHostJsonValue>
+  server: ZeroDirectServer<Schema, Models>
+}
+
+export class MutationApplicationError extends Error {
+  constructor(
+    readonly details: string,
+    message = details,
+  ) {
+    super(message)
+    this.name = 'MutationApplicationError'
+  }
+}
+
+export function createZeroSyncHostAdapter<
+  Schema extends ZeroSchema,
+  Models extends GenericModels,
+  ServerActions extends Record<string, unknown>,
+>({
+  encodeValue,
+  mapAuthData = defaultMapAuthData,
+  transaction,
+  ...options
+}: CreateZeroSyncHostAdapterOptions<Schema, Models, ServerActions>): ZeroSyncHostAdapter<
+  Schema,
+  Models
+> {
+  setSchema(options.schema, createBuilder(options.schema))
+  setEnvironment('server')
+
+  const permissions = createPermissions({
+    environment: 'server',
+    schema: options.schema,
+    adminRoleMode: options.defaultAllowAdminRole ?? 'all',
+  })
+  const transactionOptions = {
+    encodeValue,
+    schema: options.schema,
+  }
+  const mutators: Record<string, SyncHostRegisteredMutator> = {}
+
+  for (const [modelName, model] of Object.entries(options.models)) {
+    for (const mutatorName of Object.keys(model.mutate ?? {})) {
+      mutators[`${modelName}|${mutatorName}`] = async (executor, args, context) => {
+        const authData = mapAuthData(context.claims)
+        const asyncTaskEntries: AsyncTaskEntry[] = []
+        const modelMutators = createMutators({
+          enqueueTask(task, opts) {
+            asyncTaskEntries.push({ task, barrier: opts?.barrier === true })
+          },
+          authData,
+          can: permissions.can,
+          createServerActions: options.createServerActions,
+          environment: 'server',
+          models: options.models,
+          mutationValidators: options.mutations,
+          validateMutation: options.validateMutation,
+        }) as Record<
+          string,
+          Record<string, (tx: unknown, args: unknown) => Promise<void>>
+        >
+        const mutation = modelMutators[modelName]?.[mutatorName]
+        if (!mutation)
+          throw new Error(`unknown on-zero mutator: ${modelName}|${mutatorName}`)
+
+        const mutationID = numericMutationID(context.mutationID)
+        const onZeroTransaction = createZeroSQLiteTransaction(
+          transactionOptions,
+          toSQLiteExecutor(executor),
+          {
+            clientGroupID: 'orez-sync-host',
+            clientID: context.clientID ?? '',
+            mutationID,
+            upstreamSchema: 'orez-sync-host',
+          },
+        )
+        try {
+          await mutation(onZeroTransaction, args)
+        } catch (error) {
+          throw asMutationApplicationError(error)
+        }
+        for (const { task } of asyncTaskEntries) {
+          context.defer(() => runWithAuthScope(authData, task))
+        }
+      }
+    }
+  }
+
+  // orez owns result retention and lmids. zero clients may still emit this
+  // protocol mutation, so accepting it advances the host ledger without
+  // creating a second on-zero cleanup ledger.
+  mutators._zero_cleanupResults = async () => {}
+
+  const transactionProvider: SQLiteTransactionProvider = (work) =>
+    transaction((executor) => work(toSQLiteExecutor(executor)))
+  const directDatabaseOptions = {
+    encodeValue: encodeValue ?? encodeSQLiteValue,
+    initializedLedgers: new Set<string>(),
+    ledgerTables: defaultLedgerTables,
+    schema: options.schema,
+    transactionProvider,
+  }
+  const direct = createZeroDirectServer({
+    ...options,
+    createDatabase: () => createSQLiteDatabase(directDatabaseOptions),
+  })
+
+  return {
+    mutators: Object.freeze(mutators),
+    async resolveQuery(
+      name: string,
+      args: readonly SyncHostJsonValue[],
+      claims: SyncHostClaims,
+    ): Promise<SyncHostJsonValue> {
+      if (!options.queries) {
+        throw new Error(
+          'No queries registered with createZeroSyncHostAdapter. Pass the syncedQueries registry via the queries option.',
+        )
+      }
+      const authData = mapAuthData(claims)
+      const query = await runWithQueryContext({ authData }, () =>
+        resolveServerQuery({
+          authData,
+          args: args[0],
+          name,
+          permissions,
+          queries: options.queries!,
+          validateQuery: options.validateQuery,
+        }),
+      )
+      return asQueryInternals(query as never).ast as unknown as SyncHostJsonValue
+    },
+    server: {
+      mutate: direct.mutate,
+      query: direct.query,
+      transaction: direct.transaction,
+    },
+  }
+}
+
+function defaultMapAuthData(claims: SyncHostClaims): AuthData {
+  return {
+    ...claims,
+    id: typeof claims.id === 'string' ? claims.id : claims.userID,
+  } as AuthData
+}
+
+function toSQLiteExecutor(
+  executor: SyncHostTransactionExecutor,
+): SQLiteTransactionExecutor {
+  return {
+    exec(sql, params, metadata) {
+      return executor.exec(sql, params, metadata)
+    },
+    query<Row extends Record<string, unknown>>(sql: string, params?: readonly unknown[]) {
+      return executor.query<Row>(sql, params)
+    },
+    queryAst<Result>(ast, format, queryName) {
+      return executor.queryAst<Result>(
+        ast as unknown as SyncHostJsonValue,
+        format,
+        queryName,
+      )
+    },
+  }
+}
+
+function numericMutationID(value: string | number | undefined): number {
+  if (value === undefined) return 0
+  const numeric = typeof value === 'number' ? value : Number(value)
+  if (!Number.isSafeInteger(numeric) || numeric < 0) {
+    throw new TypeError(`invalid Zero mutation ID: ${value}`)
+  }
+  return numeric
+}
+
+function asMutationApplicationError(error: unknown): MutationApplicationError {
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    (error as { name?: unknown }).name === 'MutationApplicationError' &&
+    typeof (error as { details?: unknown }).details === 'string'
+  ) {
+    return error as MutationApplicationError
+  }
+  const message = error instanceof Error ? error.message : String(error)
+  const applicationError = new MutationApplicationError(message)
+  if (error instanceof Error && error.stack) applicationError.stack = error.stack
+  return applicationError
+}

package/src/types.ts

@@ -66,6 +66,11 @@ export type AsyncTaskOptions = {
   barrier?: boolean
 }
 
+export type AsyncTaskEntry = {
+  task: AsyncTask
+  barrier: boolean
+}
+
 /**
  * ➗0️⃣ END OVERRIDDEN TYPES
  */

package/src/zeroRunner.ts

@@ -37,7 +37,7 @@ export function getAmbientRunner(instance?: { runner: ZeroRunner | null }): Zero
 
   if (!runner) {
     throw new Error(
-      'Zero runner not initialized. Ensure ProvideZero is mounted or server bindings are active.',
+      'Zero runner not initialized. Ensure ProvideZero is mounted (client) or createZeroServer is called (server).',
     )
   }
 

package/test-fixtures/server-return-types.ts

@@ -1,8 +1,19 @@
-import { createOrezBindings } from 'on-zero/orez'
+import {
+  createZeroServer,
+  runAsyncTaskEntries,
+  type AsyncTaskEntry,
+  type BackgroundTaskScheduler,
+  type HandleMutationRequestOptions,
+} from 'on-zero/server'
+import { createZeroSQLiteServer, type SqlStatementMetadata } from 'on-zero/sqlite'
 
+import {
+  runAsyncTaskEntries as runAsyncTaskEntriesFromRoot,
+  type Config,
+  type MutatorContext,
+  type RunAsyncTaskEntriesOptions,
+} from 'on-zero'
 import type { Schema as ZeroSchema } from '@rocicorp/zero'
-import type { NormalizedClaims, SyncExecutor } from 'orez/sync-executor'
-import type { Config, MutatorContext } from 'on-zero'
 
 type AppAuthData = {
   email: string
@@ -25,31 +36,57 @@ type Models = {
 }
 
 type Actions = Record<string, never>
+type PostgresServer = ReturnType<typeof createZeroServer<ZeroSchema, Models, Actions>>
+type SQLiteServer = ReturnType<typeof createZeroSQLiteServer<ZeroSchema, Models, Actions>>
 
-const bindings = createOrezBindings<ZeroSchema, Models, Actions>({
-  schema: {} as ZeroSchema,
-  models: {} as Models,
-  createServerActions: () => ({}),
-})
-
-declare const executor: SyncExecutor<ZeroSchema>
-const server = bindings.server(executor)
+declare const postgresServer: PostgresServer
+declare const sqliteServer: SQLiteServer
+declare const taskEntries: AsyncTaskEntry[]
 
 const authData: Config['authData'] = {
   email: 'admin@example.com',
   id: 'admin',
   role: 'admin',
 }
-const claims: NormalizedClaims = {
-  email: authData.email,
-  role: authData.role ?? null,
-  userID: authData.id,
+
+const sqliteWrite: SqlStatementMetadata = {
+  table: 'project_records',
+  publicTable: 'project',
+  kind: 'upsert',
+}
+void sqliteWrite
+
+void runAsyncTaskEntries(taskEntries, {
+  background(promise) {
+    void promise
+  },
+})
+
+const rootTaskOptions: RunAsyncTaskEntriesOptions = {
+  background(promise) {
+    void promise
+  },
+}
+void runAsyncTaskEntriesFromRoot(taskEntries, rootTaskOptions)
+
+const scheduleBackgroundTask: BackgroundTaskScheduler = (promise) => {
+  void promise
+}
+const mutationRequest: HandleMutationRequestOptions = {
+  authData,
+  request: new Request('https://example.com/api/zero/push'),
+  scheduleBackgroundTask,
 }
+void postgresServer.handleMutationRequest(mutationRequest)
 
-void bindings.resolveQuery('project|byID', [{ id: 'project' }], claims)
-void server.mutate.project.create({ id: 'project' }, { authData })
-void server.transaction(claims, async (tx) => tx.location)
-void server.query(claims, () => null as never)
+postgresServer.mutate.project.create(
+  { id: 'pg' },
+  { authData: { email: authData.email, id: authData.id, role: authData.role } },
+)
+sqliteServer.mutate.project.create(
+  { id: 'sqlite' },
+  { authData: { email: authData.email, id: authData.id, role: authData.role } },
+)
 
-// @ts-expect-error mutation argument types remain enforced through the Orez facade
-void server.mutate.project.create({ id: 42 }, { authData })
+// @ts-expect-error consumer auth augmentation must remain enforced
+postgresServer.mutate.project.create({ id: 'invalid' }, { authData: { id: 'admin' } })

package/types/asyncTasks.d.ts

@@ -0,0 +1,11 @@
+type AsyncTaskEntry = {
+    task: () => Promise<void>;
+    barrier: boolean;
+};
+export type RunAsyncTaskEntriesOptions = {
+    /** Receives the background-task promise. Omit this to await all entries. */
+    background?: (promise: Promise<void>) => void;
+};
+export declare function runAsyncTaskEntries(entries: readonly AsyncTaskEntry[], { background }?: RunAsyncTaskEntriesOptions): Promise<void>;
+export {};
+//# sourceMappingURL=asyncTasks.d.ts.map

package/types/asyncTasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncTasks.d.ts","sourceRoot":"","sources":["../src/asyncTasks.ts"],"names":[],"mappings":"AAAA,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAA;CAC9C,CAAA;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,EAAE,UAAU,EAAE,GAAE,0BAA+B,GAC9C,OAAO,CAAC,IAAI,CAAC,CAsBf"}