Skip to content

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.mjs
index 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 FR1
expect(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.yml
index 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: read
contents: read
id-token: write # npm OIDC trusted publishing + provenance
+ outputs:
+ verified: ${{ steps.publish.outputs.verified }}
steps:
- name: Checkout immutable release tag
uses: actions/checkout@v7
@@ -174,6 +183,7 @@ jobs:
run: pnpm build
- name: Publish changed packages
+ id: publish
env:
DRY_RUN: ${{ inputs.dry-run }}
RELEASE_VERSION: ${{ inputs['release-version'] }}
@@ -233,12 +243,96 @@ jobs:
if [ "$DRY_RUN" = "true" ]; then
echo "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=0
node 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"
+ ;;
+ esac
fi
+ # 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@canary
diff --git a/scripts/npm/verify-published.mjs b/scripts/npm/verify-published.mjs
index 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.mjs
index 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',
+ );
+ });
+});