@eik/core 2.1.78 → 2.1.79

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [2.1.79](https://github.com/eik-lib/core/compare/v2.1.78...v2.1.79) (2026-08-19)
+
+
+### Bug Fixes
+
+* use atomic sink writes to prevent concurrent upload races ([#638](https://github.com/eik-lib/core/issues/638)) ([cf29a68](https://github.com/eik-lib/core/commit/cf29a6838622360f8c80bc83c86d07536d580f33)), closes [#1](https://github.com/eik-lib/core/issues/1) [#2](https://github.com/eik-lib/core/issues/2) [#3](https://github.com/eik-lib/core/issues/3) [#6](https://github.com/eik-lib/core/issues/6)
+
 ## [2.1.78](https://github.com/eik-lib/core/compare/v2.1.77...v2.1.78) (2026-08-17)
 
 

package/lib/handlers/alias.put.js

@@ -8,7 +8,7 @@ import {
 	createFilePathToAlias,
 	createFilePathToAliasOrigin,
 } from "../utils/path-builders-fs.js";
-import { decodeUriComponent, writeJSON } from "../utils/utils.js";
+import { decodeUriComponent, writeJSONWithOptions } from "../utils/utils.js";
 import { createURIToAlias } from "../utils/path-builders-uri.js";
 import MultipartParser from "../multipart/parser.js";
 import HttpIncoming from "../classes/http-incoming.js";
@@ -109,8 +109,18 @@ const AliasPut = class AliasPut {
 					);
 
 					try {
-						await writeJSON(this._sink, path, alias, "application/json");
+						await writeJSONWithOptions(
+							this._sink,
+							path,
+							alias,
+							"application/json",
+							{ ifNotExists: true },
+						);
 					} catch (error) {
+						const err = /** @type {any} */ (error);
+						if (err.code === "ALREADY_EXISTS") {
+							throw new HttpError.Conflict();
+						}
 						this._log.error(
 							`alias:put - Failed writing alias to sink - Pathname: ${path}`,
 						);

package/lib/handlers/map.put.js

@@ -20,7 +20,8 @@ import {
 	decodeUriComponent,
 	streamCollector,
 	writeJSON,
-	readJSON,
+	writeJSONWithOptions,
+	readJSONWithGeneration,
 } from "../utils/utils.js";
 
 /**
@@ -172,7 +173,7 @@ const MapPut = class MapPut {
 
 	/**
 	 * @param {any} incoming
-	 * @returns {Promise<InstanceType<typeof Versions>>}
+	 * @returns {Promise<{ versions: InstanceType<typeof Versions>, generation: string }>}
 	 */
 	async _readVersions(incoming) {
 		const path = createFilePathToVersion(incoming);
@@ -186,30 +187,65 @@ const MapPut = class MapPut {
 			this._log.info(
 				`map:put - Version meta file did not exist in sink - Create new - Pathname: ${path}`,
 			);
-			return new Versions(incoming);
+			return { versions: new Versions(incoming), generation: "" };
 		}
 
 		// File exists. Any failure here must propagate rather than be
 		// swallowed — silently falling back to an empty Versions object
 		// would cause _writeVersions to overwrite the index and erase the
 		// entire version history.
-		const obj = await readJSON(this._sink, path);
+		const { data, generation } = await readJSONWithGeneration(this._sink, path);
 		this._log.info(
 			`map:put - Successfully read version meta file from sink - Pathname: ${path}`,
 		);
-		return new Versions(obj);
+		return { versions: new Versions(data), generation };
 	}
 
 	/**
+	 * Writes versions.json with compare-and-swap semantics when a generation
+	 * token is available. On conflict the read-modify-write cycle is retried.
+	 *
 	 * @param {any} incoming
-	 * @param {any} versions
+	 * @param {InstanceType<typeof Versions>} versions
+	 * @param {string} generation
+	 * @param {string} pVersion
+	 * @param {string} integrity
 	 */
-	async _writeVersions(incoming, versions) {
+	async _writeVersions(incoming, versions, generation, pVersion, integrity) {
 		const path = createFilePathToVersion(incoming);
-		await writeJSON(this._sink, path, versions, "application/json");
-		this._log.info(
-			`map:put - Successfully wrote version meta file to sink - Pathname: ${path}`,
-		);
+		const maxRetries = 3;
+		/** @type {{ ifGenerationMatch?: string | number }} */
+		let options = generation ? { ifGenerationMatch: generation } : {};
+		let currentVersions = versions;
+		for (let attempt = 0; attempt <= maxRetries; attempt++) {
+			try {
+				await writeJSONWithOptions(
+					this._sink,
+					path,
+					currentVersions,
+					"application/json",
+					options,
+				);
+				this._log.info(
+					`map:put - Successfully wrote version meta file to sink - Pathname: ${path}`,
+				);
+				return;
+			} catch (error) {
+				const err = /** @type {any} */ (error);
+				if (err.code === "CONFLICT" && attempt < maxRetries) {
+					this._log.info(
+						`map:put - versions.json conflict on attempt ${attempt + 1}, retrying`,
+					);
+					const { versions: fresh, generation: newGen } =
+						await this._readVersions(incoming);
+					fresh.setVersion(pVersion, integrity);
+					currentVersions = fresh;
+					options = newGen ? { ifGenerationMatch: newGen } : {};
+					continue;
+				}
+				throw error;
+			}
+		}
 	}
 
 	/**
@@ -258,11 +294,13 @@ const MapPut = class MapPut {
 			org,
 		});
 
-		const versions = await this._readVersions(incoming).catch(() => {
-			const e = new HttpError.BadGateway();
-			end({ labels: { success: false, status: e.status, type: "map" } });
-			throw e;
-		});
+		const { versions, generation } = await this._readVersions(incoming).catch(
+			() => {
+				const e = new HttpError.BadGateway();
+				end({ labels: { success: false, status: e.status, type: "map" } });
+				throw e;
+			},
+		);
 
 		if (!versions.check(pVersion)) {
 			this._log.info(
@@ -277,7 +315,13 @@ const MapPut = class MapPut {
 		versions.setVersion(pVersion, integrity);
 
 		try {
-			await this._writeVersions(incoming, versions);
+			await this._writeVersions(
+				incoming,
+				versions,
+				generation,
+				pVersion,
+				integrity,
+			);
 			// eslint-disable-next-line no-unused-vars
 		} catch (error) {
 			const e = new HttpError.BadGateway();

package/lib/handlers/pkg.put.js

@@ -13,7 +13,8 @@ import {
 import {
 	decodeUriComponent,
 	writeJSON,
-	readJSON,
+	writeJSONWithOptions,
+	readJSONWithGeneration,
 	readEikJson,
 } from "../utils/utils.js";
 import { createURIPathToPkgLog } from "../utils/path-builders-uri.js";
@@ -129,11 +130,12 @@ const PkgPut = class PkgPut {
 			type: incoming.type,
 		};
 		const eikJsonPath = createFilePathToEikJson(incoming);
-		const buffer = await writeJSON(
+		const buffer = await writeJSONWithOptions(
 			this._sink,
 			eikJsonPath,
 			content,
 			"application/json",
+			{ ifNotExists: true },
 		);
 		this._log.info(
 			`pkg:put - Successfully wrote eik.json to sink - Pathname: ${eikJsonPath}`,
@@ -155,7 +157,7 @@ const PkgPut = class PkgPut {
 
 	/**
 	 * @param {any} incoming
-	 * @returns {Promise<InstanceType<typeof Versions>>}
+	 * @returns {Promise<{ versions: InstanceType<typeof Versions>, generation: string }>}
 	 */
 	async _readVersions(incoming) {
 		const path = createFilePathToVersion(incoming);
@@ -169,18 +171,18 @@ const PkgPut = class PkgPut {
 			this._log.info(
 				`pkg:put - Version meta file did not exist in sink - Create new - Pathname: ${path}`,
 			);
-			return new Versions(incoming);
+			return { versions: new Versions(incoming), generation: "" };
 		}
 
 		// File exists. Any failure here (GCS error, corrupt JSON, network
 		// timeout) must propagate rather than be swallowed — silently falling
 		// back to an empty Versions object would cause _writeVersions to
 		// overwrite the index and erase the entire version history.
-		const obj = await readJSON(this._sink, path);
+		const { data, generation } = await readJSONWithGeneration(this._sink, path);
 		this._log.info(
 			`pkg:put - Successfully read version meta file from sink - Pathname: ${path}`,
 		);
-		return new Versions(obj);
+		return { versions: new Versions(data), generation };
 	}
 
 	/**
@@ -205,15 +207,50 @@ const PkgPut = class PkgPut {
 	}
 
 	/**
+	 * Writes versions.json with compare-and-swap semantics when a generation
+	 * token is available. On conflict the read-modify-write cycle is retried.
+	 *
 	 * @param {any} incoming
-	 * @param {any} versions
+	 * @param {InstanceType<typeof Versions>} versions
+	 * @param {string} generation
+	 * @param {string} pVersion
+	 * @param {string} integrity
 	 */
-	async _writeVersions(incoming, versions) {
+	async _writeVersions(incoming, versions, generation, pVersion, integrity) {
 		const path = createFilePathToVersion(incoming);
-		await writeJSON(this._sink, path, versions, "application/json");
-		this._log.info(
-			`pkg:put - Successfully wrote version meta file to sink - Pathname: ${path}`,
-		);
+		const maxRetries = 3;
+		/** @type {{ ifGenerationMatch?: string | number }} */
+		let options = generation ? { ifGenerationMatch: generation } : {};
+		let currentVersions = versions;
+		for (let attempt = 0; attempt <= maxRetries; attempt++) {
+			try {
+				await writeJSONWithOptions(
+					this._sink,
+					path,
+					currentVersions,
+					"application/json",
+					options,
+				);
+				this._log.info(
+					`pkg:put - Successfully wrote version meta file to sink - Pathname: ${path}`,
+				);
+				return;
+			} catch (error) {
+				const err = /** @type {any} */ (error);
+				if (err.code === "CONFLICT" && attempt < maxRetries) {
+					this._log.info(
+						`pkg:put - versions.json conflict on attempt ${attempt + 1}, retrying`,
+					);
+					const { versions: fresh, generation: newGen } =
+						await this._readVersions(incoming);
+					fresh.setVersion(pVersion, integrity);
+					currentVersions = fresh;
+					options = newGen ? { ifGenerationMatch: newGen } : {};
+					continue;
+				}
+				throw error;
+			}
+		}
 	}
 
 	/**
@@ -275,11 +312,13 @@ const PkgPut = class PkgPut {
 			throw e;
 		}
 
-		const versions = await this._readVersions(incoming).catch(() => {
-			const e = new HttpError.BadGateway();
-			end({ labels: { success: false, status: e.status, type } });
-			throw e;
-		});
+		const { versions, generation } = await this._readVersions(incoming).catch(
+			() => {
+				const e = new HttpError.BadGateway();
+				end({ labels: { success: false, status: e.status, type } });
+				throw e;
+			},
+		);
 
 		const { pkg, eikJson } = await this._parser(incoming);
 
@@ -288,8 +327,15 @@ const PkgPut = class PkgPut {
 		let eikJsonAsset;
 		try {
 			eikJsonAsset = await this._writeEikJson(incoming, eikJson);
-			// eslint-disable-next-line no-unused-vars
 		} catch (error) {
+			const err = /** @type {any} */ (error);
+			if (err.code === "ALREADY_EXISTS") {
+				// Another replica committed this version while this upload was in
+				// flight. Treat it as a conflict identical to the early existence check.
+				const e = new HttpError.Conflict();
+				end({ labels: { success: false, status: e.status, type } });
+				throw e;
+			}
 			const e = new HttpError.BadGateway();
 			end({ labels: { success: false, status: e.status, type } });
 			throw e;
@@ -309,10 +355,14 @@ const PkgPut = class PkgPut {
 			throw e;
 		}
 
-		versions.setVersion(pVersion, pkg.integrity);
-
 		try {
-			await this._writeVersions(incoming, versions);
+			await this._writeVersions(
+				incoming,
+				versions,
+				generation,
+				pVersion,
+				pkg.integrity,
+			);
 			// eslint-disable-next-line no-unused-vars
 		} catch (error) {
 			const e = new HttpError.BadGateway();

package/lib/utils/utils.js

@@ -107,9 +107,86 @@ const decodeUriComponent = (value) => {
 	return decodeURIComponent(value);
 };
 
+/**
+ * Like readJSON but also returns the generation token from the ReadFile,
+ * which can be passed back to writeJSONWithOptions as ifGenerationMatch
+ * for compare-and-swap semantics.
+ *
+ * @param {any} sink
+ * @param {string} path
+ * @returns {Promise<{ data: any, generation: string }>}
+ */
+const readJSONWithGeneration = (sink, path) =>
+	// eslint-disable-next-line no-async-promise-executor
+	new Promise(async (resolve, reject) => {
+		try {
+			/** @type {any[]} */
+			const buffer = [];
+			const from = await sink.read(path);
+
+			const to = new Writable({
+				objectMode: false,
+				write(chunk, encoding, callback) {
+					buffer.push(chunk);
+					callback();
+				},
+			});
+
+			pipeline(from.stream, to, (error) => {
+				if (error) return reject(error);
+				const str = Buffer.concat(buffer).toString("utf8");
+				try {
+					const obj = JSON.parse(str);
+					return resolve({ data: obj, generation: from.generation ?? "" });
+				} catch (err) {
+					return reject(err);
+				}
+			});
+		} catch (error) {
+			reject(error);
+		}
+	});
+
+/**
+ * Like writeJSON but accepts sink write options (e.g. { ifNotExists, ifGenerationMatch })
+ * for atomic conditional writes.
+ *
+ * @param {any} sink
+ * @param {string} path
+ * @param {any} obj
+ * @param {string} contentType
+ * @param {{ ifNotExists?: boolean, ifGenerationMatch?: string | number }} [options]
+ */
+const writeJSONWithOptions = (sink, path, obj, contentType, options = {}) =>
+	// eslint-disable-next-line no-async-promise-executor
+	new Promise(async (resolve, reject) => {
+		try {
+			const buffer = Buffer.from(JSON.stringify(obj));
+
+			const from = new Readable({
+				objectMode: false,
+				read() {
+					this.push(buffer);
+					this.push(null);
+				},
+			});
+
+			const to = await sink.write(path, contentType, options);
+
+			pipeline(from, to, (error) => {
+				if (error) return reject(error);
+				return resolve(buffer);
+			});
+		} catch (error) {
+			reject(error);
+		}
+	});
+
 export {
 	readJSON,
+	readJSONWithGeneration,
 	writeJSON,
+	writeJSONWithOptions,
 	streamCollector,
 	etagFromFsStat,
 	decodeUriComponent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eik/core",
-  "version": "2.1.78",
+  "version": "2.1.79",
   "description": "Core server package",
   "main": "lib/main.js",
   "types": "./types/main.d.ts",
@@ -29,7 +29,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@eik/common": "5.1.34",
+    "@eik/common": "5.2.0",
     "@eik/sink": "1.2.7",
     "@eik/sink-file-system": "2.0.40",
     "@eik/sink-memory": "2.0.37",

package/types/handlers/map.put.d.ts

@@ -42,14 +42,23 @@ declare const MapPut: {
         }): Promise<string>;
         /**
          * @param {any} incoming
-         * @returns {Promise<InstanceType<typeof Versions>>}
+         * @returns {Promise<{ versions: InstanceType<typeof Versions>, generation: string }>}
          */
-        _readVersions(incoming: any): Promise<InstanceType<typeof Versions>>;
+        _readVersions(incoming: any): Promise<{
+            versions: InstanceType<typeof Versions>;
+            generation: string;
+        }>;
         /**
+         * Writes versions.json with compare-and-swap semantics when a generation
+         * token is available. On conflict the read-modify-write cycle is retried.
+         *
          * @param {any} incoming
-         * @param {any} versions
+         * @param {InstanceType<typeof Versions>} versions
+         * @param {string} generation
+         * @param {string} pVersion
+         * @param {string} integrity
          */
-        _writeVersions(incoming: any, versions: any): Promise<void>;
+        _writeVersions(incoming: any, versions: InstanceType<typeof Versions>, generation: string, pVersion: string, integrity: string): Promise<void>;
         /**
          * @param {any} req
          * @param {any} user

package/types/handlers/pkg.put.d.ts

@@ -82,18 +82,27 @@ declare const PkgPut: {
         _writeEikJson(incoming: any, capturedEikJson: Record<string, any> | null): Promise<InstanceType<typeof Asset>>;
         /**
          * @param {any} incoming
-         * @returns {Promise<InstanceType<typeof Versions>>}
+         * @returns {Promise<{ versions: InstanceType<typeof Versions>, generation: string }>}
          */
-        _readVersions(incoming: any): Promise<InstanceType<typeof Versions>>;
+        _readVersions(incoming: any): Promise<{
+            versions: InstanceType<typeof Versions>;
+            generation: string;
+        }>;
         /**
          * @param {any} incoming
          */
         _readVersion(incoming: any): Promise<boolean>;
         /**
+         * Writes versions.json with compare-and-swap semantics when a generation
+         * token is available. On conflict the read-modify-write cycle is retried.
+         *
          * @param {any} incoming
-         * @param {any} versions
+         * @param {InstanceType<typeof Versions>} versions
+         * @param {string} generation
+         * @param {string} pVersion
+         * @param {string} integrity
          */
-        _writeVersions(incoming: any, versions: any): Promise<void>;
+        _writeVersions(incoming: any, versions: InstanceType<typeof Versions>, generation: string, pVersion: string, integrity: string): Promise<void>;
         /**
          * @param {any} req
          * @param {any} user

package/types/utils/utils.d.ts

@@ -3,6 +3,19 @@
  * @param {string} path
  */
 export function readJSON(sink: any, path: string): Promise<any>;
+/**
+ * Like readJSON but also returns the generation token from the ReadFile,
+ * which can be passed back to writeJSONWithOptions as ifGenerationMatch
+ * for compare-and-swap semantics.
+ *
+ * @param {any} sink
+ * @param {string} path
+ * @returns {Promise<{ data: any, generation: string }>}
+ */
+export function readJSONWithGeneration(sink: any, path: string): Promise<{
+    data: any;
+    generation: string;
+}>;
 /**
  * @param {any} sink
  * @param {string} path
@@ -10,6 +23,20 @@ export function readJSON(sink: any, path: string): Promise<any>;
  * @param {string} contentType
  */
 export function writeJSON(sink: any, path: string, obj: any, contentType: string): Promise<any>;
+/**
+ * Like writeJSON but accepts sink write options (e.g. { ifNotExists, ifGenerationMatch })
+ * for atomic conditional writes.
+ *
+ * @param {any} sink
+ * @param {string} path
+ * @param {any} obj
+ * @param {string} contentType
+ * @param {{ ifNotExists?: boolean, ifGenerationMatch?: string | number }} [options]
+ */
+export function writeJSONWithOptions(sink: any, path: string, obj: any, contentType: string, options?: {
+    ifNotExists?: boolean;
+    ifGenerationMatch?: string | number;
+}): Promise<any>;
 /**
  * @param {any} from
  */