Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/runtime/child-process.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -313,7 +313,7 @@ childProc.disconnect();

### IPC between Bun & Node.js

To use IPC between a `bun` process and a Node.js process, set `serialization: "json"` in `Bun.spawn`. This is because Node.js and Bun use different JavaScript engines with different object serialization formats.
To use IPC between a `bun` process and a Node.js process, set `serialization: "json"` in `Bun.spawn`. This is because Node.js and Bun use different JavaScript engines with different object serialization formats. If the formats do not match, the Bun process reports the first message it cannot decode as an uncaught exception and closes the channel.

```js bun-node-ipc.js icon="file-code"
if (typeof Bun !== "undefined") {
Expand Down
47 changes: 46 additions & 1 deletion src/runtime/ipc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -982,6 +982,29 @@ impl SendQueueOwner {
SendQueueOwner::Instance(_) => JSValue::ZERO,
}
}

/// Names the process at the other end of the channel in error messages.
fn peer(self) -> PeerName {
match self {
// SAFETY: an attached owner is live (it holds a ref on the SendQueue).
SendQueueOwner::Subprocess(p) => PeerName::Subprocess(unsafe { p.as_ref() }.pid()),
SendQueueOwner::Instance(_) => PeerName::Parent,
}
}
}

enum PeerName {
Subprocess(i32),
Parent,
}

impl core::fmt::Display for PeerName {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
PeerName::Subprocess(pid) => write!(f, "The subprocess (pid {pid})"),
PeerName::Parent => f.write_str("The parent process"),
}
}
}

#[derive(Copy, Clone, Eq, PartialEq)]
Expand Down Expand Up @@ -2267,12 +2290,34 @@ fn finish_decode(send_queue: &SendQueue, step: &DecodeStep) {
crate::dispatch::fold(Err(*err));
send_queue.close_socket(CloseReason::Failure, CloseFrom::User);
}
DecodeStep::Fail(_) => {
// Closed first, so an `uncaughtException` handler sees the channel disconnected.
DecodeStep::Fail(IPCDecodeError::InvalidFormat) => {
send_queue.close_socket(CloseReason::Failure, CloseFrom::User);
report_undecodable_message(send_queue);
}
DecodeStep::Fail(IPCDecodeError::Stopped | IPCDecodeError::NotEnoughBytes) => {
send_queue.close_socket(CloseReason::Failure, CloseFrom::User);
}
}
}

fn report_undecodable_message(send_queue: &SendQueue) {
let Some(owner) = send_queue.owner_ref() else {
return;
};
let global = send_queue.get_global_this();
let peer = owner.peer();
let err = match send_queue.mode {
Mode::Advanced => global.create_error_instance(format_args!(
"{peer} sent an IPC message that is not in Bun's \"advanced\" serialization format, so Bun closed the IPC channel. \"advanced\" serialization only works between two Bun processes. For IPC between Bun and Node.js, use serialization: \"json\"."
)),
Mode::Json => global.create_error_instance(format_args!(
"{peer} sent an IPC message that is not valid JSON, so Bun closed the IPC channel."
)),
Comment on lines +2314 to +2316

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 nit (optional): a user debugging a bad "json" IPC line gets only "not valid JSON" and never learns what was rejected or why. The parser's SyntaxError is discarded by global_this.clear_exception() at src/runtime/ipc.rs:533 before the InvalidFormat report is built, and the report at src/runtime/ipc.rs:2314-2316 echoes neither that message nor any part of the line. Fix: carry the cause into the report, e.g. keep the SyntaxError's message (or a bounded prefix of the offending line) alongside InvalidFormat and append it to the "json" error text, so the same report also covers the empty-line and lone-tag-byte rejections at ipc.rs:491-492.

Why this was flagged

A peer in serialization "json" writes a line such as "undefined\n" or "{not json\n"; it arrives through on_data2 -> decode_next_json -> json::decode_ipc_message (src/runtime/ipc.rs:456). to_js_by_parse_json throws a SyntaxError that names the bad token; the Err(JsError::Thrown) arm at src/runtime/ipc.rs:531-534 calls clear_exception() and returns InvalidFormat, so the cause is gone. finish_decode then calls report_undecodable_message (src/runtime/ipc.rs:2304), whose Mode::Json arm at 2314-2316 formats only the peer name and the fixed sentence "sent an IPC message that is not valid JSON, so Bun closed the IPC channel." The user sees a report (the base branch printed nothing) but cannot tell which line or which parse failure caused it; Node, whose behaviour the PR cites, surfaces the SyntaxError itself with the unexpected token. REVIEW.md asks that error messages carry the rejected value and the underlying cause; this one carries neither. No safeguard prevents it: the exception is cleared before any caller can read it.

Verification: nit. Any peer in serialization "json" writes a line that JSON.parse rejects. /home/claude/bun/src/runtime/ipc.rs:521 throws a SyntaxError; the Err(JsError::Thrown) arm at lines 531-535 does global_this.clear_exception(); return Err(IPCDecodeError::InvalidFormat);, so the parser's message is discarded. The message at 2314-2316 is built solely from {peer} and fixed text.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The SyntaxError is cleared in json::decode_ipc_message on main too, so the report in this PR has no cause to show. To carry it (for example as the cause of the reported error) changes the shape of that error, and the shape is the open question on this PR. I will add it in the shape that a maintainer picks.

};
crate::dispatch::fold(Err(global.throw_value(err)));
}

fn decode_next_json(incoming: &JsCell<IncomingBuffer>, global: &JSGlobalObject) -> DecodeStep {
incoming.with_mut(|inc| {
let IncomingBuffer::Json(json_buf) = inc else {
Expand Down
52 changes: 52 additions & 0 deletions test/js/bun/spawn/spawn.ipc.bun-node.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,58 @@ p I am your father
expect(await new Response(child.stderr).text()).toEqual("");
});

// A Bun parent with no uncaughtException handler whose Node.js child sends one
// message. `spawnOptions` is spliced into the Bun.spawn() options.
async function bunParentOfNodeChild(spawnOptions: string, message: string) {
const parentSource = `
const child = Bun.spawn({
cmd: [process.env.NODE_BIN, "-e", 'process.send(${message}, () => process.disconnect())'],
stdio: ["ignore", "inherit", "inherit"],
${spawnOptions}
ipc(message) { console.log("UNEXPECTED_IPC_MESSAGE", message); },
});
await child.exited;
`;

await using proc = Bun.spawn({
cmd: [bunExe(), "-e", parentSource],
env: { ...bunEnv, NODE_BIN: nodeExe()! },
stdout: "pipe",
stderr: "pipe",
});

const [stdout, stderr, exitCode] = await Promise.all([proc.stdout.text(), proc.stderr.text(), proc.exited]);
return { stdout, stderr, exitCode };
}

test.skipIf(!nodeExe())(
'a node child under the default serialization is reported, with the "json" remedy',
async () => {
// Bun.spawn({ ipc }) defaults to serialization: "advanced", which only Bun
// speaks. A Node.js child answers in v8's framing; the parent cannot decode it
// and must fail loudly instead of leaving the user with a channel that never
// delivers anything.
const { stdout, stderr, exitCode } = await bunParentOfNodeChild("", `{ hello: "from node" }`);

// No uncaughtException handler: the parent exits 1 at the report.
expect(stdout).toBe("");
expect(stderr).toContain(
`sent an IPC message that is not in Bun's "advanced" serialization format, so Bun closed the IPC channel. "advanced" serialization only works between two Bun processes. For IPC between Bun and Node.js, use serialization: "json".`,
);
expect(exitCode).toBe(1);
},
);

test.skipIf(!nodeExe())("a line from a node child that is not JSON is reported", async () => {
// JSON.stringify() of an object whose toJSON() returns undefined is undefined,
// so Node.js writes the line "undefined" to the channel.
const { stdout, stderr, exitCode } = await bunParentOfNodeChild(`serialization: "json",`, `{ toJSON() {} }`);

expect(stdout).toBe("");
expect(stderr).toContain("sent an IPC message that is not valid JSON, so Bun closed the IPC channel.");
expect(exitCode).toBe(1);
});

test.skipIf(isWindows || !nodeExe())(
"receives a net.Socket handle from a node child and releases its descriptor",
async () => {
Expand Down
62 changes: 61 additions & 1 deletion test/js/bun/spawn/spawn.ipc.node-bun.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { expect, test } from "bun:test";
import { bunExe } from "harness";
import { bunEnv, bunExe, nodeExe } from "harness";
import path from "path";

test("ipc with json serialization still works when bun is not the parent and the child", async () => {
Expand All @@ -19,3 +19,63 @@ p I am your father
`,
);
});

// A Node.js parent that sends one message to a Bun child with no
// uncaughtException handler. Returns what the parent saw of the child.
async function bunChildOfNodeParent(serialization: "advanced" | "json", message: string) {
const parentSource = `
const { spawn } = require("node:child_process");
const child = spawn(process.argv[1], ["-e", 'process.on("message", msg => console.log("UNEXPECTED_IPC_MESSAGE", msg));'], {
stdio: ["ignore", "pipe", "pipe", "ipc"],
serialization: "${serialization}",
});
let stdout = "", stderr = "";
child.stdout.setEncoding("utf8").on("data", chunk => (stdout += chunk));
child.stderr.setEncoding("utf8").on("data", chunk => (stderr += chunk));
child.on("close", (exitCode, signalCode) => {
console.log(JSON.stringify({ stdout, stderr, exitCode, signalCode }));
});
child.send(${message});
`;

await using proc = Bun.spawn({
cmd: [nodeExe()!, "-e", parentSource, bunExe()],
env: bunEnv,
stdout: "pipe",
stderr: "pipe",
});

const [stdout, stderr, exitCode] = await Promise.all([proc.stdout.text(), proc.stderr.text(), proc.exited]);
expect(stderr).toBe("");
expect(exitCode).toBe(0);
return JSON.parse(stdout) as { stdout: string; stderr: string; exitCode: number | null; signalCode: string | null };
}

test.skipIf(!nodeExe())(
'a bun child of a node parent using serialization: "advanced" reports the mismatch',
async () => {
// Node's "advanced" serialization is v8's wire format, which Bun cannot decode.
Comment on lines +55 to +57

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 nit (optional): the new subprocess tests run serially, so the suite takes longer than it needs to on the debug/ASAN lanes. sweep:^test\.skipIf\(!nodeExe\(\)\)\( Each new test in spawn.ipc.node-bun.test.ts:55 and spawn.ipc.bun-node.test.ts:46 spawns a node parent/child plus a bun process and shares no state with its neighbours. Fix: make every independent subprocess test in the two files test.concurrent.skipIf(!nodeExe())(...) (test/CLAUDE.md asks for concurrent tests whenever several tests in one file spawn processes), leaving the fixture-based first test alone if it must stay serial.

Why this was flagged

test/CLAUDE.md says to prefer test.concurrent when multiple tests in the same file spawn processes. The four tests added at test/js/bun/spawn/spawn.ipc.node-bun.test.ts:55 and :72 and test/js/bun/spawn/spawn.ipc.bun-node.test.ts:46 and :66 each spawn a node process that in turn spawns or is spawned by a bun process, and none of them share files, ports or globals. They are declared with plain test.skipIf(!nodeExe()), so each file's two-process startups run one after another; on debug+ASAN CI lanes (10-100x slower per test/CLAUDE.md) that is avoidable wall time. The base branch had only one serial test per file, so the cost is new with this change. No functional failure; this is a convention slip.

Verification: nit. Triggering condition: whenever the suite runs, the four new two-process tests execute one after another. Mechanism verified: test/js/bun/spawn/spawn.ipc.node-bun.test.ts:54 and :71 and test/js/bun/spawn/spawn.ipc.bun-node.test.ts:46 and :64 are all declared test.skipIf(!nodeExe())(...). test/CLAUDE.md:22 states "Prefer concurrent tests over sequential tests".

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. test.concurrent.skipIf(!nodeExe()) is the form the repo uses. I am not pushing for this alone, because a push restarts the CI run that this PR waits on. It goes in with the next push to this branch.

// The child must report the first such message instead of dropping the channel
// silently.
const child = await bunChildOfNodeParent("advanced", `{ hello: "from node" }`);

// No uncaughtException handler in the child: it exits 1 at the report.
expect(child.stdout).toBe("");
expect(child.stderr).toContain(
`The parent process sent an IPC message that is not in Bun's "advanced" serialization format, so Bun closed the IPC channel. "advanced" serialization only works between two Bun processes. For IPC between Bun and Node.js, use serialization: "json".`,
);
expect({ exitCode: child.exitCode, signalCode: child.signalCode }).toEqual({ exitCode: 1, signalCode: null });
},
);

test.skipIf(!nodeExe())("a bun child reports a line from a node parent that is not JSON", async () => {
// JSON.stringify() of an object whose toJSON() returns undefined is undefined,
// so Node.js writes the line "undefined" to the channel.
const child = await bunChildOfNodeParent("json", `{ toJSON() {} }`);

expect(child.stdout).toBe("");
expect(child.stderr).toContain(
"The parent process sent an IPC message that is not valid JSON, so Bun closed the IPC channel.",
);
expect({ exitCode: child.exitCode, signalCode: child.signalCode }).toEqual({ exitCode: 1, signalCode: null });
});
Loading
Loading