@rebasepro/server 0.10.1-canary.gdaf6ba4 → 0.11.0

package/dist/api/rest/api-generator.d.ts

@@ -16,6 +16,12 @@ export declare class RestApiGenerator {
     private listLimits;
     private authAdapter?;
     constructor(collections: CollectionConfig[], driver: DataDriver, authAdapter?: AuthAdapter, maxBulkRows?: number, listLimits?: ListLimitOptions);
+    /**
+     * Built on first use rather than in the constructor: it probes the driver
+     * for SQL support and creates a table, and most requests never send a key.
+     */
+    private idempotencyStore?;
+    private idempotency;
     /**
      * Parse request query params into QueryOptions, applying this generator's
      * list-pagination bounds (default page size + hard max limit) so no read

package/dist/api/rest/idempotency.d.ts

@@ -0,0 +1,20 @@
+import { DataDriver } from "@rebasepro/types";
+export interface IdempotencyStore {
+    /** What this key answered before, or `undefined` if it is new. */
+    recall(key: string, uid: string | undefined): Promise<unknown | undefined>;
+    /** Record what this key answered. Never throws — see {@link createIdempotencyStore}. */
+    remember(key: string, uid: string | undefined, response: unknown): Promise<void>;
+}
+/**
+ * Returns `undefined` when the driver cannot run SQL, which disables the whole
+ * mechanism rather than failing writes: a document backend has no table to put
+ * this in, and refusing to serve is far worse than the duplicate this prevents.
+ *
+ * Every method swallows its own errors for the same reason. A write must not
+ * fail because the bookkeeping around it did — the worst case of a failed
+ * `remember` is the duplicate we already have today, while a thrown error would
+ * reject a write the database has already accepted.
+ */
+export declare function createIdempotencyStore(driver: DataDriver): IdempotencyStore | undefined;
+/** The header the client sends. Matches the widely used Stripe/IETF spelling. */
+export declare const IDEMPOTENCY_HEADER = "Idempotency-Key";

package/dist/index.es.js

@@ -739,6 +739,101 @@ function isFunctionAllowed(permissions, functionName, operation) {
 	return false;
 }
 //#endregion
+//#region src/api/rest/idempotency.ts
+/**
+* Remembering what a write already answered, so replaying it does not do it twice.
+*
+* The offline queue replays a mutation whenever it did not see the response —
+* which includes every case where the write *committed* and the ACK was lost to
+* a dropped connection. For a collection whose id the client chooses, the replay
+* collides on that id and the client can recognise its own earlier attempt. For
+* a collection with a serial id it cannot: the server ignored the id the client
+* invented and assigned its own, so the replay is indistinguishable from a new
+* row and inserts a second one. The scaffold's own collections use
+* `isId: "increment"`, so that is the default case, not an exotic one.
+*
+* A key is honoured only for the principal that created it. Mutation ids are
+* generated on the client, so keying on the id alone would let anyone who
+* learned (or guessed) another user's id replay their key and be handed that
+* user's row back — a read of someone else's data through a write endpoint.
+*/
+var TABLE$2 = "\"rebase\".\"idempotency_keys\"";
+/**
+* How long a replay is recognised. Long enough to cover an offline stretch and
+* a retry schedule; short enough that the table stays small and a key cannot be
+* replayed indefinitely. Rows past this are pruned opportunistically rather than
+* by a scheduled job — there is no cron guaranteed to be running.
+*/
+var TTL_HOURS = 24;
+/** The principal a key belongs to; anonymous and service writes share a sentinel. */
+function principal(uid) {
+	return uid && uid.length > 0 ? uid : "\0anon";
+}
+/**
+* Returns `undefined` when the driver cannot run SQL, which disables the whole
+* mechanism rather than failing writes: a document backend has no table to put
+* this in, and refusing to serve is far worse than the duplicate this prevents.
+*
+* Every method swallows its own errors for the same reason. A write must not
+* fail because the bookkeeping around it did — the worst case of a failed
+* `remember` is the duplicate we already have today, while a thrown error would
+* reject a write the database has already accepted.
+*/
+function createIdempotencyStore(driver) {
+	const admin = driver.admin;
+	if (!isSQLAdmin(admin)) return void 0;
+	const exec = (sql, params) => admin.executeSql(sql, params ? { params } : void 0);
+	let ready;
+	/** Created on first use: most deployments never send a key at all. */
+	const ensure = () => {
+		ready ??= (async () => {
+			try {
+				await exec("CREATE SCHEMA IF NOT EXISTS rebase");
+				await exec(`
+                    CREATE TABLE IF NOT EXISTS ${TABLE$2} (
+                        key TEXT NOT NULL,
+                        uid TEXT NOT NULL,
+                        response JSONB,
+                        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                        PRIMARY KEY (uid, key)
+                    )
+                `);
+				await exec(`CREATE INDEX IF NOT EXISTS idx_idempotency_created ON ${TABLE$2}(created_at)`);
+				return true;
+			} catch (error) {
+				logger.warn("Idempotency keys unavailable — a replayed offline write may insert a duplicate row.", { detail: error instanceof Error ? error.message : String(error) });
+				return false;
+			}
+		})();
+		return ready;
+	};
+	return {
+		async recall(key, uid) {
+			if (!key || !await ensure()) return void 0;
+			try {
+				return (await exec(`SELECT response FROM ${TABLE$2}
+                     WHERE uid = $1 AND key = $2 AND created_at > NOW() - INTERVAL '${TTL_HOURS} hours'`, [principal(uid), key]))[0]?.response;
+			} catch {
+				return;
+			}
+		},
+		async remember(key, uid, response) {
+			if (!key || !await ensure()) return;
+			try {
+				await exec(`INSERT INTO ${TABLE$2} (key, uid, response) VALUES ($1, $2, $3::jsonb)
+                     ON CONFLICT (uid, key) DO NOTHING`, [
+					key,
+					principal(uid),
+					JSON.stringify(response ?? null)
+				]);
+				if (Math.random() < .01) await exec(`DELETE FROM ${TABLE$2} WHERE created_at < NOW() - INTERVAL '${TTL_HOURS} hours'`);
+			} catch {}
+		}
+	};
+}
+/** The header the client sends. Matches the widely used Stripe/IETF spelling. */
+var IDEMPOTENCY_HEADER = "Idempotency-Key";
+//#endregion
 //#region src/api/rest/api-generator.ts
 /**
 * Parse a JSON request body for a create/update. An empty body yields `{}`
@@ -780,6 +875,15 @@ var RestApiGenerator = class {
 		this.router = new Hono();
 	}
 	/**
+	* Built on first use rather than in the constructor: it probes the driver
+	* for SQL support and creates a table, and most requests never send a key.
+	*/
+	idempotencyStore;
+	idempotency() {
+		this.idempotencyStore ??= createIdempotencyStore(this.driver) ?? null;
+		return this.idempotencyStore ?? void 0;
+	}
+	/**
 	* Parse request query params into QueryOptions, applying this generator's
 	* list-pagination bounds (default page size + hard max limit) so no read
 	* path can be tricked into buffering an entire table into memory.
@@ -973,6 +1077,13 @@ var RestApiGenerator = class {
 						..."emailDeliveryFailed" in result && result.emailDeliveryFailed ? { emailDeliveryFailed: true } : {}
 					}, 201);
 				}
+				const idempotencyKey = c.req.header(IDEMPOTENCY_HEADER);
+				const uid = c.get("user")?.uid;
+				const store = this.idempotency();
+				if (idempotencyKey && store) {
+					const already = await store.recall(idempotencyKey, uid);
+					if (already !== void 0) return c.json(already, 201);
+				}
 				const entity = await driver.save({
 					path,
 					values: body,
@@ -980,6 +1091,7 @@ var RestApiGenerator = class {
 					status: "new"
 				});
 				const response = this.formatResponse(entity);
+				if (idempotencyKey && store) await store.remember(idempotencyKey, uid, response);
 				return c.json(response, 201);
 			} catch (error) {
 				if (isRebaseApiError(error) && !error.code) {
@@ -13207,12 +13319,13 @@ function createCollectionClient(transport, slug, ws) {
 				throw err;
 			}
 		},
-		async create(data, id) {
+		async create(data, id, options) {
 			const body = { ...data };
 			if (id !== void 0) body.id = id;
 			return await transport.request(basePath, {
 				method: "POST",
-				body: JSON.stringify(body)
+				body: JSON.stringify(body),
+				...options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : {}
 			});
 		},
 		async createMany(data, options) {
@@ -15195,6 +15308,21 @@ function isRetryableError(error) {
 	if (error instanceof RebaseApiError) return error.status !== void 0 && RETRYABLE_STATUSES.has(error.status);
 	return false;
 }
+/**
+* Did this write fail because the row is already there?
+*
+* Matched on the SQLSTATE the server passes through (`23505`, unique_violation)
+* and on 409, never on the message — a duplicate-key message names the
+* constraint and the values, so it is neither stable nor safe to parse.
+*
+* The queue uses this to recognise its own earlier attempt. A create whose
+* response was lost is replayed, and for a row carrying an id the SDK generated
+* the server can only be rejecting it because the first attempt actually landed.
+*/
+function isDuplicateKeyError(error) {
+	if (!(error instanceof RebaseApiError)) return false;
+	return error.code === "23505" || error.status === 409;
+}
 var ConnectivityMonitor = class {
 	state = "online";
 	backoffMs;
@@ -15801,6 +15929,25 @@ var OfflineManager = class {
 	collections = /* @__PURE__ */ new Map();
 	/** In-memory mirror of the current scope's queue, in replay order. */
 	queue = [];
+	/**
+	* The mutation currently on the wire, if any.
+	*
+	* `flush` awaits `replay(op)` with `op` still at the head of `queue`, so for
+	* the whole duration of that request the in-flight op is also the queue's
+	* *tail* whenever it is the only entry. Both shortcuts in `enqueue` reach
+	* for the tail, and neither may touch an op the server is already reading:
+	*
+	* - Coalescing an update into it mutates a payload that has already been
+	*   serialized and sent, and `drop` then removes the whole entry on ACK —
+	*   so the second edit is neither sent nor kept. A silently lost write.
+	* - Cancelling it out against a delete assumes the server never saw the
+	*   create. It is seeing it right now, so the row would be created and the
+	*   delete never queued — an orphan row nothing will ever remove.
+	*
+	* Guarding on the id rather than on a boolean keeps this correct if the
+	* flush loop ever sends more than one op at a time.
+	*/
+	inFlightId = null;
 	queueLoad;
 	/** Serializes enqueues so concurrent writes keep the order the app made them. */
 	enqueueChain = Promise.resolve();
@@ -16048,7 +16195,7 @@ var OfflineManager = class {
 			},
 			update: async (id, data) => {
 				await this.ensureCollection(slug);
-				if (this.connectivity.shouldAttempt()) try {
+				if (this.connectivity.shouldAttempt() && !this.hasPending(slug, id)) try {
 					const row = await inner.update(id, data);
 					this.connectivity.markSuccess();
 					await this.ingest(slug, [row]);
@@ -16077,7 +16224,7 @@ var OfflineManager = class {
 			},
 			delete: async (id) => {
 				await this.ensureCollection(slug);
-				if (this.connectivity.shouldAttempt()) try {
+				if (this.connectivity.shouldAttempt() && !this.hasPending(slug, id)) try {
 					await inner.delete(id);
 					this.connectivity.markSuccess();
 					this.removeLocalRow(slug, id, true);
@@ -16619,7 +16766,7 @@ var OfflineManager = class {
 			await this.ensureQueueLoaded();
 			if (mutation.type === "update") {
 				const tail = this.queue[this.queue.length - 1];
-				if (tail && tail.collection === mutation.collection && (tail.type === "create" || tail.type === "update") && tail.id === mutation.id) {
+				if (tail && tail.mutationId !== this.inFlightId && tail.collection === mutation.collection && (tail.type === "create" || tail.type === "update") && tail.id === mutation.id) {
 					tail.data = {
 						...tail.data,
 						...mutation.data,
@@ -16630,8 +16777,8 @@ var OfflineManager = class {
 				}
 			}
 			if (mutation.type === "delete") {
-				if (this.queue.some((m) => m.collection === mutation.collection && m.type === "create" && m.id === mutation.id && m.generatedId === true)) {
-					const doomed = this.queue.filter((m) => m.collection === mutation.collection && m.id === mutation.id && (m.type === "create" || m.type === "update"));
+				if (this.queue.some((m) => m.collection === mutation.collection && m.type === "create" && m.id === mutation.id && m.generatedId === true && m.mutationId !== this.inFlightId)) {
+					const doomed = this.queue.filter((m) => m.collection === mutation.collection && m.id === mutation.id && (m.type === "create" || m.type === "update") && m.mutationId !== this.inFlightId);
 					for (const op of doomed) await this.store.dequeue(this.queueKey(op));
 					this.queue = this.queue.filter((m) => !doomed.includes(m));
 					this.afterQueueChange();
@@ -16706,27 +16853,32 @@ var OfflineManager = class {
 			while (this.queue.length > 0 && !this.disposed) {
 				const op = this.queue[0];
 				touched.add(op.collection);
+				this.inFlightId = op.mutationId;
 				try {
-					await this.replay(op);
-				} catch (error) {
-					if (isNetworkError(error)) {
-						this.connectivity.markFailure();
-						break;
-					}
-					op.attempts = (op.attempts ?? 0) + 1;
-					op.lastError = error?.message ?? String(error);
-					if (isRetryableError(error) && op.attempts < this.maxRetries) {
-						await this.store.enqueue(this.queueKey(op), op).catch(() => void 0);
-						this.connectivity.deferRetry();
-						this.patchStatus({ lastError: op.lastError });
-						break;
+					try {
+						await this.replay(op);
+					} catch (error) {
+						if (isNetworkError(error)) {
+							this.connectivity.markFailure();
+							break;
+						}
+						op.attempts = (op.attempts ?? 0) + 1;
+						op.lastError = error?.message ?? String(error);
+						if (isRetryableError(error) && op.attempts < this.maxRetries) {
+							await this.store.enqueue(this.queueKey(op), op).catch(() => void 0);
+							this.connectivity.deferRetry();
+							this.patchStatus({ lastError: op.lastError });
+							break;
+						}
+						await this.rejectMutation(op, error);
+						continue;
 					}
-					await this.rejectMutation(op, error);
-					continue;
+					this.connectivity.markSuccess();
+					await this.drop(op);
+					flushed++;
+				} finally {
+					this.inFlightId = null;
 				}
-				this.connectivity.markSuccess();
-				await this.drop(op);
-				flushed++;
 			}
 		} finally {
 			this.patchStatus({ syncing: false });
@@ -16747,7 +16899,14 @@ var OfflineManager = class {
 	async replay(op) {
 		const inner = this.innerFor(op.collection);
 		if (op.type === "create") {
-			const row = await inner.create(op.data);
+			let row;
+			try {
+				row = await inner.create(op.data, void 0, { idempotencyKey: op.mutationId });
+			} catch (error) {
+				if (!(op.generatedId === true && isDuplicateKeyError(error))) throw error;
+				row = await inner.findById(op.id).catch(() => void 0);
+				if (!row) return;
+			}
 			await this.adoptServerRow(op, op.id, row);
 		} else if (op.type === "createMany") {
 			const queued = op.data ?? [];