@aigne/afs-did-space 1.12.0-beta.5

package/dist/cloudflare.cjs

@@ -0,0 +1,510 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_blocklet_hook = require('./blocklet-hook.cjs');
+const require_cid = require('./cid.cjs');
+const require_did_utils = require('./did-utils.cjs');
+require('./mime-utils.cjs');
+const require_inline_content = require('./inline-content.cjs');
+const require_share_declaration = require('./share-declaration.cjs');
+const require_share_hook = require('./share-hook.cjs');
+const require_upload_session_store = require('./upload-session-store.cjs');
+const require_cid_byte_cache = require('./cid-byte-cache.cjs');
+const require_d1_gc_queue = require('./d1-gc-queue.cjs');
+const require_d1_resolve_store = require('./d1-resolve-store.cjs');
+const require_object_key = require('./object-key.cjs');
+const require_d1_tree_index = require('./d1-tree-index.cjs');
+const require_prefixed_tree_index = require('./prefixed-tree-index.cjs');
+const require_resolve = require('./resolve.cjs');
+const require_scope_id = require('./scope-id.cjs');
+const require_index = require('./index.cjs');
+let _aigne_afs = require("@aigne/afs");
+let _aigne_afs_provider_utils = require("@aigne/afs-provider-utils");
+
+//#region src/cloudflare.ts
+/**
+* CloudflareDIDSpace — Cloudflare backend for DID-scoped storage.
+*
+* Composes DIDSpaceProvider (files via R2 + D1 TreeIndex) per app,
+* with logical isolation (separate D1 scope per user+app DID).
+*
+* Same interface as local DIDSpace for 100% compatibility.
+*
+* Usage:
+*   const space = new CloudflareDIDSpace({ userDid: "did:abt:z1...", objectStore, indexDb });
+*   const afs = await space.getInstanceSpace({ instanceDid: "z1app", role: "system" });
+*   await afs.write("/hello.txt", { content: "hello" });
+*/
+/** provider:did-space structured logger (debug self-guards; off by default). */
+const log = (0, _aigne_afs.nsLog)("provider:did-space");
+var CloudflareDIDSpace = class {
+	/** Real normalizeId(DID) — identity, returned to callers (NOT a storage key). */
+	userDid;
+	/**
+	* Storage scope — `deriveScope(userDid, secret)` when de-id is on, else the
+	* plaintext `userDid`. Every D1 storage/query key uses this, never `userDid`.
+	* Named `_scope` to avoid colliding with the `get scope()` accessor (README §4.1).
+	*/
+	_scope;
+	objectStore;
+	indexDb;
+	_resolver;
+	/** Optional ShareResolver for .share reconcile hook (Phase 0.4) */
+	shareResolver;
+	/** Read replica opt-in for read-serving paths only — see options doc. */
+	useReplica;
+	/** upload-limits Phase 5 per-scope byte quota (0 = off, the opt-in default). */
+	maxBytesPerScope;
+	/**
+	* Instance space cache keyed by (role, useReplica) — same shape as `local.ts`
+	* `instanceSpaces`. Without it, `getInstanceSpace` returns a fresh `AFS`
+	* (and fresh `EventBus`) every call, so propBind subscribe (registered on
+	* AFS_A at session start) and the agent's subsequent write (executing on
+	* AFS_B for that exec) cross different buses — the write's `afs:write`
+	* event never reaches the subscriber, so the live patch silently drops and
+	* the user only sees the new value after a manual page reload (Layer 2
+	* staleness on staging). Bounded by the lifetime of this DID-Space (per
+	* caller in the resolver), the same memory budget the resolver already
+	* spends on `spaces`.
+	*/
+	instanceSpaces = /* @__PURE__ */ new Map();
+	/**
+	* User-space cache keyed by (accessMode, useReplica) — the getUserSpace
+	* counterpart of {@link instanceSpaces}. Without it, every `getUserSpace()`
+	* builds a fresh `AFS` and re-runs `AFS.mount()`'s async provider health check
+	* (a root `stat` → `countChildren` + list). Blocklet serve calls getUserSpace
+	* once PER stage (reader / afsRoot), so a cold page paid that root enumeration
+	* 3× (issue #808 #4). Caching the handle reuses the mounted provider; data
+	* reads stay fresh (path→cid D1 lookups are never cached), so zero staleness.
+	*/
+	userSpaces = /* @__PURE__ */ new Map();
+	/** Shared GC queue instance — created once per CloudflareDIDSpace instance */
+	gcQueue;
+	/** Injected presigned-PUT signer (upload plane). Undefined → no grant capability. */
+	signer;
+	constructor(options) {
+		require_did_utils.validateId(options.userDid);
+		this.userDid = require_did_utils.normalizeId(options.userDid);
+		this._scope = options.scopeHmacSecret ? require_scope_id.deriveScope(this.userDid, options.scopeHmacSecret) : this.userDid;
+		this.objectStore = new require_cid_byte_cache.CachingObjectStore(options.objectStore, new require_cid_byte_cache.CidByteCache());
+		this.indexDb = options.indexDb;
+		this.gcQueue = new require_d1_gc_queue.D1GCQueue(options.indexDb);
+		this.shareResolver = options.shareResolver;
+		this.useReplica = options.useReplica ?? false;
+		this.maxBytesPerScope = options.maxBytesPerScope ?? 0;
+		this.signer = options.signer;
+	}
+	/**
+	* Construct a D1TreeIndex for this scope with the per-scope byte quota
+	* (upload-limits Phase 5) always injected — so every write path enforces it
+	* uniformly without each call site remembering to thread it. 0 = quota off.
+	*/
+	makeTreeIndex(opts) {
+		return new require_d1_tree_index.D1TreeIndex(this.indexDb, this._scope, {
+			...opts,
+			maxBytesPerScope: this.maxBytesPerScope
+		});
+	}
+	/**
+	* The injected presigned-PUT signer, or undefined when no R2 signer
+	* credentials are configured. The seam through which `prepare-upload` (P2)
+	* mints upload grants; also the capability signal clients use to decide
+	* grant-path vs batchWrite fallback (§15 decision 7/8).
+	*/
+	get presignSigner() {
+		return this.signer;
+	}
+	/**
+	* Upload-plane deps for the user-facing `DIDSpaceProvider` (design §7): the
+	* injected signer (CF mints grants; absent → fallback), a D1-backed session
+	* store, and the de-identified storage scope written into `upload_sessions`.
+	* Only the user space gets these — `/instance` (installer) + config don't.
+	*/
+	uploadDeps() {
+		return {
+			signer: this.signer,
+			uploadSessionStore: new require_upload_session_store.D1UploadSessionStore(this.indexDb),
+			uploadScope: this._scope
+		};
+	}
+	/**
+	* Get an isolated AFS instance for a blocklet instance under this DID Space,
+	* scoped by role (system = installer-side data, user = caller-side data).
+	*
+	* Layout (PrefixedTreeIndex prefix relative to `entries.scope = userDid`):
+	*   role:"system" → blocklets/{instanceDid}/system/   (content tree, mounted at `/`)
+	*   role:"user"   → blocklets/{instanceDid}/user/      (content tree, mounted at `/`)
+	*   config        → blocklets/{instanceDid}/config/    (sibling fragment, getConfigSpace)
+	*
+	* /files-prefix-removal: content tree is the role root (no `files/` wrapper);
+	* config is a sibling fragment (invisible to `/instance`); vault removed.
+	*
+	* did-space-composition Phase 2 (symmetric with the local backend): the user
+	* fragment is a SINGLE `user` subtree. Per-user isolation comes from scope =
+	* caller's userDid (the resolver hands back a CloudflareDIDSpace scoped to the
+	* caller), so a `users/{userDid}` path segment would be redundant. `userDid`
+	* is @deprecated for this call and ignored for the path.
+	*
+	* Cached per (instanceDid, role, useReplica) — first caller's accessMode
+	* wins for that triple (mirrors local.ts). See `instanceSpaces` for the
+	* live-update rationale.
+	*/
+	async getInstanceSpace(opts) {
+		log.debug({
+			message: "getInstanceSpace",
+			instanceDid: opts.instanceDid,
+			role: opts.role
+		});
+		require_did_utils.validateId(opts.instanceDid);
+		if (opts.role !== "system" && opts.role !== "user") throw new Error(`getInstanceSpace: invalid role "${opts.role}"`);
+		if (opts.role === "user" && opts.userDid != null) require_did_utils.validateId(opts.userDid);
+		const bareInstanceId = require_did_utils.normalizeId(opts.instanceDid);
+		const useReplica = opts.consistency === "primary" ? false : this.useReplica;
+		const cacheKey = `${bareInstanceId}::${opts.role}::${useReplica ? "r" : "p"}`;
+		const cached = this.instanceSpaces.get(cacheKey);
+		if (cached) return cached;
+		const subtree = opts.role === "system" ? `blocklets/${bareInstanceId}/system` : `blocklets/${bareInstanceId}/user`;
+		const accessMode = opts.accessMode ?? "readwrite";
+		const afs = new _aigne_afs.AFS();
+		const baseTreeIndex = this.makeTreeIndex({
+			useReplica,
+			inlineCache: "on"
+		});
+		const fileProvider = new require_index.DIDSpaceProvider({
+			did: bareInstanceId,
+			objectStore: this.objectStore,
+			treeIndex: new require_prefixed_tree_index.PrefixedTreeIndex(baseTreeIndex, `${subtree}/`),
+			name: "content",
+			accessMode,
+			gcQueue: this.gcQueue,
+			...opts.role === "user" ? {
+				shareTreePrefix: `${subtree}/`,
+				...this.shareResolver ? {
+					shareResolver: this.shareResolver,
+					shareOwnerDid: this._scope
+				} : {},
+				blockletResolver: this.resolver,
+				blockletOwnerDid: this.userDid
+			} : {},
+			...opts.role === "user" ? this.uploadDeps() : {}
+		});
+		await afs.mount(fileProvider, "/", { skipHealthCheck: true });
+		this.instanceSpaces.set(cacheKey, afs);
+		return afs;
+	}
+	/**
+	* Runtime-internal config fragment (`blocklets/<i>/config/`, mounted at
+	* `/`). Mirrors local `getConfigSpace`. Invisible to `/instance`; holds
+	* per-instance machine state like `mounts.toml`.
+	*/
+	async getConfigSpace(instanceDid) {
+		require_did_utils.validateId(instanceDid);
+		const bareInstanceId = require_did_utils.normalizeId(instanceDid);
+		const afs = new _aigne_afs.AFS();
+		const baseTreeIndex = this.makeTreeIndex({
+			useReplica: this.useReplica,
+			inlineCache: "on"
+		});
+		const configProvider = new require_index.DIDSpaceProvider({
+			did: bareInstanceId,
+			objectStore: this.objectStore,
+			treeIndex: new require_prefixed_tree_index.PrefixedTreeIndex(baseTreeIndex, `blocklets/${bareInstanceId}/config/`),
+			name: "config",
+			accessMode: "readwrite",
+			gcQueue: this.gcQueue
+		});
+		await afs.mount(configProvider, "/", { skipHealthCheck: true });
+		return afs;
+	}
+	/**
+	* List all instance DIDs that have storage in this user's space.
+	*
+	* Enumerates entries under the `blocklets/<instanceDid>/...` prefix and
+	* returns the distinct instance-DID segment. This mirrors the local
+	* backend's `listApps`, which enumerates `{userDir}/blocklets/*`. Legacy
+	* top-level `getAppSpace` segments are NOT enumerated — that layout is
+	* deprecated and removed in P4.
+	*/
+	async listApps() {
+		const result = await this.makeTreeIndex({ useReplica: this.useReplica }).list("", { limit: 1e3 });
+		const apps = /* @__PURE__ */ new Set();
+		for (const entry of result.entries) {
+			const parts = entry.path.split("/");
+			if (parts[0] === "blocklets" && parts[1]) apps.add(parts[1]);
+		}
+		return [...apps];
+	}
+	/**
+	* Contract alias (分叉 A, observability Phase 2) for the whole-space root.
+	* Delegates to {@link getUserSpace}; satisfies `DIDSpaceLike.getSpaceRoot`
+	* without renaming the existing CF method. Defaults readonly via getUserSpace.
+	*/
+	async getSpaceRoot(options) {
+		return this.getUserSpace(options);
+	}
+	/**
+	* Get an AFS instance scoped to the user's entire DID Space.
+	* No appDid sub-partitioning.
+	*/
+	async getUserSpace(options) {
+		log.debug({
+			message: "getUserSpace",
+			userDid: this.userDid
+		});
+		const accessMode = options?.accessMode ?? "readonly";
+		const cacheKey = `${accessMode}::${this.useReplica ? "r" : "p"}`;
+		const cached = this.userSpaces.get(cacheKey);
+		if (cached) return cached;
+		const afs = new _aigne_afs.AFS();
+		const provider = new require_index.DIDSpaceProvider({
+			did: this.userDid,
+			objectStore: this.objectStore,
+			treeIndex: this.makeTreeIndex({
+				useReplica: this.useReplica,
+				inlineCache: "on"
+			}),
+			name: "did-space-user",
+			accessMode,
+			shareResolver: this.shareResolver,
+			blockletResolver: this.resolver,
+			blockletOwnerDid: this.userDid,
+			...this.uploadDeps()
+		});
+		await afs.mount(provider, "/", { skipHealthCheck: true });
+		this.userSpaces.set(cacheKey, afs);
+		return afs;
+	}
+	get resolver() {
+		if (!this._resolver) this._resolver = new require_resolve.DIDSpaceResolver(new require_d1_resolve_store.D1ResolveStore(this.indexDb, { useReplica: this.useReplica }));
+		return this._resolver;
+	}
+	/**
+	* Expose the underlying storage scope — used by worker handlers for
+	* cid-permission queries. MUST return the derived scope (not the plaintext
+	* DID) so the worker's `entries.scope` lookups match what was written.
+	*/
+	get scope() {
+		return this._scope;
+	}
+	/**
+	* Direct write path for the Worker HTTP handler (Task 2.4b).
+	*
+	* Bypasses the generic `afs.write()` path because `AFSWriteEntryPayload` has
+	* no `deviceId`/`skipChangelog` field — the `PutOpts` cannot be smuggled
+	* through the public AFS API. The Worker handler therefore constructs a
+	* `CloudflareDIDSpace` and calls this method directly, passing the per-
+	* request `deviceId` read from the `X-Device-Id` header.
+	*
+	* Semantics mirror `DIDSpaceProvider.writeHandler`:
+	*   1. Compute the content-addressed CID from the payload bytes.
+	*   2. R2 put `objects/{cid}` if not already stored (head-check for dedup).
+	*   3. `treeIndex.put` — atomic `entries` + `changelog` write (Task 2.4a).
+	*   4. Enqueue the previous CID (if any) onto the GC queue for deferred
+	*      cleanup. Enqueuing an overwritten CID is a no-op if the CID is still
+	*      referenced by another row (the GC job's reference check handles it).
+	*
+	* Path conventions:
+	*   - `afsPath` is an AFS-style path WITH leading slash (e.g. `/foo.json`
+	*     or `/blocklets/z1abc/index.html`).
+	*   - The leading slash is stripped before `treeIndex.put`; the remainder is
+	*     stored verbatim under `entries.scope = this._scope` (the derived storage
+	*     scope when de-id is on, else the plaintext DID). This matches the
+	*     `getUserSpace()` layout (no appDid sub-partition) that blocklet publish
+	*     and general user-space CRUD share.
+	*
+	* Returns `{ cid, oldCid }`. `oldCid` is present only when an existing row
+	* was overwritten; the caller can treat its presence as "something was
+	* replaced" for change-tracking. `seq` is not returned — Task 2.4a's
+	* `treeIndex.put` does not expose the changelog's AUTOINCREMENT `seq`, and
+	* adding a separate SELECT round trip here is wasted work for the current
+	* sync path (which only cares about cid + oldCid).
+	*
+	* No event dispatch is performed (Decision 3A round 5): CloudflareDIDSpace
+	* has no event bus reference, the Worker runtime is request/response with
+	* no long-lived subscriber, and the sync protocol polls `changelog` rows
+	* by `seq` rather than reacting to transient event fan-out.
+	*/
+	async internalWrite(afsPath, content, opts) {
+		let bytes;
+		let storeValue;
+		if (content instanceof Uint8Array) {
+			bytes = content;
+			storeValue = bytes.buffer;
+		} else if (content instanceof ArrayBuffer) {
+			bytes = new Uint8Array(content);
+			storeValue = content;
+		} else {
+			bytes = new TextEncoder().encode(content);
+			storeValue = content;
+		}
+		const cid = await require_cid.computeCID(bytes);
+		const objectKey = require_object_key.objectKeyForCid(cid);
+		const treePath = afsPath.replace(/^\/+/, "");
+		if (require_share_declaration.isShareReservedPath(afsPath)) throw new _aigne_afs.AFSForbiddenError(afsPath, "share-path-reserved");
+		await require_share_hook.applyShareWriteHook({
+			afsPath,
+			treePath,
+			bytes,
+			cid,
+			ownerDid: this._scope,
+			resolver: this.shareResolver,
+			phase: "pre-io"
+		});
+		if (!await this.objectStore.head(objectKey)) await this.objectStore.put(objectKey, storeValue);
+		const now = Date.now();
+		const mimeType = (0, _aigne_afs_provider_utils.detectMimeType)(afsPath) ?? void 0;
+		const treeIndex = this.makeTreeIndex({ inlineCache: "on" });
+		const entry = {
+			cid,
+			size: bytes.length,
+			mtime: now,
+			ctime: now,
+			mimeType
+		};
+		const inlineText = require_inline_content.decodeInlineText(bytes, mimeType);
+		if (inlineText !== null) entry.content = inlineText;
+		const { oldCid } = await treeIndex.put(treePath, entry, opts);
+		await this.gcQueue.remove(cid);
+		if (oldCid && oldCid !== cid) await this.gcQueue.enqueue([oldCid]);
+		await require_share_hook.applyShareWriteHook({
+			afsPath,
+			treePath,
+			bytes,
+			cid,
+			ownerDid: this._scope,
+			resolver: this.shareResolver,
+			phase: "post-io"
+		});
+		await require_blocklet_hook.applyBlockletWriteHook({
+			afsPath,
+			treePath,
+			bytes,
+			ownerDid: this.userDid,
+			resolver: this.resolver,
+			purgeCachesForDomains: typeof caches !== "undefined" ? async (domains) => {
+				const cfCaches = caches;
+				for (const domain of domains) {
+					const rootKey = new Request(`https://${domain}/`, { method: "GET" });
+					await cfCaches.default.delete(rootKey);
+				}
+			} : void 0
+		});
+		return oldCid === void 0 ? { cid } : {
+			cid,
+			oldCid
+		};
+	}
+	/**
+	* Read the current entry's cid + mtime + last-write deviceId for an
+	* If-Match precondition check (Task 3.3).
+	*
+	* Used by `_createSpaceHandler` BEFORE issuing a write when the client
+	* sends `If-Match: <cid>` for optimistic concurrency control. The
+	* handler compares the returned `cid` to the header value and returns
+	* 409 (with the full snapshot below) on mismatch, or 412 if the row
+	* doesn't exist (first-create with If-Match).
+	*
+	* The query joins `entries` (cid + mtime authoritative) with the most
+	* recent put row in `changelog` (device_id of last writer). Both
+	* indices used (`PRIMARY KEY (scope, path)` on entries +
+	* `idx_changelog_scope_seq` on changelog) keep this O(log n).
+	*
+	* `deviceId` is `null` when the entry was written via the blocklet
+	* exemption path (skipChangelog = true) — there's no changelog row to
+	* read the device id from. The handler exposes `null` to clients in
+	* the 409 body.
+	*
+	* Returns `null` when no entry exists at this path.
+	*/
+	async getCurrentEntry(afsPath) {
+		const treePath = afsPath.replace(/^\/+/, "");
+		const row = await this.indexDb.prepare(`SELECT
+           e.cid AS cid,
+           e.mtime AS mtime,
+           (SELECT device_id FROM ds_changelog
+              WHERE scope = ? AND path = ? AND op = 'put'
+              ORDER BY seq DESC LIMIT 1) AS device_id
+         FROM ds_entries e
+         WHERE e.scope = ? AND e.path = ? AND e.kind = 'file'`).bind(this._scope, treePath, this._scope, treePath).first();
+		if (!row || row.cid === null) return null;
+		return {
+			cid: row.cid,
+			mtime: row.mtime,
+			deviceId: row.device_id
+		};
+	}
+	/**
+	* Read the changelog `seq` of the most recent write by `(scope, path,
+	* deviceId)` (Task 3.3).
+	*
+	* The Worker handler calls this AFTER `internalWrite/internalDelete`
+	* to recover the seq of the row just inserted, so the PUT/DELETE
+	* response can echo `{cid, seq}` for the client.
+	*
+	* The triple WHERE clause (scope + path + device_id) is the safety
+	* mechanism for concurrent writers: each writer is guaranteed to have
+	* a unique `device_id` (validated by the Worker handler's strict
+	* format regex BEFORE we get here), so even if two PUTs on the same
+	* path race, each call's getLastSeq sees ONLY its own write — never
+	* the other writer's.
+	*
+	* Returns `0` when no row matches (impossible if called immediately
+	* after a successful internalWrite, but defensive against
+	* skipChangelog = true callers — blocklet exempt PUTs have no
+	* changelog row at all and the handler should NOT call this for them).
+	*/
+	async getLastSeq(afsPath, deviceId) {
+		const treePath = afsPath.replace(/^\/+/, "");
+		return (await this.indexDb.prepare(`SELECT MAX(seq) AS seq FROM ds_changelog
+         WHERE scope = ? AND path = ? AND device_id = ?`).bind(this._scope, treePath, deviceId).first())?.seq ?? 0;
+	}
+	/**
+	* Direct delete path for the Worker HTTP handler (Task 2.4b).
+	*
+	* Semantics mirror `DIDSpaceProvider.deleteHandler`:
+	*   1. Read the current entry (for GC enqueue of the soon-to-be-orphaned CID).
+	*   2. `treeIndex.delete` — atomic `entries` delete + `changelog` delete row
+	*      (Task 2.4a's `INSERT INTO ds_changelog SELECT ... FROM ds_entries` pattern
+	*      captures the old CID in-batch).
+	*   3. Enqueue the old CID for GC. Enqueueing is safe even under races —
+	*      the GC job's `isReferenced` check skips CIDs still referenced by
+	*      other rows.
+	*
+	* Returns an empty object (no `seq` for the same reason as `internalWrite`).
+	* Callers that need to know whether anything was actually deleted can rely
+	* on the absence of an `AFSNotFoundError` — Task 2.4b's handler converts
+	* that to a 404 response.
+	*/
+	async internalDelete(afsPath, opts) {
+		const treePath = afsPath.replace(/^\/+/, "");
+		const treeIndex = this.makeTreeIndex();
+		if (require_share_declaration.isShareReservedPath(afsPath)) throw new _aigne_afs.AFSForbiddenError(afsPath, "share-path-reserved");
+		const entry = await treeIndex.get(treePath, { includeContent: false });
+		if (!entry) return { deleted: false };
+		await this.gcQueue.enqueue([entry.cid]);
+		await treeIndex.delete(treePath, opts);
+		await require_share_hook.applyShareDeleteHook({
+			afsPath,
+			treePath,
+			ownerDid: this._scope,
+			resolver: this.shareResolver
+		});
+		await require_blocklet_hook.applyBlockletDeleteHook({
+			afsPath,
+			treePath,
+			ownerDid: this.userDid,
+			resolver: this.resolver
+		});
+		return { deleted: true };
+	}
+	/**
+	* Clean up resources. Drops the cached instance-space map so retained AFS
+	* instances are GC-eligible alongside this DID-Space.
+	*/
+	close() {
+		this.instanceSpaces.clear();
+	}
+};
+
+//#endregion
+exports.CloudflareDIDSpace = CloudflareDIDSpace;
+exports.normalizeId = require_did_utils.normalizeId;
+exports.validateId = require_did_utils.validateId;