@zapier/kitcore 0.17.2 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @zapier/kitcore
 
+## 0.19.0
+
+### Minor Changes
+
+- 1ec9410: Added `RetryHttpRequestOptions.onRetry` and exported `RetryHttpRequestAttempt` for observing retries scheduled by `retryHttpRequestPlugin`. The callback runs before the retry wait and receives the request, operation ID, failed attempt number, selected delay, and response or error. Promise results are not awaited, and thrown errors or rejected promises do not cancel the retry. When a response is present, read only its status and headers.
+
+### Patch Changes
+
+- 1ec9410: `retryHttpRequestPlugin` now waits at least 100 milliseconds before retrying when generated backoff is capped by a zero or near-zero `maxDelayMilliseconds`. Use `maxAttempts: 1` to disable retries.
+
+## 0.18.0
+
+### Minor Changes
+
+- 2c8ea56: **Added `httpFetchPluginRef` (`kitcore/httpFetch`), the function
+  `dispatchHttpRequest` calls to reach the network.** Provide it and the default
+  dispatch stage calls that function instead of the ambient `fetch` — a
+  debug-wrapped fetch, a test double, a polyfill. Provide nothing and the stage
+  behaves as before.
+
+  ```ts
+  const httpFetch = defineProperty({
+    namespace: "kitcore",
+    name: "httpFetch",
+    value: myFetch,
+  });
+
+  // Or supply it by id, with no plugin of your own:
+  createSdk(root, { configuration: { [HTTP_FETCH_ID]: myFetch } });
+  ```
+
+  It is a value rather than a wrap, so the `dispatchHttpRequest` wrap slot stays
+  free for a host that replaces the stage outright.
+
 ## 0.17.2
 
 ### Patch Changes

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(index_exports, {
   CoreError: () => CoreError,
   CoreErrorCode: () => CoreErrorCode,
   CoreSignal: () => CoreSignal,
+  HTTP_FETCH_ID: () => HTTP_FETCH_ID,
   RETRY_HTTP_REQUEST_OPTIONS_ID: () => RETRY_HTTP_REQUEST_OPTIONS_ID,
   STABILITY_LEVELS: () => STABILITY_LEVELS,
   STABILITY_TITLES: () => STABILITY_TITLES,
@@ -89,6 +90,7 @@ __export(index_exports, {
   getRegistry: () => getRegistry,
   getRegistryPlugin: () => getRegistryPlugin,
   getSchemaDescription: () => getSchemaDescription,
+  httpFetchPluginRef: () => httpFetchPluginRef,
   initializeHttpRequestPlugin: () => initializeHttpRequestPlugin,
   isCoreCancelledSignal: () => isCoreCancelledSignal,
   isCoreError: () => isCoreError,
@@ -773,6 +775,11 @@ function toIterable(source) {
   return { [Symbol.asyncIterator]: () => source[Symbol.asyncIterator]() };
 }
 
+// src/utils/promise-utils.ts
+function isPromiseLike(value) {
+  return value !== null && typeof value === "object" && typeof value.then === "function";
+}
+
 // src/utils/validation.ts
 var parseOrThrow = (schema, input, { adaptError } = {}) => {
   const result = schema.safeParse(input);
@@ -1239,7 +1246,7 @@ function createRawFunction(coreFn, options) {
       try {
         const parsed = schema ? validateOptions(schema, input, { adaptError }) : input;
         const result = coreFn(parsed, context);
-        if (result !== null && typeof result === "object" && typeof result.then === "function") {
+        if (isPromiseLike(result)) {
           return result.then(
             (value) => {
               fireEnd();
@@ -2571,9 +2578,6 @@ function applyListOutputPolicy(page, policy) {
 var FRAMEWORK_CONFIGURATION_IDS = /* @__PURE__ */ new Set([
   CORE_OPTIONS_ID
 ]);
-function isPromiseLike(value) {
-  return value !== null && typeof value === "object" && typeof value.then === "function";
-}
 function normalizeOutput(output) {
   if (output === void 0) return { type: "raw" };
   if (typeof output === "string") return { type: output };
@@ -4944,6 +4948,8 @@ var authorizeHttpRequestPlugin = defineMethod({
 
 // src/transport/dispatch-http-request.ts
 var import_zod7 = require("zod");
+var HTTP_FETCH_ID = "kitcore/httpFetch";
+var httpFetchPluginRef = declareOptionalProperty({ id: HTTP_FETCH_ID });
 function toFetchInput(request) {
   const init = { ...request };
   const { url } = request;
@@ -4954,11 +4960,12 @@ function toFetchInput(request) {
 var dispatchHttpRequestPlugin = defineMethod({
   name: "dispatchHttpRequest",
   namespace: "kitcore",
+  imports: [httpFetchPluginRef],
   inputSchema: import_zod7.z.custom(),
   skipInputValidation: true,
-  run: async ({ input }) => {
+  run: async ({ input, imports }) => {
     const { url, init } = toFetchInput(input.request);
-    return fetch(url, init);
+    return (imports.httpFetch ?? fetch)(url, init);
   }
 });
 
@@ -5057,6 +5064,7 @@ var DEFAULT_IDEMPOTENT_METHODS = [
   "TRACE"
 ];
 var BASE_BACKOFF_MILLISECONDS = 1e3;
+var MIN_BACKOFF_MILLISECONDS = 100;
 var JITTER_FACTOR = 0.5;
 var EPOCH_THRESHOLD_SECONDS = 1e9;
 function directedDelayMilliseconds(response) {
@@ -5081,6 +5089,12 @@ function backoffMilliseconds(attemptNumber) {
   const base = BASE_BACKOFF_MILLISECONDS * 2 ** (attemptNumber - 1);
   return base + Math.random() * JITTER_FACTOR * base;
 }
+function clampBackoffMilliseconds(attemptNumber, maxDelayMilliseconds) {
+  return Math.max(
+    Math.min(backoffMilliseconds(attemptNumber), maxDelayMilliseconds),
+    MIN_BACKOFF_MILLISECONDS
+  );
+}
 function abortReason(signal) {
   const reason = signal?.reason;
   return reason ?? new Error("The request was aborted.");
@@ -5115,6 +5129,20 @@ var retryHttpRequestPlugin = defineHook({
       const maxDelayMilliseconds = options.maxDelayMilliseconds ?? DEFAULT_MAX_DELAY_MILLISECONDS;
       const idempotentMethods = options.idempotentMethods ?? DEFAULT_IDEMPOTENT_METHODS;
       const statuses = isIdempotent(input.request, idempotentMethods) ? options.retryStatuses ?? DEFAULT_RETRY_STATUSES : options.nonIdempotentRetryStatuses ?? DEFAULT_NON_IDEMPOTENT_RETRY_STATUSES;
+      const notifyRetry = (notice) => {
+        try {
+          const observed = options.onRetry?.({
+            ...notice,
+            request: input.attempt.operation.request,
+            operationId: input.attempt.operation.operationId
+          });
+          if (isPromiseLike(observed)) {
+            void observed.then(void 0, () => {
+            });
+          }
+        } catch {
+        }
+      };
       for (let attemptNumber = 1; ; attemptNumber++) {
         const attempt = {
           ...input.attempt,
@@ -5136,10 +5164,16 @@ var retryHttpRequestPlugin = defineHook({
           )) {
             throw error;
           }
-          await sleep(
-            Math.min(backoffMilliseconds(attemptNumber), maxDelayMilliseconds),
-            attempt.signal
+          const errorDelay = clampBackoffMilliseconds(
+            attemptNumber,
+            maxDelayMilliseconds
           );
+          notifyRetry({
+            attemptNumber,
+            delayMilliseconds: errorDelay,
+            error
+          });
+          await sleep(errorDelay, attempt.signal);
           continue;
         }
         if (!statuses.includes(response.status) || !canRetry(
@@ -5152,10 +5186,8 @@ var retryHttpRequestPlugin = defineHook({
         const directed = directedDelayMilliseconds(response);
         if (directed != null && directed > maxDelayMilliseconds)
           return response;
-        const delay = Math.min(
-          directed ?? backoffMilliseconds(attemptNumber),
-          maxDelayMilliseconds
-        );
+        const delay = directed ?? clampBackoffMilliseconds(attemptNumber, maxDelayMilliseconds);
+        notifyRetry({ attemptNumber, delayMilliseconds: delay, response });
         await response.body?.cancel().catch(() => {
         });
         await sleep(delay, attempt.signal);
@@ -5311,6 +5343,7 @@ var resolveConnectionPlugin = defineMethod({
   CoreError,
   CoreErrorCode,
   CoreSignal,
+  HTTP_FETCH_ID,
   RETRY_HTTP_REQUEST_OPTIONS_ID,
   STABILITY_LEVELS,
   STABILITY_TITLES,
@@ -5371,6 +5404,7 @@ var resolveConnectionPlugin = defineMethod({
   getRegistry,
   getRegistryPlugin,
   getSchemaDescription,
+  httpFetchPluginRef,
   initializeHttpRequestPlugin,
   isCoreCancelledSignal,
   isCoreError,