@qawolf/ci-sdk 0.12.1 → 0.13.0

package/README.md

@@ -101,6 +101,13 @@ an up-to-date API usage version.
 
 # Changelog
 
+## v0.13.0
+
+- New `pollTimeout` parameter for `pollCiGreenlightStatus` to allow for a custom
+  timeout in milliseconds for the polling operation. It now defaults to two hours.
+- New `abortReason` and `httpStatus` fields added to the `PollCiGreenlightStatus` type
+  with `"aborted"` outcome to provide more context on why the poll was aborted.
+
 ## v0.12.1
 
 - Export dependencies types from root module.

package/dist/cjs/lib/sdk/domain/poll-ci-greenlight.js

@@ -3,24 +3,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pollCiGreenlightStatus = void 0;
 const utils_js_1 = require("../../utils.js");
 const ci_greenlight_js_1 = require("../../api/ci-greenlight.js");
+// If you change these values, make sure you update the JSDoc
+// comments in the PollConfig type.
 const safeDefaults = {
     maxRetries: 10,
     retryInterval: 10 * 1000,
     runInProgressInterval: 30 * 1000,
     runUnderReviewInterval: 60 * 1000,
+    pollTimeout: 120 * 60 * 1000,
 };
 async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChanged: onRunStageChanged = () => void 0, ...pollConfig }) {
     let retries = 0;
     const { log } = deps;
-    const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, } = pollConfig;
+    const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, pollTimeout = safeDefaults.pollTimeout, } = pollConfig;
     let currentStatus = undefined;
-    while (true) {
+    const startedAt = Date.now();
+    let hasTimedOut = false;
+    while (!(hasTimedOut = Date.now() - startedAt > pollTimeout)) {
         const responseState = await (0, ci_greenlight_js_1.fetchCiGreenlightStatus)(apiConfig, {
             runId,
         }, deps);
         if (!responseState.ok && !responseState.canRetry) {
             log.error(`🚫 Unrecoverable error (status ${responseState.httpStatus}) from CI greenlight, aborting.`);
-            return { outcome: "aborted" };
+            return {
+                outcome: "aborted",
+                abortReason: "4XX-client-error",
+                httpStatus: responseState.httpStatus,
+            };
         }
         if (!responseState.ok) {
             // This is a non-OK retryable status.
@@ -29,7 +38,24 @@ async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChange
                 log.error(`🚫 Unrecoverable error${responseState.httpStatus
                     ? ` (status ${responseState.httpStatus})`
                     : ""} from CI greenlight, aborting after ${maxRetries} attempts.`);
-                return { outcome: "aborted" };
+                if (responseState.errorType === "network")
+                    return {
+                        outcome: "aborted",
+                        abortReason: "network-error",
+                        httpStatus: undefined,
+                    };
+                let abortReason = "XXX-other-http-code";
+                if (responseState.errorType === "not-found")
+                    abortReason = "404-run-not-found";
+                else if (responseState.errorType === "server")
+                    abortReason = "5XX-server-error";
+                else
+                    (0, utils_js_1.assertType)(responseState);
+                return {
+                    outcome: "aborted",
+                    abortReason,
+                    httpStatus: responseState.httpStatus,
+                };
             }
             const { errorType, httpStatus } = responseState;
             const retryLabel = `${httpStatus ? ` (status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
@@ -88,6 +114,23 @@ async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChange
                 return { outcome: "failed", greenlightStatus };
             }
         }
+        if (runStage === "canceled") {
+            log.info(`🚫 Run was canceled. Aborting... Please contact support.\n${urlInfo}`);
+            return {
+                outcome: "aborted",
+                abortReason: "run-canceled",
+                httpStatus: undefined,
+            };
+        }
+        // Non-terminal run stages
+        if (hasTimedOut) {
+            log.warn(`❌ Poll timed out after ${pollTimeout / 1000}s. Aborting...`);
+            return {
+                outcome: "aborted",
+                abortReason: "poll-timed-out",
+                httpStatus: undefined,
+            };
+        }
         if (runStage === "initializing") {
             log.info(`⏳ Run is in progress... ${urlInfo}`);
             await (0, utils_js_1.sleep)(runInProgressInterval);
@@ -96,12 +139,16 @@ async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChange
             log.info(`🕵️  Run is under review... ${urlInfo}`);
             await (0, utils_js_1.sleep)(runUnderReviewInterval);
         }
-        else if (runStage === "canceled") {
-            log.info(`🚫 Run was canceled. Aborting... Please contact support.\n${urlInfo}`);
-            return { outcome: "aborted" };
-        }
-        else
+        else {
+            (0, utils_js_1.assertType)(runStage);
             throw new Error(`Unexpected run stage: ${runStage}`);
+        }
     }
+    log.warn(`❌ Poll timed out after ${pollTimeout / 1000}s. Aborting...`);
+    return {
+        outcome: "aborted",
+        abortReason: "poll-timed-out",
+        httpStatus: undefined,
+    };
 }
 exports.pollCiGreenlightStatus = pollCiGreenlightStatus;

package/dist/esm/lib/sdk/domain/poll-ci-greenlight.js

@@ -1,23 +1,32 @@
-import { sleep, pluralize } from "../../utils.js";
+import { sleep, pluralize, assertType } from "../../utils.js";
 import { fetchCiGreenlightStatus, } from "../../api/ci-greenlight.js";
+// If you change these values, make sure you update the JSDoc
+// comments in the PollConfig type.
 const safeDefaults = {
     maxRetries: 10,
     retryInterval: 10 * 1000,
     runInProgressInterval: 30 * 1000,
     runUnderReviewInterval: 60 * 1000,
+    pollTimeout: 120 * 60 * 1000,
 };
 export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChanged: onRunStageChanged = () => void 0, ...pollConfig }) {
     let retries = 0;
     const { log } = deps;
-    const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, } = pollConfig;
+    const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, pollTimeout = safeDefaults.pollTimeout, } = pollConfig;
     let currentStatus = undefined;
-    while (true) {
+    const startedAt = Date.now();
+    let hasTimedOut = false;
+    while (!(hasTimedOut = Date.now() - startedAt > pollTimeout)) {
         const responseState = await fetchCiGreenlightStatus(apiConfig, {
             runId,
         }, deps);
         if (!responseState.ok && !responseState.canRetry) {
             log.error(`🚫 Unrecoverable error (status ${responseState.httpStatus}) from CI greenlight, aborting.`);
-            return { outcome: "aborted" };
+            return {
+                outcome: "aborted",
+                abortReason: "4XX-client-error",
+                httpStatus: responseState.httpStatus,
+            };
         }
         if (!responseState.ok) {
             // This is a non-OK retryable status.
@@ -26,7 +35,24 @@ export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStag
                 log.error(`🚫 Unrecoverable error${responseState.httpStatus
                     ? ` (status ${responseState.httpStatus})`
                     : ""} from CI greenlight, aborting after ${maxRetries} attempts.`);
-                return { outcome: "aborted" };
+                if (responseState.errorType === "network")
+                    return {
+                        outcome: "aborted",
+                        abortReason: "network-error",
+                        httpStatus: undefined,
+                    };
+                let abortReason = "XXX-other-http-code";
+                if (responseState.errorType === "not-found")
+                    abortReason = "404-run-not-found";
+                else if (responseState.errorType === "server")
+                    abortReason = "5XX-server-error";
+                else
+                    assertType(responseState);
+                return {
+                    outcome: "aborted",
+                    abortReason,
+                    httpStatus: responseState.httpStatus,
+                };
             }
             const { errorType, httpStatus } = responseState;
             const retryLabel = `${httpStatus ? ` (status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
@@ -85,6 +111,23 @@ export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStag
                 return { outcome: "failed", greenlightStatus };
             }
         }
+        if (runStage === "canceled") {
+            log.info(`🚫 Run was canceled. Aborting... Please contact support.\n${urlInfo}`);
+            return {
+                outcome: "aborted",
+                abortReason: "run-canceled",
+                httpStatus: undefined,
+            };
+        }
+        // Non-terminal run stages
+        if (hasTimedOut) {
+            log.warn(`❌ Poll timed out after ${pollTimeout / 1000}s. Aborting...`);
+            return {
+                outcome: "aborted",
+                abortReason: "poll-timed-out",
+                httpStatus: undefined,
+            };
+        }
         if (runStage === "initializing") {
             log.info(`⏳ Run is in progress... ${urlInfo}`);
             await sleep(runInProgressInterval);
@@ -93,11 +136,15 @@ export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStag
             log.info(`🕵️  Run is under review... ${urlInfo}`);
             await sleep(runUnderReviewInterval);
         }
-        else if (runStage === "canceled") {
-            log.info(`🚫 Run was canceled. Aborting... Please contact support.\n${urlInfo}`);
-            return { outcome: "aborted" };
-        }
-        else
+        else {
+            assertType(runStage);
             throw new Error(`Unexpected run stage: ${runStage}`);
+        }
     }
+    log.warn(`❌ Poll timed out after ${pollTimeout / 1000}s. Aborting...`);
+    return {
+        outcome: "aborted",
+        abortReason: "poll-timed-out",
+        httpStatus: undefined,
+    };
 }

package/dist/types/lib/sdk/domain/poll-ci-greenlight.d.ts

@@ -2,11 +2,40 @@ import { CiGreenlightStatus } from "../../api/ci-greenlight.js";
 import { ApiConfig } from "../../api-types.js";
 import { SdkDependencies } from "../dependencies.js";
 export type PollConfig = {
+    /**
+     * Maximum number of network operations retries before aborting the job.
+     *
+     * @default 10
+     */
     maxRetries: number;
+    /**
+     * Interval in milliseconds between network operations retries.
+     *
+     * @default 10 seconds
+     */
     retryInterval: number;
+    /**
+     * Interval in milliseconds between polling for a run in progress.
+     *
+     * @default 30 seconds
+     */
     runInProgressInterval: number;
+    /**
+     * Interval in milliseconds between polling for a run under review.
+     *
+     * @default 60 minutes
+     */
     runUnderReviewInterval: number;
+    /**
+     * Timeout in milliseconds before aborting this polling operation.
+     *
+     * @default 120 minutes
+     */
+    pollTimeout: number;
 };
+export type HttpRelatedAbortReason = "4XX-client-error" | "404-run-not-found" | "5XX-server-error" | "XXX-other-http-code";
+export type NonHttpRelatedAbortReason = "poll-timed-out" | "run-canceled" | "network-error";
+export type AbortReason = NonHttpRelatedAbortReason | HttpRelatedAbortReason;
 export type PollCiGreenlightStatus = {
     /**
      * No blocking bugs were found in the run.
@@ -28,6 +57,15 @@ export type PollCiGreenlightStatus = {
      * The run was aborted due to an unrecoverable error.
      */
     outcome: "aborted";
+    abortReason: HttpRelatedAbortReason;
+    httpStatus: number;
+} | {
+    /**
+     * The run was aborted due to an unrecoverable error.
+     */
+    outcome: "aborted";
+    abortReason: NonHttpRelatedAbortReason;
+    httpStatus: undefined;
 };
 export type PollCiGreenlightParams = {
     runId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/ci-sdk",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "A simple SDK for interacting with QAWolf in CI scripts.",
   "type": "module",
   "private": false,