Implement etag handling

Fixes #295

Author: carlobeltrame

dist/index.mjs

@@ -34,6 +34,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.28.0",
+    "@octokit/types": "^14.1.0",
     "@opentf/std": "^0.13.0",
     "@total-typescript/ts-reset": "^0.6.1",
     "@types/node": "~20.19.0",

package.json

@@ -20,6 +20,7 @@ import {
   init,
   retryOrTimeout,
 } from "./api.ts";
+import { clearEtags } from "./etags.js";
 import { mockLoggingFunctions } from "./test-utils/logging.mock.ts";
 import { getBranchName } from "./utils.ts";
 
@@ -29,6 +30,7 @@ vi.mock("@actions/github");
 interface MockResponse {
   data: any;
   status: number;
+  headers: object;
 }
 
 function* mockPageIterator<T, P>(
@@ -66,6 +68,10 @@ const mockOctokit = {
   },
 };
 
+afterEach(() => {
+  clearEtags();
+});
+
 describe("API", () => {
   const {
     coreDebugLogMock,
@@ -119,6 +125,7 @@ describe("API", () => {
         Promise.resolve({
           data: undefined,
           status: 204,
+          headers: {},
         }),
       );
 
@@ -147,6 +154,7 @@ describe("API", () => {
         Promise.resolve({
           data: undefined,
           status: errorStatus,
+          headers: {},
         }),
       );
 
@@ -176,6 +184,7 @@ describe("API", () => {
         return Promise.resolve({
           data: undefined,
           status: 204,
+          headers: {},
         });
       });
 
@@ -219,6 +228,7 @@ describe("API", () => {
         Promise.resolve({
           data: mockData,
           status: 200,
+          headers: {},
         }),
       );
 
@@ -246,6 +256,7 @@ describe("API", () => {
         Promise.resolve({
           data: undefined,
           status: errorStatus,
+          headers: {},
         }),
       );
 
@@ -268,6 +279,7 @@ describe("API", () => {
         Promise.resolve({
           data: [],
           status: 200,
+          headers: {},
         }),
       );
 
@@ -303,6 +315,7 @@ describe("API", () => {
         Promise.resolve({
           data: mockData,
           status: 200,
+          headers: {},
         }),
       );
 
@@ -355,6 +368,7 @@ describe("API", () => {
         Promise.resolve({
           data: mockData,
           status: 200,
+          headers: {},
         }),
       );
 
@@ -387,6 +401,7 @@ describe("API", () => {
         Promise.resolve({
           data: undefined,
           status: errorStatus,
+          headers: {},
         }),
       );
 
@@ -417,6 +432,7 @@ describe("API", () => {
         Promise.resolve({
           data: mockData,
           status: 200,
+          headers: {},
         }),
       );
 
@@ -454,6 +470,7 @@ describe("API", () => {
               workflow_runs: [],
             },
             status: 200,
+            headers: {},
           };
           return Promise.resolve(mockResponse);
         },
@@ -494,6 +511,7 @@ describe("API", () => {
               workflow_runs: [],
             },
             status: 200,
+            headers: {},
           };
           return Promise.resolve(mockResponse);
         },
@@ -534,6 +552,7 @@ describe("API", () => {
               workflow_runs: [],
             },
             status: 200,
+            headers: {},
           };
           return Promise.resolve(mockResponse);
         },
@@ -588,6 +607,7 @@ describe("API", () => {
         Promise.resolve({
           data: mockData,
           status: 200,
+          headers: {},
         }),
       );
 
@@ -620,6 +640,7 @@ describe("API", () => {
         Promise.resolve({
           data: undefined,
           status: errorStatus,
+          headers: {},
         }),
       );
 
@@ -653,6 +674,7 @@ describe("API", () => {
         Promise.resolve({
           data: mockData,
           status: 200,
+          headers: {},
         }),
       );
 
@@ -672,6 +694,64 @@ describe("API", () => {
       `,
       );
     });
+
+    it("should send the etag from the previous response in the If-None-Match header", async () => {
+      const mockData = {
+        total_count: 1,
+        jobs: [
+          {
+            id: 0,
+            steps: undefined,
+          },
+        ],
+      };
+      const etag =
+        "37c2311495bbea359329d0bb72561bdb2b2fffea1b7a54f696b5a287e7ccad1e";
+      let submittedEtag = null;
+      vi.spyOn(
+        mockOctokit.rest.actions,
+        "listJobsForWorkflowRun",
+      ).mockImplementation(({ headers }) => {
+        if (headers["If-None-Match"]) {
+          submittedEtag = headers["If-None-Match"];
+          return Promise.resolve({
+            data: null,
+            status: 304,
+            headers: {
+              etag: `W/"${submittedEtag}"`,
+            },
+          });
+        }
+        return Promise.resolve({
+          data: mockData,
+          status: 200,
+          headers: {
+            etag: `W/"${etag}"`,
+          },
+        });
+      });
+
+      // Behaviour
+      // First API call will return 200 with an etag response header
+      await fetchWorkflowRunJobSteps(0);
+      expect(submittedEtag).eq(null);
+      // Second API call will return 304 because of If-None-Match header
+      await expect(fetchWorkflowRunJobSteps(0)).resolves.toStrictEqual([]);
+      expect(submittedEtag).eq(etag);
+
+      // Logging
+      assertOnlyCalled(coreDebugLogMock);
+      expect(coreDebugLogMock).toHaveBeenCalledTimes(2);
+      expect(coreDebugLogMock.mock.calls[0]?.[0]).toMatchInlineSnapshot(
+        `
+        "Fetched Workflow Run Job Steps:
+          Repository: owner/repo
+          Workflow Run ID: 0
+          Jobs Fetched: [0]
+          Steps Fetched: []"
+      `,
+      );
+    });
   });
 
   describe("fetchWorkflowRunUrl", () => {
@@ -683,6 +763,7 @@ describe("API", () => {
         Promise.resolve({
           data: mockData,
           status: 200,
+          headers: {},
         }),
       );
 
@@ -696,6 +777,7 @@ describe("API", () => {
         Promise.resolve({
           data: undefined,
           status: errorStatus,
+          headers: {},
         }),
       );