An open source design system that's fully customizable and agent ready
TypeScript
fix(release): verify the registry in bounded windows, with at most two follow-up verification jobs (#9658)
Cindy Zhang85b462725173
diff --git a/.github/scripts/release-publish-workflow.test.mjs b/.github/scripts/release-publish-workflow.test.mjsindex b4a814a558..2c7d908d59 100644--- a/.github/scripts/release-publish-workflow.test.mjs+++ b/.github/scripts/release-publish-workflow.test.mjs@@ -184,7 +184,11 @@ async function runCanaryPublish({}/** Runs the stable publish step over two packages with stubbed npm and pnpm. */-function runStablePublish({failingPackage = '', failOnce = ''} = {}) {+function runStablePublish({+ failingPackage = '',+ failOnce = '',+ verifyExit = null,+} = {}) {const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-stable-publish-'));const publishLog = path.join(root, 'publish.log');try {@@ -212,6 +216,9 @@ function runStablePublish({failingPackage = '', failOnce = ''} = {}) {writeExecutable(root, 'npm', '#!/bin/sh\nexit 1\n');writeExecutable(root, 'pnpm', PNPM_STUB);const publisherEnv = withPublisher(root);+ if (verifyExit !== null) writeVerifierStub(root, verifyExit);+ const githubOutput = path.join(root, 'github-output');+ fs.writeFileSync(githubOutput, '');const result = spawnSync('bash',['-c', step(stable, 'Publish changed packages').run],@@ -224,6 +231,7 @@ function runStablePublish({failingPackage = '', failOnce = ''} = {}) {DRY_RUN: 'false',FAIL_ONCE: failOnce,FAIL_PACKAGE: failingPackage,+ GITHUB_OUTPUT: githubOutput,PATH: `${path.join(root, 'bin')}:${process.env.PATH}`,PUBLISH_LOG: publishLog,RELEASE_VERSION: '0.7.7',@@ -232,6 +240,7 @@ function runStablePublish({failingPackage = '', failOnce = ''} = {}) {);return {...result,+ output: fs.readFileSync(githubOutput, 'utf8'),published: fs.existsSync(publishLog)? fs.readFileSync(publishLog, 'utf8'): '',@@ -241,6 +250,39 @@ function runStablePublish({failingPackage = '', failOnce = ''} = {}) {}}+/** A registry verifier stand-in that exits with `code`. */+function writeVerifierStub(root, code) {+ const file = path.join(root, 'scripts/npm/verify-published.mjs');+ fs.mkdirSync(path.dirname(file), {recursive: true});+ fs.writeFileSync(file, `process.exit(${code});\n`);+}++/** Runs one follow-up verification job's script with a verifier stand-in. */+function runFollowUp(job, verifyExit) {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-verify-'));+ try {+ writeVerifierStub(root, verifyExit);+ const githubOutput = path.join(root, 'github-output');+ fs.writeFileSync(githubOutput, '');+ const result = spawnSync(+ 'bash',+ ['-c', step(job, 'Verify published packages').run],+ {+ cwd: root,+ encoding: 'utf8',+ env: {+ ...process.env,+ GITHUB_OUTPUT: githubOutput,+ RELEASE_VERSION: '0.7.7',+ },+ },+ );+ return {...result, output: fs.readFileSync(githubOutput, 'utf8')};+ } finally {+ fs.rmSync(root, {recursive: true, force: true});+ }+}+describe('stable and canary publication authority', () => {it('keeps stable explicit and canary limited to main pushes', () => {expect(stable.if).toBe("github.event_name == 'workflow_dispatch'");@@ -609,4 +651,97 @@ describe('stable publish requires the cut commit release-check (spec:AST-030 FR1expect(stable.steps[guard]['continue-on-error']).toBeUndefined();expect(stable.permissions.actions).toBe('read');});++ it('passes the release when every package is readable in the first window', () => {+ const result = runStablePublish({verifyExit: 0});++ expect(result.status).toBe(0);+ expect(result.output).toContain('verified=true');+ });++ it('ends the publish job as "not yet readable", not failed, and hands over to a follow-up', () => {+ const result = runStablePublish({verifyExit: 2});++ expect(result.status).toBe(0);+ expect(result.output).toContain('verified=pending');+ expect(result.stdout).toContain('not yet readable on the registry');+ });++ it('still fails the publish job on a verification error', () => {+ const result = runStablePublish({verifyExit: 1});++ expect(result.status).toBe(1);+ expect(result.output).not.toContain('verified=');+ });++ it('runs at most two bounded follow-up verification jobs, each only while packages are pending', () => {+ const first = workflow.jobs['verify-registry-1'];+ const last = workflow.jobs['verify-registry-2'];+ const followUps = Object.keys(workflow.jobs).filter(name =>+ name.startsWith('verify-registry'),+ );++ expect(followUps).toEqual(['verify-registry-1', 'verify-registry-2']);+ expect(stable.outputs.verified).toBe(+ '${{ steps.publish.outputs.verified }}',+ );+ expect(first.needs).toBe('publish');+ expect(first.if).toBe("needs.publish.outputs.verified == 'pending'");+ expect(last.needs).toBe('verify-registry-1');+ expect(last.if).toBe(+ "needs.verify-registry-1.outputs.verified == 'pending'",+ );+ for (const job of [first, last]) {+ expect(job['runs-on']).toBe('ubuntu-latest');+ expect(job['timeout-minutes']).toBeLessThanOrEqual(10);+ expect(job.permissions).toEqual({contents: 'read'});+ expect(step(job, 'Verify published packages').run).toContain(+ 'node scripts/npm/verify-published.mjs --version "$RELEASE_VERSION" --tag latest --window-ms 420000',+ );+ }+ });++ it('hands a still-pending check from the first follow-up to the last one', () => {+ const pending = runFollowUp(workflow.jobs['verify-registry-1'], 2);+ expect(pending.status).toBe(0);+ expect(pending.output).toContain('verified=pending');++ const readable = runFollowUp(workflow.jobs['verify-registry-1'], 0);+ expect(readable.status).toBe(0);+ expect(readable.output).toContain('verified=true');+ });++ it('fails the release when the last follow-up still finds a package unreadable', () => {+ const result = runFollowUp(workflow.jobs['verify-registry-2'], 2);++ expect(result.status).toBe(2);+ expect(result.stdout).toContain(+ 'still not readable on the registry after three verification windows',+ );+ });++ it('lets nothing act on a stable release before the final verification decides the run', () => {+ // Every job that depends on the publish job is the next verification+ // window, so no release step can start on the publish job's pass alone.+ const dependents = name =>+ Object.entries(workflow.jobs)+ .filter(([, job]) => [job.needs].flat().includes(name))+ .map(([jobName]) => jobName);+ expect(dependents('publish')).toEqual(['verify-registry-1']);+ expect(dependents('verify-registry-1')).toEqual(['verify-registry-2']);+ expect(dependents('verify-registry-2')).toEqual([]);++ // Pending in the publish job and in follow-up 1, still unreadable in+ // follow-up 2: the run ends failed, so anything that waits for the run's+ // conclusion does not proceed.+ const publish = runStablePublish({verifyExit: 2});+ const first = runFollowUp(workflow.jobs['verify-registry-1'], 2);+ const last = runFollowUp(workflow.jobs['verify-registry-2'], 2);+ const jobResults = [publish.status, first.status, last.status];+ expect(jobResults).toEqual([0, 0, 2]);+ expect(jobResults.some(status => status !== 0)).toBe(true);+ expect(stable.outputs.verified).toBeDefined();+ expect(publish.output).toContain('verified=pending');+ expect(first.output).toContain('verified=pending');+ });});diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 6b40c9ba9b..dbe0389733 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -24,6 +24,13 @@# release branch and head. Stable publication from main is rejected.# Version-gated and idempotent: any version already on the registry is# skipped, so re-running (or a `dry-run` first) is safe.+# Registry verification runs in bounded windows: the publish job's own,+# then at most two follow-up verification jobs while packages are not yet+# readable. Anything that acts on a stable release (the GitHub+# Release, deployment, merge-back, release receipts, release tracking)+# waits for this workflow run's conclusion, never the publish job's: while+# packages are still propagating, the publish job passes and a follow-up+# job decides the run.# - canary: push to main only. Main normally declares the next planned version,# so this publishes <declared>-canary.<short-sha> to the `canary` dist-tag.# The trusted release merge-back briefly leaves main equal to the stable tag;@@ -94,6 +101,8 @@ jobs:actions: readcontents: readid-token: write # npm OIDC trusted publishing + provenance+ outputs:+ verified: ${{ steps.publish.outputs.verified }}steps:- name: Checkout immutable release taguses: actions/checkout@v7@@ -174,6 +183,7 @@ jobs:run: pnpm build- name: Publish changed packages+ id: publishenv:DRY_RUN: ${{ inputs.dry-run }}RELEASE_VERSION: ${{ inputs['release-version'] }}@@ -233,12 +243,96 @@ jobs:if [ "$DRY_RUN" = "true" ]; thenecho "Dry run complete; no packages were published."else+ # One bounded verification window. Packages that are still not+ # readable when it ends (exit 2) do not fail the release: the+ # follow-up verification jobs below continue with windows of+ # their own.+ STATUS=0node scripts/npm/verify-published.mjs \--version "$RELEASE_VERSION" \- --tag latest- echo "Published $published package(s); registry verification passed."+ --tag latest || STATUS=$?+ case "$STATUS" in+ 0)+ echo "verified=true" >> "$GITHUB_OUTPUT"+ echo "Published $published package(s); registry verification passed."+ ;;+ 2)+ echo "verified=pending" >> "$GITHUB_OUTPUT"+ echo "::notice::Published $published package(s); some are not yet readable on the registry. A follow-up verification job continues."+ ;;+ *)+ exit "$STATUS"+ ;;+ esacfi+ # Follow-up registry verification: each job is one more bounded window for+ # packages that were published but not yet readable, with the same exact-+ # version proofs. The last one fails the release if a package is still not+ # readable.+ # A follow-up starts no check after 7 minutes, which leaves room in its+ # 10-minute limit for checkout, Node setup and a last slow check.+ verify-registry-1:+ name: Verify registry (follow-up 1)+ needs: publish+ if: needs.publish.outputs.verified == 'pending'+ runs-on: ubuntu-latest+ timeout-minutes: 10+ permissions:+ contents: read+ outputs:+ verified: ${{ steps.verify.outputs.verified }}+ steps:+ - name: Checkout immutable release tag+ uses: actions/checkout@v7+ - name: Setup Node+ uses: ./.github/actions/setup+ with:+ install: 'false'+ - name: Verify published packages+ id: verify+ env:+ RELEASE_VERSION: ${{ inputs['release-version'] }}+ run: |+ set -eu+ STATUS=0+ node scripts/npm/verify-published.mjs --version "$RELEASE_VERSION" --tag latest --window-ms 420000 || STATUS=$?+ case "$STATUS" in+ 0) echo "verified=true" >> "$GITHUB_OUTPUT" ;;+ 2)+ echo "verified=pending" >> "$GITHUB_OUTPUT"+ echo "::notice::Some packages are still not readable on the registry. The last follow-up verification job continues."+ ;;+ *) exit "$STATUS" ;;+ esac++ verify-registry-2:+ name: Verify registry (follow-up 2, last)+ needs: verify-registry-1+ if: needs.verify-registry-1.outputs.verified == 'pending'+ runs-on: ubuntu-latest+ timeout-minutes: 10+ permissions:+ contents: read+ steps:+ - name: Checkout immutable release tag+ uses: actions/checkout@v7+ - name: Setup Node+ uses: ./.github/actions/setup+ with:+ install: 'false'+ - name: Verify published packages+ env:+ RELEASE_VERSION: ${{ inputs['release-version'] }}+ run: |+ set -eu+ STATUS=0+ node scripts/npm/verify-published.mjs --version "$RELEASE_VERSION" --tag latest --window-ms 420000 || STATUS=$?+ if [ "$STATUS" -eq 2 ]; then+ echo "::error::Published packages are still not readable on the registry after three verification windows."+ fi+ exit "$STATUS"+# Canary publish — runs on every push to main. The @canary dist-tag always# points to the latest main commit:# npm install @astryxdesign/core@canarydiff --git a/scripts/npm/verify-published.mjs b/scripts/npm/verify-published.mjsindex abc4595f22..eb3d559d0e 100644--- a/scripts/npm/verify-published.mjs+++ b/scripts/npm/verify-published.mjs@@ -8,6 +8,13 @@* tarball response for each package before the release workflow reports* success. Packages that are already visible are not fetched again while a* slower package continues propagating.+ *+ * One run is a bounded window: the wait between checks starts at 15 s and+ * grows to at most 60 s, and no new check starts after 8 minutes. A new+ * version of a package with a very large registry document can take longer+ * than that to become readable, so packages still unreadable at the end exit 2+ * ("not yet readable") rather than 1, and the release workflow continues in a+ * follow-up verification job with a window of its own.*/import fs from 'node:fs';@@ -21,8 +28,26 @@ import {fetchVersionDocument,} from './registry.mjs';-const DEFAULT_ATTEMPTS = 41;const DEFAULT_INTERVAL_MS = 15_000;+const DEFAULT_MAX_INTERVAL_MS = 60_000;+const DEFAULT_WINDOW_MS = 8 * 60_000;+const INTERVAL_GROWTH = 1.5;+export const EXIT_NOT_YET_READABLE = 2;++/** Packages still unreadable when a verification window ends. */+export class NotYetReadableError extends Error {}++/** The wait before check `attempt + 1`: grows by half, capped. */+export function verificationWait(+ attempt,+ intervalMs = DEFAULT_INTERVAL_MS,+ maxIntervalMs = DEFAULT_MAX_INTERVAL_MS,+) {+ return Math.min(+ Math.round(intervalMs * INTERVAL_GROWTH ** (attempt - 1)),+ maxIntervalMs,+ );+}async function jsonResponse(response, label) {if (response.status !== 200) {@@ -84,16 +109,19 @@ export async function verifyPublishedPackages({version,tag = 'latest',registry = DEFAULT_REGISTRY,- attempts = DEFAULT_ATTEMPTS,intervalMs = DEFAULT_INTERVAL_MS,+ maxIntervalMs = DEFAULT_MAX_INTERVAL_MS,+ windowMs = DEFAULT_WINDOW_MS,fetchImpl = fetch,+ now = () => Date.now(),sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),onAttempt = () => {},}) {const pending = new Map(packages.map(name => [name, 'not checked']));- for (let attempt = 1; attempt <= attempts; attempt += 1) {+ const start = now();+ for (let attempt = 1; ; attempt += 1) {const names = [...pending.keys()];- onAttempt({attempt, attempts, names});+ onAttempt({attempt, names, elapsedMs: now() - start});await Promise.all(names.map(async name => {try {@@ -111,9 +139,11 @@ export async function verifyPublishedPackages({}),);if (pending.size === 0) return;- if (attempt < attempts) await sleep(intervalMs);+ const wait = verificationWait(attempt, intervalMs, maxIntervalMs);+ if (now() - start + wait > windowMs) break;+ await sleep(wait);}- throw new Error(+ throw new NotYetReadableError([...pending].map(([name, error]) => `${name}@${version}: ${error}`).join('\n'),@@ -156,7 +186,7 @@ function parseArgs(argv) {const value = argv[index + 1];if (!key?.startsWith('--') || value == null) {throw new Error(- 'expected --version X.Y.Z and optional --tag, --registry, --attempts, or --interval-ms',+ 'expected --version X.Y.Z and optional --tag, --registry, --interval-ms, --max-interval-ms, or --window-ms',);}values[key.slice(2)] = value;@@ -174,6 +204,21 @@ async function main() {path.dirname(fileURLToPath(import.meta.url)),'../..',);+ const timing = Object.fromEntries(+ [+ ['interval-ms', DEFAULT_INTERVAL_MS],+ ['max-interval-ms', DEFAULT_MAX_INTERVAL_MS],+ ['window-ms', DEFAULT_WINDOW_MS],+ ].map(([key, fallback]) => {+ const value = Number(values[key] ?? fallback);+ if (!Number.isFinite(value) || value < 0) {+ throw new Error(+ `--${key} must be a non-negative number of milliseconds`,+ );+ }+ return [key, value];+ }),+ );const packages = stablePackageNames(root, version);if (packages.length === 0) throw new Error('no stable packages found');await verifyPublishedPackages({@@ -181,11 +226,12 @@ async function main() {version,tag: values.tag ?? 'latest',registry: values.registry ?? DEFAULT_REGISTRY,- attempts: Number(values.attempts ?? DEFAULT_ATTEMPTS),- intervalMs: Number(values['interval-ms'] ?? DEFAULT_INTERVAL_MS),- onAttempt({attempt, attempts, names}) {+ intervalMs: timing['interval-ms'],+ maxIntervalMs: timing['max-interval-ms'],+ windowMs: timing['window-ms'],+ onAttempt({attempt, names, elapsedMs}) {console.log(- `Registry verification ${attempt}/${attempts}: ${names.length} package(s) pending`,+ `Registry verification ${attempt} after ${Math.round(elapsedMs / 1000)} s: ${names.length} package(s) pending`,);},});@@ -199,6 +245,12 @@ if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {main().catch(error => {+ if (error instanceof NotYetReadableError) {+ console.error(+ `published packages are not yet readable on the registry:\n${error.message}`,+ );+ process.exit(EXIT_NOT_YET_READABLE);+ }console.error(`published package registry verification failed:\n${error.message}`,);diff --git a/scripts/npm/verify-published.test.mjs b/scripts/npm/verify-published.test.mjsindex faf6282efa..f47748b7ca 100644--- a/scripts/npm/verify-published.test.mjs+++ b/scripts/npm/verify-published.test.mjs@@ -1,5 +1,6 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+import {spawnSync} from 'node:child_process';import fs from 'node:fs';import os from 'node:os';import path from 'node:path';@@ -7,7 +8,9 @@ import path from 'node:path';import {afterEach, describe, expect, it} from 'vitest';import {+ NotYetReadableError,stablePackageNames,+ verificationWait,verifyPublishedPackages,verifyRegistryEntry,} from './verify-published.mjs';@@ -110,7 +113,6 @@ describe('verifyPublishedPackages', () => {await verifyPublishedPackages({packages: ['@astryxdesign/cli', '@astryxdesign/core'],version: '0.7.5',- attempts: 2,intervalMs: 1,fetchImpl,sleep: async ms => sleeps.push(ms),@@ -129,8 +131,8 @@ describe('verifyPublishedPackages', () => {verifyPublishedPackages({packages: ['@astryxdesign/core'],version: '0.7.5',- attempts: 2,intervalMs: 0,+ windowMs: 0,fetchImpl: async () => response({}, 404),sleep: async () => {},}),@@ -182,3 +184,107 @@ describe('stablePackageNames', () => {);});});++describe('verification window', () => {+ /** A clock that moves only when the verifier sleeps. */+ function clock() {+ let time = 0;+ const sleeps = [];+ return {+ sleeps,+ now: () => time,+ sleep: async ms => {+ sleeps.push(ms);+ time += ms;+ },+ };+ }++ it('waits 15 s first and grows by half to at most 60 s', () => {+ expect(+ [1, 2, 3, 4, 5, 6].map(attempt => verificationWait(attempt)),+ ).toEqual([15_000, 22_500, 33_750, 50_625, 60_000, 60_000]);+ });++ it('starts no check after 8 minutes, then reports the packages as not yet readable', async () => {+ const time = clock();+ const result = verifyPublishedPackages({+ packages: ['@astryxdesign/core'],+ version: '0.7.5',+ fetchImpl: async () => response({}, 404),+ now: time.now,+ sleep: time.sleep,+ });+ await expect(result).rejects.toBeInstanceOf(NotYetReadableError);+ await expect(result).rejects.toThrow('version document returned HTTP 404');+ const total = time.sleeps.reduce((sum, wait) => sum + wait, 0);+ expect(total).toBeLessThanOrEqual(8 * 60_000);+ expect(total).toBeGreaterThan(7 * 60_000);+ });++ it('passes as soon as a slow package becomes readable inside the window', async () => {+ const time = clock();+ let coreReads = 0;+ await verifyPublishedPackages({+ packages: ['@astryxdesign/core'],+ version: '0.7.5',+ now: time.now,+ sleep: time.sleep,+ fetchImpl: async url => {+ if (url.includes('/dist-tags')) return response({latest: '0.7.5'});+ if (url.endsWith('.tgz')) return response('tarball');+ coreReads += 1;+ if (coreReads < 4) return response({}, 404);+ return response({+ version: '0.7.5',+ dist: {tarball: 'https://registry.npmjs.org/core-0.7.5.tgz'},+ });+ },+ });+ expect(time.sleeps).toEqual([15_000, 22_500, 33_750]);+ });++ it('exits 2, "not yet readable", when the window ends with packages unreadable', () => {+ const root = path.resolve(import.meta.dirname, '../..');+ const {version} = JSON.parse(+ fs.readFileSync(path.join(root, 'packages/core/package.json'), 'utf8'),+ );+ const result = spawnSync(+ process.execPath,+ [+ 'scripts/npm/verify-published.mjs',+ '--version',+ version,+ '--registry',+ 'http://127.0.0.1:9',+ '--window-ms',+ '0',+ ],+ {cwd: root, encoding: 'utf8', timeout: 20_000},+ );+ expect(result.status).toBe(2);+ expect(result.stderr).toContain('not yet readable on the registry');+ });++ it('refuses a window that is not a number, which would never end', () => {+ const root = path.resolve(import.meta.dirname, '../..');+ const {version} = JSON.parse(+ fs.readFileSync(path.join(root, 'packages/core/package.json'), 'utf8'),+ );+ const result = spawnSync(+ process.execPath,+ [+ 'scripts/npm/verify-published.mjs',+ '--version',+ version,+ '--window-ms',+ '8m',+ ],+ {cwd: root, encoding: 'utf8', timeout: 20_000},+ );+ expect(result.status).toBe(1);+ expect(result.stderr).toContain(+ '--window-ms must be a non-negative number of milliseconds',+ );+ });+});