@tinycloud/sdk-services 3.1.0-beta.7 → 3.1.0

package/dist/kv/index.js

@@ -5,6 +5,10 @@ var ErrorCodes = {
   AUTH_EXPIRED: "AUTH_EXPIRED",
   AUTH_REQUIRED: "AUTH_REQUIRED",
   AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+  /** HTTP 401: the delegation the invocation cites was revoked. */
+  AUTH_DELEGATION_REVOKED: "AUTH_DELEGATION_REVOKED",
+  /** HTTP 401: a delegation the cited one rests on was revoked. */
+  AUTH_DELEGATION_ANCESTOR_REVOKED: "AUTH_DELEGATION_ANCESTOR_REVOKED",
   NETWORK_ERROR: "NETWORK_ERROR",
   TIMEOUT: "TIMEOUT",
   ABORTED: "ABORTED",
@@ -16,6 +20,10 @@ var ErrorCodes = {
   KV_PRECONDITION_FAILED: "KV_PRECONDITION_FAILED",
   KV_CONFLICT: "KV_CONFLICT",
   KV_RESPONSE_TOO_LARGE: "KV_RESPONSE_TOO_LARGE",
+  /** HTTP 410 from the change feed: discard sync state and restart without a cursor; `meta.reason` says why. */
+  KV_SYNC_RESET_REQUIRED: "KV_SYNC_RESET_REQUIRED",
+  /** HTTP 403 from the change feed: the retention grant was refused; `meta.reason` says why. */
+  KV_RETENTION_GRANT_REFUSED: "KV_RETENTION_GRANT_REFUSED",
   // SQL-specific errors
   SQL_ERROR: "SQL_ERROR",
   SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
@@ -705,6 +713,30 @@ var PrefixedKVService = class _PrefixedKVService {
       removePrefix
     });
   }
+  /**
+   * Read the change feed for everything under this prefix. A view with an
+   * empty prefix (`""` or `"/"`) is refused: the node does not serve a
+   * whole-space feed.
+   */
+  async changes(options) {
+    if (this._prefix.replace(/\/+$/, "") === "") {
+      return err(serviceError(
+        ErrorCodes.INVALID_INPUT,
+        "KV changes needs a non-empty prefix; this view has none",
+        "kv"
+      ));
+    }
+    const syncPrefix = `${this._prefix}/`;
+    const response = await this._kv.changes({ ...options, prefix: syncPrefix });
+    if (!response.ok) return response;
+    return ok({
+      ...response.data,
+      changes: response.data.changes.map((change) => ({
+        ...change,
+        key: change.key.startsWith(syncPrefix) ? change.key.slice(syncPrefix.length) : change.key
+      }))
+    });
+  }
   /**
    * Delete a key.
    */
@@ -757,11 +789,36 @@ var KVAction = {
   PUT: "tinycloud.kv/put",
   LIST: "tinycloud.kv/list",
   DELETE: "tinycloud.kv/del",
-  HEAD: "tinycloud.kv/metadata"
+  HEAD: "tinycloud.kv/metadata",
+  /** The change feed; never implied by `*` or `tinycloud.kv/*`. */
+  SYNC: "tinycloud.kv/sync",
+  /** Retention attestation; presented through `retentionGrant`, never invoked or implied. */
+  RETAIN: "tinycloud.kv/retain"
 };
 
 // src/kv/KVService.ts
 var MAX_KV_BATCH_READ_ITEMS = 100;
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var pathByteEncoder = new TextEncoder();
+function comparePathsByBytes(a, b) {
+  const left = pathByteEncoder.encode(a);
+  const right = pathByteEncoder.encode(b);
+  const length = Math.min(left.length, right.length);
+  for (let index = 0; index < length; index++) {
+    if (left[index] !== right[index]) {
+      return left[index] - right[index];
+    }
+  }
+  return left.length - right.length;
+}
+var REVOKED_BODY = /^(?:Invalid invocation: )?delegation-(?:(revoked): [A-Za-z0-9]+|(ancestor-revoked): ancestor=[A-Za-z0-9]+ invoked=[A-Za-z0-9]+)$/;
+function revocationCodeOf(body) {
+  const match = REVOKED_BODY.exec(body.trim());
+  if (match === null) return void 0;
+  return match[1] !== void 0 ? ErrorCodes.AUTH_DELEGATION_REVOKED : ErrorCodes.AUTH_DELEGATION_ANCESTOR_REVOKED;
+}
 function encodeKvBatchPartName(path) {
   return encodeURIComponent(path).replace(
     /[!'()*]/g,
@@ -989,15 +1046,25 @@ var KVService = class extends BaseService {
     )?.[1];
     return contentType?.includes("application/json") ? JSON.parse(text) : text;
   }
+  /**
+   * Validate a batch read response and return its items in the caller's
+   * request order. The node flattens invocation abilities from a `BTreeMap`,
+   * so results arrive sorted by UTF-8 byte order of the path, not in request
+   * order. Items that carry their path in `key` are matched by path; if no
+   * item carries a key, items are assumed to be in the node's byte-sorted
+   * order and the request is aligned the same way. Any mix of keyed and
+   * keyless items, a missing requested path, an unrequested path, or a
+   * malformed item fails closed (returns undefined).
+   */
   normalizeBatchReadResponse(data, paths, requireData) {
     if (!data || typeof data !== "object") return void 0;
     const response = data;
-    if (!Array.isArray(response.results) || response.results.length !== paths.length) {
+    const items = response.results;
+    if (!Array.isArray(items) || items.length !== paths.length) {
       return void 0;
     }
-    for (let index = 0; index < response.results.length; index++) {
-      const item = response.results[index];
-      if (!item || typeof item !== "object" || item.key !== paths[index] || typeof item.ok !== "boolean") {
+    for (const item of items) {
+      if (!item || typeof item !== "object" || typeof item.ok !== "boolean") {
         return void 0;
       }
       if (item.ok && (!item.headers || typeof item.headers !== "object" || Object.values(item.headers).some((value) => typeof value !== "string") || requireData && typeof item.dataBase64 !== "string")) {
@@ -1007,7 +1074,24 @@ var KVService = class extends BaseService {
         return void 0;
       }
     }
-    return response;
+    if (items.every((item) => typeof item.key === "string")) {
+      const byPath = new Map(items.map((item) => [item.key, item]));
+      if (byPath.size !== items.length) return void 0;
+      const aligned2 = [];
+      for (const path of paths) {
+        const item = byPath.get(path);
+        if (!item) return void 0;
+        aligned2.push(item);
+      }
+      return aligned2;
+    }
+    if (items.some((item) => item.key !== void 0)) return void 0;
+    const requestOrder = paths.map((_, index) => index).sort((a, b) => comparePathsByBytes(paths[a], paths[b]));
+    const aligned = new Array(items.length);
+    for (let position = 0; position < requestOrder.length; position++) {
+      aligned[requestOrder[position]] = items[position];
+    }
+    return aligned;
   }
   async batchRead(keys, action, options) {
     if (!this.requireAuth()) return err(authRequiredError("kv"));
@@ -1100,19 +1184,19 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
-      const payload = this.normalizeBatchReadResponse(
+      const items = this.normalizeBatchReadResponse(
         await response.json(),
         paths,
         action === KVAction.GET
       );
-      if (!payload) {
+      if (!items) {
         return err(serviceError(
           ErrorCodes.NETWORK_ERROR,
           "KV batch read response did not match the requested keys",
           "kv"
         ));
       }
-      const results = payload.results.map((item, index) => {
+      const results = items.map((item, index) => {
         if (!item.ok) {
           return {
             key: keys[index],
@@ -1680,6 +1764,169 @@ var KVService = class extends BaseService {
       }
     });
   }
+  /**
+   * Read one page of the `tinycloud.kv/sync` change feed for a prefix.
+   */
+  async changes(options) {
+    return this.withTelemetry("changes", options?.prefix, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      if (typeof options?.prefix !== "string" || options.prefix.length === 0) {
+        return err(serviceError(
+          ErrorCodes.INVALID_INPUT,
+          "KV changes prefix must be a non-empty string",
+          "kv"
+        ));
+      }
+      if (options.limit !== void 0 && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 1e3)) {
+        return err(serviceError(
+          ErrorCodes.INVALID_INPUT,
+          "KV changes limit must be an integer from 1 through 1000",
+          "kv"
+        ));
+      }
+      const headers = {};
+      if (options.limit !== void 0) headers["x-tinycloud-limit"] = String(options.limit);
+      if (options.cursor !== void 0) headers["x-tinycloud-cursor"] = options.cursor;
+      if (options.retentionGrant !== void 0) {
+        headers["x-tinycloud-retention-grant"] = options.retentionGrant;
+      }
+      const request = this.createRequestSignal(options.signal, options.timeout);
+      try {
+        const response = await this.invokeOperation(
+          options.prefix,
+          KVAction.SYNC,
+          void 0,
+          request.signal,
+          headers
+        );
+        if (!response.ok) {
+          return await this.changesFailure(response, options.prefix, request.signal);
+        }
+        const text = await response.text();
+        let body;
+        try {
+          body = JSON.parse(text);
+        } catch {
+          body = void 0;
+        }
+        const page = this.normalizeChangesResponse(body);
+        if (!page) {
+          return err(serviceError(
+            ErrorCodes.NETWORK_ERROR,
+            "KV changes response was not a tinycloud.kv/sync page",
+            "kv",
+            { meta: { status: response.status, statusText: response.statusText } }
+          ));
+        }
+        return ok(page);
+      } catch (error) {
+        return err(wrapError("kv", error));
+      } finally {
+        request.dispose();
+      }
+    });
+  }
+  /**
+   * Map a failed `kv/sync` response. 410 and the retention 403 carry
+   * `{"error":{"code","reason"}}`; a revoked grant is a 401 whose whole body
+   * is the node's revocation error (see REVOKED_BODY). A body read that
+   * fails because the request was cancelled or timed out rethrows, so the
+   * caller sees `ABORTED`/`TIMEOUT` rather than a mapped status.
+   */
+  async changesFailure(response, prefix, signal) {
+    if (response.status === 404) {
+      return this.classifyNotFound(response, prefix);
+    }
+    let errorText;
+    try {
+      errorText = await response.text();
+    } catch (error) {
+      if (signal.aborted) throw error;
+      errorText = "";
+    }
+    const meta = { status: response.status, statusText: response.statusText };
+    let reason;
+    let bodyCode;
+    try {
+      const body = JSON.parse(errorText);
+      const error = isJsonObject(body) ? body.error : void 0;
+      if (isJsonObject(error)) {
+        if (typeof error.code === "string") bodyCode = error.code;
+        if (typeof error.reason === "string") reason = error.reason;
+      }
+    } catch {
+    }
+    const context = `Failed to read KV changes for ${JSON.stringify(prefix)}`;
+    if (response.status === 410) {
+      return err(serviceError(
+        ErrorCodes.KV_SYNC_RESET_REQUIRED,
+        `${context}: the node requires a reset (${reason ?? "reason not given"}); discard sync state and restart without a cursor`,
+        "kv",
+        { meta: { ...meta, reason } }
+      ));
+    }
+    if (response.status === 403 && bodyCode === "RETENTION_GRANT_REFUSED") {
+      return err(serviceError(
+        ErrorCodes.KV_RETENTION_GRANT_REFUSED,
+        `${context}: the retention grant was refused (${reason ?? "reason not given"})`,
+        "kv",
+        { meta: { ...meta, reason } }
+      ));
+    }
+    if (response.status === 401) {
+      const revoked = revocationCodeOf(errorText);
+      if (revoked !== void 0) {
+        return err(serviceError(revoked, `${context}: 401 - ${errorText}`, "kv", { meta }));
+      }
+    }
+    if (response.status === 401 || response.status === 403) {
+      return this.authorizationFailure(context, response, errorText, [prefix], KVAction.SYNC);
+    }
+    return err(serviceError(
+      response.status === 400 ? ErrorCodes.INVALID_INPUT : ErrorCodes.NETWORK_ERROR,
+      `${context}: ${response.status} - ${errorText}`,
+      "kv",
+      { meta }
+    ));
+  }
+  normalizeChangesResponse(data) {
+    if (!isJsonObject(data)) return void 0;
+    const { changes, more, cursor, source, authority } = data;
+    if (!Array.isArray(changes) || typeof more !== "boolean" || typeof cursor !== "string" || !isJsonObject(source) || typeof source.nodeDid !== "string" || typeof source.space !== "string" || typeof source.prefix !== "string" || !isJsonObject(authority)) {
+      return void 0;
+    }
+    const { notBefore, expiresAt, retainUntil } = authority;
+    if (notBefore !== null && typeof notBefore !== "string" || expiresAt !== null && typeof expiresAt !== "string" || retainUntil !== null && typeof retainUntil !== "string") {
+      return void 0;
+    }
+    const parsed = [];
+    for (const change of changes) {
+      if (!isJsonObject(change) || typeof change.key !== "string") return void 0;
+      if (change.deleted === true) {
+        parsed.push({ key: change.key, deleted: true });
+        continue;
+      }
+      const { metadata } = change;
+      if (change.deleted !== false || typeof change.etag !== "string" || !isJsonObject(metadata) || !Object.values(metadata).every((value) => typeof value === "string")) {
+        return void 0;
+      }
+      parsed.push({
+        key: change.key,
+        deleted: false,
+        etag: change.etag,
+        metadata
+      });
+    }
+    return {
+      changes: parsed,
+      more,
+      cursor,
+      source: { nodeDid: source.nodeDid, space: source.space, prefix: source.prefix },
+      authority: { notBefore, expiresAt, retainUntil }
+    };
+  }
   /**
    * Delete a key.
    */