@tinycloud/sdk-services 3.2.0-beta.3 → 3.2.0-beta.7

package/dist/index.cjs

@@ -59,6 +59,8 @@ __export(src_exports, {
   SQLMigrations: () => SQLMigrations,
   SQLService: () => SQLService,
   STORAGE_FULL_MESSAGE: () => STORAGE_FULL_MESSAGE,
+  STORAGE_MANAGE_URL: () => STORAGE_MANAGE_URL,
+  STORAGE_NEARLY_FULL_RATIO: () => STORAGE_NEARLY_FULL_RATIO,
   STORAGE_WRITE_TOO_LARGE_MESSAGE: () => STORAGE_WRITE_TOO_LARGE_MESSAGE,
   SecretsService: () => SecretsService,
   ServiceContext: () => ServiceContext,
@@ -68,6 +70,7 @@ __export(src_exports, {
   ServiceResponseEventSchema: () => ServiceResponseEventSchema,
   ServiceRetryEventSchema: () => ServiceRetryEventSchema,
   ServiceSessionSchema: () => ServiceSessionSchema,
+  StorageFullMonitor: () => StorageFullMonitor,
   TC832_RESERVED_SCOPES: () => TC832_RESERVED_SCOPES,
   TelemetryEvents: () => TelemetryEvents,
   TelemetrySpanEventSchema: () => TelemetrySpanEventSchema,
@@ -129,6 +132,8 @@ __export(src_exports, {
   parsePermissionHintFromErrorText: () => parsePermissionHintFromErrorText,
   parseSecretCatalogKey: () => parseSecretCatalogKey,
   parseStorageQuotaBytes: () => parseStorageQuotaBytes,
+  parseStorageRejection: () => parseStorageRejection,
+  parseStorageStatus: () => parseStorageStatus,
   permissionDeniedError: () => permissionDeniedError,
   replicationIdentityKey: () => replicationIdentityKey,
   requiresSecretsOptIn: () => requiresSecretsOptIn,
@@ -138,6 +143,7 @@ __export(src_exports, {
   storageLimitReachedError: () => storageLimitReachedError,
   storageQuotaExceededError: () => storageQuotaExceededError,
   storageRejectionError: () => storageRejectionError,
+  storageUsageState: () => storageUsageState,
   timeoutError: () => timeoutError,
   tinyCloudDebugLogger: () => tinyCloudDebugLogger,
   utf8Decode: () => utf8Decode,
@@ -195,6 +201,8 @@ var ErrorCodes = {
   // Storage quota errors
   STORAGE_QUOTA_EXCEEDED: "STORAGE_QUOTA_EXCEEDED",
   STORAGE_LIMIT_REACHED: "STORAGE_LIMIT_REACHED",
+  /** The node answered the usage read without usage numbers (it predates the read). */
+  STORAGE_STATUS_UNAVAILABLE: "STORAGE_STATUS_UNAVAILABLE",
   // DuckDB-specific errors
   DUCKDB_ERROR: "DUCKDB_ERROR",
   DUCKDB_PERMISSION_DENIED: "DUCKDB_PERMISSION_DENIED",
@@ -224,7 +232,9 @@ var TelemetryEvents = {
   REPLICATION_WRITE: "replication.write",
   REPLICATION_SYNC: "replication.sync",
   REPLICATION_STATE: "replication.state",
-  REPLICATION_DIVERGENCE: "replication.divergence"
+  REPLICATION_DIVERGENCE: "replication.divergence",
+  /** Emitted once, on the first write rejected because storage is full. */
+  STORAGE_FULL: "storage.full"
 };
 function ok(data) {
   return { ok: true, data };
@@ -1443,8 +1453,43 @@ function parseStorageQuotaBytes(responseText) {
     limitBytes: parseInt(match[2], 10)
   };
 }
+var STORAGE_REJECTION_BODY_ERRORS = {
+  storage_quota_exceeded: true,
+  storage_limit_reached: true
+};
+function isByteCount(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function byteCountsOf(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const { usedBytes, limitBytes } = value;
+  return isByteCount(usedBytes) && isByteCount(limitBytes) ? { usedBytes, limitBytes } : void 0;
+}
+function parseStorageRejection(responseText) {
+  let body;
+  try {
+    body = JSON.parse(responseText);
+  } catch {
+    return parseStorageQuotaBytes(responseText);
+  }
+  if (typeof body !== "object" || body === null) return void 0;
+  const record = body;
+  const message = typeof record.message === "string" ? record.message : "";
+  const space = byteCountsOf(record.space) ?? parseStorageQuotaBytes(message);
+  const isStorageBody = typeof record.error === "string" && STORAGE_REJECTION_BODY_ERRORS[record.error] === true;
+  if (!space && !isStorageBody) {
+    return void 0;
+  }
+  const details = { ...space };
+  const account = byteCountsOf(record.account);
+  if (account) {
+    const plan = record.account.plan;
+    details.account = typeof plan === "string" && plan !== "" ? { ...account, plan } : account;
+  }
+  return details;
+}
 function storageRejectionError(service, status, meta, responseText) {
-  const quotaMeta = { ...meta, ...parseStorageQuotaBytes(responseText) };
+  const quotaMeta = { ...meta, ...parseStorageRejection(responseText) };
   return status === 402 ? storageQuotaExceededError(service, STORAGE_FULL_MESSAGE, quotaMeta) : storageLimitReachedError(service, STORAGE_WRITE_TOO_LARGE_MESSAGE, quotaMeta);
 }
 function isStorageFullError(error) {
@@ -1973,7 +2018,7 @@ var KVService = class extends BaseService {
     if (response.status !== 402 && response.status !== 413) {
       return void 0;
     }
-    if (response.status === 413 && !parseStorageQuotaBytes(errorText)) {
+    if (response.status === 413 && !parseStorageRejection(errorText)) {
       return void 0;
     }
     return err(
@@ -3013,6 +3058,7 @@ var KVService = class extends BaseService {
           "kv"
         ));
       }
+      const requestPrefix = options.prefix === "/" ? "" : options.prefix;
       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;
@@ -3022,7 +3068,7 @@ var KVService = class extends BaseService {
       const request = this.createRequestSignal(options.signal, options.timeout);
       try {
         const response = await this.invokeOperation(
-          options.prefix,
+          requestPrefix,
           KVAction.SYNC,
           void 0,
           request.signal,
@@ -3038,7 +3084,7 @@ var KVService = class extends BaseService {
         } catch {
           body = void 0;
         }
-        const page = this.normalizeChangesResponse(body);
+        const page = this.normalizeChangesResponse(body, options.prefix);
         if (!page) {
           return err(serviceError(
             ErrorCodes.NETWORK_ERROR,
@@ -3118,7 +3164,7 @@ var KVService = class extends BaseService {
       { meta }
     ));
   }
-  normalizeChangesResponse(data) {
+  normalizeChangesResponse(data, requestedPrefix) {
     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)) {
@@ -3150,7 +3196,11 @@ var KVService = class extends BaseService {
       changes: parsed,
       more,
       cursor,
-      source: { nodeDid: source.nodeDid, space: source.space, prefix: source.prefix },
+      source: {
+        nodeDid: source.nodeDid,
+        space: source.space,
+        prefix: requestedPrefix === "/" && source.prefix === "" ? "/" : source.prefix
+      },
       authority: { notBefore, expiresAt, retainUntil }
     };
   }
@@ -3445,13 +3495,14 @@ ${canonical.space}
 ${canonical.principal}`;
 }
 
-// src/kv/replication/scope.ts
+// src/kv/replication/prefix.ts
 function kvPrefixCovers(prefix, key) {
-  if (prefix === "") return true;
-  if (prefix.endsWith("/")) return key.startsWith(prefix);
-  return key === prefix || key.startsWith(`${prefix}/`);
+  return prefix === "/" || key.startsWith(prefix);
 }
+
+// src/kv/replication/scope.ts
 function requiresSecretsOptIn(space, prefix) {
+  if (prefix === "/") return true;
   if (space === "secrets" || space.endsWith(":secrets")) return true;
   return prefix.split("/", 1)[0] === "vault";
 }
@@ -3890,6 +3941,9 @@ var SQLService = class extends BaseService {
     if (response.status === 402) {
       return err(storageRejectionError("sql", 402, meta, errorText));
     }
+    if (response.status === 413 && parseStorageRejection(errorText)) {
+      return err(storageRejectionError("sql", 413, meta, errorText));
+    }
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -4356,6 +4410,9 @@ var DuckDbService = class extends BaseService {
     if (response.status === 402) {
       return err(storageRejectionError("duckdb", 402, meta, errorText));
     }
+    if (response.status === 413 && parseStorageRejection(errorText)) {
+      return err(storageRejectionError("duckdb", 413, meta, errorText));
+    }
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -5417,6 +5474,122 @@ function parsedStringArrayField(value, key) {
   }
 }
 
+// src/storage/StorageFullMonitor.ts
+var StorageFullMonitor = class {
+  /**
+   * @param ownerOf Owner key of a space id. Spaces with one key share one
+   * storage budget. Defaults to the space id itself.
+   */
+  constructor(ownerOf = (spaceId) => spaceId) {
+    this.ownerOf = ownerOf;
+    /** First rejection per owner key; {@link UNKNOWN_OWNER} when the space was unknown. */
+    this.full = /* @__PURE__ */ new Map();
+    this.handlers = /* @__PURE__ */ new Set();
+  }
+  /** True while any owner's storage is known to be full. */
+  get isFull() {
+    return this.full.size > 0;
+  }
+  /** The rejection `storage.full` announced, until the episode ends. */
+  get rejection() {
+    return this.event;
+  }
+  /**
+   * True when a write to `spaceId`'s owner was rejected, or a write whose
+   * space was unknown was: that one could have been any owner's.
+   */
+  isFullFor(spaceId) {
+    return this.full.has(UNKNOWN_OWNER) || spaceId !== void 0 && this.full.has(this.ownerOf(spaceId));
+  }
+  /** Watch a context's service errors. Returns the unsubscribe function. */
+  observe(context) {
+    return context.on(TelemetryEvents.SERVICE_ERROR, (data) => {
+      const { service, error } = data;
+      if (!error || !isStorageFullError(error)) return;
+      const spaceId = context.session?.spaceId;
+      const owner = spaceId ? this.ownerOf(spaceId) : UNKNOWN_OWNER;
+      if (this.full.has(owner)) return;
+      const meta = error.meta ?? {};
+      const event = { service: service ?? error.service, error };
+      if (typeof meta.usedBytes === "number") event.usedBytes = meta.usedBytes;
+      if (typeof meta.limitBytes === "number") event.limitBytes = meta.limitBytes;
+      if (typeof meta.account === "object" && meta.account !== null) {
+        event.account = meta.account;
+      }
+      if (spaceId) event.spaceId = spaceId;
+      this.full.set(owner, event);
+      if (this.event) return;
+      this.event = event;
+      context.emit(TelemetryEvents.STORAGE_FULL, event);
+      for (const handler of this.handlers) {
+        try {
+          handler(event);
+        } catch (handlerError) {
+          console.error(`Error in "${TelemetryEvents.STORAGE_FULL}" handler:`, handlerError);
+        }
+      }
+    });
+  }
+  /** Subscribe to the `storage.full` event. Returns the unsubscribe function. */
+  on(handler) {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+  /** Forget that any owner's storage is full; the next rejection emits `storage.full` again. */
+  clear() {
+    this.full.clear();
+    this.event = void 0;
+  }
+  /**
+   * Forget that `spaceId`'s owner is full (`undefined`: the rejections whose
+   * space was unknown). Once no owner is full, the next rejection emits
+   * `storage.full` again.
+   */
+  clearFor(spaceId) {
+    this.full.delete(spaceId === void 0 ? UNKNOWN_OWNER : this.ownerOf(spaceId));
+    if (this.full.size === 0) this.event = void 0;
+  }
+};
+var UNKNOWN_OWNER = "\0unknown";
+
+// src/storage/status.ts
+var STORAGE_MANAGE_URL = "https://account.tinycloud.xyz/billing";
+var STORAGE_NEARLY_FULL_RATIO = 0.9;
+function storageUsageState(usedBytes, limitBytes) {
+  if (limitBytes === null) return "ok";
+  if (usedBytes >= limitBytes) return "full";
+  return usedBytes >= limitBytes * STORAGE_NEARLY_FULL_RATIO ? "nearly_full" : "ok";
+}
+function storageUsageOf(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const { usedBytes, limitBytes } = value;
+  const isByteCount2 = (n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+  if (!isByteCount2(usedBytes)) return void 0;
+  if (limitBytes !== null && !isByteCount2(limitBytes)) return void 0;
+  return { usedBytes, limitBytes };
+}
+function parseStorageStatus(body) {
+  if (typeof body !== "object" || body === null) return void 0;
+  const record = body;
+  const space = storageUsageOf(record.space);
+  if (!space) return void 0;
+  const status = {
+    ...space,
+    state: storageUsageState(space.usedBytes, space.limitBytes),
+    manageUrl: typeof record.manageUrl === "string" && record.manageUrl.startsWith("https://") ? record.manageUrl : STORAGE_MANAGE_URL
+  };
+  const account = storageUsageOf(record.account);
+  if (account) {
+    const plan = record.account.plan;
+    status.account = typeof plan === "string" && plan !== "" ? { ...account, plan } : account;
+    if (status.account.plan) status.plan = status.account.plan;
+    status.state = storageUsageState(account.usedBytes, account.limitBytes);
+  }
+  return status;
+}
+
 // src/quota/TinyCloudQuota.ts
 var TinyCloudQuota = class {
   constructor(config = {}) {
@@ -8220,6 +8393,8 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   SQLMigrations,
   SQLService,
   STORAGE_FULL_MESSAGE,
+  STORAGE_MANAGE_URL,
+  STORAGE_NEARLY_FULL_RATIO,
   STORAGE_WRITE_TOO_LARGE_MESSAGE,
   SecretsService,
   ServiceContext,
@@ -8229,6 +8404,7 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   ServiceResponseEventSchema,
   ServiceRetryEventSchema,
   ServiceSessionSchema,
+  StorageFullMonitor,
   TC832_RESERVED_SCOPES,
   TelemetryEvents,
   TelemetrySpanEventSchema,
@@ -8290,6 +8466,8 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   parsePermissionHintFromErrorText,
   parseSecretCatalogKey,
   parseStorageQuotaBytes,
+  parseStorageRejection,
+  parseStorageStatus,
   permissionDeniedError,
   replicationIdentityKey,
   requiresSecretsOptIn,
@@ -8299,6 +8477,7 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   storageLimitReachedError,
   storageQuotaExceededError,
   storageRejectionError,
+  storageUsageState,
   timeoutError,
   tinyCloudDebugLogger,
   utf8Decode,