@lix-js/sdk 0.0.1

package/src/server-api-handler/environment/create-in-memory-environment.ts

@@ -0,0 +1,111 @@
+import { openLixInMemory } from "../../lix/open-lix-in-memory.js";
+import type { Lix } from "../../lix/open-lix.js";
+import type { LsaEnvironment } from "./environment.js";
+
+/**
+ * Create an in-memory storage.
+ *
+ * Great for testing or quick prototyping.
+ */
+export const createLsaInMemoryEnvironment = (): LsaEnvironment => {
+	const store = new Map<string, Blob>();
+
+	/**
+	 * Map of open lixes.
+	 *
+	 * @example
+	 *   openLixes.set('id', lix);
+	 *   openLixes.delete('id');
+	 *   openLixes.has('id');
+	 */
+	const openLixes = new Map<string, Lix>();
+
+	/**
+	 * Map of open connections.
+	 *
+	 * @example
+	 *   openConnections['lix-id'].add('connection-id');
+	 *   openConnections['lix-id'].delete('connection-id');
+	 *   openConnections['lix-id'].has('connection-id');
+	 *   openConnections['lix-id'].size;
+	 */
+	const openConnections = new Map<string, Set<string>>();
+
+	return {
+		async get(key: string): Promise<Blob | undefined> {
+			return store.get(key);
+		},
+
+		async set(key: string, value: Blob): Promise<void> {
+			store.set(key, value);
+		},
+
+		async delete(key: string): Promise<void> {
+			store.delete(key);
+		},
+
+		async has(key: string): Promise<boolean> {
+			return store.has(key);
+		},
+
+		async hasLix(args) {
+			return store.has(args.id);
+		},
+
+		async getLix(args) {
+			return store.get(args.id);
+		},
+
+		async setLix(args) {
+			store.set(args.id, args.blob);
+		},
+
+		async openLix(args) {
+			const connectionId = Math.random().toString(36).slice(2);
+			let lix: Lix;
+
+			// TODO no concurrency guarantees
+			if (openLixes.has(args.id)) {
+				lix = openLixes.get(args.id)!;
+			} else {
+				const blob = store.get(args.id);
+				lix = await openLixInMemory({
+					blob,
+					// don't sync the server with itself
+					keyValues: [{ key: "#lix_sync", value: "false" }],
+				});
+
+				lix.sqlite.exec("PRAGMA foreign_keys = OFF;");
+
+				openLixes.set(args.id, lix);
+			}
+
+			if (openConnections.has(args.id)) {
+				openConnections.get(args.id)!.add(connectionId);
+			} else {
+				openConnections.set(args.id, new Set([connectionId]));
+			}
+
+			return { lix, id: args.id, connectionId };
+		},
+
+		async closeLix(args: { id: string; connectionId: string }): Promise<void> {
+			const connections = openConnections.get(args.id);
+			if (!connections) {
+				throw new Error(`No open connections for lix ${args.id}`);
+			}
+
+			connections.delete(args.connectionId);
+
+			if (connections.size === 0) {
+				// TODO no concurrency guarantees
+				const lix = openLixes.get(args.id);
+				const blob = await lix!.toBlob();
+				await lix?.close();
+				openConnections.delete(args.id);
+				openLixes.delete(args.id);
+				store.set(args.id, blob);
+			}
+		},
+	};
+};

package/src/server-api-handler/environment/environment.ts

@@ -0,0 +1,43 @@
+import type { Lix } from "../../lix/open-lix.js";
+
+/**
+ * Key value storage interface.
+ */
+export type LsaEnvironment = {
+	get(key: string): Promise<Blob | undefined>;
+	set(key: string, value: Blob): Promise<void>;
+	has(key: string): Promise<boolean>;
+	delete(key: string): Promise<void>;
+
+	getLix(args: { id: string }): Promise<Blob | undefined>;
+
+	/**
+	 * If a lix exists on the server.
+	 */
+	hasLix(args: { id: string }): Promise<boolean>;
+
+	/**
+	 * Set's a lix.
+	 */
+	setLix(args: { id: string; blob: Blob }): Promise<void>;
+
+	/**
+	 * Opens a lix.
+	 *
+	 * The server will return a connection id that can be used to close the lix.
+	 */
+	openLix(args: {
+		id: string;
+	}): Promise<{ lix: Lix; id: string; connectionId: string }>;
+	/**
+	 * Closes a lix.
+	 *
+	 * The connection id is returned when opening a lix.
+	 *
+	 * @example
+	 *   const { lix, connectionId } = await openLix({ id: 'my-lix' });
+	 *   // do stuff with the lix
+	 *   await closeLix({ connectionId });
+	 */
+	closeLix(args: { id: string; connectionId: string }): Promise<void>;
+};

package/src/server-api-handler/index.ts

@@ -0,0 +1,5 @@
+export {
+	createServerApiHandler,
+	type LixServerApiHandlerContext,
+} from "./create-server-api-handler.js";
+export { createLsaInMemoryEnvironment } from "./environment/create-in-memory-environment.js";

package/src/server-api-handler/routes/get-v1.test.ts

@@ -0,0 +1,146 @@
+import { test, expect } from "vitest";
+import { createServerApiHandler } from "../create-server-api-handler.js";
+import { newLixFile } from "../../lix/new-lix.js";
+import { openLixInMemory } from "../../lix/open-lix-in-memory.js";
+import { createLsaInMemoryEnvironment } from "../environment/create-in-memory-environment.js";
+
+test("it should fetch the lix file from the server", async () => {
+	const lix = await openLixInMemory({
+		blob: await newLixFile(),
+	});
+	const { value: id } = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "lix_id")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	await lix.db
+		.insertInto("key_value")
+		.values({ key: "mock_key", value: "hello world" })
+		.execute();
+
+	const environment = createLsaInMemoryEnvironment();
+	const lsaHandler = await createServerApiHandler({ environment });
+
+	// Store the lix file
+	await lsaHandler(
+		new Request("http://localhost:3000/lsa/new-v1", {
+			method: "POST",
+			body: await lix.toBlob(),
+		})
+	);
+
+	// Fetch the lix file
+	const response = await lsaHandler(
+		new Request("http://localhost:3000/lsa/get-v1", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({ lix_id: id }),
+		})
+	);
+
+	const blob = await response.blob();
+
+	const lixFromServer = await openLixInMemory({ blob });
+
+	const mockKey = await lixFromServer.db
+		.selectFrom("key_value")
+		.where("key", "=", "mock_key")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	const idFromServer = await lixFromServer.db
+		.selectFrom("key_value")
+		.where("key", "=", "lix_id")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(response.status).toBe(200);
+	expect(idFromServer.value).toBe(id);
+	expect(mockKey.value).toBe("hello world");
+});
+
+test("it should return 404 if the lix file does not exist", async () => {
+	const environment = createLsaInMemoryEnvironment();
+
+	const lsaHandler = await createServerApiHandler({ environment });
+
+	const response = await lsaHandler(
+		new Request("http://localhost:3000/lsa/get-v1", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({ lix_id: "non-existent-id" }),
+		})
+	);
+
+	const responseJson = await response.json();
+
+	expect(response.status).toBe(404);
+	expect(responseJson.error).toBe("Lix not found");
+});
+
+test("it should return 400 for a request without lix_id", async () => {
+	const environment = createLsaInMemoryEnvironment();
+	const lsaHandler = await createServerApiHandler({ environment });
+
+	const response = await lsaHandler(
+		new Request("http://localhost:3000/lsa/get-v1", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({}),
+		})
+	);
+
+	const responseJson = await response.json();
+
+	expect(response.status).toBe(400);
+	expect(responseJson.error).toBe("Missing required field 'lix_id'");
+});
+
+test("#lix_sync is set to true", async () => {
+	const environment = createLsaInMemoryEnvironment();
+	const lsaHandler = await createServerApiHandler({ environment });
+
+	const lix = await openLixInMemory({
+		blob: await newLixFile(),
+		keyValues: [{ key: "#lix_sync", value: "false" }],
+	});
+
+	// Store the lix file
+	const response0 = await lsaHandler(
+		new Request("http://localhost:3000/lsa/new-v1", {
+			method: "POST",
+			body: await lix.toBlob(),
+		})
+	);
+
+	const id = (await response0.json()).id;
+
+	const response1 = await lsaHandler(
+		new Request("http://localhost:3000/lsa/get-v1", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({ lix_id: id }),
+		})
+	);
+
+	const blob = await response1.blob();
+
+	const lixFromServer = await openLixInMemory({ blob });
+
+	const lixSync = await lixFromServer.db
+		.selectFrom("key_value")
+		.where("key", "=", "#lix_sync")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(lixSync.value).toBe("true");
+});

package/src/server-api-handler/routes/get-v1.ts

@@ -0,0 +1,63 @@
+import {
+	contentFromDatabase,
+	createInMemoryDatabase,
+	importDatabase,
+} from "sqlite-wasm-kysely";
+import type { LixServerApiHandlerRoute } from "../create-server-api-handler.js";
+
+export const route: LixServerApiHandlerRoute = async (context) => {
+	const { lix_id } = await context.request.json();
+
+	if (!lix_id) {
+		return new Response(
+			JSON.stringify({ error: "Missing required field 'lix_id'" }),
+			{
+				status: 400,
+				headers: {
+					"Content-Type": "application/json",
+				},
+			}
+		);
+	}
+
+	const exists = await context.environment.hasLix({ id: lix_id });
+
+	if (!exists) {
+		return new Response(JSON.stringify({ error: "Lix not found" }), {
+			status: 404,
+			headers: {
+				"Content-Type": "application/json",
+			},
+		});
+	}
+
+	const blob = await context.environment.getLix({ id: lix_id });
+
+	// setting the sync to true if a client requests the lix
+	// else, the client opens the lix and it's not syncing
+	//
+	// - not opening via openLix because that would trigger
+	//   the sync process
+	const sqlite = await createInMemoryDatabase({
+		readOnly: false,
+	});
+
+	importDatabase({
+		db: sqlite,
+		content: new Uint8Array(await blob!.arrayBuffer()),
+	});
+
+	sqlite.exec("UPDATE key_value SET value = 'true' WHERE key = '#lix_sync'");
+
+	const blob2 = new Blob([contentFromDatabase(sqlite)]);
+
+	sqlite.close();
+
+	return new Response(blob2, {
+		status: 200,
+		headers: {
+			"Content-Type": "application/octet-stream",
+			"Content-Disposition": `attachment; filename="${lix_id}.bin"`,
+		},
+	});
+};

package/src/server-api-handler/routes/new-v1.test.ts

@@ -0,0 +1,102 @@
+import { test, expect } from "vitest";
+import { createServerApiHandler } from "../create-server-api-handler.js";
+import { newLixFile } from "../../lix/new-lix.js";
+import { openLixInMemory } from "../../lix/open-lix-in-memory.js";
+import { createLsaInMemoryEnvironment } from "../environment/create-in-memory-environment.js";
+
+test("it should store the lix file", async () => {
+	const initLix = await openLixInMemory({
+		blob: await newLixFile(),
+	});
+
+	const initLixId = await initLix.db
+		.selectFrom("key_value")
+		.where("key", "=", "lix_id")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	const environment = createLsaInMemoryEnvironment();
+
+	const lsaHandler = await createServerApiHandler({ environment });
+
+	const response = await lsaHandler(
+		new Request("http://localhost:3000/lsa/new-v1", {
+			method: "POST",
+			body: await initLix.toBlob(),
+		})
+	);
+	const json = await response.json();
+
+	expect(response.status).toBe(201);
+	expect(json.id).toBe(initLixId.value);
+
+	const hasLix = await environment.hasLix({ id: initLixId.value });
+
+	expect(hasLix).toBe(true);
+
+	const open = await environment.openLix({
+		id: initLixId.value,
+	});
+
+	const lixId = await open.lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "lix_id")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(lixId.value).toEqual(initLixId.value);
+
+	await environment.closeLix({
+		id: initLixId.value,
+		connectionId: open.connectionId,
+	});
+});
+
+// Test is skipped because it works as expected but
+// the opening of the lix file is logged as error to
+// the console. Requires lix logging system to be
+// implemented. Hence, skipped for now.
+test.skip("it should return 400 for an invalid lix file", async () => {
+	const invalidLixFile = new Blob(["invalid content"]);
+
+	console.error = () => {};
+
+	const environment = createLsaInMemoryEnvironment();
+
+	const lsaHandler = await createServerApiHandler({ environment });
+
+	const response = await lsaHandler(
+		new Request("http://localhost:3000/lsa/new-v1", {
+			method: "POST",
+			body: invalidLixFile,
+		})
+	);
+
+	expect(response.status).toBe(400);
+});
+
+test("it should return 409 if the lix file already exists", async () => {
+	const lixFile = await newLixFile();
+
+	const environment = createLsaInMemoryEnvironment();
+
+	const lsaHandler = await createServerApiHandler({ environment });
+
+	// First request to store the lix file
+	await lsaHandler(
+		new Request("http://localhost:3000/lsa/new-v1", {
+			method: "POST",
+			body: lixFile,
+		})
+	);
+
+	// Second request to store the same lix file
+	const response = await lsaHandler(
+		new Request("http://localhost:3000/lsa/new-v1", {
+			method: "POST",
+			body: lixFile,
+		})
+	);
+
+	expect(response.status).toBe(409);
+});

package/src/server-api-handler/routes/new-v1.ts

@@ -0,0 +1,44 @@
+import { openLixInMemory } from "../../lix/open-lix-in-memory.js";
+import type { Lix } from "../../lix/open-lix.js";
+import type { LixServerApiHandlerRoute } from "../create-server-api-handler.js";
+
+export const route: LixServerApiHandlerRoute = async (context) => {
+	const blob = await context.request.blob();
+
+	let lix: Lix;
+
+	try {
+		lix = await openLixInMemory({
+			blob,
+			// turn off sync for server
+			keyValues: [{ key: "#lix_sync", value: "false" }],
+		});
+	} catch {
+		return new Response(null, {
+			status: 400,
+		});
+	}
+
+	const lixId = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "lix_id")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	const exists = await context.environment.hasLix({ id: lixId.value });
+
+	if (exists) {
+		return new Response(null, {
+			status: 409,
+		});
+	}
+
+	await context.environment.setLix({ id: lixId.value, blob });
+
+	return new Response(JSON.stringify({ id: lixId.value }), {
+		status: 201,
+		headers: {
+			"Content-Type": "application/json",
+		},
+	});
+};