Add clickhouse-wsproxy: standalone WebSocket proxy (prototype)

[peter-leonov-ch]

Prototype of a standalone WebSocket proxy built on the ClickHouse native-protocol client layer.

clickhouse-wsproxy is a separate binary, deliberately kept out of the multi-call clickhouse dispatch (its own clickhouse_add_executable, no mainEntryClickHouseWsProxy, no clickhouse_program_install line). It reuses Connection and FormatFactory while dropping the CLI/ClientBase layer, and serves a WebSocket endpoint through ClickHouse's own HTTPServer.

Motivation is deployment velocity: run format conversion and mid-query push (Progress/ProfileEvents/Log) at an edge sidecar instead of requiring managed-cloud changes.

Scope so far (steps 1-2): the standalone build wiring is proven, the global Context and registerFormats are bootstrapped, the RFC 6455 handshake and framing are factored into a reusable module (adapted from WebTerminalRequestHandler), and SIGINT/SIGTERM give a clean shutdown. The WebSocket loop currently echoes frames; the next step replaces it with a native-protocol Connection to a backend server plus edge format conversion.

Note: this targets my fork, not upstream — intentionally kept off the upstream CI and review burden while it is still a prototype.

Changelog category (leave one):

• Experimental Feature

Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):

Added clickhouse-wsproxy, an experimental standalone WebSocket-to-native-protocol proxy (prototype).

[peter-leonov-ch]

Using the proxy from JavaScript

The test suite ships a tiny WebSocket client that doubles as a usage reference — Session, runQuery, and backendScalar are defined in programs/wsproxy/tests/test/helpers.mjs, added in commit 2e7522149b0. They use Node's built-in global WebSocket (Node ≥ 22), so there are no runtime dependencies.

The proxy listens on ws://127.0.0.1:9010. A query is sent as a text frame; results stream back as binary frames in the output format chosen via the URL ?format= parameter; progress and the terminal outcome arrive as JSON text frames ({"event":"end"|"error"|"cancelled"|"progress", ...}).

SELECT

import { runQuery } from "./helpers.mjs";

const { text, control } = await runQuery("SELECT number FROM numbers(5)", {
  format: "JSONEachRow",
});

console.log(control.event); // "end"
console.log(text);          // 5 lines of JSONEachRow

runQuery returns { data: Buffer, text: string, progress: object[], control: { event, message? } }.

Output-format conversion at the edge

(await runQuery("SELECT 42, 'x'", { format: "TSV" })).text; // "42\tx\n"
(await runQuery("SELECT 42, 'x'", { format: "CSV" })).text; // "42,\"x\"\n"
(await runQuery("SELECT 42 AS n", { format: "JSONEachRow" })).text; // {"n":42}

Mid-query progress push

const { progress, control } = await runQuery(
  "SELECT sleepEachRow(0.1), number FROM numbers(30) SETTINGS max_block_size = 1",
);

console.log(control.event);      // "end"
console.log(progress.length);    // several updates pushed while the query ran
console.log(progress.at(-1));    // { event: "progress", read_rows: 30, read_bytes: …, total_rows_to_read: 30 }

INSERT (streaming data to the backend)

import { Session } from "./helpers.mjs";

const s = new Session("JSONEachRow");
const { control } = await s.insert(
  "INSERT INTO default.events FORMAT JSONEachRow",
  ['{"a":1,"b":"x"}\n', '{"a":2,"b":"y"}\n'], // streamed as binary frames
);
console.log(control.event); // "end"
s.close();

Inline VALUES works too (the Values input format is inferred):

await new Session().insert("INSERT INTO default.events VALUES (10, 'v'), (11, 'w')", []);

Cancellation

Closing the socket mid-query cancels the running query server-side:

const s = new Session("JSONEachRow");
await s.ready();
s.sendQuery("SELECT sleepEachRow(0.2), number FROM numbers(1000) SETTINGS max_block_size = 1");

// read a frame or two…
await s.nextFrame();

s.close(); // -> proxy calls Connection::sendCancel; the backend stops the query

Error handling

Backend errors are delivered as a terminal control frame rather than a broken stream:

const { control } = await runQuery("SELECT * FROM default.no_such_table");
// control.event === "error", control.message === "DB::Exception: … Unknown table …"

Errors / verifying server state

backendScalar(sql) runs a query as TSV and returns the trimmed text — handy for assertions:

import { backendScalar } from "./helpers.mjs";
await backendScalar("SELECT count() FROM default.events"); // "2"

---

The Session/runQuery/backendScalar API above is defined in commit 2e7522149b0; run the suite with cd programs/wsproxy/tests && npm install && npm test.