@tinycloud/sdk-services 3.1.0-beta.1 → 3.1.0-beta.10

package/dist/sql/index.cjs

@@ -34,6 +34,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",
@@ -45,6 +49,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",
@@ -100,6 +108,7 @@ function serviceError(code, message, service, options) {
 }
 
 // src/errors.ts
+var import_bootstrap = require("@tinycloud/bootstrap");
 function authRequiredError(service) {
   return {
     code: ErrorCodes.AUTH_REQUIRED,
@@ -107,11 +116,31 @@ function authRequiredError(service) {
     service
   };
 }
-function timeoutError(service) {
+var RequestTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms.`);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+function isRequestTimeoutError(error) {
+  return error instanceof RequestTimeoutError || error instanceof Error && error.name === "TimeoutError" && typeof error.timeoutMs === "number";
+}
+function timeoutError(service, timeoutMs, cause) {
+  if (timeoutMs === void 0) {
+    return {
+      code: ErrorCodes.TIMEOUT,
+      message: "Request timed out.",
+      service,
+      ...cause === void 0 ? {} : { cause }
+    };
+  }
   return {
     code: ErrorCodes.TIMEOUT,
-    message: "Request timed out.",
-    service
+    message: `Request timed out after ${timeoutMs}ms.`,
+    service,
+    ...cause === void 0 ? {} : { cause },
+    meta: { timeoutMs }
   };
 }
 function abortedError(service) {
@@ -128,8 +157,47 @@ function parseAuthError(responseText) {
   }
   return {};
 }
+var grantableActions = new Set(
+  import_bootstrap.CAPABILITY_REGISTRY.map(({ urn }) => urn).filter((urn) => !urn.endsWith("/*"))
+);
+var capabilityServices = new Set(
+  import_bootstrap.CAPABILITY_REGISTRY.map(({ service }) => service.slice("tinycloud.".length))
+);
+function storageQuotaExceededError(service, message, meta) {
+  return {
+    code: ErrorCodes.STORAGE_QUOTA_EXCEEDED,
+    message,
+    service,
+    meta
+  };
+}
+function storageLimitReachedError(service, message, meta) {
+  return {
+    code: ErrorCodes.STORAGE_LIMIT_REACHED,
+    message,
+    service,
+    meta
+  };
+}
+var STORAGE_FULL_MESSAGE = "TinyCloud storage is full, so this change was not saved. Reading still works. Free up space or upgrade your plan to save again.";
+var STORAGE_WRITE_TOO_LARGE_MESSAGE = "This change is larger than the TinyCloud storage you have left, so it was not saved. Reading still works. Free up space or upgrade your plan to save it.";
+function parseStorageQuotaBytes(responseText) {
+  const match = responseText.match(/Used:\s*(\d+)\s*bytes,\s*Limit:\s*(\d+)\s*bytes/i);
+  if (!match) return void 0;
+  return {
+    usedBytes: parseInt(match[1], 10),
+    limitBytes: parseInt(match[2], 10)
+  };
+}
+function storageRejectionError(service, status, meta, responseText) {
+  const quotaMeta = { ...meta, ...parseStorageQuotaBytes(responseText) };
+  return status === 402 ? storageQuotaExceededError(service, STORAGE_FULL_MESSAGE, quotaMeta) : storageLimitReachedError(service, STORAGE_WRITE_TOO_LARGE_MESSAGE, quotaMeta);
+}
 function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
   if (error instanceof Error) {
+    if (isRequestTimeoutError(error)) {
+      return timeoutError(service, error.timeoutMs, error);
+    }
     if (error.name === "AbortError") {
       return abortedError(service);
     }
@@ -151,6 +219,7 @@ function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
 }
 
 // src/base/BaseService.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
 var BaseService = class {
   constructor() {
     /**
@@ -331,6 +400,64 @@ var BaseService = class {
     }
     return controller.signal;
   }
+  /**
+   * Create the abort signal for one request, bounded by the request timeout.
+   *
+   * The signal aborts when the service signs out, the context aborts, the
+   * caller's `signal` aborts, or the timeout elapses, whichever comes first.
+   * A timeout aborts with a {@link RequestTimeoutError} (`TimeoutError`), which
+   * `wrapError` maps to `ErrorCodes.TIMEOUT`; the other sources keep their own
+   * reason (normally `AbortError`, mapped to `ErrorCodes.ABORTED`).
+   *
+   * The timeout is `timeoutMs` when given, otherwise `config.timeout`. Only a
+   * positive, finite value (at most 2^31-1 ms) applies; `undefined`, `0`, and
+   * `Infinity` mean no timeout, so a per-call `0` opts out of a configured one.
+   *
+   * Callers must call `dispose()` once the response body has been consumed,
+   * which clears the timer and removes the listeners this adds to the
+   * long-lived service and context signals.
+   *
+   * @param signal - The caller's abort signal for this request
+   * @param timeoutMs - Per-request timeout override in milliseconds
+   */
+  createRequestSignal(signal, timeoutMs) {
+    const controller = new AbortController();
+    const detachers = [];
+    let timer;
+    const dispose = () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      for (const detach of detachers.splice(0)) {
+        detach();
+      }
+    };
+    const abort = (reason) => {
+      dispose();
+      controller.abort(reason);
+    };
+    const requestSignal = { signal: controller.signal, dispose };
+    const parents = [
+      this.abortController.signal,
+      this.context?.abortSignal,
+      signal
+    ].filter((parent) => parent !== void 0);
+    for (const parent of parents) {
+      if (parent.aborted) {
+        abort(parent.reason);
+        return requestSignal;
+      }
+      const onAbort = () => abort(parent.reason);
+      parent.addEventListener("abort", onAbort, { once: true });
+      detachers.push(() => parent.removeEventListener("abort", onAbort));
+    }
+    const timeout = timeoutMs ?? this._config.timeout;
+    if (typeof timeout === "number" && timeout > 0 && timeout <= MAX_TIMER_DELAY_MS) {
+      timer = setTimeout(() => abort(new RequestTimeoutError(timeout)), timeout);
+    }
+    return requestSignal;
+  }
   /**
    * Wrap an operation with error handling and telemetry.
    *
@@ -432,16 +559,16 @@ var DatabaseHandle = class {
 };
 
 // src/sql/types.ts
-var import_bootstrap = require("@tinycloud/bootstrap");
+var import_bootstrap2 = require("@tinycloud/bootstrap");
 var SQLAction = {
-  READ: import_bootstrap.SQL.READ,
-  WRITE: import_bootstrap.SQL.WRITE,
-  SCHEMA: import_bootstrap.SQL.SCHEMA,
-  ADMIN: import_bootstrap.SQL.ADMIN,
-  SELECT: import_bootstrap.SQL.SELECT,
-  EXECUTE: import_bootstrap.SQL.EXECUTE,
-  EXPORT: import_bootstrap.SQL.EXPORT,
-  ALL: import_bootstrap.SQL.ALL
+  READ: import_bootstrap2.SQL.READ,
+  WRITE: import_bootstrap2.SQL.WRITE,
+  SCHEMA: import_bootstrap2.SQL.SCHEMA,
+  ADMIN: import_bootstrap2.SQL.ADMIN,
+  SELECT: import_bootstrap2.SQL.SELECT,
+  EXECUTE: import_bootstrap2.SQL.EXECUTE,
+  EXPORT: import_bootstrap2.SQL.EXPORT,
+  ALL: import_bootstrap2.SQL.ALL
 };
 
 // src/sql/SQLService.ts
@@ -519,6 +646,7 @@ var SQLService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("sql"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const body = {
           action: "query",
@@ -527,19 +655,22 @@ var SQLService = class extends BaseService {
         };
         if (options?.maxRows !== void 0) body.maxRows = options.maxRows;
         if (options?.maxBytes !== void 0) body.maxBytes = options.maxBytes;
+        const action = this.actionForSql(sql, SQLAction.READ);
         const response = await this.invokeSQL(
           dbName,
-          this.actionForSql(sql, SQLAction.READ),
+          action,
           body,
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "query");
+          return this.handleErrorResponse(response, "query", dbName, [action]);
         }
         const data = await response.json();
         return ok(data);
       } catch (error) {
         return err(wrapError("sql", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -548,6 +679,7 @@ var SQLService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("sql"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const body = {
           action: "execute",
@@ -563,19 +695,22 @@ var SQLService = class extends BaseService {
             (statement) => this.actionForSql(statement, SQLAction.SCHEMA)
           )
         ];
+        const requestedActions = this.dedupeActions(actions);
         const response = await this.invokeSQL(
           dbName,
-          this.dedupeActions(actions),
+          requestedActions,
           body,
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "execute");
+          return this.handleErrorResponse(response, "execute", dbName, requestedActions);
         }
         const data = await response.json();
         return ok(data);
       } catch (error) {
         return err(wrapError("sql", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -584,20 +719,24 @@ var SQLService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("sql"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
+        const requestedActions = this.actionsForSqlBatch(statements);
         const response = await this.invokeSQL(
           dbName,
-          this.actionsForSqlBatch(statements),
+          requestedActions,
           { action: "batch", statements },
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "batch");
+          return this.handleErrorResponse(response, "batch", dbName, requestedActions);
         }
         const data = await response.json();
         return ok(data);
       } catch (error) {
         return err(wrapError("sql", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -606,20 +745,23 @@ var SQLService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("sql"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const response = await this.invokeSQL(
           dbName,
           SQLAction.WRITE,
           { action: "execute_statement", name, params: params ?? [] },
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "executeStatement");
+          return this.handleErrorResponse(response, "executeStatement", dbName, [SQLAction.WRITE]);
         }
         const data = await response.json();
         return ok(data);
       } catch (error) {
         return err(wrapError("sql", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -628,15 +770,16 @@ var SQLService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("sql"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const response = await this.invokeSQL(
           dbName,
           SQLAction.READ,
           { action: "export" },
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "export");
+          return this.handleErrorResponse(response, "export", dbName, [SQLAction.READ]);
         }
         const resp = response;
         if (typeof resp.blob === "function") {
@@ -647,26 +790,31 @@ var SQLService = class extends BaseService {
         return ok(text);
       } catch (error) {
         return err(wrapError("sql", error));
+      } finally {
+        request.dispose();
       }
     });
   }
   async applyMigrationsOnDbUnlocked(dbName, options) {
     return this.withTelemetry("migrations.apply", dbName, async () => {
-      const created = await this.ensureMigrationsTable(dbName, options.signal);
-      if (!created.ok) return created;
       const listed = await this.queryOnDb(
         dbName,
         `SELECT id FROM ${MIGRATIONS_TABLE} WHERE namespace = ? ORDER BY applied_at, id`,
         [options.namespace],
         { signal: options.signal }
       );
-      if (!listed.ok) return listed;
+      const tableMissing = !listed.ok && (listed.error.code === ErrorCodes.SQL_DATABASE_NOT_FOUND || isMissingTableError(listed.error.message));
+      if (!listed.ok && !tableMissing) return listed;
       const appliedIds = new Set(
-        listed.data.rows.map((row) => rowValue(row, 0)).filter((id) => typeof id === "string")
+        (listed.ok ? listed.data.rows : []).map((row) => rowValue(row, 0)).filter((id) => typeof id === "string")
       );
       const skipped = options.migrations.filter((migration) => appliedIds.has(migration.id)).map((migration) => migration.id);
       const pending = options.migrations.filter((migration) => !appliedIds.has(migration.id));
       const applied = [];
+      if (pending.length > 0 && tableMissing) {
+        const created = await this.ensureMigrationsTable(dbName, options.signal);
+        if (!created.ok) return created;
+      }
       for (const migration of pending) {
         const result = await this.applyOneMigration(dbName, options.namespace, migration, options.signal);
         if (!result.ok) return result;
@@ -734,7 +882,7 @@ var SQLService = class extends BaseService {
         "Content-Type": "application/json"
       },
       body: JSON.stringify(body),
-      signal: this.combineSignals(signal)
+      signal
     });
   }
   actionForSql(sql, fallback) {
@@ -767,8 +915,12 @@ var SQLService = class extends BaseService {
       }))
     );
   }
-  async handleErrorResponse(response, operation) {
+  async handleErrorResponse(response, operation, dbName, requestedActions) {
     const errorText = await response.text();
+    const meta = responseErrorMeta(response.status, response.statusText, errorText);
+    if (response.status === 402) {
+      return err(storageRejectionError("sql", 402, meta, errorText));
+    }
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -781,11 +933,12 @@ var SQLService = class extends BaseService {
       errorText,
       errorBody
     );
-    const meta = responseErrorMeta(response.status, response.statusText, errorText);
     if (response.status === 401) {
-      const { resource, action } = parseAuthError(errorText);
-      if (action) meta.requiredAction = action;
-      if (resource) meta.resource = resource;
+      const { action } = parseAuthError(errorText);
+      if (action && requestedActions.includes(action)) {
+        meta.requiredAction = action;
+        meta.resource = `${this.context.session.spaceId}/sql/${dbName}`;
+      }
     }
     return err(
       serviceError(errorCode, message, "sql", { meta })
@@ -882,6 +1035,9 @@ function serializeSqlValues(values) {
     (value) => value instanceof Uint8Array ? Array.from(value) : value
   );
 }
+function isMissingTableError(message) {
+  return /no such table/i.test(message);
+}
 function migrationKey(namespace, id) {
   return `${encodeURIComponent(namespace)}:${encodeURIComponent(id)}`;
 }