Interface: SyncHandlerOptions<S, TCtx>

Interface: SyncHandlerOptions<S, TCtx>

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

Type Parameters

S

S extends Schema<Record<string, AnyTable>>

TCtx

TCtx

Properties

schema

readonly schema: S

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

---

executor

readonly executor: SqlExecutor

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

---

dialect?

readonly optional dialect?: SqlDialect

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

---

schemaVersion

readonly schemaVersion: string

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

---

mutators

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

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

---

auth

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

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

Parameters

request

Request

Returns

Promise<AuthResult<TCtx>>

---

basePath?

readonly optional basePath?: string

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

Path prefix; defaults to /sync.

---

onPushed?

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

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

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:144

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:151

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:158

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:165

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:183

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:193

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:199

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