@wnlx/o2-client 1.0.0

package/dist/index.mjs

@@ -0,0 +1,595 @@
+import { createConnection, isIP } from "node:net";
+import { connect } from "node:tls";
+import crypto from "crypto";
+//#region src/helpers/hmac.ts
+function calculateResponse(challenge, clientSecret) {
+	return crypto.createHmac("sha256", clientSecret).update(challenge).digest("hex");
+}
+const MAX_BODY_SIZE = 1048576;
+function buildHeader(opcode, streamId, paramLen, flagsLen, bodyLen) {
+	validateHeader({
+		opcode,
+		streamId,
+		paramLen,
+		flagsLen,
+		bodyLen
+	});
+	const header = /* @__PURE__ */ new Uint8Array(20);
+	const view = new DataView(header.buffer);
+	view.setUint32(0, opcode, false);
+	view.setUint32(4, streamId, false);
+	view.setUint32(8, paramLen, false);
+	view.setUint32(12, flagsLen, false);
+	view.setUint32(16, bodyLen, false);
+	return header;
+}
+function parseHeader(header) {
+	if (header.byteLength < 20) throw new Error("Incomplete O2 header");
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	const parsed = {
+		opcode: view.getUint32(0, false),
+		streamId: view.getUint32(4, false),
+		paramLen: view.getUint32(8, false),
+		flagsLen: view.getUint32(12, false),
+		bodyLen: view.getUint32(16, false)
+	};
+	validateHeader(parsed);
+	return parsed;
+}
+function validateHeader(header) {
+	const { opcode, streamId, paramLen, flagsLen, bodyLen } = header;
+	for (const value of [
+		opcode,
+		streamId,
+		paramLen,
+		flagsLen,
+		bodyLen
+	]) if (!Number.isInteger(value) || value < 0 || value > 4294967295) throw new Error("Invalid O2 header value");
+	if (paramLen > 65536 || flagsLen > 65536 || bodyLen > 1048576) throw new Error("O2 frame exceeds size limits");
+}
+function parseMessage(message, header) {
+	const { opcode, streamId, paramLen, flagsLen, bodyLen } = header;
+	const expectedLength = 20 + paramLen + flagsLen + bodyLen;
+	if (message.byteLength < expectedLength) throw new Error(`Incomplete O2 frame: expected ${expectedLength} bytes, got ${message.byteLength}`);
+	let offset = 20;
+	const param = message.subarray(offset, offset + paramLen);
+	offset += paramLen;
+	const flags = message.subarray(offset, offset + flagsLen);
+	offset += flagsLen;
+	return {
+		opcode,
+		streamId,
+		param,
+		flags,
+		body: message.subarray(offset, offset + bodyLen)
+	};
+}
+function parseFlags(flags) {
+	const flagPairs = flags.split(",");
+	const flagObject = Object.create(null);
+	for (const pair of flagPairs) {
+		const [key, value] = pair.split("=");
+		if (key && value) flagObject[key.trim()] = value.trim();
+	}
+	return flagObject;
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+var FrameReader = class {
+	buffer = /* @__PURE__ */ new Uint8Array(20);
+	offset = 0;
+	header = null;
+	get incomplete() {
+		return this.offset !== 0;
+	}
+	*push(data) {
+		let position = 0;
+		while (position < data.length) {
+			const count = Math.min(this.buffer.length - this.offset, data.length - position);
+			this.buffer.set(data.subarray(position, position + count), this.offset);
+			this.offset += count;
+			position += count;
+			if (this.offset !== this.buffer.length) continue;
+			if (!this.header) {
+				this.header = parseHeader(this.buffer);
+				const length = 20 + this.header.paramLen + this.header.flagsLen + this.header.bodyLen;
+				if (length > 20) {
+					const frame = new Uint8Array(length);
+					frame.set(this.buffer);
+					this.buffer = frame;
+					continue;
+				}
+			}
+			const parsed = parseMessage(this.buffer, this.header);
+			this.buffer = /* @__PURE__ */ new Uint8Array(20);
+			this.offset = 0;
+			this.header = null;
+			yield parsed;
+		}
+	}
+};
+var SocketWriter = class {
+	socket;
+	queue = [];
+	pendingBytes = 0;
+	failure = null;
+	constructor(socket) {
+		this.socket = socket;
+	}
+	write(bytes) {
+		if (this.failure) return Promise.reject(this.failure);
+		if (this.pendingBytes + bytes.length > 4194304) return Promise.reject(/* @__PURE__ */ new Error("Outbound queue exceeds limit"));
+		return new Promise((resolve, reject) => {
+			this.queue.push({
+				bytes,
+				offset: 0,
+				resolve,
+				reject
+			});
+			this.pendingBytes += bytes.length;
+			if (this.queue.length === 1) this.drain();
+		});
+	}
+	frame(opcode, streamId, param = "", flags = /* @__PURE__ */ new Uint8Array(), body = /* @__PURE__ */ new Uint8Array()) {
+		const params = encoder.encode(param);
+		const header = buildHeader(opcode, streamId, params.length, flags.length, body.length);
+		const bytes = new Uint8Array(header.length + params.length + flags.length + body.length);
+		let offset = 0;
+		bytes.set(header, offset);
+		offset += header.length;
+		bytes.set(params, offset);
+		offset += params.length;
+		bytes.set(flags, offset);
+		offset += flags.length;
+		bytes.set(body, offset);
+		return this.write(bytes);
+	}
+	drain() {
+		try {
+			while (this.queue.length) {
+				const pending = this.queue[0];
+				const written = this.socket.write(pending.bytes.subarray(pending.offset));
+				if (written < 0) throw new Error("Socket closed during write");
+				pending.offset += written;
+				this.pendingBytes -= written;
+				if (pending.offset < pending.bytes.length) return;
+				this.queue.shift();
+				pending.resolve();
+			}
+		} catch (error) {
+			this.close(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	close(error = /* @__PURE__ */ new Error("Connection closed")) {
+		this.failure ??= error;
+		for (const pending of this.queue.splice(0)) pending.reject(this.failure);
+		this.pendingBytes = 0;
+	}
+};
+//#endregion
+//#region src/sdk/client.ts
+var O2Error = class extends Error {
+	streamId;
+	constructor(message, streamId) {
+		super(message);
+		this.streamId = streamId;
+		this.name = "O2Error";
+	}
+};
+function deferred() {
+	let resolve;
+	let reject;
+	return {
+		promise: new Promise((res, rej) => {
+			resolve = res;
+			reject = rej;
+		}),
+		resolve,
+		reject
+	};
+}
+var AsyncByteQueue = class {
+	highWaterMark;
+	chunks = [];
+	readers = [];
+	drainWaiters = [];
+	buffered = 0;
+	ended = false;
+	failure = null;
+	constructor(highWaterMark) {
+		this.highWaterMark = highWaterMark;
+	}
+	async push(chunk) {
+		if (this.ended || this.failure) return;
+		const reader = this.readers.shift();
+		if (reader) {
+			reader.resolve({
+				value: chunk,
+				done: false
+			});
+			return;
+		}
+		this.chunks.push(chunk);
+		this.buffered += chunk.byteLength;
+		if (this.buffered > this.highWaterMark) await new Promise((resolve) => this.drainWaiters.push(resolve));
+	}
+	close() {
+		if (this.ended || this.failure) return;
+		this.ended = true;
+		for (const reader of this.readers.splice(0)) reader.resolve({
+			value: void 0,
+			done: true
+		});
+		this.releaseDrainWaiters();
+	}
+	fail(error) {
+		if (this.failure || this.ended) return;
+		this.failure = error;
+		for (const reader of this.readers.splice(0)) reader.reject(error);
+		this.releaseDrainWaiters();
+	}
+	async next() {
+		if (this.failure) throw this.failure;
+		const chunk = this.chunks.shift();
+		if (chunk) {
+			this.buffered -= chunk.byteLength;
+			if (this.buffered <= this.highWaterMark / 2) this.releaseDrainWaiters();
+			return {
+				value: chunk,
+				done: false
+			};
+		}
+		if (this.ended) return {
+			value: void 0,
+			done: true
+		};
+		const waiter = deferred();
+		this.readers.push(waiter);
+		return waiter.promise;
+	}
+	[Symbol.asyncIterator]() {
+		return this;
+	}
+	releaseDrainWaiters() {
+		for (const resolve of this.drainWaiters.splice(0)) resolve();
+	}
+};
+var O2Client = class {
+	options;
+	socket = null;
+	writer = null;
+	reader = new FrameReader();
+	incomingWork = Promise.resolve();
+	pendingBytes = 0;
+	writeBlocked = false;
+	nextStreamId = 1;
+	connected = false;
+	closing = false;
+	challengeWaiter = null;
+	controlWaiter = null;
+	requests = /* @__PURE__ */ new Map();
+	transfers = /* @__PURE__ */ new Map();
+	host;
+	port;
+	transferBufferBytes;
+	constructor(options) {
+		this.options = options;
+		this.host = options.host ?? "127.0.0.1";
+		this.port = options.port ?? 52202;
+		this.transferBufferBytes = options.transferBufferBytes ?? 4194304;
+	}
+	async connect() {
+		if (this.connected) return;
+		if (this.socket) throw new Error("O2 connection is already opening");
+		const tlsOptions = this.options.tls;
+		const socket = tlsOptions ? connect({
+			host: this.host,
+			port: this.port,
+			...typeof tlsOptions === "object" ? tlsOptions : {},
+			servername: typeof tlsOptions === "object" && tlsOptions.servername !== void 0 ? tlsOptions.servername : isIP(this.host) ? void 0 : this.host
+		}) : createConnection({
+			host: this.host,
+			port: this.port
+		});
+		this.socket = socket;
+		this.writer = new SocketWriter({ write: (data) => {
+			if (socket.destroyed) return -1;
+			if (this.writeBlocked) return 0;
+			this.writeBlocked = !socket.write(data);
+			return data.length;
+		} });
+		socket.on("drain", () => {
+			this.writeBlocked = false;
+			this.writer?.drain();
+		});
+		socket.on("data", (incoming) => {
+			socket.pause();
+			const data = new Uint8Array(incoming);
+			this.pendingBytes += data.byteLength;
+			if (this.pendingBytes > 4194304) {
+				socket.destroy(/* @__PURE__ */ new Error("Incoming O2 queue exceeds limit"));
+				return;
+			}
+			this.incomingWork = this.incomingWork.then(async () => {
+				for (const frame of this.reader.push(data)) await this.handleFrame(frame);
+			}).catch((error) => socket.destroy(error)).finally(() => {
+				this.pendingBytes -= data.byteLength;
+				if (!socket.destroyed && this.pendingBytes === 0) socket.resume();
+			});
+		});
+		socket.on("error", (error) => this.failAll(error));
+		socket.on("close", () => {
+			this.connected = false;
+			this.writer?.close();
+			this.failAll(/* @__PURE__ */ new Error("O2 connection closed"));
+			this.socket = null;
+			this.writer = null;
+		});
+		await new Promise((resolve, reject) => {
+			const readyEvent = tlsOptions ? "secureConnect" : "connect";
+			const onReady = () => {
+				socket.off("error", onError);
+				resolve();
+			};
+			const onError = (error) => {
+				socket.off(readyEvent, onReady);
+				reject(error);
+			};
+			socket.once(readyEvent, onReady);
+			socket.once("error", onError);
+		});
+		this.challengeWaiter = deferred();
+		await this.writer.frame(0, 0);
+		const challenge = await this.challengeWaiter.promise;
+		this.controlWaiter = deferred();
+		await this.writer.frame(1, 0, `${this.options.keyId}:${calculateResponse(challenge, this.options.secret)}`);
+		await this.controlWaiter.promise;
+		this.connected = true;
+	}
+	async close() {
+		if (!this.socket) return;
+		this.closing = true;
+		try {
+			if (this.writer && !this.socket.destroyed) {
+				this.controlWaiter = deferred();
+				await this.writer.frame(255, 0);
+				await Promise.race([this.controlWaiter.promise, new Promise((resolve) => setTimeout(() => resolve("timeout"), 1e3))]);
+			}
+		} finally {
+			this.socket?.end();
+			this.closing = false;
+		}
+	}
+	async listNamespaces() {
+		const message = await this.request(2);
+		if (!message) return [];
+		return message.split(",").map((entry) => {
+			const separator = entry.lastIndexOf(":");
+			return {
+				name: entry.slice(0, separator),
+				length: Number(entry.slice(separator + 1))
+			};
+		});
+	}
+	async listObjects(namespace) {
+		const message = await this.request(2, namespace);
+		if (!message) return [];
+		return message.split(",").map((entry) => {
+			const separator = entry.lastIndexOf(":");
+			return {
+				key: entry.slice(0, separator),
+				size: Number(entry.slice(separator + 1))
+			};
+		});
+	}
+	async createNamespace(namespace) {
+		await this.request(3, namespace);
+	}
+	async deleteNamespace(namespace) {
+		await this.request(4, namespace);
+	}
+	async metadata(namespace, key) {
+		const message = await this.request(11, `${namespace}:${key}`);
+		const separator = message.lastIndexOf(":");
+		if (separator <= 0) throw new O2Error("Invalid METADATA response");
+		return {
+			sha256: message.slice(0, separator),
+			size: Number(message.slice(separator + 1))
+		};
+	}
+	async deleteObject(namespace, key) {
+		return this.request(9, `${namespace}:${key}`);
+	}
+	async putObject(namespace, key, data, options = {}) {
+		async function* chunks() {
+			const chunkSize = options.chunkSize ?? 262144;
+			for (let offset = 0; offset < data.length; offset += chunkSize) yield data.subarray(offset, Math.min(offset + chunkSize, data.length));
+		}
+		await this.putObjectStream(namespace, key, chunks());
+	}
+	async putObjectStream(namespace, key, source) {
+		this.ensureConnected();
+		const streamId = this.allocateStreamId();
+		const identifier = `${namespace}:${key}`;
+		try {
+			await this.requestOnStream(streamId, 5, identifier);
+			for await (const chunk of source) {
+				if (!(chunk instanceof Uint8Array)) throw new Error("PUT source must yield Uint8Array chunks");
+				if (!chunk.length) continue;
+				if (chunk.length > 1048576) throw new Error(`PUT chunk exceeds ${MAX_BODY_SIZE} bytes`);
+				await this.requestOnStream(streamId, 6, identifier, /* @__PURE__ */ new Uint8Array(), Uint8Array.from(chunk));
+			}
+			await this.requestOnStream(streamId, 7, identifier);
+		} catch (error) {
+			if (this.writer && this.socket && !this.socket.destroyed) await this.writer.frame(8, streamId, identifier).catch(() => {});
+			throw error;
+		}
+	}
+	async signObject(namespace, key, expirySeconds) {
+		if (!Number.isSafeInteger(expirySeconds) || expirySeconds <= 0) throw new Error("expirySeconds must be a positive integer");
+		return this.request(12, `${namespace}:${key}`, encoder.encode(`EXPIRY=${expirySeconds}`));
+	}
+	async retrieve(namespace, key, options = {}) {
+		const chunkSize = options.chunkSize ?? 262144;
+		if (!Number.isSafeInteger(chunkSize) || chunkSize < 1 || chunkSize > 1048576) throw new Error(`chunkSize must be between 1 and ${MAX_BODY_SIZE}`);
+		if (options.offset !== void 0 && (!Number.isSafeInteger(options.offset) || options.offset < 0)) throw new Error("offset must be a non-negative integer");
+		if (options.length !== void 0 && (!Number.isSafeInteger(options.length) || options.length <= 0)) throw new Error("length must be a positive integer");
+		if (options.length !== void 0 && options.offset === void 0) throw new Error("length requires offset");
+		this.ensureConnected();
+		const streamId = this.allocateStreamId();
+		const begin = deferred();
+		const state = {
+			begin,
+			queue: new AsyncByteQueue(this.transferBufferBytes),
+			identifier: `${namespace}:${key}`,
+			namespace,
+			key,
+			finished: false
+		};
+		this.transfers.set(streamId, state);
+		const flags = [`CHUNK_SIZE=${chunkSize}`];
+		if (options.offset !== void 0) flags.push(`OFFSET=${options.offset}`);
+		if (options.length !== void 0) flags.push(`LENGTH=${options.length}`);
+		try {
+			await this.writer.frame(10, streamId, state.identifier, encoder.encode(flags.join(",")));
+		} catch (error) {
+			this.transfers.delete(streamId);
+			throw error;
+		}
+		return begin.promise;
+	}
+	async request(opcode, param = "", flags = /* @__PURE__ */ new Uint8Array()) {
+		this.ensureConnected();
+		const streamId = this.allocateStreamId();
+		const waiter = deferred();
+		this.requests.set(streamId, waiter);
+		try {
+			await this.writer.frame(opcode, streamId, param, flags);
+			return await waiter.promise;
+		} finally {
+			this.requests.delete(streamId);
+		}
+	}
+	async handleFrame(frame) {
+		const message = decoder.decode(frame.param);
+		if (frame.streamId === 0) {
+			if (frame.opcode === 2) {
+				this.challengeWaiter?.resolve(message);
+				this.challengeWaiter = null;
+				return;
+			}
+			if (frame.opcode === 1) {
+				this.controlWaiter?.resolve(message);
+				this.controlWaiter = null;
+				return;
+			}
+			if (frame.opcode === 0) {
+				const error = new O2Error(message, 0);
+				this.controlWaiter?.reject(error);
+				this.challengeWaiter?.reject(error);
+				this.controlWaiter = null;
+				this.challengeWaiter = null;
+				return;
+			}
+			throw new O2Error(`Unexpected control response ${frame.opcode}`, 0);
+		}
+		const transfer = this.transfers.get(frame.streamId);
+		if (transfer) {
+			if (frame.opcode === 0) {
+				const error = new O2Error(message, frame.streamId);
+				transfer.begin.reject(error);
+				transfer.queue.fail(error);
+				this.transfers.delete(frame.streamId);
+				return;
+			}
+			if (frame.opcode === 3) {
+				if (message !== transfer.identifier || frame.body.length) throw new O2Error("Invalid RET_BEGIN", frame.streamId);
+				const metadata = parseFlags(decoder.decode(frame.flags));
+				const size = Number(metadata.SIZE);
+				if (!Number.isSafeInteger(size) || size < 0) throw new O2Error("RET_BEGIN missing valid SIZE", frame.streamId);
+				const sha256 = metadata.SHA256;
+				const retrieval = {
+					streamId: frame.streamId,
+					namespace: transfer.namespace,
+					key: transfer.key,
+					size,
+					sha256,
+					[Symbol.asyncIterator]: () => transfer.queue,
+					cancel: async () => this.cancelTransfer(frame.streamId)
+				};
+				transfer.begin.resolve(retrieval);
+				return;
+			}
+			if (frame.opcode === 4) {
+				if (frame.param.length || frame.flags.length || !frame.body.length) throw new O2Error("Invalid RET_CHUNK", frame.streamId);
+				await transfer.queue.push(frame.body.slice());
+				return;
+			}
+			if (frame.opcode === 5) {
+				if (message !== transfer.identifier || frame.flags.length || frame.body.length) throw new O2Error("Invalid RET_END", frame.streamId);
+				transfer.finished = true;
+				transfer.queue.close();
+				this.transfers.delete(frame.streamId);
+				return;
+			}
+			throw new O2Error(`Unexpected transfer response ${frame.opcode}`, frame.streamId);
+		}
+		const request = this.requests.get(frame.streamId);
+		if (!request) return;
+		if (frame.flags.length || frame.body.length) {
+			request.reject(new O2Error("Invalid response payload", frame.streamId));
+			return;
+		}
+		if (frame.opcode === 1) request.resolve(message);
+		else if (frame.opcode === 0) request.reject(new O2Error(message, frame.streamId));
+		else request.reject(new O2Error(`Unexpected response ${frame.opcode}`, frame.streamId));
+	}
+	async requestOnStream(streamId, opcode, param = "", flags = /* @__PURE__ */ new Uint8Array(), body = /* @__PURE__ */ new Uint8Array()) {
+		this.ensureConnected();
+		if (this.requests.has(streamId)) throw new Error(`Stream ${streamId} already has a pending request`);
+		const waiter = deferred();
+		this.requests.set(streamId, waiter);
+		try {
+			await this.writer.frame(opcode, streamId, param, flags, body);
+			return await waiter.promise;
+		} finally {
+			this.requests.delete(streamId);
+		}
+	}
+	async cancelTransfer(streamId) {
+		const transfer = this.transfers.get(streamId);
+		if (!transfer) return;
+		this.transfers.delete(streamId);
+		const error = new O2Error("Transfer cancelled", streamId);
+		transfer.begin.reject(error);
+		transfer.queue.fail(error);
+		if (this.writer && this.socket && !this.socket.destroyed) await this.writer.frame(13, streamId).catch(() => {});
+	}
+	allocateStreamId() {
+		for (let attempts = 0; attempts < 4294967295; attempts++) {
+			const id = this.nextStreamId++;
+			if (this.nextStreamId > 4294967295) this.nextStreamId = 1;
+			if (!this.requests.has(id) && !this.transfers.has(id)) return id;
+		}
+		throw new Error("No O2 stream IDs available");
+	}
+	ensureConnected() {
+		if (!this.connected || !this.writer || !this.socket || this.socket.destroyed) throw new Error("O2 client is not connected");
+	}
+	failAll(error) {
+		if (this.closing) return;
+		this.challengeWaiter?.reject(error);
+		this.controlWaiter?.reject(error);
+		this.challengeWaiter = null;
+		this.controlWaiter = null;
+		for (const waiter of this.requests.values()) waiter.reject(error);
+		this.requests.clear();
+		for (const transfer of this.transfers.values()) {
+			transfer.begin.reject(error);
+			transfer.queue.fail(error);
+		}
+		this.transfers.clear();
+	}
+};
+//#endregion
+export { O2Client, O2Error };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@wnlx/o2-client",
+  "version": "1.0.0",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.mts",
+  "module": "./dist/index.js",
+  "private": false,
+  "dependencies": {
+    "elysia": "^1.4.30",
+    "jose": "^6.2.12",
+    "mime-types": "^3.0.2"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown src/sdk/index.ts --format esm,cjs --dts --clean",
+    "prepublishOnly": "bun run typecheck && bun run build"
+  },
+  "type": "module",
+  "devDependencies": {
+    "tsdown": "^0.23.0"
+  }
+}