@tinycloud/sdk-services 3.2.6-beta.2 → 3.3.0-beta.7

package/dist/kv/index.d.cts

@@ -1,8 +1,11 @@
-import { B as BaseService } from '../BaseService-4wwJq1Gn.cjs';
-import { R as Result, I as IService } from '../types-D-9A3Sut.cjs';
-import { Y as KVGetOptions, a1 as KVResponse, Q as KVBatchReadResponse, a0 as KVPutOptions, M as KVBatchPutItem, N as KVBatchPutOptions, O as KVBatchPutResponse, _ as KVListOptions, $ as KVListResponse, U as KVChangesOptions, V as KVChangesResponse, X as KVDeleteOptions, Z as KVHeadOptions, W as KVCreateSignedReadUrlOptions, a4 as KVSignedReadUrlResponse, a3 as KVServiceConfig, c as KVReadThrough } from '../scope-D7wmjbMH.cjs';
-export { A as AuthorityRefusal, C as CLEAR_PENDING_WARNING, H as DEFAULT_SIGNED_READ_URL_EXPIRY_MS, I as KVAction, J as KVActionType, S as KVChange, T as KVChangesAuthority, b as KVListPage, d as KVReplicaHandle, e as KVReplicaSpec, f as KVReplicaStorage, a as KVReplicationController, K as KVReplicationDeps, a2 as KVResponseHeaders, L as LocalGetResult, g as LocalListResult, h as LocalReadMeta, i as LocalReplicaStatus, j as LocalSyncResult, k as PendingWriteRecord, l as PendingWriteState, P as PendingWriteStore, m as PinnedKey, n as PurgeTarget, o as ReplicaAuthorityState, p as ReplicaCoverage, q as ReplicaDevice, r as ReplicaGrantInfo, s as ReplicaState, t as ReplicaStatusEntry, u as ReplicationAuthority, v as ReplicationControl, w as ReplicationEvent, R as ReplicationIdentity, x as ReplicationOptions, y as ReplicationPurgeReport, z as ReplicationReason, B as ReplicationScheduler, D as ResolvedReplicationOptions, E as canonicalReplicationIdentity, F as replicationIdentityKey, G as requiresSecretsOptIn } from '../scope-D7wmjbMH.cjs';
+import { B as BaseService } from '../BaseService-Cc6Ueicm.cjs';
+import { R as Result, I as IService } from '../types-BjH0ZtGy.cjs';
+import { aD as KVGetOptions, aI as KVResponse, aw as KVBatchReadResponse, aH as KVPutOptions, at as KVBatchPutItem, au as KVBatchPutOptions, av as KVBatchPutResponse, aF as KVListOptions, aG as KVListResponse, az as KVChangesOptions, aA as KVChangesResponse, aC as KVDeleteOptions, aE as KVHeadOptions, aB as KVCreateSignedReadUrlOptions, aL as KVSignedReadUrlResponse, aK as KVServiceConfig, c as KVReadThrough } from '../scope-B7oeKdLM.cjs';
+export { A as AuthorityRefusal, C as CLEAR_PENDING_WARNING, aq as DEFAULT_SIGNED_READ_URL_EXPIRY_MS, ar as KVAction, as as KVActionType, ax as KVChange, ay as KVChangesAuthority, b as KVListPage, d as KVReplicaHandle, e as KVReplicaSpec, f as KVReplicaStorage, a as KVReplicationController, K as KVReplicationDeps, aJ as KVResponseHeaders, L as LocalGetResult, g as LocalListResult, h as LocalReadMeta, i as LocalReplicaStatus, j as LocalSyncResult, k as PendingWriteRecord, l as PendingWriteState, P as PendingWriteStore, m as PinnedKey, w as PurgeTarget, z as ReplicaAuthorityState, H as ReplicaCoverage, N as ReplicaDevice, X as ReplicaGatedHandle, _ as ReplicaGrantInfo, a0 as ReplicaInspectedStatus, ac as ReplicaState, ad as ReplicaStatusEntry, ae as ReplicationAuthority, af as ReplicationControl, ag as ReplicationEvent, R as ReplicationIdentity, ah as ReplicationOptions, ai as ReplicationPurgeReport, aj as ReplicationReason, ak as ReplicationScheduler, al as ResolvedReplicationOptions, an as canonicalReplicationIdentity, ao as replicationIdentityKey, ap as requiresSecretsOptIn } from '../scope-B7oeKdLM.cjs';
 export { kvPrefixCovers } from './replication/prefix.cjs';
+import './replication/contractConstants.cjs';
+import './replication/grantPolicyConstants.cjs';
+import './replication/grantPolicyTypes.cjs';
 
 /**
  * PrefixedKVService - A prefix-scoped view of KVService.

package/dist/kv/index.d.ts

@@ -1,8 +1,11 @@
-import { B as BaseService } from '../BaseService-BGr2slUz.js';
-import { R as Result, I as IService } from '../types-D-9A3Sut.js';
-import { Y as KVGetOptions, a1 as KVResponse, Q as KVBatchReadResponse, a0 as KVPutOptions, M as KVBatchPutItem, N as KVBatchPutOptions, O as KVBatchPutResponse, _ as KVListOptions, $ as KVListResponse, U as KVChangesOptions, V as KVChangesResponse, X as KVDeleteOptions, Z as KVHeadOptions, W as KVCreateSignedReadUrlOptions, a4 as KVSignedReadUrlResponse, a3 as KVServiceConfig, c as KVReadThrough } from '../scope-CoKKmMiI.js';
-export { A as AuthorityRefusal, C as CLEAR_PENDING_WARNING, H as DEFAULT_SIGNED_READ_URL_EXPIRY_MS, I as KVAction, J as KVActionType, S as KVChange, T as KVChangesAuthority, b as KVListPage, d as KVReplicaHandle, e as KVReplicaSpec, f as KVReplicaStorage, a as KVReplicationController, K as KVReplicationDeps, a2 as KVResponseHeaders, L as LocalGetResult, g as LocalListResult, h as LocalReadMeta, i as LocalReplicaStatus, j as LocalSyncResult, k as PendingWriteRecord, l as PendingWriteState, P as PendingWriteStore, m as PinnedKey, n as PurgeTarget, o as ReplicaAuthorityState, p as ReplicaCoverage, q as ReplicaDevice, r as ReplicaGrantInfo, s as ReplicaState, t as ReplicaStatusEntry, u as ReplicationAuthority, v as ReplicationControl, w as ReplicationEvent, R as ReplicationIdentity, x as ReplicationOptions, y as ReplicationPurgeReport, z as ReplicationReason, B as ReplicationScheduler, D as ResolvedReplicationOptions, E as canonicalReplicationIdentity, F as replicationIdentityKey, G as requiresSecretsOptIn } from '../scope-CoKKmMiI.js';
+import { B as BaseService } from '../BaseService-DOdXd7sr.js';
+import { R as Result, I as IService } from '../types-BjH0ZtGy.js';
+import { aD as KVGetOptions, aI as KVResponse, aw as KVBatchReadResponse, aH as KVPutOptions, at as KVBatchPutItem, au as KVBatchPutOptions, av as KVBatchPutResponse, aF as KVListOptions, aG as KVListResponse, az as KVChangesOptions, aA as KVChangesResponse, aC as KVDeleteOptions, aE as KVHeadOptions, aB as KVCreateSignedReadUrlOptions, aL as KVSignedReadUrlResponse, aK as KVServiceConfig, c as KVReadThrough } from '../scope-B-m6cKH-.js';
+export { A as AuthorityRefusal, C as CLEAR_PENDING_WARNING, aq as DEFAULT_SIGNED_READ_URL_EXPIRY_MS, ar as KVAction, as as KVActionType, ax as KVChange, ay as KVChangesAuthority, b as KVListPage, d as KVReplicaHandle, e as KVReplicaSpec, f as KVReplicaStorage, a as KVReplicationController, K as KVReplicationDeps, aJ as KVResponseHeaders, L as LocalGetResult, g as LocalListResult, h as LocalReadMeta, i as LocalReplicaStatus, j as LocalSyncResult, k as PendingWriteRecord, l as PendingWriteState, P as PendingWriteStore, m as PinnedKey, w as PurgeTarget, z as ReplicaAuthorityState, H as ReplicaCoverage, N as ReplicaDevice, X as ReplicaGatedHandle, _ as ReplicaGrantInfo, a0 as ReplicaInspectedStatus, ac as ReplicaState, ad as ReplicaStatusEntry, ae as ReplicationAuthority, af as ReplicationControl, ag as ReplicationEvent, R as ReplicationIdentity, ah as ReplicationOptions, ai as ReplicationPurgeReport, aj as ReplicationReason, ak as ReplicationScheduler, al as ResolvedReplicationOptions, an as canonicalReplicationIdentity, ao as replicationIdentityKey, ap as requiresSecretsOptIn } from '../scope-B-m6cKH-.js';
 export { kvPrefixCovers } from './replication/prefix.js';
+import './replication/contractConstants.js';
+import './replication/grantPolicyConstants.js';
+import './replication/grantPolicyTypes.js';
 
 /**
  * PrefixedKVService - A prefix-scoped view of KVService.

package/dist/kv/index.js

@@ -14,6 +14,14 @@ var ErrorCodes = {
   ABORTED: "ABORTED",
   INVALID_INPUT: "INVALID_INPUT",
   PERMISSION_DENIED: "PERMISSION_DENIED",
+  // Node retry signals (tinycloud-node #347). `meta.retryable` says whether a
+  // retry is safe; `meta.retryAfterMs` carries the node's Retry-After.
+  /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`: nothing was applied; retry after `meta.retryAfterMs`. */
+  NODE_BUSY: "NODE_BUSY",
+  /** HTTP 503 `request_timeout`: the node's deadline passed before any write began; nothing was applied. */
+  REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
+  /** HTTP 500 `outcome_unknown`: a write may have been applied; read back before retrying a non-idempotent operation. */
+  OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN",
   // KV-specific errors
   KV_NOT_FOUND: "KV_NOT_FOUND",
   KV_WRITE_FAILED: "KV_WRITE_FAILED",
@@ -68,6 +76,8 @@ var TelemetryEvents = {
   REPLICATION_SYNC: "replication.sync",
   REPLICATION_STATE: "replication.state",
   REPLICATION_DIVERGENCE: "replication.divergence",
+  REPLICATION_GRANT: "replication.grant",
+  REPLICATION_LIFECYCLE: "replication.lifecycle",
   /** Emitted once, on the first write rejected because storage is full. */
   STORAGE_FULL: "storage.full"
 };
@@ -87,6 +97,20 @@ function serviceError(code, message, service, options) {
   };
 }
 
+// src/responseErrors.ts
+function responseErrorMeta(status, statusText, errorText) {
+  const meta = { status, statusText };
+  const snippet = compactMessage(errorText);
+  if (snippet) {
+    meta.responseSnippet = snippet.slice(0, 300);
+  }
+  return meta;
+}
+function compactMessage(message) {
+  const compact = message.replace(/\s+/g, " ").trim();
+  return compact.length > 500 ? `${compact.slice(0, 500)}...` : compact;
+}
+
 // src/errors.ts
 import { CAPABILITY_REGISTRY } from "@tinycloud/bootstrap";
 
@@ -180,6 +204,30 @@ function authRequiredError(service) {
     service
   };
 }
+function nodeRetryError(service, message, response, errorText) {
+  const body = errorText.trim();
+  const [, token, stage] = /^([a-z_]+)(?::\s*([a-z_]+):)?/.exec(body) ?? [];
+  let code;
+  if (response.status === 503 && (token === "sql_busy" || token === "unavailable_retryable")) {
+    code = ErrorCodes.NODE_BUSY;
+  } else if (response.status === 503 && token === "request_timeout") {
+    code = ErrorCodes.REQUEST_TIMEOUT;
+  } else if (response.status === 500 && token === "outcome_unknown") {
+    code = ErrorCodes.OUTCOME_UNKNOWN;
+  } else {
+    return void 0;
+  }
+  const retryable = code !== ErrorCodes.OUTCOME_UNKNOWN;
+  const retryAfter = response.headers.get("retry-after")?.trim();
+  return serviceError(code, message, service, {
+    meta: {
+      ...responseErrorMeta(response.status, response.statusText, errorText),
+      retryable,
+      ...token === "sql_busy" && stage ? { stage } : {},
+      ...retryable && retryAfter && /^\d{1,9}$/.test(retryAfter) ? { retryAfterMs: Number(retryAfter) * 1e3 } : {}
+    }
+  });
+}
 var RequestTimeoutError = class extends Error {
   constructor(timeoutMs) {
     super(`Request timed out after ${timeoutMs}ms.`);
@@ -1498,9 +1546,12 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
+      const message = `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -1582,19 +1633,14 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
-      if (response.status === 503 && (options?.ifMatch !== void 0 || options?.ifNoneMatch !== void 0)) {
-        return err(serviceError(
-          ErrorCodes.KV_CONFLICT,
-          `Concurrent KV update conflicted for key ${JSON.stringify(key)}`,
-          "kv",
-          { meta: { status: response.status, statusText: response.statusText } }
-        ));
-      }
+      const message = `Failed to put key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       const quotaError = this.handleQuotaErrorResponse(response, errorText, key);
       if (quotaError) return quotaError;
       return err(serviceError(
         ErrorCodes.KV_WRITE_FAILED,
-        `Failed to put key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -1894,9 +1940,12 @@ var KVService = class extends BaseService {
         );
       }
       const errorText = await response.text();
+      const message = `Failed to list keys: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to list keys: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -2147,17 +2196,12 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
-      if (response.status === 503 && options?.ifMatch !== void 0) {
-        return err(serviceError(
-          ErrorCodes.KV_CONFLICT,
-          `Concurrent KV delete conflicted for key ${JSON.stringify(key)}`,
-          "kv",
-          { meta: { status: response.status, statusText: response.statusText } }
-        ));
-      }
+      const message = `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -2198,10 +2242,13 @@ var KVService = class extends BaseService {
             return await this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
+          const message = `Failed to get metadata for key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+          const retryError = nodeRetryError("kv", message, response, errorText);
+          if (retryError) return err(retryError);
           return err(
             serviceError(
               ErrorCodes.NETWORK_ERROR,
-              `Failed to get metadata for key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+              message,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             )