Skip to content

Commit 28bb13f

Browse files
Brooooooklynclaude
andauthored
fix(cloudflare): stop on unsupported runtimes and keep deploy failures readable and safe (#721)
Fixes #627 ## What went wrong ``` generated Bun workflow (setup-bun only) └─ bunx void deploy → "#!/usr/bin/env node" → runner Node 22 ├─ build, checks, cf children ── work on Node 22 └─ credential helper child ── fails to load (node:http has no setGlobalProxyFromEnv) ├─ reason dropped → "Cloudflare session has no bearer for version-aware upload." └─ later run: trigger sync failed after go-live └─ recovery switched traffic back to an empty previous version → secrets looked gone ``` The keyring flag in the issue plays no part: with `CLOUDFLARE_API_TOKEN` set, the token is returned before any keyring use. ## Changes | Part | Change | |---|---| | Runtime | `void` and `create-void` check the runtime first and stop with a clear message on Node outside `^24.22.0 \|\| >=26.12.0` or Bun < 1.4.0. The bin entry imports only the check, then loads the CLI, so an old Node never hits a load-time `SyntaxError`. | | CI template | `void init --github` adds `actions/setup-node` to Bun workflows; setup-node gets `check-latest: true`. | | Child errors | One reporter for Cloudflare child steps: exit code / signal / spawn error plus a stderr tail. Credentials are scrubbed by exact value before truncation; the credential step's stdout is never logged. "no bearer" becomes the real cause. | | Logs | Each child step writes a debug `cloudflare_op` record; `cloudflare_deploy_failed` carries reason, status and version ids; failures write `deploy_end`. Log writes are synchronous so records survive `process.exit`. | | Settings | When observability/logpush settings will be published, the credential is read before upload, so a missing credential leaves traffic unchanged. The publish step reads a fresh one. | | Recovery | If trigger sync fails after go-live and the previous version is an empty draft, a placeholder, or has no Void trigger snapshot, the new version stays live. `activeVersionId` always names the live version; new `triggersRestored` / `restoreSkipped` fields. The message always says `Live now: <id>` and gives Cloudflare's reason. | | keep_vars | `keep_vars` no longer drops secret types from the kept bindings (regression from 546a76e; hardening, not the reporter's cause). | Recovery decision table: ``` trigger sync fails after N got 100% previous P = Void version with trigger snapshot ─► switch back to P, replay its triggers previous P = draft / placeholder / non-Void ─────► keep N live, say so P could not be read ──────────────────────────────► keep N live, no rollback hint someone else moved traffic ───────────────────────► report the live version, no switch ``` ## Release notes (behaviour changes) - Every `void` command, including `--help`, now exits 1 on Node 22, 24.14–24.21, 25.x or 26.0–26.11, and on Bun < 1.4.0. Existing Bun CI workflows need an `actions/setup-node` step (Node 24.22+) before `bunx void`. - `@void/deploy-cloudflare`: trigger-failure results always set `activeVersionId` and add `triggersRestored` and `restoreSkipped`. - Deploy log files are created owner-only (0600). ## Not in this PR - Warning before deploying over a version another tool made, a check for declared secrets missing on the live version, trigger preflight, and auto-retry. These are separate product decisions. - A few exits (migration check, prompt cancel, managed deploy Ctrl-C) still skip `deploy_end`; their earlier records now reach disk. ## Verification - Built CLI on real Node 22 (Docker): message + exit 1. `create-void` on Node 18/22: message, exit 1, no folder. Node 24.22 and Bun 1.4.4: `void --version` works. - Two review rounds (6 + 3 reviewers, 2 skeptics per finding); 9 confirmed findings fixed, each with a regression test. - `vp run check`: 33/33. `vp run test`: 780 files passed (16082 tests). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 8931ec6 commit 28bb13f

36 files changed

Lines changed: 3696 additions & 675 deletions

‎docs/guide/quickstart.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ yarn void init
2828
```
2929

3030
```sh [bun]
31+
# bunx runs Void with the `node` on your PATH: use Node.js 24.22+ or 26.12+
3132
bun add -D void
3233
bunx void init
3334
```

‎docs/integrations/cloudflare.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ Set production server values with `void secret put <NAME>`. Void preserves exist
174174

175175
### Readiness and rollback
176176

177-
Void normally verifies an uploaded version before sending it traffic. A Worker with workers.dev turned off and no route or Custom Domain has no URL Void can check, so that deploy skips the readiness check and activates the uploaded version. If readiness or trigger updates fail, it restores the previous deployment. Finish or cancel any gradual rollout in Cloudflare before deploying through Void.
177+
Void normally verifies an uploaded version before sending it traffic. A Worker with workers.dev turned off and no route or Custom Domain has no URL Void can check, so that deploy skips the readiness check and activates the uploaded version. If readiness or trigger updates fail, it restores the previous deployment. If trigger updates fail and Void cannot restore the previous version's triggers, for example because another tool deployed it or it is an empty draft, the new version stays live and the error says which version is serving traffic. Finish or cancel any gradual rollout in Cloudflare before deploying through Void.
178178

179179
For an existing Durable Object Worker that Cloudflare cannot stage, review the changes and use:
180180

‎docs/reference/cli.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,8 @@ Use this page as a command reference. If you are setting up a project for the fi
8282

8383
The docs use `void` for brevity. Outside package scripts, run it with your package manager: `npx void`, `pnpm void`, `yarn void`, `bunx void`, or `vpx void`.
8484

85+
The CLI needs Node.js 24.22+ or 26.12+. `npx`, `bunx` and package scripts use the `node` on your `PATH`; `vpx` uses the version in `.node-version`.
86+
8587
Alternatively, you can add `./node_modules/.bin` to your `PATH` so that you can invoke `void` directly when you are in the root directory of your app.
8688

8789
:::warning ⚠️ Prefer local install

‎packages/create-void/src/index.ts‎

Lines changed: 14 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,17 @@
11
#!/usr/bin/env node
22

3-
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
4-
import * as p from '@voidzero-dev/vite-plus-prompts';
5-
import { resolve } from 'pathslash';
6-
import pc from 'picocolors';
7-
import { parseCreateArgs, validateProjectName } from './args.ts';
8-
import { detectPM, pmExec, pmInstall, run, writePnpmBuildPolicy } from './pm.ts';
9-
10-
const pm = detectPM();
11-
12-
async function main() {
13-
console.log();
14-
15-
const createArgs = parseCreateArgs(process.argv.slice(2));
16-
let appName = createArgs.appName;
17-
18-
if (!appName && !process.stdin.isTTY) {
19-
p.log.error('create-void: Pass a project name when running without an interactive terminal.');
20-
process.exit(1);
21-
}
22-
23-
if (!appName) {
24-
const name = await p.text({
25-
message: 'Project name:',
26-
defaultValue: 'my-app',
27-
placeholder: 'my-app',
28-
validate: validateProjectName,
29-
});
30-
if (p.isCancel(name) || typeof name !== 'string') {
31-
p.cancel('Cancelled.');
32-
process.exit(0);
33-
}
34-
appName = name;
35-
}
36-
37-
const targetDir = resolve(appName);
38-
39-
if (existsSync(targetDir)) {
40-
const entries = readdirSync(targetDir);
41-
if (entries.length > 0) {
42-
p.log.error(`create-void: Directory '${pc.bold(appName)}' is not empty.`);
43-
process.exit(1);
44-
}
45-
}
46-
47-
// The release publishes the scaffolder and CLI at the same version. Preserve
48-
// that exact version, including prereleases, instead of switching to latest.
49-
const { version: voidVersion } = JSON.parse(
50-
readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
51-
) as { version: string };
52-
53-
mkdirSync(targetDir, { recursive: true });
54-
55-
const pkg = {
56-
name: appName,
57-
private: true,
58-
type: 'module',
59-
devDependencies: {
60-
void: voidVersion,
61-
},
62-
};
63-
64-
writeFileSync(resolve(targetDir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
65-
// pnpm 12 fails the first install when a dependency has an unapproved build
66-
// script. Write Void's narrow policy before installing the CLI so a fresh
67-
// project can bootstrap without disabling pnpm's build-script protection.
68-
writePnpmBuildPolicy(targetDir, pm);
69-
70-
p.log.step('Installing Void...');
71-
await run(pmInstall(pm), targetDir);
72-
73-
p.log.step('Scaffolding starter...');
74-
await run([...pmExec(pm), 'void', 'init', ...createArgs.initArgs], targetDir);
75-
76-
p.log.step('Installing starter dependencies...');
77-
await run(pmInstall(pm), targetDir);
78-
79-
p.outro(`\n${pc.green(`✓ Created ${appName}`)}`, { withGuide: false });
80-
p.outro(`cd ${appName} && ${pm === 'npm' ? 'npm run' : pm} dev`);
3+
// The bin entry. It imports only the dependency-free runtime check, so an
4+
// unsupported Node or Bun gets a clear message instead of a link-time
5+
// SyntaxError from a newer API in the bundled prompts. `void init` stops on an
6+
// unsupported runtime too, so checking first keeps a failed run from leaving a
7+
// half-created folder that blocks the next attempt.
8+
import { unsupportedRuntimeMessage } from './runtime-support.ts';
9+
10+
const message = unsupportedRuntimeMessage(process.versions, process.execPath, 'create-void');
11+
if (message) {
12+
process.stderr.write(`${message}\n`);
13+
// exitCode instead of exit() so the message is flushed when stderr is a pipe.
14+
process.exitCode = 1;
15+
} else {
16+
await import('./main.ts');
8117
}
82-
83-
main().catch((err) => {
84-
p.log.error(err.message);
85-
process.exit(1);
86-
});

‎packages/create-void/src/main.ts‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
2+
import * as p from '@voidzero-dev/vite-plus-prompts';
3+
import { resolve } from 'pathslash';
4+
import pc from 'picocolors';
5+
import { parseCreateArgs, validateProjectName } from './args.ts';
6+
import { detectPM, pmExec, pmInstall, run, writePnpmBuildPolicy } from './pm.ts';
7+
8+
const pm = detectPM();
9+
10+
async function main() {
11+
console.log();
12+
13+
const createArgs = parseCreateArgs(process.argv.slice(2));
14+
let appName = createArgs.appName;
15+
16+
if (!appName && !process.stdin.isTTY) {
17+
p.log.error('create-void: Pass a project name when running without an interactive terminal.');
18+
process.exit(1);
19+
}
20+
21+
if (!appName) {
22+
const name = await p.text({
23+
message: 'Project name:',
24+
defaultValue: 'my-app',
25+
placeholder: 'my-app',
26+
validate: validateProjectName,
27+
});
28+
if (p.isCancel(name) || typeof name !== 'string') {
29+
p.cancel('Cancelled.');
30+
process.exit(0);
31+
}
32+
appName = name;
33+
}
34+
35+
const targetDir = resolve(appName);
36+
37+
if (existsSync(targetDir)) {
38+
const entries = readdirSync(targetDir);
39+
if (entries.length > 0) {
40+
p.log.error(`create-void: Directory '${pc.bold(appName)}' is not empty.`);
41+
process.exit(1);
42+
}
43+
}
44+
45+
// The release publishes the scaffolder and CLI at the same version. Preserve
46+
// that exact version, including prereleases, instead of switching to latest.
47+
const { version: voidVersion } = JSON.parse(
48+
readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
49+
) as { version: string };
50+
51+
mkdirSync(targetDir, { recursive: true });
52+
53+
const pkg = {
54+
name: appName,
55+
private: true,
56+
type: 'module',
57+
devDependencies: {
58+
void: voidVersion,
59+
},
60+
};
61+
62+
writeFileSync(resolve(targetDir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
63+
// pnpm 12 fails the first install when a dependency has an unapproved build
64+
// script. Write Void's narrow policy before installing the CLI so a fresh
65+
// project can bootstrap without disabling pnpm's build-script protection.
66+
writePnpmBuildPolicy(targetDir, pm);
67+
68+
p.log.step('Installing Void...');
69+
await run(pmInstall(pm), targetDir);
70+
71+
p.log.step('Scaffolding starter...');
72+
await run([...pmExec(pm), 'void', 'init', ...createArgs.initArgs], targetDir);
73+
74+
p.log.step('Installing starter dependencies...');
75+
await run(pmInstall(pm), targetDir);
76+
77+
p.outro(`\n${pc.green(`✓ Created ${appName}`)}`, { withGuide: false });
78+
p.outro(`cd ${appName} && ${pm === 'npm' ? 'npm run' : pm} dev`);
79+
}
80+
81+
main().catch((err) => {
82+
p.log.error(err.message);
83+
process.exit(1);
84+
});
Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
// Checks the runtime before the CLI loads. On an older Node, a static import of a
2+
// newer API (such as `setGlobalProxyFromEnv` from `node:http`) fails at link time
3+
// with a SyntaxError before any code can run, and child processes reuse
4+
// `process.execPath`, so a deploy would stop halfway. This file must therefore
5+
// load on any Node or Bun release: it has no imports and uses no new APIs.
6+
//
7+
// packages/void/src/cli/runtime-support.ts and packages/create-void/src/runtime-support.ts
8+
// are byte-identical copies, because create-void runs before `void` is installed.
9+
// A unit test keeps the two files and both `engines.node` fields equal.
10+
11+
/** Must equal `engines.node` in packages/void and packages/create-void. */
12+
export const NODE_ENGINES = '^24.22.0 || >=26.12.0';
13+
14+
/**
15+
* Bun is not a documented runtime, but `bunx --bun` and Bun-only images (where
16+
* `node` is Bun) run the CLI on it. Bun reports a Node version below 26.12, so
17+
* it gets its own floor: 1.4.0 is the first release where Void's Cloudflare
18+
* helper process loads. This lets working setups keep working.
19+
*/
20+
export const BUN_MINIMUM = '1.4.0';
21+
22+
type Version = [major: number, minor: number, patch: number];
23+
24+
export type RuntimeVersions = { readonly node?: string; readonly bun?: string };
25+
26+
function isDigits(text: string): boolean {
27+
if (text.length === 0) {
28+
return false;
29+
}
30+
for (let i = 0; i < text.length; i++) {
31+
const code = text.charCodeAt(i);
32+
if (code < 48 || code > 57) {
33+
return false;
34+
}
35+
}
36+
return true;
37+
}
38+
39+
/**
40+
* Parses `1.2.3`, with an optional leading `v`. A pre-release or build tag
41+
* (`27.0.0-nightly2026...`, `1.4.0+abc`) is ignored, so a nightly counts as its
42+
* release line.
43+
*/
44+
export function parseVersion(text: string): Version | null {
45+
let core = text.trim();
46+
if (core.startsWith('v')) {
47+
core = core.slice(1);
48+
}
49+
for (const separator of ['-', '+']) {
50+
const index = core.indexOf(separator);
51+
if (index !== -1) {
52+
core = core.slice(0, index);
53+
}
54+
}
55+
const parts = core.split('.');
56+
if (parts.length !== 3 || !parts.every(isDigits)) {
57+
return null;
58+
}
59+
return [Number(parts[0]), Number(parts[1]), Number(parts[2])];
60+
}
61+
62+
function compareVersions(a: Version, b: Version): number {
63+
return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
64+
}
65+
66+
type Clause = { caret: boolean; version: Version };
67+
68+
/** Supports only the forms used in `engines.node`: `^x.y.z` and `>=x.y.z`, joined by `||`. */
69+
function parseRange(range: string): Array<Clause> {
70+
return range.split('||').map((raw) => {
71+
const clause = raw.trim();
72+
const caret = clause.startsWith('^');
73+
const prefix = caret ? '^' : clause.startsWith('>=') ? '>=' : null;
74+
const version = prefix === null ? null : parseVersion(clause.slice(prefix.length));
75+
if (!version) {
76+
throw new Error(`runtime-support: unsupported range clause '${clause}'`);
77+
}
78+
return { caret, version };
79+
});
80+
}
81+
82+
export function satisfiesRange(version: Version, range: string): boolean {
83+
return parseRange(range).some(
84+
({ caret, version: floor }) =>
85+
compareVersions(version, floor) >= 0 && (!caret || version[0] === floor[0]),
86+
);
87+
}
88+
89+
/** `^24.22.0 || >=26.12.0` -> `24.22+ or 26.12+`. */
90+
function describeRange(range: string): string {
91+
return parseRange(range)
92+
.map(({ version: [major, minor, patch] }) =>
93+
patch === 0 ? `${major}.${minor}+` : `${major}.${minor}.${patch}+`,
94+
)
95+
.join(' or ');
96+
}
97+
98+
/**
99+
* Returns the error to print when this runtime cannot run the CLI, or `null`.
100+
* The text names only the runtime version and executable path, never env or argv.
101+
*/
102+
export function unsupportedRuntimeMessage(
103+
versions: RuntimeVersions,
104+
execPath: string,
105+
command = 'void',
106+
): string | null {
107+
const nodeRange = describeRange(NODE_ENGINES);
108+
if (versions.bun !== undefined) {
109+
const bun = parseVersion(versions.bun);
110+
const minimum = parseVersion(BUN_MINIMUM);
111+
if (bun && minimum && compareVersions(bun, minimum) >= 0) {
112+
return null;
113+
}
114+
return (
115+
`${command}: Bun ${BUN_MINIMUM} or later is required. Found Bun ${versions.bun} (${execPath}).\n` +
116+
`Update Bun, or run ${command} on Node.js ${nodeRange}.`
117+
);
118+
}
119+
const node = versions.node === undefined ? null : parseVersion(versions.node);
120+
if (node && satisfiesRange(node, NODE_ENGINES)) {
121+
return null;
122+
}
123+
const found = versions.node === undefined ? 'an unknown version' : `v${versions.node}`;
124+
return (
125+
`${command}: Node.js ${nodeRange} is required. Found Node.js ${found} (${execPath}).\n` +
126+
'bunx, npx and package scripts use the `node` on PATH; vp/vpx use .node-version.\n' +
127+
'Update .node-version or the node on PATH. In GitHub Actions add actions/setup-node\n' +
128+
'with `node-version: lts/*` and `check-latest: true` before this step.'
129+
);
130+
}
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import { spawnSync } from 'node:child_process';
2+
import { mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
3+
import { tmpdir } from 'node:os';
4+
import { join } from 'node:path';
5+
import { pathToFileURL } from 'node:url';
6+
import { afterAll, beforeAll, describe, expect, it } from 'vite-plus/test';
7+
8+
const ENTRY = join(import.meta.dirname, '..', '..', 'src', 'index.ts');
9+
10+
let root: string;
11+
12+
beforeAll(() => {
13+
root = mkdtempSync(join(tmpdir(), 'create-void-entry-'));
14+
});
15+
16+
afterAll(() => {
17+
rmSync(root, { recursive: true, force: true });
18+
});
19+
20+
describe('create-void entry', () => {
21+
it('prints the runtime message before any other module links', () => {
22+
// An old Node fails to link a module that imports a newer API (for example `styleText`
23+
// from node:util in the bundled prompts). The hook makes every module other than the
24+
// entry and the runtime check fail the same way, so the message must come first.
25+
const preload = join(root, 'old-node.mjs');
26+
writeFileSync(
27+
preload,
28+
`import { registerHooks } from 'node:module';
29+
Object.defineProperty(process, 'versions', { value: { ...process.versions, node: '18.20.8' } });
30+
const allowed = [${JSON.stringify(pathToFileURL(ENTRY).href)}, ${JSON.stringify(
31+
pathToFileURL(join(ENTRY, '..', 'runtime-support.ts')).href,
32+
)}];
33+
registerHooks({
34+
resolve(specifier, context, next) {
35+
const result = next(specifier, context);
36+
if (!allowed.includes(result.url)) {
37+
throw new SyntaxError('cannot link ' + result.url);
38+
}
39+
return result;
40+
},
41+
});
42+
`,
43+
);
44+
const result = spawnSync(
45+
process.execPath,
46+
['--import', pathToFileURL(preload).href, ENTRY, 'my-app'],
47+
{ cwd: root, encoding: 'utf8', env: { PATH: process.env.PATH } },
48+
);
49+
50+
expect(result.status).toBe(1);
51+
expect(result.stderr.split('\n')[0]).toBe(
52+
`create-void: Node.js 24.22+ or 26.12+ is required. Found Node.js v18.20.8 (${process.execPath}).`,
53+
);
54+
expect(readdirSync(root)).not.toContain('my-app');
55+
});
56+
});

0 commit comments

Comments
 (0)