@midsummer-ai/sdk 0.0.0-stage → 0.1.0-next.1723

package/contract.d.mts

@@ -0,0 +1,10 @@
+import { p as Storage } from "./index-sgdyoA2P.mjs";
+//#region src/contract.d.ts
+interface ContractCase {
+  /** A line of the specification. */
+  readonly name: string;
+  run(storage: Storage): Promise<void>;
+}
+declare const storageContract: ReadonlyArray<ContractCase>;
+//#endregion
+export { ContractCase, storageContract };

package/contract.mjs

@@ -0,0 +1,469 @@
+import { h as StorageError } from "./names-DfCBKupJ.mjs";
+import "./index.mjs";
+//#region src/contract.ts
+/**
+* Storage's contract: what every engine promises, as cases any test runner can run. The Stand-in
+* runs them in this package; the real Capability runs the same cases against its own engine,
+* through the wire. A behaviour that is not a case here is not promised.
+*
+*   for (const c of storageContract) test(c.name, () => c.run(storage(makeEngine())))
+*
+* Each case gets a Storage with nothing in it and throws when the engine breaks the promise.
+* Expected values are written out, never computed with the SDK's own code.
+*/
+const HELLO = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824";
+const HELLO_WORLD = "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9";
+const storageContract = [
+	{
+		name: "an Object put is read back byte for byte, with its size, content type, metadata and SHA-256 etag",
+		async run(storage) {
+			const bucket = storage.bucket("avatars");
+			const put = await bucket.put("ada.txt", "hello", {
+				contentType: "text/plain",
+				metadata: { owner: "ada" }
+			});
+			equal(pick(put), {
+				key: "ada.txt",
+				size: 5,
+				etag: HELLO,
+				contentType: "text/plain",
+				metadata: { owner: "ada" }
+			}, "the put's answer");
+			const read = await bucket.get("ada.txt");
+			equal(read && text(read.body), "hello", "the bytes read");
+			equal(read && pick(read), pick(put), "the read's description");
+			equal(await bucket.head("ada.txt"), put, "the head");
+		}
+	},
+	{
+		name: "a key that holds nothing reads and heads as null, and deleting it is not an error",
+		async run(storage) {
+			const bucket = storage.bucket("avatars");
+			equal(await bucket.get("nobody.png"), null, "the read");
+			equal(await bucket.head("nobody.png"), null, "the head");
+			await bucket.delete("nobody.png");
+			await bucket.put("ada.txt", "hello");
+			await bucket.delete("ada.txt");
+			equal(await bucket.get("ada.txt"), null, "the read after its delete");
+		}
+	},
+	{
+		name: "a put replaces the Object and the next read sees it, whatever the caller does to its buffer afterwards",
+		async run(storage) {
+			const bucket = storage.bucket("avatars");
+			await bucket.put("ada.txt", "hello");
+			const bytes = new TextEncoder().encode("hello world");
+			const put = await bucket.put("ada.txt", bytes);
+			bytes.fill(0);
+			const read = await bucket.get("ada.txt");
+			equal(read && text(read.body), "hello world", "the bytes read");
+			equal(put.etag, HELLO_WORLD, "the new etag");
+			equal(put.contentType, "application/octet-stream", "the default content type");
+		}
+	},
+	{
+		name: "a conditional put refuses to overwrite: ifNoneMatch when the key holds something, ifMatch when the etag differs",
+		async run(storage) {
+			const bucket = storage.bucket("avatars");
+			await bucket.put("ada.txt", "hello", { ifNoneMatch: "*" });
+			await fails(bucket.put("ada.txt", "again", { ifNoneMatch: "*" }), "conflict", "ifNoneMatch on a key that holds something");
+			await fails(bucket.put("ada.txt", "again", { ifMatch: HELLO_WORLD }), "conflict", "ifMatch with another etag");
+			await fails(bucket.put("grace.txt", "hello", { ifMatch: HELLO }), "conflict", "ifMatch on a key that holds nothing");
+			await bucket.put("ada.txt", "hello world", { ifMatch: HELLO });
+			const read = await bucket.get("ada.txt");
+			equal(read && text(read.body), "hello world", "the bytes after the conditional put that held");
+		}
+	},
+	{
+		name: "a range read returns exactly those bytes, cut at the end, and a range that starts past the end is invalid",
+		async run(storage) {
+			const bucket = storage.bucket("videos");
+			await bucket.put("clip.bin", "0123456789");
+			for (const [options, bytes, range] of [
+				[
+					{ range: {
+						offset: 2,
+						length: 3
+					} },
+					"234",
+					{
+						offset: 2,
+						length: 3
+					}
+				],
+				[
+					{ range: { offset: 7 } },
+					"789",
+					{
+						offset: 7,
+						length: 3
+					}
+				],
+				[
+					{ range: {
+						offset: 8,
+						length: 100
+					} },
+					"89",
+					{
+						offset: 8,
+						length: 2
+					}
+				],
+				[
+					{ range: { suffix: 3 } },
+					"789",
+					{
+						offset: 7,
+						length: 3
+					}
+				],
+				[
+					{ range: { suffix: 100 } },
+					"0123456789",
+					{
+						offset: 0,
+						length: 10
+					}
+				]
+			]) {
+				const read = await bucket.get("clip.bin", options);
+				equal(read && [
+					text(read.body),
+					read.range,
+					read.size
+				], [
+					bytes,
+					range,
+					10
+				], `the read of ${JSON.stringify(options)}`);
+			}
+			await fails(bucket.get("clip.bin", { range: { offset: 10 } }), "invalid", "a range that starts at the end");
+			equal(await bucket.get("missing.bin", { range: {
+				offset: 0,
+				length: 1
+			} }), null, "a range of a key that holds nothing");
+		}
+	},
+	{
+		name: "a listing is in UTF-8 byte order under its prefix, folds keys at the delimiter into prefixes, and pages with after",
+		async run(storage) {
+			const bucket = storage.bucket("photos");
+			for (const key of [
+				"b.txt",
+				"photos/dog.png",
+				"a.txt",
+				"photos/2026/2.png",
+				"Z.txt",
+				"photos/2026/1.png",
+				"photos/cat.png",
+				"😀",
+				"�"
+			]) await bucket.put(key, "x");
+			const keys = (listing) => [
+				listing.objects.map((o) => o.key),
+				listing.prefixes,
+				listing.next ?? null
+			];
+			equal(keys(await bucket.list()), [
+				[
+					"Z.txt",
+					"a.txt",
+					"b.txt",
+					"photos/2026/1.png",
+					"photos/2026/2.png",
+					"photos/cat.png",
+					"photos/dog.png",
+					"�",
+					"😀"
+				],
+				[],
+				null
+			], "the whole listing");
+			equal(keys(await bucket.list({
+				prefix: "photos/",
+				delimiter: "/"
+			})), [
+				["photos/cat.png", "photos/dog.png"],
+				["photos/2026/"],
+				null
+			], "one level of photos/");
+			equal(keys(await bucket.list({
+				prefix: "photos/",
+				delimiter: "/",
+				limit: 2
+			})), [
+				["photos/cat.png"],
+				["photos/2026/"],
+				"photos/cat.png"
+			], "the first page of two");
+			equal(keys(await bucket.list({
+				prefix: "photos/",
+				delimiter: "/",
+				limit: 2,
+				after: "photos/cat.png"
+			})), [
+				["photos/dog.png"],
+				[],
+				null
+			], "the second page");
+			equal(keys(await bucket.list({
+				prefix: "photos/",
+				delimiter: "/",
+				after: "photos/2026/"
+			})), [
+				["photos/cat.png", "photos/dog.png"],
+				[],
+				null
+			], "after a folded prefix, none of its keys");
+			equal(keys(await bucket.list({ limit: 9 })), [
+				(await bucket.list()).objects.map((o) => o.key),
+				[],
+				null
+			], "a page that ends exactly at the last key has no next");
+		}
+	},
+	{
+		name: "a copy puts the same content under a second key, with its content type and metadata",
+		async run(storage) {
+			const bucket = storage.bucket("avatars");
+			await bucket.put("ada.txt", "hello", {
+				contentType: "text/plain",
+				metadata: { owner: "ada" }
+			});
+			equal(pick(await bucket.copy("ada.txt", "ada-copy.txt")), {
+				key: "ada-copy.txt",
+				size: 5,
+				etag: HELLO,
+				contentType: "text/plain",
+				metadata: { owner: "ada" }
+			}, "the copy");
+			const read = await bucket.get("ada-copy.txt");
+			equal(read && text(read.body), "hello", "the copy's bytes");
+			await fails(bucket.copy("nobody.txt", "x.txt"), "not_found", "a copy from a key that holds nothing");
+			await fails(bucket.copy("ada.txt", "ada-copy.txt", { ifNoneMatch: "*" }), "conflict", "a conditional copy onto a key that holds something");
+		}
+	},
+	{
+		name: "Buckets are separate: what one holds is not in another",
+		async run(storage) {
+			await storage.bucket("avatars").put("ada.txt", "hello");
+			equal(await storage.bucket("invoices").get("ada.txt"), null, "the read in another Bucket");
+			equal((await storage.bucket("invoices").list()).objects.length, 0, "the other Bucket's listing");
+		}
+	},
+	{
+		name: "names, ranges and limits are checked: Bucket names, empty keys, keys over 1,024 UTF-8 bytes, metadata names",
+		async run(storage) {
+			for (const name of [
+				"Avatars",
+				"ab",
+				"-avatars",
+				"avatars_2",
+				"a".repeat(64)
+			]) await fails(Promise.resolve().then(() => storage.bucket(name)), "invalid", `the Bucket name "${name}"`);
+			const bucket = storage.bucket("avatars");
+			await fails(bucket.put("", "x"), "invalid", "an empty key");
+			await fails(bucket.put("é".repeat(513), "x"), "invalid", "a key of 1,026 bytes");
+			await bucket.put("é".repeat(512), "x");
+			await fails(bucket.put("ada.txt", "x", { metadata: { Owner: "ada" } }), "invalid", "a metadata name with a capital");
+			await fails(bucket.get("ada.txt", { range: { offset: -1 } }), "invalid", "a negative range offset");
+			await fails(bucket.list({ limit: 0 }), "invalid", "a listing limit of 0");
+		}
+	},
+	{
+		name: "an upload in parts becomes one Object of their bytes in part-number order when it completes, and until then the key holds what it held",
+		async run(storage) {
+			const bucket = storage.bucket("media");
+			await bucket.put("film.mp4", "old");
+			const { uploadId } = await bucket.createUpload("film.mp4", {
+				contentType: "video/mp4",
+				metadata: { owner: "ada" }
+			});
+			const second = await bucket.uploadPart("film.mp4", uploadId, 2, "hello");
+			const first = await bucket.uploadPart("film.mp4", uploadId, 1, new Uint8Array(FIVE_MIB).fill(97));
+			equal([
+				second.partNumber,
+				second.etag,
+				second.size
+			], [
+				2,
+				HELLO,
+				5
+			], "the second part, sent first");
+			equal(first.size, FIVE_MIB, "the first part's size");
+			const before = await bucket.get("film.mp4");
+			equal(before && text(before.body), "old", "the key before the upload completes");
+			const done = await bucket.completeUpload("film.mp4", uploadId, [first, second]);
+			equal([
+				done.size,
+				done.contentType,
+				done.metadata
+			], [
+				FIVE_MIB + 5,
+				"video/mp4",
+				{ owner: "ada" }
+			], "the completed Object");
+			const read = await bucket.get("film.mp4");
+			equal(read && [
+				read.body.length,
+				read.body[0],
+				read.body[FIVE_MIB - 1],
+				text(read.body.subarray(FIVE_MIB))
+			], [
+				FIVE_MIB + 5,
+				97,
+				97,
+				"hello"
+			], "the joined bytes");
+			const whole = new Uint8Array(FIVE_MIB + 5).fill(97);
+			whole.set(new TextEncoder().encode("hello"), FIVE_MIB);
+			equal(done.etag, (await bucket.put("same.bin", whole)).etag, "the etag, the same as one put of the same bytes");
+			await fails(bucket.uploadPart("film.mp4", uploadId, 3, "more"), "not_found", "a part sent after completing", "upload");
+		}
+	},
+	{
+		name: "a part sent again replaces it, and completing checks each part's etag, their order, the 5 MiB floor and that parts but the last are one size, leaving the upload open when it refuses",
+		async run(storage) {
+			const bucket = storage.bucket("media");
+			const { uploadId } = await bucket.createUpload("film.mp4");
+			const stale = await bucket.uploadPart("film.mp4", uploadId, 1, "small");
+			const first = await bucket.uploadPart("film.mp4", uploadId, 1, new Uint8Array(FIVE_MIB));
+			const second = await bucket.uploadPart("film.mp4", uploadId, 2, "hello");
+			await fails(bucket.uploadPart("film.mp4", uploadId, 10001, "x"), "invalid", "part number 10,001");
+			await fails(bucket.completeUpload("film.mp4", uploadId, [stale, second]), "invalid", "a part whose etag was replaced", "part");
+			await fails(bucket.completeUpload("film.mp4", uploadId, [second, first]), "invalid", "parts out of order", "part-order");
+			await fails(bucket.completeUpload("film.mp4", uploadId, [first, {
+				partNumber: 3,
+				etag: HELLO
+			}]), "invalid", "a part never sent", "part");
+			const small = await bucket.createUpload("small.bin");
+			const a = await bucket.uploadPart("small.bin", small.uploadId, 1, "hello");
+			const b = await bucket.uploadPart("small.bin", small.uploadId, 2, "hello");
+			await fails(bucket.completeUpload("small.bin", small.uploadId, [a, b]), "invalid", "a first part under 5 MiB", "part-too-small");
+			const uneven = await bucket.createUpload("uneven.bin");
+			const big = await bucket.uploadPart("uneven.bin", uneven.uploadId, 1, new Uint8Array(FIVE_MIB + 1));
+			const less = await bucket.uploadPart("uneven.bin", uneven.uploadId, 2, new Uint8Array(FIVE_MIB));
+			const last = await bucket.uploadPart("uneven.bin", uneven.uploadId, 3, "hello");
+			await fails(bucket.completeUpload("uneven.bin", uneven.uploadId, [
+				big,
+				less,
+				last
+			]), "invalid", "a middle part smaller than the first", "part");
+			const growing = await bucket.createUpload("growing.bin");
+			const one = await bucket.uploadPart("growing.bin", growing.uploadId, 1, new Uint8Array(FIVE_MIB));
+			const two = await bucket.uploadPart("growing.bin", growing.uploadId, 2, new Uint8Array(FIVE_MIB + 1));
+			await fails(bucket.completeUpload("growing.bin", growing.uploadId, [one, two]), "invalid", "a last part larger than the first", "part");
+			equal((await bucket.completeUpload("film.mp4", uploadId, [first, second])).size, FIVE_MIB + 5, "the upload completed after its refusals");
+		}
+	},
+	{
+		name: "an Object larger than one call carries is put, read whole and read by any range, with the etag one put of its bytes has",
+		async run(storage) {
+			const bucket = storage.bucket("media");
+			const body = pattern(LARGE);
+			const put = await bucket.put("big.bin", body);
+			equal([put.size, put.etag], [LARGE, await hex(body)], "its size, and the hash of its bytes as its etag");
+			const whole = await bucket.get("big.bin");
+			equal([
+				whole?.size,
+				whole?.range,
+				await hex(whole.body)
+			], [
+				LARGE,
+				void 0,
+				put.etag
+			], "read whole, every byte");
+			const ranges = [
+				{
+					offset: 5242887,
+					length: 31457280
+				},
+				{ suffix: 20971523 },
+				{ offset: LARGE - 1048576 }
+			];
+			for (const range of ranges) {
+				const read = await bucket.get("big.bin", { range });
+				const offset = "suffix" in range ? LARGE - range.suffix : range.offset;
+				const length = "suffix" in range ? range.suffix : range.length ?? LARGE - offset;
+				equal(read?.range, {
+					offset,
+					length
+				}, `the range ${JSON.stringify(range)}`);
+				equal(await hex(read.body), await hex(body.subarray(offset, offset + length)), `the bytes of ${JSON.stringify(range)}`);
+			}
+		}
+	},
+	{
+		name: "an aborted upload takes no more parts and cannot complete, and an unknown one is not found",
+		async run(storage) {
+			const bucket = storage.bucket("media");
+			await bucket.put("film.mp4", "old");
+			const { uploadId } = await bucket.createUpload("film.mp4");
+			const part = await bucket.uploadPart("film.mp4", uploadId, 1, "hello");
+			await bucket.abortUpload("film.mp4", uploadId);
+			await fails(bucket.uploadPart("film.mp4", uploadId, 2, "x"), "not_found", "a part after aborting", "upload");
+			await fails(bucket.completeUpload("film.mp4", uploadId, [part]), "not_found", "completing after aborting", "upload");
+			await fails(bucket.abortUpload("film.mp4", uploadId), "not_found", "aborting twice", "upload");
+			await fails(bucket.uploadPart("film.mp4", "no-such-upload", 1, "x"), "not_found", "a part of an unknown upload", "upload");
+			const read = await bucket.get("film.mp4");
+			equal(read && text(read.body), "old", "the key after the abort");
+		}
+	},
+	{
+		name: "an upload made with ifNoneMatch refuses to complete over a key that holds something",
+		async run(storage) {
+			const bucket = storage.bucket("media");
+			const { uploadId } = await bucket.createUpload("film.mp4", { ifNoneMatch: "*" });
+			const part = await bucket.uploadPart("film.mp4", uploadId, 1, "hello");
+			await bucket.put("film.mp4", "someone else's");
+			await fails(bucket.completeUpload("film.mp4", uploadId, [part]), "conflict", "completing over a key that now holds something");
+		}
+	}
+];
+function pick(o) {
+	return {
+		key: o.key,
+		size: o.size,
+		etag: o.etag,
+		contentType: o.contentType,
+		metadata: o.metadata
+	};
+}
+const text = (bytes) => new TextDecoder().decode(bytes);
+function equal(actual, expected, what) {
+	const a = JSON.stringify(actual), e = JSON.stringify(expected);
+	if (a !== e) throw new Error(`${what}: expected ${e}, got ${a}`);
+}
+async function fails(call, code, what, reason) {
+	const expected = `a StorageError "${code}"${reason ? ` for ${reason}` : ""}`;
+	try {
+		await call;
+	} catch (error) {
+		if (error instanceof StorageError && error.code === code && (reason === void 0 || error.reason === reason)) return;
+		throw new Error(`${what}: expected ${expected}, got ${error instanceof StorageError ? `"${error.code}" (${error.reason ?? "no reason"}): ${error.message}` : String(error)}`);
+	}
+	throw new Error(`${what}: expected ${expected}, but it succeeded`);
+}
+const FIVE_MIB = 5242880;
+const LARGE = 41943040;
+/** `size` bytes that differ along their length, so a byte read from the wrong place shows. */
+function pattern(size) {
+	const bytes = new Uint8Array(size);
+	let state = 2463534242;
+	for (let i = 0; i < size; i += 4) {
+		state ^= state << 13;
+		state ^= state >>> 17;
+		state ^= state << 5;
+		bytes[i] = state & 255;
+		bytes[i + 1] = state >>> 8 & 255;
+		bytes[i + 2] = state >>> 16 & 255;
+		bytes[i + 3] = state >>> 24 & 255;
+	}
+	return bytes;
+}
+async function hex(bytes) {
+	return [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
+export { storageContract };

package/database/build.d.mts

@@ -0,0 +1,2 @@
+import { a as isSource, i as buildDatabase, n as BuiltFunction, o as typeOf, r as Refused, t as Built } from "../build-SQ44jwSa.mjs";
+export { Built, BuiltFunction, Refused, buildDatabase, isSource, typeOf };