Interface: SyncHandlerOptions<S, TCtx>

Defined in: server/src/sync-handler.ts:151

Type Parameters

S

S extends Schema<Record<string, AnyTable>>

TCtx

TCtx

Properties

schema

readonly schema: S

Defined in: server/src/sync-handler.ts:152

executor

readonly executor: SqlExecutor

Defined in: server/src/sync-handler.ts:153

dialect?

readonly optional dialect?: SqlDialect

Defined in: server/src/sync-handler.ts:154

schemaVersion

readonly schemaVersion: string

Defined in: server/src/sync-handler.ts:155

schemaVersionBreakdown?

readonly optional schemaVersionBreakdown?: SchemaHashBreakdown

Defined in: server/src/sync-handler.ts:156

minClientVersion?

readonly optional minClientVersion?: string

Defined in: server/src/sync-handler.ts:157

mutators

readonly mutators: Record<string, Mutator<S, TCtx, any>>

Defined in: server/src/sync-handler.ts:159

auth

readonly auth: (request) => Promise<AuthResult<TCtx>>

Defined in: server/src/sync-handler.ts:160

Parameters

request

Request

Returns

Promise<AuthResult<TCtx>>

basePath?

readonly optional basePath?: string

Defined in: server/src/sync-handler.ts:162

Path prefix; defaults to /sync.

onPushed?

readonly optional onPushed?: (auth) => void | Promise<void>

Defined in: server/src/sync-handler.ts:170

Called once per successful push (i.e. after every mutation batch that changed something). Use it to nudge subscribed clients to pull now — the canonical wiring is a Durable Object SyncCoordinator broadcasting over WebSocket. Kept optional; the client’s poll interval is a working fallback when this is absent.

Parameters

auth

clientGroupID

string

clientID

string

ctx

TCtx

Returns

void | Promise<void>

onError?

readonly optional onError?: (event) => void

Defined in: server/src/sync-handler.ts:181

Observability sink. Called with a discriminated SyncServerError any time the handler swallows or rejects a request — so failed mutations, schema mismatches, and onPushed failures land in your logs / Sentry even though the wire response is friendly.

Parameters

event

SyncServerError

Returns

void

maxMutationsPerPush?

readonly optional maxMutationsPerPush?: number

Defined in: server/src/sync-handler.ts:188

Maximum number of mutations accepted in a single push request. A push exceeding this is rejected with 413 before any mutator runs — a defence against a compromised or buggy client trying to burn D1 write budget. Default: 200.

maxPayloadBytes?

readonly optional maxPayloadBytes?: number

Defined in: server/src/sync-handler.ts:195

Maximum body size accepted for push. Requests larger are rejected with 413 before JSON parsing. Default: 1 MiB. Applied via the Content-Length header when present — clients that omit it are allowed through and the mutation cap catches the rest.

envelopeValidation?

readonly optional envelopeValidation?: { maxCiphertextBytes?: number; allowedKeyIds?: readonly string[]; maxKemCiphertextBytes?: number; }

Defined in: server/src/sync-handler.ts:202

Server-side encryption envelope validator. Called for any value that looks like a plasma Envelope ({ v, alg, keyId, nonce, ct }) in incoming mutation args, so a compromised client can’t push oversized ciphertexts or unknown key ids. Absent → basic shape check only.

maxCiphertextBytes?

readonly optional maxCiphertextBytes?: number

allowedKeyIds?

readonly optional allowedKeyIds?: readonly string[]

maxKemCiphertextBytes?

readonly optional maxKemCiphertextBytes?: number

Cap the kem.ct field of a PQ hybrid envelope (base64 length, pre-decode). ML-KEM-768 ciphertexts are 1088 bytes ≈ 1452 chars base64; the default 4096 leaves headroom for larger PQ primitives without letting a malicious client inflate the KEM ciphertext up to the per-mutation cap. v1.0 zeus W3 fix.

blobs?

readonly optional blobs?: { default: Storage; }

Defined in: server/src/sync-handler.ts:220

Storage adapter map for file() columns. v0.3 only honours a single default entry; per-table override lands in v0.4 (createSyncHandler throws at startup when a non-default storageRef is seen — see spec §Q9 / plan §C2). Required when the schema declares any file() column.

default

readonly default: Storage

readAuthMaxRefs?

readonly optional readAuthMaxRefs?: number

Defined in: server/src/sync-handler.ts:230

Reverse-lookup fan-out cap for blob GET auth. assertCanReadBlob only inspects the newest N refs pointing at a hash; if none of them belong to a row the caller can read, the request is denied even when an older ref would have. This is a performance guard for viral content-addressed assets (see round-4 W-1). Defaults to 128 — bump if you have shared assets referenced by many rows and want exhaustive auth to always find a readable owner.

waitUntil?

readonly optional waitUntil?: (promise) => void

Defined in: server/src/sync-handler.ts:236

Non-blocking Cache API put hook. Typically ctx.waitUntil.bind(ctx) from the fetch handler. When absent the cache write awaits inline; that is safe but stretches p95 for cold-cache blob GETs.

Parameters

promise

Promise<unknown>

Returns

void

requireTableAuth?

readonly optional requireTableAuth?: boolean

Defined in: server/src/sync-handler.ts:248

When true, createSyncHandler refuses to start if any user table in schema declares no auth: { read, write } predicates. Guards against the footgun of shipping a table that authenticated users can freely read across tenants because the TableOptions.auth block was forgotten. Default: false (opt-in).

When you legitimately want a per-tenant-blind table (a public announcement feed, a lookup table), pass auth: { read: () => true, write: () => true } explicitly — the flag catches only the forgotten case.

maxPullPageSize?

readonly optional maxPullPageSize?: number

Defined in: server/src/sync-handler.ts:255

Server-side upper bound on ?limit=N for pull responses. Clients that don’t pass ?limit are capped at this many rows too. Guards against a single pull dragging back an unbounded change log segment. Default: 1000.

onMetric?

readonly optional onMetric?: (event) => void

Defined in: server/src/sync-handler.ts:263

Observability sink for numeric metrics. Fires on every push / pull / blob endpoint completion with the relevant timing and outcome — wire to Prometheus / Analytics Engine / whatever your infra ingests. Absent → no measurement is recorded (matches v1.0 behaviour).

Parameters

event

PlasmaMetric

Returns

void

audit?

readonly optional audit?: AuditLogOptions<TCtx>

Defined in: server/src/sync-handler.ts:270

Enables the opt-in audit log primitive. Undefined (or omitted) means “no audit hooks fire, no schema check runs, no DDL is expected.” Set this together with generated artifacts emitted with audit DDL — the schema and runtime flags must match or the first request will fail-fast.