routier-collection / plugins/replication/src / HttpSwrDbPluginOptions
Interface: HttpSwrDbPluginOptions
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:91
SWR-specific options for HttpSwrDbPlugin.
Extends
Properties
getUrl()
getUrl: (
collectionName) =>string
Defined in: plugins/replication/src/HttpDbPlugin.ts:48
Parameters
collectionName
string
Returns
string
Inherited from
databaseName?
optionaldatabaseName:string
Defined in: plugins/replication/src/HttpDbPlugin.ts:58
See IDbPlugin.databaseName. getUrl is a caller-supplied function of collection name, so there is no origin this plugin can read without inventing a collection to ask about — hence a plain option with a shared default.
Set it whenever an application talks to more than one HTTP backend over the same schema: leaving both on the default makes them one database as far as subscriptions are concerned, and each would be notified of the other's writes.
Inherited from
HttpPluginOptions.databaseName
getHeaders()?
optionalgetHeaders: () =>Record<string,string> |Promise<Record<string,string>>
Defined in: plugins/replication/src/HttpDbPlugin.ts:60
Headers for every request (e.g. Authorization). Can be async. Re-evaluated per retry attempt.
Returns
Record<string, string> | Promise<Record<string, string>>
Inherited from
ignoreQueryForCollections?
optionalignoreQueryForCollections:string[]
Defined in: plugins/replication/src/HttpDbPlugin.ts:65
Collection names for which to ignore the query and select everything. No filter, sort, skip, or take is sent; server returns full allowed set.
Inherited from
HttpPluginOptions.ignoreQueryForCollections
queryRetryMaxAttempts?
optionalqueryRetryMaxAttempts:number
Defined in: plugins/replication/src/HttpDbPlugin.ts:75
Max number of query attempts (including initial). Default 10. 401/403 stop immediately.
Inherited from
HttpPluginOptions.queryRetryMaxAttempts
requestTimeoutMs?
optionalrequestTimeoutMs:number
Defined in: plugins/replication/src/HttpDbPlugin.ts:77
Per-request timeout (ms); a hung connection fails instead of stalling forever. Default 30_000; 0 disables.
Inherited from
HttpPluginOptions.requestTimeoutMs
minRequestIntervalMs?
optionalminRequestIntervalMs:number
Defined in: plugins/replication/src/HttpDbPlugin.ts:86
Minimum gap between requests to the same URL (reads) or collection (writes). Default 100.
This plugin is the only place HTTP actually leaves the process, so pacing lives here: a composing plugin cannot leak past it, and an app using this plugin directly gets the same protection. Concurrent GETs for one URL collapse into a single request. 0 removes the gap; calls for one key still never overlap.
Inherited from
HttpPluginOptions.minRequestIntervalMs
writeBatchDelayMs?
optionalwriteBatchDelayMs:number
Defined in: plugins/replication/src/HttpDbPlugin.ts:94
Quiet window (ms) used to batch writes to the same URL. Default 25.
Every POST accepted during the window contributes its adds/updates/removes (and opIds) to one request. The timer restarts when another write arrives, so a burst of ten saves becomes one POST rather than ten serialized POSTs. Set to 0 to disable batching.
Inherited from
HttpPluginOptions.writeBatchDelayMs
onAuthError?
optionalonAuthError:AuthErrorHandler
Defined in: plugins/replication/src/HttpDbPlugin.ts:100
Called when the remote returns 401 or 403 (query and bulkPersist; use event.context to distinguish). Return/resolve true to signal re-auth succeeded — the failed operation then retries once with fresh headers.
Inherited from
translateRemoteResponse()?
optionaltranslateRemoteResponse: (schema,data) =>unknown
Defined in: plugins/replication/src/HttpDbPlugin.ts:102
Parameters
schema
CompiledSchema<UnknownRecord>
data
unknown
Returns
unknown
Inherited from
HttpPluginOptions.translateRemoteResponse
autoSync?
optionalautoSync:false|AutoSyncOptions
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:100
Background sync policy. Omit for the automatic default (retry on a backing-off timer plus an immediate flush when connectivity returns), pass an object to tune it, or pass false to turn it off entirely and drive syncNow() yourself.
Turning it off does not turn off queueing — changes are still recorded durably before every ack. It only means nothing replays them until you ask.
onSync()?
optionalonSync: (outcome) =>void
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:105
Called after every flush, automatic or manual, with what it moved. Use it for a "last synced" indicator or to refresh a pending count.
Parameters
outcome
Returns
void
postOnPersist?
optionalpostOnPersist:boolean
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:122
Whether a save also POSTs immediately, or is left to the batching flush. Default true.
true is the low-latency path: the write enters HttpDbPlugin's short batching window immediately, and its response can be reconciled through translatePersistResponse. Rapid writes to the same URL share one POST by default (writeBatchDelayMs controls the window), while an isolated write pays only that short delay.
false acknowledges locally, records the change durably as always, and leaves delivery to the paced queue flush — one request per collection per flush, however many saves went into it. This adds up to autoSync.delayMs of latency and skips echo reconciliation (the flush has no schema to translate with), but is useful when delivery should happen only on the background/manual sync cadence.
With autoSync: false as well, nothing is delivered until you call syncNow().
maxAgeMs?
optionalmaxAgeMs:number
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:124
Max time (ms) to consider cache fresh; after this, the next read triggers a background revalidate. Default 60_000.
bulkPersistRetryBaseDelayMs?
optionalbulkPersistRetryBaseDelayMs:number
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:126
Base delay (ms) for exponential backoff on bulkPersist retry. Default 1000.
bulkPersistRetryMaxDelayMs?
optionalbulkPersistRetryMaxDelayMs:number
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:128
Max delay (ms) between bulkPersist retries. Default 60_000.
bulkPersistRetryMaxAttempts?
optionalbulkPersistRetryMaxAttempts:number
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:130
Max number of bulkPersist attempts (including initial). Default 10. Auth errors (401/403) stop immediately.
queryRetryBaseDelayMs?
optionalqueryRetryBaseDelayMs:number
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:132
Passed to HttpDbPlugin (query retry is handled there). Base delay (ms) for backoff. Default 1000.
Overrides
HttpPluginOptions.queryRetryBaseDelayMs
queryRetryMaxDelayMs?
optionalqueryRetryMaxDelayMs:number
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:134
Passed to HttpDbPlugin (query retry is handled there). Max delay (ms) between retries. Default 60_000.
Overrides
HttpPluginOptions.queryRetryMaxDelayMs
onRevalidateError()?
optionalonRevalidateError: (error,context) =>void
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:139
Called when background revalidate fails (e.g. offline, network error). Use for logging or toasts. Revalidate failures are not reported back via done(); the UI keeps showing cached data.
Parameters
error
Error
context
collectionName
string
cacheKey?
string
Returns
void
onSyncDeadLetter()?
optionalonSyncDeadLetter: (changes,error) =>void
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:145
Called when the queue permanently gives up on changes: the server rejected them with a non-retryable status (4xx other than 401/403/408/429). Dead-lettered changes stop flushing and stop shielding their entities from revalidate — surface them to the user.
Parameters
changes
error
Error
Returns
void
onConflict()?
optionalonConflict: (context) =>void
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:150
Called when the server answers 409 Conflict for a change. Informational — the change dead-letters (409 is non-retryable) and the server copy wins on the next revalidate.
Parameters
context
collectionName
string
entities
unknown[]
error
Error
Returns
void
translatePersistResponse()?
optionaltranslatePersistResponse: (schema,responseBody) =>unknown[]
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:156
Reconciles the POST response into the SWR store: given the response body, return the canonical entities the server echoed (or null to skip). Fixes server-assigned ids and timestamps drifting from the optimistic local copy.
Parameters
schema
CompiledSchema<UnknownRecord>
responseBody
unknown
Returns
unknown[]
unsyncedQueueStore
unsyncedQueueStore:
IDbPlugin
Defined in: plugins/replication/src/HttpSwrDbPlugin.ts:164
IDbPlugin to use for persisting the unsynced queue (e.g. same as swrStore). No datastore required. The queue is stored via query/bulkPersist in a reserved collection (_routier_unsynced).
Required: UnsyncedQueue has no default store. Pass a durable plugin to survive a refresh with unsynced items intact, or a MemoryPlugin to accept losing them.