Repository navigation
Expand file tree
/
Copy pathPowersyncConnector.singlefile.ts
More file actions
397 lines (346 loc) · 14 KB
/
Copy pathPowersyncConnector.singlefile.ts
File metadata and controls
397 lines (346 loc) · 14 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
// PowerSync Reference Write Implementation — single-file client connector
//
// Copy this file into your app to upload queued transactions with plain fetch.
// It requires @powersync/web or @powersync/react-native >=1.26.0 for getCrudTransactions().
// For the modular version, see PowersyncConnector.ts and library/powersync/.
//
// Set BACKEND_URL, POWERSYNC_URL and AUTH_TOKEN below. Adjust the batch limits, request timeout,
// and localStorage key as needed, or connect these constants to your application's configuration.
//
// The default fetchCredentials() uses the fixed AUTH_TOKEN for sync and reuses it for writes.
// The write API accepts tokens your PowerSync instance trusts. Replace fetchAuthToken() with your
// identity provider's token retrieval. Sync and writes should identify the same user.
//
// Setup references:
// https://docs.powersync.com/configuration/app-backend/client-side-integration#backend-connector
// See docs/auth/providers.md in this repository for Supabase and Clerk examples.
import type { AbstractPowerSyncDatabase, CrudEntry, CrudTransaction, PowerSyncBackendConnector } from '@powersync/web';
// Configuration
/** Base URL of your write API, e.g. `http://localhost:6060` in local dev. */
const BACKEND_URL = 'http://localhost:6060';
/** Your PowerSync instance URL. */
const POWERSYNC_URL = '';
/**
* Token for sync and writes, e.g. a session token copied from your auth provider. Replace
* fetchAuthToken() with your provider's token retrieval instead of hardcoding one.
*/
const AUTH_TOKEN = '';
/** localStorage key used to persist the anonymous user id across reloads. */
const USER_ID_STORAGE_KEY = 'ps_user_id';
/** Transactions per upload request. Defaults to one transaction per attempt. */
const MAX_TRANSACTIONS_PER_BATCH = 1;
/** Upper bound on total CRUD operations per upload request, regardless of transaction count. */
const MAX_OPERATIONS_PER_BATCH = 1000;
/** Abort a write API request that takes longer than this many milliseconds. */
const REQUEST_TIMEOUT_MS = 30_000;
// Connector implementation; supporting types and helpers follow the class.
export class PowersyncConnector implements PowerSyncBackendConnector {
// Called by PowerSync to upload queued local changes to the write API.
async uploadData(database: AbstractPowerSyncDatabase): Promise<void> {
const batching = this.getBatchingConfig();
return this.uploadTransactionBatch(database, batching);
}
// Returns credentials for the PowerSync sync connection, reusing the write API token.
// The write API accepts tokens your PowerSync instance trusts. See docs/auth/providers.md.
async fetchCredentials() {
return {
endpoint: POWERSYNC_URL,
token: await this.getAuthToken()
};
}
readonly userId: string;
private _authToken: string | null;
constructor() {
// Provide a crypto.randomUUID() polyfill or a platform UUID generator where unavailable,
// including older React Native environments.
let userId = localStorage.getItem(USER_ID_STORAGE_KEY);
if (!userId) {
userId = crypto.randomUUID();
localStorage.setItem(USER_ID_STORAGE_KEY, userId);
}
this.userId = userId;
this._authToken = null;
}
// Replace with your auth provider's session token (e.g. Supabase `session.access_token`).
private async fetchAuthToken(): Promise<string> {
if (!AUTH_TOKEN) {
throw new Error('No auth token. Set AUTH_TOKEN or replace fetchAuthToken().');
}
return AUTH_TOKEN;
}
/**
* Returns the cached token shared by sync and write requests.
* Fetches a token on first use or after {@link onTransportError} clears the cache.
*/
private async getAuthToken(): Promise<string> {
if (!this._authToken) {
this._authToken = await this.fetchAuthToken();
}
return this._authToken;
}
/**
* The batching config to use for the current upload. Reads the consts at the top of this file;
* override to make batching dynamic (e.g. shrink batch size after a fatal error, adjust for
* network conditions).
*/
protected getBatchingConfig() {
return {
maxTransactions: MAX_TRANSACTIONS_PER_BATCH,
maxOperations: MAX_OPERATIONS_PER_BATCH
};
}
/**
* Called only for client-directed fatal errors. Retaining blocks later uploads and may call
* this hook again. Return 'complete' to explicitly discard the failed transaction.
* See docs/error-handling.md for user interaction and notification deduplication guidance.
*/
protected async onFatalTransaction(
transaction: CrudTransaction,
result: ClientHandledFatalResult
): Promise<'retain' | 'complete'> {
console.error('Client handling required:', result.failedOperation.error_code, result.message);
return 'retain';
}
/**
* Handles a write API `retryable_error` result. Waits for retryAfterMs, if supplied,
* then throws so PowerSync retains the transaction and retries the upload.
* Overrides must also throw to keep the transaction queued.
*/
protected async onRetryableError(result: Extract<TransactionResult, { status: 'retryable_error' }>): Promise<never> {
await sleep(result.retryAfterMs ?? 0);
throw new Error(result.message ?? 'Retryable error');
}
/**
* Handles network errors, timeouts, and non-2xx responses through {@link onRetryableError}.
* Clears the cached token on {@link AuthenticationError} so the next upload fetches a new one.
* Override to handle transport failures separately from write API retryable results.
*/
protected async onTransportError(error: unknown): Promise<never> {
if (error instanceof AuthenticationError) {
this._authToken = null;
}
const message = error instanceof Error ? error.message : String(error);
return this.onRetryableError({ status: 'retryable_error', message });
}
/**
* POST /api/data via plain fetch — no openapi-fetch, no generated client. Every non-2xx response
* the write API returns (400/401/500) is `{ message }` (see backend/shared/powersync-reference-write-api.openapi.yaml); 401/403 become
* an {@link AuthenticationError} so onTransportError can clear the cached token and retry.
*/
private async postTransactionBatch(body: TransactionBatchAPI): Promise<TransactionBatchResponseAPI> {
const response = await fetch(`${BACKEND_URL}/api/data`, {
method: 'POST',
headers: {
'content-type': 'application/json',
Authorization: `Bearer ${await this.getAuthToken()}`
},
body: JSON.stringify(body),
signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
});
if (!response.ok) {
const { message } = (await response.json().catch(() => ({ message: response.statusText }))) as MessageResponseAPI;
if (response.status === 401 || response.status === 403) {
throw new AuthenticationError(
`Authentication failed (${response.status}) posting transaction batch: ${message}`
);
}
throw new Error(`Failed to post transaction batch (${response.status}): ${message}`);
}
return response.json();
}
private async uploadTransactionBatch(
database: AbstractPowerSyncDatabase,
batching: ReturnType<PowersyncConnector['getBatchingConfig']>
): Promise<void> {
const batch: CrudTransaction[] = [];
let operations = 0;
for await (const transaction of database.getCrudTransactions()) {
// Take the transaction, then test the bounds. Testing first would either split a transaction
// that alone exceeds maxOperations, or stall the queue on it forever.
batch.push(transaction);
operations += transaction.crud.length;
if (batch.length >= batching.maxTransactions || operations >= batching.maxOperations) {
break;
}
}
if (batch.length === 0) return;
const body: TransactionBatchAPI = {
transactions: batch.map(toApiTransaction)
};
let results: TransactionResult[];
try {
const response = await this.postTransactionBatch(body);
results = response.results.map(toResult);
} catch (error) {
await this.onTransportError(error);
return;
}
await completeAcceptedPrefix(
batch,
results,
(index, result) => this.onFatalTransaction(batch[index], result),
(result) => this.onRetryableError(result)
);
}
}
// API types matching backend/shared/powersync-reference-write-api.openapi.yaml. Update these when the API contract changes;
// this file does not use generated types.
type CrudOp = 'PUT' | 'PATCH' | 'DELETE';
interface CrudEntryAPI {
id: string;
op: CrudOp;
table: string;
transaction_id?: number;
op_data?: Record<string, unknown>;
}
interface CrudTransactionAPI {
crud: CrudEntryAPI[];
transaction_id?: number;
}
interface TransactionBatchAPI {
transactions: CrudTransactionAPI[];
}
/** `not_attempted` means the batch ended before this transaction was reached. */
type TransactionStatus = 'success' | 'retryable_error' | 'fatal_error' | 'not_attempted';
/** Machine-readable classification of a fatal failure, backend-specific. */
type ErrorCode =
| 'NOT_NULL_VIOLATION'
| 'UNIQUE_VIOLATION'
| 'FOREIGN_KEY_VIOLATION'
| 'CHECK_VIOLATION'
| 'CONSTRAINT_VIOLATION'
| 'INVALID_DATA'
| 'SCHEMA_MISMATCH'
| 'DOCUMENT_VALIDATION_FAILURE'
| 'UNAUTHORIZED'
| 'UNCLASSIFIED_ERROR'
| (string & {});
interface FailedOperationAPI {
error_code: ErrorCode;
details?: unknown;
operation_index?: number;
message?: string;
}
type TransactionResponseAPI =
| { status: 'success' | 'not_attempted' }
| { status: 'retryable_error'; message?: string; retry_after_ms?: number }
| {
status: 'fatal_error';
message?: string;
requires_client_handling: boolean;
failed_operation: FailedOperationAPI;
};
/** One result per transaction sent, in the same order and always the same length as the request. */
interface TransactionBatchResponseAPI {
results: TransactionResponseAPI[];
}
/** `{ message }` — the shape of every non-2xx response the write API returns (400/401/500). */
interface MessageResponseAPI {
message: string;
}
// Internal (camelCase) result shape passed to the overridable hooks above.
type TransactionResult =
| { status: 'success' | 'not_attempted' }
| { status: 'retryable_error'; message?: string; retryAfterMs?: number }
| {
status: 'fatal_error';
message?: string;
requiresClientHandling: boolean;
failedOperation: FailedOperationAPI;
};
type ClientHandledFatalResult = Extract<TransactionResult, { status: 'fatal_error' }> & {
requiresClientHandling: true;
};
/** Thrown when the write API rejects a request as unauthenticated/unauthorized (401/403). */
class AuthenticationError extends Error {
constructor(message: string) {
super(message);
this.name = 'AuthenticationError';
}
}
const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
/** Complete only the contiguous accepted prefix, even when a callback throws. */
async function completeAcceptedPrefix(
batch: { complete(): Promise<void> }[],
results: TransactionResult[],
onFatal: (index: number, result: ClientHandledFatalResult) => Promise<'retain' | 'complete'>,
onRetryable: (result: Extract<TransactionResult, { status: 'retryable_error' }>) => Promise<never>
): Promise<void> {
if (!Array.isArray(results) || results.length !== batch.length) throw new Error('Invalid batch result count');
let boundary = -1;
try {
for (const [index, result] of results.entries()) {
if (result?.status === 'success') {
boundary = index;
continue;
}
if (result?.status === 'fatal_error') {
if (
typeof result.requiresClientHandling !== 'boolean' ||
!result.failedOperation ||
typeof result.failedOperation.error_code !== 'string' ||
(result.failedOperation.message !== undefined && typeof result.failedOperation.message !== 'string') ||
(result.failedOperation.operation_index !== undefined &&
(!Number.isInteger(result.failedOperation.operation_index) || result.failedOperation.operation_index < 0))
) {
throw new Error('Malformed fatal transaction result');
}
if (result.requiresClientHandling) {
const decision = await onFatal(index, {
...result,
requiresClientHandling: true
});
if (decision !== 'complete') throw new Error('Fatal transaction retained for client handling');
boundary = index;
// Client-directed failures always end batch processing in either backend. Never complete a later result.
return;
}
boundary = index;
continue;
}
if (result?.status === 'retryable_error') {
// Complete the accepted prefix before invoking backoff/retry hooks.
if (boundary >= 0) {
const accepted = boundary;
boundary = -1;
await batch[accepted].complete();
}
await onRetryable(result);
throw new Error('Retryable transaction retained');
}
if (result?.status === 'not_attempted') return;
throw new Error('Malformed transaction result');
}
} finally {
if (boundary >= 0) await batch[boundary].complete();
}
}
/** Shape one SDK transaction for the wire. */
const toApiTransaction = (transaction: CrudTransaction): CrudTransactionAPI => ({
crud: transaction.crud.map((op: CrudEntry) => ({
id: op.id,
op: op.op as CrudOp,
table: op.table,
...(op.transactionId != null && { transaction_id: op.transactionId }),
...(op.opData != null && { op_data: op.opData })
})),
...(transaction.transactionId != null && {
transaction_id: transaction.transactionId
})
});
const toResult = (response: TransactionResponseAPI): TransactionResult => {
if (response?.status === 'fatal_error')
return {
status: response.status,
message: response.message,
requiresClientHandling: response.requires_client_handling,
failedOperation: response.failed_operation
};
if (response?.status === 'retryable_error')
return {
status: response.status,
message: response.message,
retryAfterMs: response.retry_after_ms
};
return response;
};