@monoflake/sdk 0.0.0

package/dist/store/src/index.js

@@ -0,0 +1,264 @@
+import { recordKey, storageKey } from "../../artifacts/src/index.js";
+import { errorBody } from "@canmi/response";
+//#region store/src/index.ts
+/**
+* Reading the bytes behind a key, from whichever store this deployment has.
+*
+* Production reads the R2 bucket a tree under `data/bucket` mirrors; development reads that
+* tree itself, handed over by `wrangler dev --assets` because it is the source of truth.
+* A worker cannot open that directory itself -- workerd's `node:fs` is virtual and cannot see
+* host paths (verified) -- so the runtime passes it in. Everything above this module works in
+* keys and knows nothing about which one answered.
+*/
+/**
+* Origin for asset-fetcher requests. `.invalid` is reserved by RFC 2606 to never resolve,
+* which is the point: the fetcher routes on the path and ignores the host, and a name that
+* cannot resolve makes it impossible for this to accidentally become a real request.
+*/
+const ASSET_ORIGIN = "https://assets.invalid";
+function isUnsatisfiable(value) {
+	return value !== null && "unsatisfiable" in value;
+}
+async function read(env, key, range) {
+	const wanted = range ? parseRange(range) : null;
+	if (env.STORE) return readFromBucket(env.STORE, key, wanted);
+	if (env.ASSETS) return readFromAssets(env.ASSETS, key, wanted);
+	throw new Error("no store bound: expected STORE in production or ASSETS under wrangler dev");
+}
+/**
+* What is known about an object under a key, without reading a byte of it.
+*
+* A caller that has to refuse work before paying for it needs the size first: an isolate gets
+* 128 MB for its heap and its WebAssembly together, so a length that arrives alongside the bytes
+* arrives too late to be a limit. Null is no such object, which makes this a presence check too.
+* The date rides along because the same head already carries it, and a caller wanting both
+* should not spend a second round trip on the second one.
+*/
+async function measure(env, key) {
+	if (env.STORE) {
+		const head = await env.STORE.head(key);
+		return head ? {
+			size: head.size,
+			uploaded: head.uploaded ?? null
+		} : null;
+	}
+	if (env.ASSETS) {
+		const response = await env.ASSETS.fetch(`${ASSET_ORIGIN}/${key}`);
+		if (!response.ok) return null;
+		const uploaded = dateOf(response.headers.get("last-modified"));
+		const declared = response.headers.get("content-length");
+		if (declared !== null) {
+			await response.body?.cancel();
+			return {
+				size: Number(declared),
+				uploaded
+			};
+		}
+		return {
+			size: (await response.arrayBuffer()).byteLength,
+			uploaded
+		};
+	}
+	throw new Error("no store bound: expected STORE in production or ASSETS under wrangler dev");
+}
+/** A header date, or null for absent and for unparseable, which are one thing to a caller. */
+function dateOf(header) {
+	if (header === null) return null;
+	const at = new Date(header);
+	return Number.isNaN(at.getTime()) ? null : at;
+}
+/**
+* `bytes=a-b`, `bytes=a-` and `bytes=-n`, or null for anything else.
+*
+* Null covers a unit that is not `bytes`, a list of ranges, and a header that is simply
+* malformed. All three are served whole, which is what a recipient is allowed to do and what a
+* client asking for something this does not implement should get.
+*/
+function parseRange(header) {
+	const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+	if (!match) return null;
+	const [, from, to] = match;
+	if (from === "") return to === "" ? null : { suffix: Number(to) };
+	const offset = Number(from);
+	if (to === "") return {
+		offset,
+		end: null
+	};
+	const end = Number(to);
+	return end < offset ? null : {
+		offset,
+		end
+	};
+}
+/** Resolve a wanted range against the object's real size. */
+function resolve(wanted, total) {
+	if ("suffix" in wanted) {
+		const length = Math.min(wanted.suffix, total);
+		return length === 0 ? null : {
+			offset: total - length,
+			length
+		};
+	}
+	if (wanted.offset >= total) return null;
+	const end = wanted.end === null ? total - 1 : Math.min(wanted.end, total - 1);
+	return {
+		offset: wanted.offset,
+		length: end - wanted.offset + 1
+	};
+}
+async function readFromBucket(bucket, key, wanted) {
+	if (!wanted) {
+		const object = await bucket.get(key);
+		if (!object?.body) return null;
+		return {
+			body: object.body,
+			contentType: object.httpMetadata?.contentType ?? contentTypeFor(key),
+			etag: object.httpEtag
+		};
+	}
+	const head = await bucket.head(key);
+	if (!head) return null;
+	const resolved = resolve(wanted, head.size);
+	if (!resolved) return {
+		unsatisfiable: true,
+		total: head.size
+	};
+	const object = await bucket.get(key, { range: resolved });
+	if (!object?.body) return null;
+	return {
+		body: object.body,
+		contentType: object.httpMetadata?.contentType ?? contentTypeFor(key),
+		etag: object.httpEtag,
+		partial: {
+			...resolved,
+			total: head.size
+		}
+	};
+}
+async function readFromAssets(assets, key, wanted) {
+	const response = await assets.fetch(`${ASSET_ORIGIN}/${key}`);
+	if (!response.ok || !response.body) return null;
+	const contentType = response.headers.get("content-type") ?? contentTypeFor(key);
+	if (!wanted) return {
+		body: response.body,
+		contentType
+	};
+	const whole = new Uint8Array(await response.arrayBuffer());
+	const resolved = resolve(wanted, whole.byteLength);
+	if (!resolved) return {
+		unsatisfiable: true,
+		total: whole.byteLength
+	};
+	return {
+		body: streamOf(whole.subarray(resolved.offset, resolved.offset + resolved.length)),
+		contentType,
+		partial: {
+			...resolved,
+			total: whole.byteLength
+		}
+	};
+}
+/**
+* What a content id looks like.
+*
+* BLAKE3 truncated to 128 bits, hex encoded. Checked before a key is built from one, because an
+* id becomes a path segment and an unchecked one is a way to ask the bucket for something else.
+*/
+const CONTENT_ID = /^[0-9a-f]{32}$/;
+function isContentId(value) {
+	return CONTENT_ID.test(value);
+}
+/**
+* A stored object as an HTTP response, with ETag only when the store supplied one.
+*
+* `Accept-Ranges` on every one of them, because every object here is served through a route that
+* can answer a range -- a player seeking, a `<video>` element probing for duration, a resumed
+* download. The header is what tells a client it may ask; without it a browser fetches whole
+* files to read a byte near the end of them.
+*/
+function toResponse(found) {
+	const headers = new Headers({
+		"Content-Type": found.contentType,
+		"Accept-Ranges": "bytes"
+	});
+	if (found.etag) headers.set("ETag", found.etag);
+	if (!found.partial) return new Response(found.body, { headers });
+	const { offset, length, total } = found.partial;
+	headers.set("Content-Range", `bytes ${offset}-${offset + length - 1}/${total}`);
+	headers.set("Content-Length", String(length));
+	return new Response(found.body, {
+		status: 206,
+		headers
+	});
+}
+/**
+* The answer to a range that names nothing inside the object.
+*
+* 416 carries the size so the client can ask again knowing it, which is the whole reason this is
+* not a 404: the object is there, the question was wrong.
+*/
+function unsatisfiableResponse(total) {
+	return Response.json(errorBody("invalid_range"), {
+		status: 416,
+		headers: {
+			"Content-Range": `bytes */${total}`,
+			"Accept-Ranges": "bytes"
+		}
+	});
+}
+/**
+* Bytes already in hand, answered as a `Range` asked for them.
+*
+* For a body that was derived rather than stored: there is no object to ask the bucket for a part
+* of, so the artifact is produced whole and the slice is taken here. The grammar stays in this
+* module -- one parser, one set of spellings -- and a header it does not implement is served
+* whole, which is what a recipient is allowed to do. See spec/architecture/delivery.md.
+*/
+function rangedResponse(bytes, contentType, range) {
+	const wanted = range ? parseRange(range) : null;
+	if (!wanted) return toResponse({
+		body: streamOf(bytes),
+		contentType
+	});
+	const total = bytes.byteLength;
+	const resolved = resolve(wanted, total);
+	if (!resolved) return unsatisfiableResponse(total);
+	return toResponse({
+		body: streamOf(bytes.subarray(resolved.offset, resolved.offset + resolved.length)),
+		contentType,
+		partial: {
+			...resolved,
+			total
+		}
+	});
+}
+/** Bytes as a body. The cast is the workers runtime's stream against the DOM's declaration. */
+function streamOf(bytes) {
+	return new Response(bytes).body;
+}
+/**
+* Content type from the key, for objects stored without one.
+*
+* R2 keeps whatever `httpMetadata` was set at upload, and rclone does set it, but an object
+* put by hand through the dashboard has none. Serving those as `application/octet-stream`
+* makes a browser download a favicon instead of drawing it.
+*/
+function contentTypeFor(key) {
+	switch (key.split(".").pop()?.toLowerCase() ?? "") {
+		case "avif": return "image/avif";
+		case "svg": return "image/svg+xml";
+		case "png": return "image/png";
+		case "jpg":
+		case "jpeg": return "image/jpeg";
+		case "ico": return "image/x-icon";
+		case "mp4": return "video/mp4";
+		case "vtt": return "text/vtt";
+		case "woff2": return "font/woff2";
+		case "json": return "application/json";
+		case "txt": return "text/plain; charset=utf-8";
+		case "md": return "text/markdown; charset=utf-8";
+		default: return "application/octet-stream";
+	}
+}
+//#endregion
+export { contentTypeFor, isContentId, isUnsatisfiable, measure, rangedResponse, read, recordKey, storageKey, toResponse, unsatisfiableResponse };

package/dist/symlink/src/index.d.ts

@@ -0,0 +1,24 @@
+//#region symlink/src/index.d.ts
+/**
+ * Ask `name` -- a `/symlink/...` address on the alias layer -- and answer with where it points:
+ * a `302` there while it resolves, a `404` while the corpus names nothing, a `502` otherwise.
+ * Each is stamped as the alias layer stamps its own.
+ */
+export declare function followSymlink(name: string, fetcher?: typeof fetch): Promise<Response>;
+/** Where a scope's file is named, `symlink` being where the alias layer answers fixed names. */
+export declare function symlinkOf(symlink: string, scope: string, file: string): string;
+/**
+ * The address `name` stands for right now, or `undefined` while it resolves to nothing. For a page
+ * that writes the object into its markup rather than redirecting to it; a failure is not kept.
+ */
+export declare function resolveSymlink(name: string, fetcher?: typeof fetch): Promise<string | undefined>;
+/** Each of `files` in `scope`, resolved together: what a head names its marks by. */
+export declare function marksOf<File extends string>(symlink: string, scope: string, files: readonly File[], fetcher?: typeof fetch): Promise<Partial<Record<File, string>>>;
+/**
+ * The bytes `name` stands for, answered from the asking origin rather than redirected to: for a
+ * file a browser uses only from the document's own origin, such as a sitemap's XSL stylesheet. A
+ * miss and a failure are answered as `followSymlink` answers them; the bytes are kept as the alias
+ * layer keeps its redirect.
+ */
+export declare function serveSymlink(name: string, contentType: string, fetcher?: typeof fetch): Promise<Response>;
+//#endregion

package/dist/symlink/src/index.js

@@ -0,0 +1,89 @@
+import { PUBLICATION_DELAY, PUBLISHED, RESOLVED } from "../../cache/src/index.js";
+//#region symlink/src/index.ts
+/**
+* A fixed name, followed for a browser: the page asks the alias layer what the name means and
+* hands the browser that object, one hop instead of two. The mapping stays the alias layer's; a
+* page knows a name and nothing behind it. See spec/architecture/delivery.md, "A page follows the
+* name for the browser".
+*/
+/** An answer about this moment rather than about the corpus, so nothing may keep it. */
+const NEVER = "no-store";
+function answer(status, cacheControl, location) {
+	const headers = new Headers({ "Cache-Control": cacheControl });
+	if (location) headers.set("Location", location);
+	return new Response(null, {
+		status,
+		headers
+	});
+}
+/**
+* Ask `name` -- a `/symlink/...` address on the alias layer -- and answer with where it points:
+* a `302` there while it resolves, a `404` while the corpus names nothing, a `502` otherwise.
+* Each is stamped as the alias layer stamps its own.
+*/
+async function followSymlink(name, fetcher = fetch) {
+	let asked;
+	try {
+		asked = await fetcher(name, { redirect: "manual" });
+	} catch {
+		return answer(502, NEVER);
+	}
+	const target = asked.headers.get("Location");
+	if (asked.status >= 300 && asked.status < 400 && target) return answer(302, RESOLVED, new URL(target, name).href);
+	if (asked.status === 404) return answer(404, PUBLISHED);
+	return answer(502, NEVER);
+}
+/** Where a scope's file is named, `symlink` being where the alias layer answers fixed names. */
+function symlinkOf(symlink, scope, file) {
+	return `${symlink}/${scope}/${file}`;
+}
+/** What each name last resolved to, held as long as the alias layer says its answer may be. */
+const resolved = /* @__PURE__ */ new Map();
+/**
+* The address `name` stands for right now, or `undefined` while it resolves to nothing. For a page
+* that writes the object into its markup rather than redirecting to it; a failure is not kept.
+*/
+async function resolveSymlink(name, fetcher = fetch) {
+	const held = resolved.get(name);
+	if (held && held.until > Date.now()) return held.target;
+	const answered = await followSymlink(name, fetcher);
+	const target = answered.headers.get("Location");
+	if (answered.status !== 302 || !target) return void 0;
+	resolved.set(name, {
+		target,
+		until: Date.now() + PUBLICATION_DELAY * 1e3
+	});
+	return target;
+}
+/** Each of `files` in `scope`, resolved together: what a head names its marks by. */
+async function marksOf(symlink, scope, files, fetcher = fetch) {
+	const targets = await Promise.all(files.map((file) => resolveSymlink(symlinkOf(symlink, scope, file), fetcher)));
+	return Object.fromEntries(files.flatMap((file, index) => targets[index] ? [[file, targets[index]]] : []));
+}
+/**
+* The bytes `name` stands for, answered from the asking origin rather than redirected to: for a
+* file a browser uses only from the document's own origin, such as a sitemap's XSL stylesheet. A
+* miss and a failure are answered as `followSymlink` answers them; the bytes are kept as the alias
+* layer keeps its redirect.
+*/
+async function serveSymlink(name, contentType, fetcher = fetch) {
+	const followed = await followSymlink(name, fetcher);
+	const target = followed.headers.get("Location");
+	if (followed.status !== 302 || !target) return followed;
+	let object;
+	try {
+		object = await fetcher(target);
+	} catch {
+		return answer(502, NEVER);
+	}
+	if (!object.ok) return answer(502, NEVER);
+	return new Response(object.body, {
+		status: 200,
+		headers: {
+			"Content-Type": contentType,
+			"Cache-Control": RESOLVED
+		}
+	});
+}
+//#endregion
+export { followSymlink, marksOf, resolveSymlink, serveSymlink, symlinkOf };

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@monoflake/sdk",
+  "version": "0.0.0",
+  "description": "The platform's addresses, and every client of its services and its policies behind a subpath",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monoflake/platform.git",
+    "directory": "libs/sdk"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./artifacts": {
+      "types": "./dist/artifacts/src/index.d.ts",
+      "default": "./dist/artifacts/src/index.js"
+    },
+    "./artifacts/types": {
+      "types": "./dist/artifacts/src/types.d.ts",
+      "default": "./dist/artifacts/src/types.js"
+    },
+    "./artifacts/anchors": {
+      "types": "./dist/artifacts/src/anchors.d.ts",
+      "default": "./dist/artifacts/src/anchors.js"
+    },
+    "./cache": {
+      "types": "./dist/cache/src/index.d.ts",
+      "default": "./dist/cache/src/index.js"
+    },
+    "./imgsrc": {
+      "types": "./dist/imgsrc/src/index.d.ts",
+      "default": "./dist/imgsrc/src/index.js"
+    },
+    "./limits": {
+      "types": "./dist/limits/src/index.d.ts",
+      "default": "./dist/limits/src/index.js"
+    },
+    "./robots": {
+      "types": "./dist/robots/src/index.d.ts",
+      "default": "./dist/robots/src/index.js"
+    },
+    "./security": {
+      "types": "./dist/security/src/index.d.ts",
+      "default": "./dist/security/src/index.js"
+    },
+    "./security/agents": {
+      "types": "./dist/security/src/agents.d.ts",
+      "default": "./dist/security/src/agents.js"
+    },
+    "./store": {
+      "types": "./dist/store/src/index.d.ts",
+      "default": "./dist/store/src/index.js"
+    },
+    "./symlink": {
+      "types": "./dist/symlink/src/index.d.ts",
+      "default": "./dist/symlink/src/index.js"
+    }
+  },
+  "dependencies": {
+    "@canmi/me": "^2026.1004.1",
+    "@canmi/response": "^2.0.0",
+    "@monoflake/urls": "^2026.1004.0",
+    "valibot": "^1.5.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20261004.1"
+  },
+  "peerDependencies": {
+    "@cloudflare/workers-types": "^5.20261004.1"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/workers-types": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}