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

package/wire.mjs

@@ -0,0 +1,731 @@
+import { _ as storageErrorReasons, a as checkMetadata, c as checkRange, g as storageErrorCodes, h as StorageError, i as checkListLimit, l as checkUploadId, n as checkBucketName, o as checkPartNumber, r as checkKey, s as checkParts } from "./names-DfCBKupJ.mjs";
+import { z } from "zod";
+//#region src/wire.ts
+/**
+* Storage's wire: how a Storage call crosses a network. `remote(transport)` is the engine a client
+* uses; `serve(engine)` replies on the other side. A server implements `serve` over its own engine
+* and nothing else, so the contract run through the wire holds for it too.
+*
+*   const files = storage(remote({ send: (frame) => lane.request(frame) }))
+*   lane.onRequest(serve(engine))          // on the server
+*
+* A frame is a 4-byte little-endian length, that many bytes of JSON header, then the body: an
+* Object's bytes on a put and a read, nothing otherwise. One request frame gets one answer frame;
+* the transport carries them and matches replies to requests. Changing a frame changes the
+* contract with every server.
+*
+* With `remote(transport, { batch: true })`, the calls made in the same turn travel as one `batch`
+* frame: its header lists the byte lengths of the ordinary frames its body holds, end to end, and
+* its answer lists the lengths of their answer frames, in the same order. Each call inside is
+* replied to as it would be alone, refusals included; a batch costs one request where it had many.
+*/
+const range = z.union([z.object({
+	offset: z.number(),
+	length: z.number().optional()
+}).strict(), z.object({ suffix: z.number() }).strict()]);
+const at = {
+	bucket: z.string(),
+	key: z.string()
+};
+const request = z.discriminatedUnion("op", [
+	z.object({
+		op: z.literal("put"),
+		...at,
+		contentType: z.string().max(256),
+		metadata: z.record(z.string(), z.string()),
+		ifNoneMatch: z.literal("*").optional(),
+		ifMatch: z.string().optional()
+	}).strict(),
+	z.object({
+		op: z.literal("get"),
+		...at,
+		range: range.optional(),
+		limit: z.number().int().positive().optional()
+	}).strict(),
+	z.object({
+		op: z.literal("head"),
+		...at
+	}).strict(),
+	z.object({
+		op: z.literal("delete"),
+		...at
+	}).strict(),
+	z.object({
+		op: z.literal("list"),
+		bucket: z.string(),
+		prefix: z.string(),
+		delimiter: z.string().min(1).optional(),
+		after: z.string().optional(),
+		limit: z.number()
+	}).strict(),
+	z.object({
+		op: z.literal("copy"),
+		bucket: z.string(),
+		from: z.string(),
+		to: z.string(),
+		ifNoneMatch: z.literal("*").optional()
+	}).strict(),
+	z.object({
+		op: z.literal("createUpload"),
+		...at,
+		contentType: z.string().max(256),
+		metadata: z.record(z.string(), z.string()),
+		ifNoneMatch: z.literal("*").optional()
+	}).strict(),
+	z.object({
+		op: z.literal("uploadPart"),
+		...at,
+		uploadId: z.string(),
+		partNumber: z.number()
+	}).strict(),
+	z.object({
+		op: z.literal("completeUpload"),
+		...at,
+		uploadId: z.string(),
+		parts: z.array(z.object({
+			partNumber: z.number(),
+			etag: z.string()
+		}).strict())
+	}).strict(),
+	z.object({
+		op: z.literal("abortUpload"),
+		...at,
+		uploadId: z.string()
+	}).strict(),
+	z.object({
+		op: z.literal("usage"),
+		bucket: z.string()
+	}).strict(),
+	z.object({
+		op: z.literal("operations"),
+		bucket: z.string(),
+		from: z.number(),
+		to: z.number()
+	}).strict()
+]);
+const stored = z.object({
+	key: z.string(),
+	size: z.number(),
+	etag: z.string(),
+	contentType: z.string(),
+	metadata: z.record(z.string(), z.string()),
+	uploadedAt: z.number()
+}).strict();
+const answer = z.union([
+	z.object({
+		error: z.enum(storageErrorCodes),
+		why: z.string(),
+		reason: z.enum(storageErrorReasons).optional()
+	}).strict(),
+	z.object({ uploadId: z.string() }).strict(),
+	z.object({ part: z.object({
+		partNumber: z.number(),
+		etag: z.string(),
+		size: z.number()
+	}).strict() }).strict(),
+	z.object({
+		object: stored.nullable(),
+		range: z.object({
+			offset: z.number(),
+			length: z.number()
+		}).strict().optional()
+	}).strict(),
+	z.object({ listing: z.object({
+		objects: z.array(stored),
+		prefixes: z.array(z.string()),
+		next: z.string().optional()
+	}).strict() }).strict(),
+	z.object({ done: z.literal(true) }).strict(),
+	z.object({ usage: z.object({
+		objects: z.number(),
+		bytes: z.number()
+	}).strict() }).strict(),
+	z.object({ operations: z.object({
+		reads: z.number(),
+		writes: z.number()
+	}).strict() }).strict(),
+	z.object({ again: z.literal(true) }).strict()
+]);
+const BATCH_MAX = 256;
+const BATCH_BYTES = 16777216;
+const PART_BYTES = 8388608;
+const ANSWER_BYTES = 29360128;
+let again;
+const AGAIN = () => again ??= encodeFrame({ again: true });
+const PARTS_AT_ONCE = 4;
+const batchRequest = z.object({
+	op: z.literal("batch"),
+	frames: z.array(z.number().int().min(4)).min(1).max(BATCH_MAX)
+}).strict();
+const batchAnswer = z.object({ batch: z.array(z.number().int().min(4)) }).strict();
+/** Frames joined end to end, with their lengths. */
+function sameBytes(a, b) {
+	return a.length === b.length && a.every((byte, i) => byte === b[i]);
+}
+function join(frames) {
+	const body = new Uint8Array(frames.reduce((n, f) => n + f.length, 0));
+	let at = 0;
+	for (const frame of frames) body.set(frame, at), at += frame.length;
+	return {
+		lengths: frames.map((f) => f.length),
+		body
+	};
+}
+/** `body` cut into frames of `lengths`; `invalid` when they do not add up to it. */
+function split(lengths, body) {
+	if (lengths.reduce((n, l) => n + l, 0) !== body.length) throw new StorageError("invalid", "the batch's frames do not add up to its body");
+	let at = 0;
+	return lengths.map((length) => body.subarray(at, at += length));
+}
+/** Sends the frames of one turn as batch frames over `transport`; a lone frame goes as it is. */
+function batched(transport) {
+	let waiting = [];
+	const flush = async (group) => {
+		if (group.length === 1) return group[0].done(await transport.send(group[0].frame));
+		const { lengths, body } = join(group.map((w) => w.frame));
+		const { header, body: answers } = decodeFrame(await transport.send(encodeFrame({
+			op: "batch",
+			frames: lengths
+		}, body)));
+		const parsed = batchAnswer.safeParse(header);
+		if (!parsed.success) {
+			const whole = encodeFrame(header);
+			return group.forEach((w) => w.done(whole));
+		}
+		const each = split(parsed.data.batch, answers);
+		if (each.length !== group.length) throw new StorageError("unavailable", "the batch's answer does not match its calls");
+		await Promise.all(group.map(async (w, i) => {
+			const answer = each[i];
+			w.done(sameBytes(answer, AGAIN()) ? await transport.send(w.frame) : answer);
+		}));
+	};
+	return (frame) => new Promise((done, fail) => {
+		if (waiting.length === 0) queueMicrotask(() => {
+			const all = waiting;
+			waiting = [];
+			for (let i = 0; i < all.length;) {
+				let bytes = 0, j = i;
+				while (j < all.length && j - i < BATCH_MAX && (j === i || bytes + all[j].frame.length <= BATCH_BYTES)) bytes += all[j++].frame.length;
+				const group = all.slice(i, j);
+				i = j;
+				flush(group).catch((error) => group.forEach((w) => w.fail(error)));
+			}
+		});
+		waiting.push({
+			frame,
+			done,
+			fail
+		});
+	});
+}
+/**
+* The engine on the client's side of the wire. With `batch`, the calls made in the same turn travel
+* as one batch frame (the platform's own calls do not batch; clients that issue many at once do).
+*/
+function remote(transport, options = {}) {
+	const send = options.batch ? batched(transport) : (frame) => transport.send(frame);
+	const call = async (header, body) => {
+		const { header: reply, body: bytes } = decodeFrame(await send(encodeFrame(header, body)));
+		const parsed = answer.parse(reply);
+		if ("error" in parsed) throw new StorageError(parsed.error, parsed.why, parsed.reason);
+		return {
+			reply: parsed,
+			bytes
+		};
+	};
+	const objectOf = (reply) => "object" in reply ? reply.object : null;
+	/** One get as the wire carries it: at most BATCH_BYTES of body. */
+	const getOne = async (bucket, key, range) => {
+		const { reply, bytes } = await call({
+			op: "get",
+			bucket,
+			key,
+			...range ? { range } : { limit: BATCH_BYTES }
+		});
+		const object = objectOf(reply);
+		if (!object) return null;
+		const at = "range" in reply ? reply.range : void 0;
+		return {
+			...object,
+			body: bytes,
+			...at ? { range: at } : {}
+		};
+	};
+	const engine = {
+		async put(bucket, key, body, put) {
+			if (body.length <= BATCH_BYTES) return objectOf((await call({
+				op: "put",
+				bucket,
+				key,
+				...put,
+				metadata: { ...put.metadata }
+			}, body)).reply);
+			if (put.ifMatch !== void 0) throw new StorageError("invalid", `ifMatch is not answered for a body over ${BATCH_BYTES} bytes, which is uploaded in parts`);
+			const { uploadId } = await engine.createUpload(bucket, key, {
+				contentType: put.contentType,
+				metadata: put.metadata,
+				...put.ifNoneMatch ? { ifNoneMatch: put.ifNoneMatch } : {}
+			});
+			try {
+				const count = Math.ceil(body.length / PART_BYTES), parts = [];
+				for (let first = 0; first < count; first += PARTS_AT_ONCE) parts.push(...await Promise.all(Array.from({ length: Math.min(PARTS_AT_ONCE, count - first) }, (_, k) => {
+					const i = first + k;
+					return engine.uploadPart(bucket, key, uploadId, i + 1, body.subarray(i * PART_BYTES, (i + 1) * PART_BYTES));
+				})));
+				return await engine.completeUpload(bucket, key, uploadId, parts);
+			} catch (error) {
+				await engine.abortUpload(bucket, key, uploadId).catch(() => {});
+				throw error;
+			}
+		},
+		async get(bucket, key, range) {
+			for (let attempt = 1;; attempt += 1) {
+				const first = await getOne(bucket, key, range && clamp(range));
+				if (!first) return null;
+				const wanted = range ? spanOf(range, first.size) : {
+					offset: 0,
+					length: first.size
+				};
+				if (first.body.length === wanted.length) {
+					if (range || first.range === void 0) return first;
+					const { range: _whole, ...object } = first;
+					return object;
+				}
+				const whole = new Uint8Array(wanted.length);
+				const at = (offset) => offset - wanted.offset;
+				const got = first.range ?? {
+					offset: 0,
+					length: first.body.length
+				};
+				whole.set(first.body, at(got.offset));
+				let changed = false;
+				const missing = [[wanted.offset, got.offset], [got.offset + got.length, wanted.offset + wanted.length]];
+				for (const [from, to] of missing) for (let offset = from; offset < to && !changed; offset += BATCH_BYTES) {
+					const piece = await getOne(bucket, key, {
+						offset,
+						length: Math.min(BATCH_BYTES, to - offset)
+					});
+					if (!piece || piece.etag !== first.etag) changed = true;
+					else whole.set(piece.body, at(offset));
+				}
+				if (!changed) {
+					const { body: _first, range: _at, ...object } = first;
+					return {
+						...object,
+						body: whole,
+						...range ? { range: wanted } : {}
+					};
+				}
+				if (attempt === 3) throw new StorageError("unavailable", `"${key}" changed while it was read in ranges`);
+			}
+		},
+		async head(bucket, key) {
+			return objectOf((await call({
+				op: "head",
+				bucket,
+				key
+			})).reply);
+		},
+		async delete(bucket, key) {
+			await call({
+				op: "delete",
+				bucket,
+				key
+			});
+		},
+		async list(bucket, options) {
+			const { reply } = await call({
+				op: "list",
+				bucket,
+				...options
+			});
+			return "listing" in reply ? reply.listing : {
+				objects: [],
+				prefixes: []
+			};
+		},
+		async copy(bucket, from, to, options) {
+			return objectOf((await call({
+				op: "copy",
+				bucket,
+				from,
+				to,
+				...options
+			})).reply);
+		},
+		async createUpload(bucket, key, upload) {
+			const { reply } = await call({
+				op: "createUpload",
+				bucket,
+				key,
+				...upload,
+				metadata: { ...upload.metadata }
+			});
+			return { uploadId: reply.uploadId };
+		},
+		async uploadPart(bucket, key, uploadId, partNumber, body) {
+			const { reply } = await call({
+				op: "uploadPart",
+				bucket,
+				key,
+				uploadId,
+				partNumber
+			}, body);
+			return reply.part;
+		},
+		async completeUpload(bucket, key, uploadId, parts) {
+			return objectOf((await call({
+				op: "completeUpload",
+				bucket,
+				key,
+				uploadId,
+				parts: parts.map((p) => ({
+					partNumber: p.partNumber,
+					etag: p.etag
+				}))
+			})).reply);
+		},
+		async abortUpload(bucket, key, uploadId) {
+			await call({
+				op: "abortUpload",
+				bucket,
+				key,
+				uploadId
+			});
+		},
+		async usage(bucket) {
+			const { reply } = await call({
+				op: "usage",
+				bucket
+			});
+			return reply.usage;
+		},
+		async operations(bucket, from, to) {
+			const { reply } = await call({
+				op: "operations",
+				bucket,
+				from,
+				to
+			});
+			return reply.operations;
+		}
+	};
+	return engine;
+}
+/** `range` cut to what one frame carries: its first BATCH_BYTES, or its last for a suffix. */
+function clamp(range) {
+	if ("suffix" in range) return { suffix: Math.min(range.suffix, BATCH_BYTES) };
+	return {
+		offset: range.offset,
+		length: Math.min(range.length ?? BATCH_BYTES, BATCH_BYTES)
+	};
+}
+/** The bytes `range` names in an Object of `size` bytes, cut at its end, as an engine resolves it. */
+function spanOf(range, size) {
+	if ("suffix" in range) return {
+		offset: Math.max(0, size - range.suffix),
+		length: Math.min(range.suffix, size)
+	};
+	return {
+		offset: range.offset,
+		length: Math.min(range.length ?? size - range.offset, size - range.offset)
+	};
+}
+/**
+* Whether sending `frame` a second time, after the first may have been carried out, returns the same as the
+* first would have and stores nothing more: reads, an unconditional put, a delete, a part sent again.
+* A conditional put, a copy (its source may have changed since), and starting, completing or aborting
+* an upload are not: a second `ifNoneMatch` put is a `conflict`, a second completion `not_found`. A
+* batch is when all it holds is and no call in it writes what another call reads or writes, so sending
+* it again cannot see one call's effect in another's answer. A transport resends a frame it lost the
+* answer to only when this allows it.
+*/
+function repeatable(frame) {
+	let header, body;
+	try {
+		({header, body} = decodeFrame(frame));
+	} catch {
+		return false;
+	}
+	const batch = batchRequest.safeParse(header);
+	if (!batch.success) {
+		const call = request.safeParse(header);
+		return call.success && repeatableCall(call.data);
+	}
+	let calls;
+	try {
+		calls = split(batch.data.frames, body).map((f) => request.parse(decodeFrame(f).header));
+	} catch {
+		return false;
+	}
+	if (!calls.every(repeatableCall)) return false;
+	const reach = (call) => call.op === "uploadPart" ? `${call.bucket}/${call.key}#${call.uploadId}#${call.partNumber}` : "key" in call ? `${call.bucket}/${call.key}` : null;
+	const written = /* @__PURE__ */ new Set(), all = /* @__PURE__ */ new Map();
+	for (const call of calls) {
+		const at = reach(call);
+		if (at === null) continue;
+		if (call.op === "put" || call.op === "delete" || call.op === "uploadPart") written.add(at);
+		all.set(at, (all.get(at) ?? 0) + 1);
+	}
+	if (written.size > 0 && calls.some((c) => c.op === "list")) return false;
+	return [...written].every((at) => all.get(at) === 1);
+}
+function repeatableCall(call) {
+	switch (call.op) {
+		case "get":
+		case "head":
+		case "list":
+		case "delete":
+		case "uploadPart":
+		case "usage":
+		case "operations": return true;
+		case "put": return call.ifNoneMatch === void 0 && call.ifMatch === void 0;
+		case "copy":
+		case "createUpload":
+		case "completeUpload":
+		case "abortUpload": return false;
+	}
+}
+/**
+* The Bucket names that the calls in `frame` use, so a server can look up only those before serving it.
+* A call it cannot read uses none: `serve` returns `invalid` for it without reaching a Bucket.
+*/
+function bucketsOf(frame) {
+	const names = /* @__PURE__ */ new Set();
+	const read = (f) => {
+		try {
+			return decodeFrame(f);
+		} catch (error) {
+			if (error instanceof StorageError) return null;
+			throw error;
+		}
+	};
+	const add = (header) => {
+		const call = request.safeParse(header);
+		if (call.success) names.add(call.data.bucket);
+	};
+	const outer = read(frame);
+	if (!outer) return [];
+	const batch = batchRequest.safeParse(outer.header);
+	if (!batch.success) add(outer.header);
+	else {
+		let frames = [];
+		try {
+			frames = split(batch.data.frames, outer.body);
+		} catch (error) {
+			if (!(error instanceof StorageError)) throw error;
+		}
+		for (const f of frames) add(read(f)?.header);
+	}
+	return [...names];
+}
+/**
+* Serves request frames from `engine`. A frame comes from the network, so its header is checked
+* here as the client would check it; a refusal is returned as `invalid`. A failure that is not a
+* `StorageError` is the engine's own fault and is thrown to the transport, never returned.
+*/
+function serve(engine) {
+	const one = async (header, body) => {
+		try {
+			const parsed = request.safeParse(header);
+			if (!parsed.success) throw new StorageError("invalid", "the request frame is not a Storage call");
+			return await answerTo(engine, parsed.data, body);
+		} catch (error) {
+			if (error instanceof StorageError) return encodeFrame({
+				error: error.code,
+				why: error.message,
+				...error.reason ? { reason: error.reason } : {}
+			});
+			throw error;
+		}
+	};
+	return async (frame) => {
+		let header, body;
+		try {
+			({header, body} = decodeFrame(frame));
+		} catch (error) {
+			if (error instanceof StorageError) return encodeFrame({
+				error: error.code,
+				why: error.message
+			});
+			throw error;
+		}
+		const batch = batchRequest.safeParse(header);
+		if (!batch.success) return one(header, body);
+		let frames;
+		try {
+			frames = split(batch.data.frames, body);
+		} catch (error) {
+			if (error instanceof StorageError) return encodeFrame({
+				error: error.code,
+				why: error.message
+			});
+			throw error;
+		}
+		const answers = await Promise.all(frames.map(async (f) => {
+			try {
+				const inner = decodeFrame(f);
+				return await one(inner.header, inner.body);
+			} catch (error) {
+				if (error instanceof StorageError) return encodeFrame({
+					error: error.code,
+					why: error.message
+				});
+				throw error;
+			}
+		}));
+		let bytes = 0;
+		const { lengths, body: joined } = join(answers.map((a) => bytes > 0 && bytes + a.length > ANSWER_BYTES && a.length > 1024 ? AGAIN() : (bytes += a.length, a)));
+		return encodeFrame({ batch: lengths }, joined);
+	};
+}
+async function answerTo(engine, call, body) {
+	checkBucketName(call.bucket);
+	switch (call.op) {
+		case "put": {
+			checkKey(call.key);
+			checkMetadata(call.metadata);
+			const put = {
+				contentType: call.contentType,
+				metadata: call.metadata,
+				...call.ifNoneMatch ? { ifNoneMatch: call.ifNoneMatch } : {},
+				...call.ifMatch !== void 0 ? { ifMatch: call.ifMatch } : {}
+			};
+			return encodeFrame({ object: await engine.put(call.bucket, call.key, body, put) });
+		}
+		case "get": {
+			checkKey(call.key);
+			const at = call.range && rangeOf(call.range);
+			if (at) checkRange(at);
+			const read = await engine.get(call.bucket, call.key, at, at ? void 0 : call.limit);
+			if (!read) return encodeFrame({ object: null });
+			const { body: bytes, range, ...object } = read;
+			return encodeFrame({
+				object,
+				...range ? { range } : {}
+			}, bytes);
+		}
+		case "head":
+			checkKey(call.key);
+			return encodeFrame({ object: await engine.head(call.bucket, call.key) });
+		case "delete":
+			checkKey(call.key);
+			await engine.delete(call.bucket, call.key);
+			return encodeFrame({ done: true });
+		case "list": {
+			checkListLimit(call.limit);
+			const options = {
+				prefix: call.prefix,
+				limit: call.limit,
+				...call.delimiter !== void 0 ? { delimiter: call.delimiter } : {},
+				...call.after !== void 0 ? { after: call.after } : {}
+			};
+			return encodeFrame({ listing: await engine.list(call.bucket, options) });
+		}
+		case "copy":
+			checkKey(call.from);
+			checkKey(call.to);
+			return encodeFrame({ object: await engine.copy(call.bucket, call.from, call.to, call.ifNoneMatch ? { ifNoneMatch: call.ifNoneMatch } : {}) });
+		case "createUpload": {
+			checkKey(call.key);
+			checkMetadata(call.metadata);
+			const upload = {
+				contentType: call.contentType,
+				metadata: call.metadata,
+				...call.ifNoneMatch ? { ifNoneMatch: call.ifNoneMatch } : {}
+			};
+			return encodeFrame(await engine.createUpload(call.bucket, call.key, upload));
+		}
+		case "uploadPart":
+			checkKey(call.key);
+			checkUploadId(call.uploadId);
+			checkPartNumber(call.partNumber);
+			return encodeFrame({ part: await engine.uploadPart(call.bucket, call.key, call.uploadId, call.partNumber, body) });
+		case "completeUpload":
+			checkKey(call.key);
+			checkUploadId(call.uploadId);
+			checkParts(call.parts);
+			return encodeFrame({ object: await engine.completeUpload(call.bucket, call.key, call.uploadId, call.parts) });
+		case "abortUpload":
+			checkKey(call.key);
+			checkUploadId(call.uploadId);
+			await engine.abortUpload(call.bucket, call.key, call.uploadId);
+			return encodeFrame({ done: true });
+		case "usage": return encodeFrame({ usage: await engine.usage(call.bucket) });
+		case "operations": return encodeFrame({ operations: await engine.operations(call.bucket, call.from, call.to) });
+	}
+}
+/**
+* A transport over HTTP: each frame is one POST to `url` with the engine's bearer token, replied to
+* by `serveHttp` on the other side. Refused credentials are `forbidden`; a server that cannot be
+* reached, or replies with anything but a frame, is `unavailable`.
+*/
+function http(url, options) {
+	const send = options.fetch ?? ((to, init) => fetch(to, init));
+	return { async send(frame) {
+		let response;
+		try {
+			response = await send(url, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${options.token}`,
+					"content-type": "application/octet-stream"
+				},
+				body: frame
+			});
+		} catch {
+			throw new StorageError("unavailable", "Storage could not be reached");
+		}
+		if (response.status === 401 || response.status === 403) throw new StorageError("forbidden", "Storage refused this deployment's credentials");
+		if (response.status !== 200) throw new StorageError("unavailable", `Storage answered ${response.status}`);
+		return new Uint8Array(await response.arrayBuffer());
+	} };
+}
+/** Answers `http` transports: a POST of one frame, with `token` as its bearer token, gets one answer frame. */
+function serveHttp(engine, options) {
+	const answer = serve(engine);
+	const expected = new TextEncoder().encode(`Bearer ${options.token}`);
+	return async (request) => {
+		if (request.method !== "POST") return new Response(null, { status: 405 });
+		const given = new TextEncoder().encode(request.headers.get("authorization") ?? "");
+		let difference = given.length ^ expected.length;
+		for (let i = 0; i < expected.length; i += 1) difference |= expected[i] ^ (given[i] ?? 0);
+		if (difference !== 0) return new Response(null, { status: 401 });
+		const frame = await answer(new Uint8Array(await request.arrayBuffer()));
+		return new Response(frame, {
+			status: 200,
+			headers: { "content-type": "application/octet-stream" }
+		});
+	};
+}
+const rangeOf = (r) => "suffix" in r ? { suffix: r.suffix } : r.length === void 0 ? { offset: r.offset } : {
+	offset: r.offset,
+	length: r.length
+};
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function encodeFrame(header, body = /* @__PURE__ */ new Uint8Array(0)) {
+	const json = encoder.encode(JSON.stringify(header));
+	const frame = new Uint8Array(4 + json.length + body.length);
+	new DataView(frame.buffer).setUint32(0, json.length, true);
+	frame.set(json, 4);
+	frame.set(body, 4 + json.length);
+	return frame;
+}
+function decodeFrame(frame) {
+	if (frame.length < 4) throw new StorageError("invalid", "the frame is shorter than its length");
+	const length = new DataView(frame.buffer, frame.byteOffset, frame.byteLength).getUint32(0, true);
+	if (4 + length > frame.length) throw new StorageError("invalid", "the frame is shorter than its header");
+	let header;
+	try {
+		header = JSON.parse(decoder.decode(frame.subarray(4, 4 + length)));
+	} catch {
+		throw new StorageError("invalid", "the frame's header is not JSON");
+	}
+	return {
+		header,
+		body: frame.subarray(4 + length)
+	};
+}
+//#endregion
+export { bucketsOf, decodeFrame, encodeFrame, http, remote, repeatable, serve, serveHttp };