feat(firewall): download from a random origin with cross-origin fallback

The free-edition binary is now also served from
install.socket.dev/firewall/dl (Socket-owned, checksum-pinned in this
action's source, so a second host cannot swap bytes). Each job picks
one of the two origins at random, which keeps the mirror's edge cache
warm on roughly half the fleet's downloads, and the retry schedule
alternates origins. A non-retryable error like a 404 still gets one
immediate try of the other origin, since a missing asset on one host
says nothing about the other; that also makes this safe to ship before
the mirror endpoint is live. Enterprise stays GitHub-only: its
repository is private and not mirrored.

Author: juliangruber

dist/main.js

@@ -87,6 +87,13 @@ export const FIREWALL_CHECKSUMS = {
  */
 export const DOWNLOAD_RETRY_DELAYS_SECONDS = [30, 60]
 
+/**
+ * Socket-owned mirror of the sfw-free release binaries, relayed by
+ * firewall-download-server in depscan. Free edition only: the enterprise
+ * repository is private and not mirrored.
+ */
+export const FIREWALL_MIRROR_BASE_URL = 'https://install.socket.dev/firewall/dl'
+
 /**
  * Name the firewall binary is cached and executed under.
  */
@@ -147,8 +154,13 @@ export async function downloadFirewall({ edition = 'free', ...inputs }) {
     process.arch,
   ]
 
-  // construct the download url
-  const url = `https://github.com/SocketDev/${repo}/releases/download/${versionToDownload}/${nameDownload}`
+  // construct the download urls
+  const urls = firewallDownloadUrls(
+    edition,
+    repo,
+    versionToDownload,
+    nameDownload,
+  )
 
   let pathCache
 
@@ -159,13 +171,13 @@ export async function downloadFirewall({ edition = 'free', ...inputs }) {
 
   // no cache, download new
   if (!pathCache) {
-    debug(`downloading Socket Firewall binary from: ${url}`)
+    debug(`downloading Socket Firewall binary from: ${urls.join(', ')}`)
 
     let pathDownload
 
     try {
       // download it
-      pathDownload = await downloadToolWithRetry(url)
+      pathDownload = await downloadToolWithRetry(urls)
     } catch (error) {
       throw new Error(
         `Failed to download Socket Firewall binary: ${errorMessage(error)}`,
@@ -228,43 +240,94 @@ export async function downloadFirewall({ edition = 'free', ...inputs }) {
 }
 
 /**
- * `downloadTool` with attempts layered on top of its own. The last error is
- * rethrown untouched so the caller still reports the real cause.
+ * `downloadTool` with attempts layered on top of its own, alternating between
+ * equivalent origins. Retryable failures spend the delay table; an error that
+ * a retry cannot change (a 404) still gets one immediate try per remaining
+ * origin, because a missing asset on one host says nothing about the others.
+ * The last error is rethrown untouched so the caller still reports the real
+ * cause.
  *
- * @param {string} url Asset to download.
+ * @param {string[]} urls Equivalent origins for the same asset, in the order
+ *   to try them.
  *
  * @returns {Promise<string>} Path the asset was downloaded to.
  */
-export async function downloadToolWithRetry(url) {
+export async function downloadToolWithRetry(urls) {
   let lastError
 
   for (
     let attempt = 0;
     attempt <= DOWNLOAD_RETRY_DELAYS_SECONDS.length;
     attempt += 1
   ) {
+    const url = urls[attempt % urls.length]
+
     try {
       return await downloadTool(url)
     } catch (error) {
       lastError = error
 
       const seconds = DOWNLOAD_RETRY_DELAYS_SECONDS[attempt]
 
-      if (seconds === undefined || !isRetryableDownloadError(error)) {
+      if (seconds === undefined) {
         break
       }
 
-      warning(
-        `Socket Firewall binary download failed (attempt ${attempt + 1} of ${DOWNLOAD_RETRY_DELAYS_SECONDS.length + 1}): ${errorMessage(error)}. Retrying in ${seconds}s.`,
-      )
-
-      await setTimeout(seconds * 1000)
+      if (isRetryableDownloadError(error)) {
+        warning(
+          `Socket Firewall binary download from ${url} failed (attempt ${attempt + 1} of ${DOWNLOAD_RETRY_DELAYS_SECONDS.length + 1}): ${errorMessage(error)}. Retrying in ${seconds}s.`,
+        )
+        await setTimeout(seconds * 1000)
+      } else if (attempt < urls.length - 1) {
+        warning(
+          `Socket Firewall binary download from ${url} failed: ${errorMessage(error)}. Trying ${urls[(attempt + 1) % urls.length]}.`,
+        )
+      } else {
+        break
+      }
     }
   }
 
   throw lastError
 }
 
+/**
+ * Origins to download one release asset from, in the order to try them. The
+ * free edition is also mirrored on Socket-owned infrastructure, and one of the
+ * two origins is picked at random per job: half the fleet's downloads keep the
+ * mirror's edge cache warm, which is what lets it keep serving during a GitHub
+ * release-asset incident. The enterprise repository is private and not
+ * mirrored, so it stays GitHub-only.
+ *
+ * @param {string} edition Firewall edition being installed.
+ * @param {string} repo GitHub repository the release lives in.
+ * @param {string} version Release tag to download.
+ * @param {string} asset Release asset name.
+ * @param {() => number} random Injectable for tests.
+ *
+ * @returns {string[]} Download URLs, primary origin first.
+ */
+export function firewallDownloadUrls(
+  edition,
+  repo,
+  version,
+  asset,
+  random = Math.random,
+) {
+  const urls = [
+    `https://github.com/SocketDev/${repo}/releases/download/${version}/${asset}`,
+  ]
+
+  if (edition === 'free') {
+    urls.push(`${FIREWALL_MIRROR_BASE_URL}/${version}/${asset}`)
+    if (random() < 0.5) {
+      urls.reverse()
+    }
+  }
+
+  return urls
+}
+
 export function firewallReleaseVersion(requestedVersion) {
   let versionToDownload = FIREWALL_VERSION
 

src/tools/firewall.js

@@ -13,6 +13,7 @@ import {
   downloadToolWithRetry,
   FIREWALL_DISTRIBUTIONS,
   FIREWALL_EXEC_NAME,
+  firewallDownloadUrls,
   isRetryableDownloadError,
 } from '../../../src/tools/firewall.js'
 
@@ -146,35 +147,112 @@ describe('isRetryableDownloadError', () => {
 })
 
 describe('downloadToolWithRetry', () => {
+  const GITHUB = 'https://github.test/sfw'
+  const MIRROR = 'https://mirror.test/sfw'
+
   it('returns the path once an attempt succeeds', async () => {
     mockDownloadTool
       .mockRejectedValueOnce(httpError(504))
       .mockResolvedValueOnce('/tmp/sfw')
 
-    await expect(
-      downloadToolWithRetry('https://example.test/sfw'),
-    ).resolves.toBe('/tmp/sfw')
+    await expect(downloadToolWithRetry([GITHUB])).resolves.toBe('/tmp/sfw')
     expect(mockDownloadTool).toHaveBeenCalledTimes(2)
     expect(sleepDelays).toEqual([30_000])
   })
 
   it('rethrows the last error after exhausting its attempts', async () => {
     mockDownloadTool.mockRejectedValue(httpError(504))
 
-    await expect(
-      downloadToolWithRetry('https://example.test/sfw'),
-    ).rejects.toThrow('Unexpected HTTP response: 504')
+    await expect(downloadToolWithRetry([GITHUB])).rejects.toThrow(
+      'Unexpected HTTP response: 504',
+    )
     expect(mockDownloadTool).toHaveBeenCalledTimes(3)
     expect(sleepDelays).toEqual([30_000, 60_000])
   })
 
   it('does not spend attempts on a missing asset', async () => {
     mockDownloadTool.mockRejectedValue(httpError(404))
 
-    await expect(
-      downloadToolWithRetry('https://example.test/sfw'),
-    ).rejects.toThrow('Unexpected HTTP response: 404')
+    await expect(downloadToolWithRetry([GITHUB])).rejects.toThrow(
+      'Unexpected HTTP response: 404',
+    )
     expect(mockDownloadTool).toHaveBeenCalledTimes(1)
     expect(sleepDelays).toEqual([])
   })
+
+  it('alternates origins across the retry schedule', async () => {
+    mockDownloadTool.mockRejectedValue(httpError(504))
+
+    await expect(downloadToolWithRetry([MIRROR, GITHUB])).rejects.toThrow(
+      'Unexpected HTTP response: 504',
+    )
+    expect(mockDownloadTool.mock.calls).toEqual([[MIRROR], [GITHUB], [MIRROR]])
+    expect(sleepDelays).toEqual([30_000, 60_000])
+  })
+
+  it('tries the other origin immediately when a retry cannot help', async () => {
+    // A 404 from the mirror says nothing about GitHub: no backoff, one
+    // immediate try of the other origin.
+    mockDownloadTool
+      .mockRejectedValueOnce(httpError(404))
+      .mockResolvedValueOnce('/tmp/sfw')
+
+    await expect(downloadToolWithRetry([MIRROR, GITHUB])).resolves.toBe(
+      '/tmp/sfw',
+    )
+    expect(mockDownloadTool.mock.calls).toEqual([[MIRROR], [GITHUB]])
+    expect(sleepDelays).toEqual([])
+  })
+
+  it('gives up once every origin reported a missing asset', async () => {
+    mockDownloadTool.mockRejectedValue(httpError(404))
+
+    await expect(downloadToolWithRetry([MIRROR, GITHUB])).rejects.toThrow(
+      'Unexpected HTTP response: 404',
+    )
+    expect(mockDownloadTool).toHaveBeenCalledTimes(2)
+    expect(sleepDelays).toEqual([])
+  })
+})
+
+describe('firewallDownloadUrls', () => {
+  it('gives the free edition both origins, ordered by the coin flip', () => {
+    const github =
+      'https://github.com/SocketDev/sfw-free/releases/download/v1.15.2/sfw-free-linux-x86_64'
+    const mirror =
+      'https://install.socket.dev/firewall/dl/v1.15.2/sfw-free-linux-x86_64'
+
+    expect(
+      firewallDownloadUrls(
+        'free',
+        'sfw-free',
+        'v1.15.2',
+        'sfw-free-linux-x86_64',
+        () => 0.9,
+      ),
+    ).toEqual([github, mirror])
+    expect(
+      firewallDownloadUrls(
+        'free',
+        'sfw-free',
+        'v1.15.2',
+        'sfw-free-linux-x86_64',
+        () => 0.1,
+      ),
+    ).toEqual([mirror, github])
+  })
+
+  it('keeps the enterprise edition GitHub-only', () => {
+    expect(
+      firewallDownloadUrls(
+        'enterprise',
+        'firewall-release',
+        'v1.15.2',
+        'sfw-windows-x86_64.exe',
+        () => 0.1,
+      ),
+    ).toEqual([
+      'https://github.com/SocketDev/firewall-release/releases/download/v1.15.2/sfw-windows-x86_64.exe',
+    ])
+  })
 })