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

package/dist/{types-BjH0ZtGy.d.cts → types-eVS1Whuf.d.cts}

@@ -81,7 +81,7 @@ declare const ErrorCodes: {
     readonly ABORTED: "ABORTED";
     readonly INVALID_INPUT: "INVALID_INPUT";
     readonly PERMISSION_DENIED: "PERMISSION_DENIED";
-    /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`: nothing was applied; retry after `meta.retryAfterMs`. */
+    /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`/`read_audit_busy`: nothing was applied; retry after `meta.retryAfterMs`. */
     readonly NODE_BUSY: "NODE_BUSY";
     /** HTTP 503 `request_timeout`: the node's deadline passed before any write began; nothing was applied. */
     readonly REQUEST_TIMEOUT: "REQUEST_TIMEOUT";
@@ -211,6 +211,17 @@ interface FetchResponse {
     text(): Promise<string>;
     arrayBuffer(): Promise<ArrayBuffer>;
     blob(): Promise<Blob>;
+    /** Present on standard Responses; the retry reads a clone so the caller's body stays intact. */
+    clone?(): FetchResponse;
+    /** Set by `ServiceContext.invokeWithRetry` on the response it returns: how many requests it took. */
+    retry?: RetryStats;
+}
+/** What automatic retry cost one request, so latency can be split from backoff. */
+interface RetryStats {
+    /** Requests sent, including the first (1 means no retry). */
+    attempts: number;
+    /** Total milliseconds spent waiting between attempts. */
+    backoffMs: number;
 }
 /**
  * Fetch function signature - allows for custom fetch implementations.
@@ -218,7 +229,12 @@ interface FetchResponse {
  */
 type FetchFunction = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>;
 /**
- * Configuration for automatic retry of failed requests.
+ * Automatic retry of node responses that guarantee nothing was applied
+ * (`NODE_BUSY`, `REQUEST_TIMEOUT`). Applied once, in the service context's
+ * `invokeWithRetry`, which re-mints the signed invocation per attempt. Backoff
+ * is full-jitter: each delay is uniform in `[0, step]`, where
+ * `step` is the strategy's delay capped at `maxDelayMs`. A node `Retry-After`
+ * replaces the delay. Opt out with `{ maxAttempts: 1 }`.
  */
 interface RetryPolicy {
     /** Maximum number of attempts (including initial) */
@@ -229,8 +245,10 @@ interface RetryPolicy {
     baseDelayMs: number;
     /** Maximum delay in milliseconds between retries */
     maxDelayMs: number;
-    /** Error codes that should trigger a retry */
+    /** Node error codes that trigger a retry. `OUTCOME_UNKNOWN` is never retried. */
     retryableErrors: string[];
+    /** Total time budget for all attempts and waits, in milliseconds. Unset: no cap. */
+    maxTotalMs?: number;
 }
 /**
  * Default retry policy.
@@ -279,6 +297,8 @@ interface IServiceContext {
     readonly invokeAny?: InvokeAnyFunction;
     /** Fetch function (defaults to globalThis.fetch) */
     readonly fetch: FetchFunction;
+    /** Send a signed invocation, retrying a busy node; `build` re-signs per attempt. Absent: sends once. */
+    invokeWithRetry?(url: string, build: () => FetchRequestInit | Promise<FetchRequestInit>): Promise<FetchResponse>;
     /** Available TinyCloud host URLs */
     readonly hosts: string[];
     /** Get another registered service by name */
@@ -384,4 +404,4 @@ declare function serviceError(code: string, message: string, service: string, op
     meta?: Record<string, unknown>;
 }): ServiceError;
 
-export { type EventHandler as E, type FetchFunction as F, type IService as I, type PermissionHint as P, type Result as R, type ServiceSession as S, type TelemetryConfig as T, type IServiceContext as a, type ServiceError as b, type InvokeFunction as c, type InvokeAnyFunction as d, type RetryPolicy as e, type StorageQuotaInfo as f, type ErrorCode as g, ErrorCodes as h, type FetchRequestInit as i, type FetchResponse as j, type InvocationFact as k, type InvocationFacts as l, type InvokeAnyEntry as m, type ServiceErrorEvent as n, type ServiceHeaders as o, type ServiceRequestEvent as p, type ServiceResponseEvent as q, type ServiceRetryEvent as r, type TelemetryEventHandler as s, TelemetryEvents as t, type TelemetrySpanEvent as u, defaultRetryPolicy as v, err as w, ok as x, serviceError as y };
+export { type EventHandler as E, type FetchRequestInit as F, type IService as I, type PermissionHint as P, type Result as R, type ServiceSession as S, type TelemetryConfig as T, type IServiceContext as a, type ServiceError as b, type ServiceHeaders as c, type FetchResponse as d, type RetryStats as e, type FetchFunction as f, type InvokeFunction as g, type InvokeAnyFunction as h, type RetryPolicy as i, type StorageQuotaInfo as j, type ErrorCode as k, ErrorCodes as l, type InvocationFact as m, type InvocationFacts as n, type InvokeAnyEntry as o, type ServiceErrorEvent as p, type ServiceRequestEvent as q, type ServiceResponseEvent as r, type ServiceRetryEvent as s, type TelemetryEventHandler as t, TelemetryEvents as u, type TelemetrySpanEvent as v, defaultRetryPolicy as w, err as x, ok as y, serviceError as z };

package/dist/{types-BjH0ZtGy.d.ts → types-eVS1Whuf.d.ts}

@@ -81,7 +81,7 @@ declare const ErrorCodes: {
     readonly ABORTED: "ABORTED";
     readonly INVALID_INPUT: "INVALID_INPUT";
     readonly PERMISSION_DENIED: "PERMISSION_DENIED";
-    /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`: nothing was applied; retry after `meta.retryAfterMs`. */
+    /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`/`read_audit_busy`: nothing was applied; retry after `meta.retryAfterMs`. */
     readonly NODE_BUSY: "NODE_BUSY";
     /** HTTP 503 `request_timeout`: the node's deadline passed before any write began; nothing was applied. */
     readonly REQUEST_TIMEOUT: "REQUEST_TIMEOUT";
@@ -211,6 +211,17 @@ interface FetchResponse {
     text(): Promise<string>;
     arrayBuffer(): Promise<ArrayBuffer>;
     blob(): Promise<Blob>;
+    /** Present on standard Responses; the retry reads a clone so the caller's body stays intact. */
+    clone?(): FetchResponse;
+    /** Set by `ServiceContext.invokeWithRetry` on the response it returns: how many requests it took. */
+    retry?: RetryStats;
+}
+/** What automatic retry cost one request, so latency can be split from backoff. */
+interface RetryStats {
+    /** Requests sent, including the first (1 means no retry). */
+    attempts: number;
+    /** Total milliseconds spent waiting between attempts. */
+    backoffMs: number;
 }
 /**
  * Fetch function signature - allows for custom fetch implementations.
@@ -218,7 +229,12 @@ interface FetchResponse {
  */
 type FetchFunction = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>;
 /**
- * Configuration for automatic retry of failed requests.
+ * Automatic retry of node responses that guarantee nothing was applied
+ * (`NODE_BUSY`, `REQUEST_TIMEOUT`). Applied once, in the service context's
+ * `invokeWithRetry`, which re-mints the signed invocation per attempt. Backoff
+ * is full-jitter: each delay is uniform in `[0, step]`, where
+ * `step` is the strategy's delay capped at `maxDelayMs`. A node `Retry-After`
+ * replaces the delay. Opt out with `{ maxAttempts: 1 }`.
  */
 interface RetryPolicy {
     /** Maximum number of attempts (including initial) */
@@ -229,8 +245,10 @@ interface RetryPolicy {
     baseDelayMs: number;
     /** Maximum delay in milliseconds between retries */
     maxDelayMs: number;
-    /** Error codes that should trigger a retry */
+    /** Node error codes that trigger a retry. `OUTCOME_UNKNOWN` is never retried. */
     retryableErrors: string[];
+    /** Total time budget for all attempts and waits, in milliseconds. Unset: no cap. */
+    maxTotalMs?: number;
 }
 /**
  * Default retry policy.
@@ -279,6 +297,8 @@ interface IServiceContext {
     readonly invokeAny?: InvokeAnyFunction;
     /** Fetch function (defaults to globalThis.fetch) */
     readonly fetch: FetchFunction;
+    /** Send a signed invocation, retrying a busy node; `build` re-signs per attempt. Absent: sends once. */
+    invokeWithRetry?(url: string, build: () => FetchRequestInit | Promise<FetchRequestInit>): Promise<FetchResponse>;
     /** Available TinyCloud host URLs */
     readonly hosts: string[];
     /** Get another registered service by name */
@@ -384,4 +404,4 @@ declare function serviceError(code: string, message: string, service: string, op
     meta?: Record<string, unknown>;
 }): ServiceError;
 
-export { type EventHandler as E, type FetchFunction as F, type IService as I, type PermissionHint as P, type Result as R, type ServiceSession as S, type TelemetryConfig as T, type IServiceContext as a, type ServiceError as b, type InvokeFunction as c, type InvokeAnyFunction as d, type RetryPolicy as e, type StorageQuotaInfo as f, type ErrorCode as g, ErrorCodes as h, type FetchRequestInit as i, type FetchResponse as j, type InvocationFact as k, type InvocationFacts as l, type InvokeAnyEntry as m, type ServiceErrorEvent as n, type ServiceHeaders as o, type ServiceRequestEvent as p, type ServiceResponseEvent as q, type ServiceRetryEvent as r, type TelemetryEventHandler as s, TelemetryEvents as t, type TelemetrySpanEvent as u, defaultRetryPolicy as v, err as w, ok as x, serviceError as y };
+export { type EventHandler as E, type FetchRequestInit as F, type IService as I, type PermissionHint as P, type Result as R, type ServiceSession as S, type TelemetryConfig as T, type IServiceContext as a, type ServiceError as b, type ServiceHeaders as c, type FetchResponse as d, type RetryStats as e, type FetchFunction as f, type InvokeFunction as g, type InvokeAnyFunction as h, type RetryPolicy as i, type StorageQuotaInfo as j, type ErrorCode as k, ErrorCodes as l, type InvocationFact as m, type InvocationFacts as n, type InvokeAnyEntry as o, type ServiceErrorEvent as p, type ServiceRequestEvent as q, type ServiceResponseEvent as r, type ServiceRetryEvent as s, type TelemetryEventHandler as t, TelemetryEvents as u, type TelemetrySpanEvent as v, defaultRetryPolicy as w, err as x, ok as y, serviceError as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinycloud/sdk-services",
-  "version": "3.3.0-beta.7",
+  "version": "3.3.0",
   "description": "TinyCloud SDK Services - Platform-agnostic service implementations",
   "author": "TinyCloud, Inc.",
   "license": "EGPL",
@@ -139,7 +139,7 @@
   },
   "devDependencies": {
     "@types/node": "^20",
-    "@tinycloud/node-sdk-wasm": "1.7.7",
+    "@tinycloud/node-sdk-wasm": "1.7.8",
     "tsup": "^8.0.0",
     "typescript": "^5.9.3"
   },