@aigne/aos 0.2.0-beta

package/dist/blocklet/did-space-registry.cjs

@@ -0,0 +1,282 @@
+const require_registry = require('./registry.cjs');
+let ufo = require("ufo");
+let _aigne_afs_did_space = require("@aigne/afs-did-space");
+let _aigne_afs_logger = require("@aigne/afs-logger");
+let _aigne_afs_timing = require("@aigne/afs-timing");
+
+//#region src/blocklet/did-space-registry.ts
+/**
+* DID-Space-backed BlockletRegistry — runtime-agnostic engine (#674 v2).
+*
+* Resolves blocklets published to a DID Space via the global resolve table
+* (`resolve/blocklet/<id>` → { owner, path }, written by the did-space provider's
+* blocklet write-hook) and reads their files back through AFS. This lives in
+* @aigne/aos (NOT @aigne/afs-did-space) because it needs `createAfsBlockletReader`
+* + the Blocklet types, and aos already depends on did-space — the reverse
+* dependency would be a cycle. Both runtimes (Node + CF) depend on aos, so this
+* engine is shared: each runtime injects only the two things it does
+* differently — how to read the resolve table and how to open an owner's space.
+*
+* Lookup path:
+*   1. resolver.resolveBlocklet(name) → { owner, path }
+*   2. openUserSpace(owner)           → AFS rooted at the owner's whole space
+*   3. createAfsBlockletReader(afs, "/"+path) → file reader for the blocklet
+*
+* The engine is decoupled from any concrete class via two minimal structural
+* interfaces (BlockletResolveSource + the loose BlockletAfsReader): a
+* `DIDSpaceResolver` satisfies the former, a mounted `AFS` the latter.
+*/
+/**
+* Publish-time serve bundle for a DID-Space blocklet (#674 Phase 4): small text
+* files inlined so a cold serve reads one object instead of one-per-file. Sits
+* at the blocklet root as the matched partner of the `.blocklet-publish.json`
+* register marker (a distinct name — NOT http-mount's `.afs/bundle.json`, which
+* is a different mechanism / consumer).
+*/
+const BLOCKLET_BUNDLE_PATH = ".blocklet-bundle.json";
+const BUNDLE_DECODER = new TextDecoder();
+/** Extract UTF-8 text from an AFS read result's `content` (string | bytes). */
+function decodeAfsText(raw) {
+	const content = raw?.content;
+	if (typeof content === "string") return content;
+	if (content instanceof Uint8Array) return BUNDLE_DECODER.decode(content);
+	if (content instanceof ArrayBuffer) return BUNDLE_DECODER.decode(new Uint8Array(content));
+	return "";
+}
+/**
+* A BlockletReader backed by a publish-time `.afs/bundle.json` (small text files
+* inlined at publish; see `shouldBundle`) layered over the live per-file AFS
+* reader — the fallback serves large/binary files (not bundled) and blocklets
+* that have no bundle.
+*
+* Why this exists: blocklet serve is one-file-per-request, so a cold isolate's
+* first page load of a many-file blocklet would otherwise do one object read per
+* file. Reading the bundle once serves every small file from memory instead.
+*
+* Why it does NOT go stale (the trap #729 fell into): the reader is memoized per
+* name for the isolate lifetime, but it never freezes content. Every call does a
+* cheap `stat` of the bundle to read its cid (a fresh path→cid index lookup, no
+* object read); the parsed map is memoized by that cid (immutable). An unchanged
+* bundle skips the re-read/re-parse; a re-publish yields a new cid and is picked
+* up on the very next request.
+*/
+function createBundleBackedReader(afs, root, fallback) {
+	const bundlePath = (0, ufo.joinURL)(root, BLOCKLET_BUNDLE_PATH);
+	let memoCid;
+	let memoReader;
+	async function currentBundle() {
+		const rc = (0, _aigne_afs_logger.getRequestScope)();
+		const rcKey = `bundle-cid:${bundlePath}`;
+		let cid;
+		if (rc?.has(rcKey)) cid = rc.get(rcKey);
+		else {
+			try {
+				const meta = (await afs.stat(bundlePath, {
+					includeActions: "none",
+					noReadFallback: true
+				}))?.data?.meta;
+				cid = meta?.version ?? meta?.cid;
+			} catch {
+				cid = void 0;
+			}
+			rc?.set(rcKey, cid);
+		}
+		if (!cid) {
+			memoCid = void 0;
+			memoReader = void 0;
+			return;
+		}
+		if (cid === memoCid && memoReader) return memoReader;
+		try {
+			memoReader = require_registry.createMapBlockletReader(JSON.parse(decodeAfsText((await afs.read(bundlePath, { includeActions: "none" }))?.data)));
+			memoCid = cid;
+			return memoReader;
+		} catch {
+			return;
+		}
+	}
+	const reader = {
+		async exists(relPath) {
+			const b = await currentBundle();
+			if (b && await b.exists(relPath)) return true;
+			return fallback.exists(relPath);
+		},
+		async readText(relPath) {
+			const b = await currentBundle();
+			if (b) {
+				const v = await b.readText(relPath);
+				if (v !== void 0) return v;
+			}
+			return fallback.readText(relPath);
+		},
+		async readBytes(relPath) {
+			const b = await currentBundle();
+			if (b) {
+				const v = await b.readBytes(relPath);
+				if (v !== void 0) return v;
+			}
+			return fallback.readBytes(relPath);
+		},
+		async hasDir(relDir) {
+			const b = await currentBundle();
+			if (b && await b.hasDir(relDir)) return true;
+			return fallback.hasDir(relDir);
+		},
+		async listDir(relDir) {
+			const b = await currentBundle();
+			const fromBundle = b ? await b.listDir(relDir) : [];
+			const fromFallback = await fallback.listDir(relDir);
+			return [...new Set([...fromBundle, ...fromFallback])];
+		}
+	};
+	if (fallback.listEntries) reader.listEntries = (relDir) => fallback.listEntries(relDir);
+	return reader;
+}
+/**
+* Create a runtime-agnostic DID-Space BlockletRegistry. Positive resolves are
+* cached per-instance; misses are NOT cached, so a newly published blocklet is
+* visible on the next lookup.
+*/
+function createDidSpaceBlockletRegistry(deps) {
+	const { resolver, openUserSpace } = deps;
+	const warn = deps.onWarn ?? (() => {});
+	const entryCache = /* @__PURE__ */ new Map();
+	async function lookup(name) {
+		const cached = entryCache.get(name);
+		if (cached !== void 0) return cached;
+		const rc = (0, _aigne_afs_logger.getRequestScope)();
+		const rcKey = `blocklet-lookup:${name}`;
+		if (rc?.has(rcKey)) return rc.get(rcKey);
+		const result = await lookupUncached(name);
+		rc?.set(rcKey, result);
+		return result;
+	}
+	async function lookupUncached(name) {
+		if (resolver.resolveBlockletOrDomain) try {
+			const r = await resolver.resolveBlockletOrDomain(name);
+			if (!r) return null;
+			const result = r.source === "blocklet" ? {
+				owner: r.owner,
+				path: r.path ?? "",
+				canonicalName: name
+			} : {
+				owner: r.owner,
+				path: r.path ?? "",
+				canonicalName: (0, _aigne_afs_did_space.normalizeId)(r.did)
+			};
+			entryCache.set(name, result);
+			return result;
+		} catch (err) {
+			warn(`resolveBlockletOrDomain("${name}") failed: ${err instanceof Error ? err.message : err}`);
+			return null;
+		}
+		try {
+			const entry = await resolver.resolveBlocklet(name);
+			if (entry?.owner) {
+				const result = {
+					owner: entry.owner,
+					path: entry.path ?? "",
+					canonicalName: name
+				};
+				entryCache.set(name, result);
+				return result;
+			}
+		} catch (err) {
+			warn(`resolveBlocklet("${name}") failed: ${err instanceof Error ? err.message : err}`);
+			return null;
+		}
+		if (!resolver.resolveDomain) return null;
+		try {
+			const domainEntry = await resolver.resolveDomain(name);
+			if (!domainEntry?.owner) return null;
+			const result = {
+				owner: domainEntry.owner,
+				path: domainEntry.path ?? "",
+				canonicalName: (0, _aigne_afs_did_space.normalizeId)(domainEntry.did)
+			};
+			entryCache.set(name, result);
+			return result;
+		} catch (err) {
+			warn(`resolveDomain("${name}") failed: ${err instanceof Error ? err.message : err}`);
+			return null;
+		}
+	}
+	return {
+		source: "remote",
+		async list() {
+			try {
+				return (await resolver.listBlocklets()).map((b) => b.id);
+			} catch {
+				return [];
+			}
+		},
+		async resolveName(name) {
+			return (await lookup(name))?.canonicalName ?? null;
+		},
+		async reader(name) {
+			const entry = await lookup(name);
+			if (!entry) return null;
+			try {
+				const afs = await openUserSpace(entry.owner);
+				const root = (0, ufo.joinURL)("/", entry.path);
+				return createBundleBackedReader(afs, root, require_registry.createAfsBlockletReader(afs, root));
+			} catch (err) {
+				warn(`reader("${name}") failed: ${err instanceof Error ? err.message : err}`);
+				return null;
+			}
+		},
+		async afsRoot(name) {
+			const entry = await lookup(name);
+			if (!entry) return null;
+			try {
+				return {
+					afs: await openUserSpace(entry.owner),
+					rootPath: (0, ufo.joinURL)("/", entry.path)
+				};
+			} catch (err) {
+				warn(`afsRoot("${name}") failed: ${err instanceof Error ? err.message : err}`);
+				return null;
+			}
+		}
+	};
+}
+/**
+* Combine a static-bundle registry with a fallback registry (e.g. DID Space).
+*
+* The static bundle always wins — the fallback is only tried when the static
+* registry returns null/empty. This preserves zero-regression for existing
+* built-in blocklets. Fully generic (composes two BlockletRegistry objects).
+*/
+function createCompositeBlockletRegistry(staticRegistry, fallbackRegistry) {
+	if (!fallbackRegistry) return staticRegistry;
+	return {
+		source: "remote",
+		async list() {
+			const [staticNames, fallbackNames] = await Promise.all([staticRegistry.list(), fallbackRegistry.list()]);
+			const seen = new Set(staticNames);
+			const merged = [...staticNames];
+			for (const name of fallbackNames) if (!seen.has(name)) merged.push(name);
+			return merged;
+		},
+		async resolveName(name) {
+			const staticResult = await staticRegistry.resolveName?.(name);
+			if (staticResult) return staticResult;
+			return fallbackRegistry.resolveName?.(name) ?? null;
+		},
+		async reader(name) {
+			const staticReader = await (0, _aigne_afs_timing.time)("resolve.static", () => staticRegistry.reader(name));
+			if (staticReader) return staticReader;
+			return (0, _aigne_afs_timing.time)("resolve.didspace", () => fallbackRegistry.reader(name));
+		},
+		async afsRoot(name) {
+			const staticRoot = await staticRegistry.afsRoot?.(name);
+			if (staticRoot) return staticRoot;
+			return await fallbackRegistry.afsRoot?.(name) ?? null;
+		}
+	};
+}
+
+//#endregion
+exports.BLOCKLET_BUNDLE_PATH = BLOCKLET_BUNDLE_PATH;
+exports.createCompositeBlockletRegistry = createCompositeBlockletRegistry;
+exports.createDidSpaceBlockletRegistry = createDidSpaceBlockletRegistry;

package/dist/blocklet/did-space-registry.d.cts

@@ -0,0 +1,82 @@
+import { BlockletAfsReader, BlockletRegistry } from "./registry.cjs";
+
+//#region src/blocklet/did-space-registry.d.ts
+/**
+ * Publish-time serve bundle for a DID-Space blocklet (#674 Phase 4): small text
+ * files inlined so a cold serve reads one object instead of one-per-file. Sits
+ * at the blocklet root as the matched partner of the `.blocklet-publish.json`
+ * register marker (a distinct name — NOT http-mount's `.afs/bundle.json`, which
+ * is a different mechanism / consumer).
+ */
+declare const BLOCKLET_BUNDLE_PATH = ".blocklet-bundle.json";
+/**
+ * Minimal resolve-table surface the engine needs. `DIDSpaceResolver`
+ * (@aigne/afs-did-space) satisfies this structurally — typed here so aos doesn't
+ * import the concrete class just for two methods.
+ *
+ * `resolveDomain` is OPTIONAL (#764 Phase 4b): a custom-domain fallback for
+ * `lookup()` when the id-keyed `resolveBlocklet` misses. Optional so any other
+ * structural implementer of this interface (e.g. a test fake, or a future
+ * resolve-table backend that never grew domain support) degrades gracefully —
+ * `lookup()` just skips straight to "not found" instead of throwing.
+ */
+interface BlockletResolveSource {
+  resolveBlocklet(id: string): Promise<{
+    owner?: string;
+    path?: string;
+  } | null>;
+  listBlocklets(): Promise<Array<{
+    id: string;
+  }>>;
+  resolveDomain?(domain: string): Promise<{
+    did: string;
+    owner: string;
+    path: string;
+  } | null>;
+  /**
+   * Optional batched host resolution (issue #808): one backend round trip for
+   * BOTH the `resolve/blocklet/<name>` and `resolve/domain/<name>` lookups the
+   * sequential `resolveBlocklet` → `resolveDomain` ladder below performs. Blocklet
+   * wins (id key), same priority. Preferred when present; absent → the ladder
+   * runs (any structural implementer without it still works). `DIDSpaceResolver`
+   * satisfies it structurally on both the D1 (CF) and SQLite (Node) stores.
+   */
+  resolveBlockletOrDomain?(name: string): Promise<{
+    source: "blocklet";
+    owner: string;
+    path: string;
+  } | {
+    source: "domain";
+    owner: string;
+    path: string;
+    did: string;
+  } | null>;
+}
+interface DidSpaceBlockletRegistryDeps {
+  /** Global DID Space resolve table (resolve/blocklet/<id> → {owner, path}). */
+  resolver: BlockletResolveSource;
+  /**
+   * Open the whole user-space AFS for a publisher's PLAINTEXT owner DID. The
+   * runtime constructs the backend (CloudflareDIDSpace / local) and may cache it.
+   */
+  openUserSpace: (ownerDid: string) => Promise<BlockletAfsReader> | BlockletAfsReader;
+  /** Optional sink for non-fatal failures (resolve/read errors are swallowed). */
+  onWarn?: (message: string) => void;
+}
+/**
+ * Create a runtime-agnostic DID-Space BlockletRegistry. Positive resolves are
+ * cached per-instance; misses are NOT cached, so a newly published blocklet is
+ * visible on the next lookup.
+ */
+declare function createDidSpaceBlockletRegistry(deps: DidSpaceBlockletRegistryDeps): BlockletRegistry;
+/**
+ * Combine a static-bundle registry with a fallback registry (e.g. DID Space).
+ *
+ * The static bundle always wins — the fallback is only tried when the static
+ * registry returns null/empty. This preserves zero-regression for existing
+ * built-in blocklets. Fully generic (composes two BlockletRegistry objects).
+ */
+declare function createCompositeBlockletRegistry(staticRegistry: BlockletRegistry, fallbackRegistry: BlockletRegistry | null): BlockletRegistry;
+//#endregion
+export { BLOCKLET_BUNDLE_PATH, BlockletResolveSource, DidSpaceBlockletRegistryDeps, createCompositeBlockletRegistry, createDidSpaceBlockletRegistry };
+//# sourceMappingURL=did-space-registry.d.cts.map

package/dist/blocklet/did-space-registry.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-space-registry.d.cts","names":[],"sources":["../../src/blocklet/did-space-registry.ts"],"mappings":";;;;;;;;;;cAyCa,oBAAA;;;;;;;;;;;;UA8II,qBAAA;EACf,eAAA,CAAgB,EAAA,WAAa,OAAA;IAAU,KAAA;IAAgB,IAAA;EAAA;EACvD,aAAA,IAAiB,OAAA,CAAQ,KAAA;IAAQ,EAAA;EAAA;EACjC,aAAA,EAAe,MAAA,WAAiB,OAAA;IAAU,GAAA;IAAa,KAAA;IAAe,IAAA;EAAA;EAoBtE;;;;;;;;EAXA,uBAAA,EACE,IAAA,WACC,OAAA;IACG,MAAA;IAAoB,KAAA;IAAe,IAAA;EAAA;IACnC,MAAA;IAAkB,KAAA;IAAe,IAAA;IAAc,GAAA;EAAA;AAAA;AAAA,UAKtC,4BAAA;EAmKD;EAjKd,QAAA,EAAU,qBAAA;;;;;EAKV,aAAA,GAAgB,QAAA,aAAqB,OAAA,CAAQ,iBAAA,IAAqB,iBAAA;EA+JjD;EA7JjB,MAAA,IAAU,OAAA;AAAA;;;;;;iBAQI,8BAAA,CACd,IAAA,EAAM,4BAAA,GACL,gBAAA;;;;;;;;iBAgJa,+BAAA,CACd,cAAA,EAAgB,gBAAA,EAChB,gBAAA,EAAkB,gBAAA,UACjB,gBAAA"}

package/dist/blocklet/did-space-registry.d.mts

@@ -0,0 +1,82 @@
+import { BlockletAfsReader, BlockletRegistry } from "./registry.mjs";
+
+//#region src/blocklet/did-space-registry.d.ts
+/**
+ * Publish-time serve bundle for a DID-Space blocklet (#674 Phase 4): small text
+ * files inlined so a cold serve reads one object instead of one-per-file. Sits
+ * at the blocklet root as the matched partner of the `.blocklet-publish.json`
+ * register marker (a distinct name — NOT http-mount's `.afs/bundle.json`, which
+ * is a different mechanism / consumer).
+ */
+declare const BLOCKLET_BUNDLE_PATH = ".blocklet-bundle.json";
+/**
+ * Minimal resolve-table surface the engine needs. `DIDSpaceResolver`
+ * (@aigne/afs-did-space) satisfies this structurally — typed here so aos doesn't
+ * import the concrete class just for two methods.
+ *
+ * `resolveDomain` is OPTIONAL (#764 Phase 4b): a custom-domain fallback for
+ * `lookup()` when the id-keyed `resolveBlocklet` misses. Optional so any other
+ * structural implementer of this interface (e.g. a test fake, or a future
+ * resolve-table backend that never grew domain support) degrades gracefully —
+ * `lookup()` just skips straight to "not found" instead of throwing.
+ */
+interface BlockletResolveSource {
+  resolveBlocklet(id: string): Promise<{
+    owner?: string;
+    path?: string;
+  } | null>;
+  listBlocklets(): Promise<Array<{
+    id: string;
+  }>>;
+  resolveDomain?(domain: string): Promise<{
+    did: string;
+    owner: string;
+    path: string;
+  } | null>;
+  /**
+   * Optional batched host resolution (issue #808): one backend round trip for
+   * BOTH the `resolve/blocklet/<name>` and `resolve/domain/<name>` lookups the
+   * sequential `resolveBlocklet` → `resolveDomain` ladder below performs. Blocklet
+   * wins (id key), same priority. Preferred when present; absent → the ladder
+   * runs (any structural implementer without it still works). `DIDSpaceResolver`
+   * satisfies it structurally on both the D1 (CF) and SQLite (Node) stores.
+   */
+  resolveBlockletOrDomain?(name: string): Promise<{
+    source: "blocklet";
+    owner: string;
+    path: string;
+  } | {
+    source: "domain";
+    owner: string;
+    path: string;
+    did: string;
+  } | null>;
+}
+interface DidSpaceBlockletRegistryDeps {
+  /** Global DID Space resolve table (resolve/blocklet/<id> → {owner, path}). */
+  resolver: BlockletResolveSource;
+  /**
+   * Open the whole user-space AFS for a publisher's PLAINTEXT owner DID. The
+   * runtime constructs the backend (CloudflareDIDSpace / local) and may cache it.
+   */
+  openUserSpace: (ownerDid: string) => Promise<BlockletAfsReader> | BlockletAfsReader;
+  /** Optional sink for non-fatal failures (resolve/read errors are swallowed). */
+  onWarn?: (message: string) => void;
+}
+/**
+ * Create a runtime-agnostic DID-Space BlockletRegistry. Positive resolves are
+ * cached per-instance; misses are NOT cached, so a newly published blocklet is
+ * visible on the next lookup.
+ */
+declare function createDidSpaceBlockletRegistry(deps: DidSpaceBlockletRegistryDeps): BlockletRegistry;
+/**
+ * Combine a static-bundle registry with a fallback registry (e.g. DID Space).
+ *
+ * The static bundle always wins — the fallback is only tried when the static
+ * registry returns null/empty. This preserves zero-regression for existing
+ * built-in blocklets. Fully generic (composes two BlockletRegistry objects).
+ */
+declare function createCompositeBlockletRegistry(staticRegistry: BlockletRegistry, fallbackRegistry: BlockletRegistry | null): BlockletRegistry;
+//#endregion
+export { BLOCKLET_BUNDLE_PATH, BlockletResolveSource, DidSpaceBlockletRegistryDeps, createCompositeBlockletRegistry, createDidSpaceBlockletRegistry };
+//# sourceMappingURL=did-space-registry.d.mts.map

package/dist/blocklet/did-space-registry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-space-registry.d.mts","names":[],"sources":["../../src/blocklet/did-space-registry.ts"],"mappings":";;;;;;;;;;cAyCa,oBAAA;;;;;;;;;;;;UA8II,qBAAA;EACf,eAAA,CAAgB,EAAA,WAAa,OAAA;IAAU,KAAA;IAAgB,IAAA;EAAA;EACvD,aAAA,IAAiB,OAAA,CAAQ,KAAA;IAAQ,EAAA;EAAA;EACjC,aAAA,EAAe,MAAA,WAAiB,OAAA;IAAU,GAAA;IAAa,KAAA;IAAe,IAAA;EAAA;EAoBtE;;;;;;;;EAXA,uBAAA,EACE,IAAA,WACC,OAAA;IACG,MAAA;IAAoB,KAAA;IAAe,IAAA;EAAA;IACnC,MAAA;IAAkB,KAAA;IAAe,IAAA;IAAc,GAAA;EAAA;AAAA;AAAA,UAKtC,4BAAA;EAmKD;EAjKd,QAAA,EAAU,qBAAA;;;;;EAKV,aAAA,GAAgB,QAAA,aAAqB,OAAA,CAAQ,iBAAA,IAAqB,iBAAA;EA+JjD;EA7JjB,MAAA,IAAU,OAAA;AAAA;;;;;;iBAQI,8BAAA,CACd,IAAA,EAAM,4BAAA,GACL,gBAAA;;;;;;;;iBAgJa,+BAAA,CACd,cAAA,EAAgB,gBAAA,EAChB,gBAAA,EAAkB,gBAAA,UACjB,gBAAA"}