vercel__next.js/scripts/wait-for-preview-tarball.mjs

// @ts-check
import { setTimeout } from 'node:timers/promises'
import { pathToFileURL } from 'node:url'
import { parseArgs } from 'node:util'
import { getGitInfo } from './git-info.mjs'

const DEFAULT_PREVIEW_BUILDS_BASE_URL =
  'https://vercel-packages.vercel.app/next'
// Comfortably above the slowest observed build-and-deploy plus
// upload-preview-tarballs, which together have topped out around 27 minutes.
const DEFAULT_TIMEOUT_MINUTES = 30
const POLL_INTERVAL_MS = 15_000
const PROGRESS_LOG_INTERVAL_MS = 60_000

/**
 * Mints a GitHub Actions OIDC token for the given audience.
 * Returns null outside of GitHub Actions.
 *
 * @param {string} audience
 * @returns {Promise<string | null>}
 */
async function mintGitHubActionsOidcToken(audience) {
  const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL
  const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN
  if (!requestUrl || !requestToken) {
    return null
  }

  const url = new URL(requestUrl)
  url.searchParams.set('audience', audience)
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${requestToken}` },
  })
  if (!response.ok) {
    throw new Error(
      `Failed to mint GitHub OIDC token: ${response.status} ${await response.text()}`
    )
  }

  const { value } = await response.json()
  return value
}

/**
 * Reads a preview-builds credential, minting a fresh one when needed.
 * vercel-packages accepts GitHub Actions OIDC tokens minted for its audience.
 * Public preview builds need no credentials and return null. Private builds
 * mint a GitHub Actions OIDC token, which expires about five minutes after
 * issuance, so the token is cached and re-minted before it expires rather
 * than minted once up front.
 *
 * @returns {() => Promise<string | null>}
 */
export function createPreviewBuildsReadTokenGetter() {
  if (process.env.PREVIEW_BUILDS_ACCESS !== 'private') {
    return async () => null
  }

  let cachedToken = null
  let cachedTokenExpiresAt = 0

  return async () => {
    if (cachedToken !== null && cachedTokenExpiresAt - 60_000 > Date.now()) {
      return cachedToken
    }
    const token = await mintGitHubActionsOidcToken(
      'https://vercel-packages.vercel.app'
    )
    if (token === null) {
      throw new Error(
        'Preview builds are private (PREVIEW_BUILDS_ACCESS=private) ' +
          'but no GitHub Actions OIDC token can be minted. ' +
          'Grant the job the `id-token: write` permission.'
      )
    }
    const payload = JSON.parse(
      Buffer.from(token.split('.')[1], 'base64url').toString()
    )
    cachedToken = token
    cachedTokenExpiresAt = payload.exp * 1000
    return token
  }
}

/**
 * URL of the preview tarball of `packageName` for a commit. `vercel-packages`
 * answers with a redirect to Vercel Blob, which only serves the tarball once
 * `upload-preview-tarballs` has published it.
 *
 * @param {string | undefined} baseUrl
 * @param {string} commitSha
 * @param {string} packageName
 * @returns {string}
 */
export function previewTarballUrl(baseUrl, commitSha, packageName) {
  return `${baseUrl || DEFAULT_PREVIEW_BUILDS_BASE_URL}/commits/${commitSha}/${packageName}`
}

/**
 * The reverse of `previewTarballUrl`: the commit that a preview build URL
 * refers to, or null when `url` was not built from `baseUrl`.
 *
 * @param {string | undefined} url
 * @param {string | undefined} baseUrl
 * @returns {string | null} the commit
 */
export function getCommitFromPreviewBuildUrl(url, baseUrl) {
  if (url === undefined) {
    return null
  }
  const commitsPrefix = `${baseUrl || DEFAULT_PREVIEW_BUILDS_BASE_URL}/commits/`
  if (!url.startsWith(commitsPrefix)) {
    return null
  }
  const [commitSha] = url.slice(commitsPrefix.length).split('/')
  if (commitSha.length === 0) {
    return null
  }
  return commitSha
}

/**
 * @param {number} milliseconds
 * @returns {string}
 */
function formatDuration(milliseconds) {
  const totalSeconds = Math.round(milliseconds / 1000)
  const minutes = Math.floor(totalSeconds / 60)
  const seconds = totalSeconds % 60
  return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`
}

/**
 * URL of the commit's check runs, where the `build-and-deploy` status is
 * visible. Undefined outside of GitHub Actions, which is the only place the
 * server and repository are known.
 *
 * @param {string} commitSha
 * @returns {string | undefined}
 */
function commitChecksUrl(commitSha) {
  const serverUrl = process.env.GITHUB_SERVER_URL
  const repository = process.env.GITHUB_REPOSITORY
  if (!serverUrl || !repository) {
    return undefined
  }
  return `${serverUrl}/${repository}/commit/${commitSha}/checks`
}

/**
 * Requests the tarball with `HEAD` so polling stays cheap: a `GET` would
 * download the whole multi-megabyte tarball on every attempt.
 *
 * `fetch` follows the redirect, so `response.ok` reflects the blob and not the
 * unconditional redirect that `vercel-packages` returns. Anything that inspects
 * this URL must follow redirects too, otherwise the redirect itself reads as
 * success while the tarball is still missing.
 *
 * `lastResponse` describes the outcome for the progress and failure messages.
 *
 * @param {string} url
 * @param {Record<string, string> | undefined} headers
 * @returns {Promise<{ published: boolean, status: number | null, lastResponse: string, responseHeaders: string | null }>}
 */
async function probeTarball(url, headers) {
  try {
    const response = await fetch(url, { method: 'HEAD', headers })
    return {
      published: response.ok,
      status: response.status,
      lastResponse:
        response.status === 404 ? 'not published yet' : `${response.status}`,
      // Response headers carry request IDs that help debug failures.
      responseHeaders: response.ok
        ? null
        : JSON.stringify(Object.fromEntries(response.headers)),
    }
  } catch (error) {
    return {
      published: false,
      status: null,
      lastResponse: `request failed (${error instanceof Error ? error.message : error})`,
      responseHeaders: null,
    }
  }
}

/**
 * @param {() => Promise<string | null>} getReadToken
 * @returns {Promise<Record<string, string> | undefined>}
 */
async function requestHeaders(getReadToken) {
  const readToken = await getReadToken()
  return readToken ? { Authorization: `Bearer ${readToken}` } : undefined
}

/**
 * @param {object} options
 * @param {string} options.commitSha
 * @param {string} options.lastResponse
 * @param {string | null} [options.responseHeaders]
 * @param {number} [options.timeoutMs] Omitted when nothing was waited out.
 * @returns {Error}
 */
function notPublishedError({
  commitSha,
  lastResponse,
  responseHeaders,
  timeoutMs,
}) {
  const checksUrl = commitChecksUrl(commitSha)
  return new Error(
    `Preview tarball for commit ${commitSha} was not published` +
      (timeoutMs === undefined ? '' : ` within ${formatDuration(timeoutMs)}`) +
      ` (last response: ${lastResponse}). ` +
      `The tarball is published by the "upload-preview-tarballs" workflow ` +
      `once "build-and-deploy" has completed for this commit, so check ` +
      `whether that run failed or is still in progress.` +
      (checksUrl ? ` See ${checksUrl}` : '') +
      (responseHeaders ? ` Response headers: ${responseHeaders}` : '')
  )
}

/**
 * Checks once whether the `next` preview tarball for `commitSha` is
 * downloadable, and throws if it is not. For callers that only need the
 * assertion because something else has already done the waiting.
 *
 * @param {object} options
 * @param {string} options.commitSha
 * @param {string} [options.previewBuildsBaseUrl]
 * @param {() => Promise<string | null>} [options.getReadToken]
 * @returns {Promise<void>}
 */
export async function assertPreviewTarballPublished({
  commitSha,
  previewBuildsBaseUrl,
  getReadToken,
}) {
  const url = previewTarballUrl(previewBuildsBaseUrl, commitSha, 'next')
  const { published, lastResponse, responseHeaders } = await probeTarball(
    url,
    await requestHeaders(getReadToken ?? (async () => null))
  )

  if (!published) {
    throw notPublishedError({ commitSha, lastResponse, responseHeaders })
  }

  console.info(`Preview tarball for commit ${commitSha} is available at ${url}`)
}

/**
 * Polls until the `next` preview tarball for `commitSha` is downloadable.
 * Rejects when `timeoutMs` elapses before that happens. Every response other
 * than a success is treated as "not ready", so a transient blob or edge error
 * does not end the wait early.
 *
 * @param {object} options
 * @param {string} options.commitSha
 * @param {string} [options.previewBuildsBaseUrl]
 * @param {number} options.timeoutMs
 * @param {() => Promise<string | null>} [options.getReadToken]
 * @param {number} [options.pollIntervalMs]
 * @returns {Promise<void>}
 */
export async function waitForPreviewTarball({
  commitSha,
  previewBuildsBaseUrl,
  timeoutMs,
  getReadToken = async () => null,
  pollIntervalMs = POLL_INTERVAL_MS,
}) {
  const url = previewTarballUrl(previewBuildsBaseUrl, commitSha, 'next')
  const startedAt = Date.now()
  const deadline = startedAt + timeoutMs
  let lastProgressLogAt = startedAt

  console.info(
    `Waiting up to ${formatDuration(timeoutMs)} for the preview tarball at ${url}`
  )

  for (;;) {
    // A fresh token per probe: the OIDC token expires after five minutes,
    // well before the overall timeout.
    const { published, status, lastResponse, responseHeaders } =
      await probeTarball(url, await requestHeaders(getReadToken))
    const now = Date.now()

    if (published) {
      console.info(
        `Preview tarball for commit ${commitSha} is available after ${formatDuration(now - startedAt)}`
      )
      return
    }

    if (status === 401 || status === 403) {
      // Retrying won't change the authorization outcome.
      throw new Error(
        `Not authorized to access the preview tarball at ${url} (last response: ${lastResponse}). ` +
          (responseHeaders ? `Response headers: ${responseHeaders}` : '')
      )
    }

    if (now >= deadline) {
      throw notPublishedError({
        commitSha,
        lastResponse,
        responseHeaders,
        timeoutMs,
      })
    }

    if (now - lastProgressLogAt >= PROGRESS_LOG_INTERVAL_MS) {
      console.info(
        `Still waiting after ${formatDuration(now - startedAt)} (last response: ${lastResponse})`
      )
      lastProgressLogAt = now
    }

    // Capping the sleep at the remaining time keeps the last probe on the
    // deadline rather than past it.
    await setTimeout(Math.min(pollIntervalMs, deadline - now))
  }
}

async function main() {
  const { values } = parseArgs({
    options: {
      'commit-sha': { type: 'string' },
      'preview-builds-base-url': { type: 'string' },
      'timeout-minutes': { type: 'string' },
    },
  })

  // Resolving the commit through `getGitInfo` rather than from a workflow
  // expression keeps this in step with `test-new-tests.mjs`, which reaches the
  // same function via `getChangedTests` to build the URL it installs from. The
  // two have to agree, otherwise this waits for a tarball the tests never ask
  // for.
  const commitSha = values['commit-sha'] ?? (await getGitInfo()).commitSha

  const rawTimeoutMinutes = values['timeout-minutes']
  const timeoutMinutes =
    rawTimeoutMinutes === undefined
      ? DEFAULT_TIMEOUT_MINUTES
      : Number(rawTimeoutMinutes)
  if (!Number.isFinite(timeoutMinutes) || timeoutMinutes <= 0) {
    throw new Error(
      `--timeout-minutes must be a positive number but got "${rawTimeoutMinutes}"`
    )
  }

  await waitForPreviewTarball({
    commitSha,
    previewBuildsBaseUrl: values['preview-builds-base-url'],
    timeoutMs: timeoutMinutes * 60_000,
    getReadToken: createPreviewBuildsReadTokenGetter(),
  })
}

// `test-new-tests.mjs` imports this module for its own verification, so the CLI
// only runs when the file is the entry point.
if (
  process.argv[1] &&
  pathToFileURL(process.argv[1]).href === import.meta.url
) {
  main().catch((error) => {
    console.error(error instanceof Error ? error.message : error)
    process.exit(1)
  })
}