@essential-apps/shopify-test-runner 1.0.0

package/src/lib/functionBuild.ts

@@ -0,0 +1,490 @@
+/**
+ * Compile a JS Shopify Function source tree into a deployable `.wasm`
+ * WITHOUT shelling out to the Shopify CLI.
+ *
+ * Why this exists
+ * ---------------
+ * `shopify app function build` is the canonical way to produce the
+ * `.wasm` artifact that Shopify Functions accepts. Tests in this repo
+ * are forbidden from depending on the Shopify CLI (binary mismatch
+ * across dev machines, interactive prompts, version drift) — so we
+ * replicate the pipeline directly.
+ *
+ * The pipeline is small and well-isolated. Traced from
+ * `Shopify/cli@packages/app/src/cli/services/function/build.ts`:
+ *
+ *   1. esbuild — bundle the user's JS source into a single ES module
+ *      whose default export is a thin wrapper around
+ *      `@shopify/shopify_function/run`. esbuild's Node API, no
+ *      subprocess.
+ *
+ *   2. javy build — wraps the bundled JS in a Wizened QuickJS runtime
+ *      AND links Shopify's host-binding plugin (`-C dynamic -C
+ *      plugin=shopify_functions_javy_v3.wasm`). Output: a stand-alone
+ *      .wasm module that the Shopify Functions runtime can invoke
+ *      directly.
+ *
+ * No "trampoline" step is required for current
+ * `@shopify/shopify_function` runtimes — the plugin v3 + Javy 7 combo
+ * already targets the modern host ABI. (Trampoline exists in the CLI
+ * but is conditional on legacy `shopify_function_v{1,2}` imports.)
+ *
+ * Pinned versions
+ * ---------------
+ * Javy:    bytecodealliance/javy v7.0.1 (stock upstream, NOT a Shopify
+ *          fork — the Shopify-specific glue lives entirely in the
+ *          plugin .wasm we pass to `-C plugin=`).
+ * Plugin:  https://cdn.shopify.com/shopifycloud/shopify-functions-javy-plugin/
+ *          shopify_functions_javy_v3.wasm
+ *          (version-pinned in URL path; Shopify CDN, effectively
+ *          immutable — when Shopify ships `_v4` we bump the const.)
+ *
+ * Binaries are cached at
+ *   ~/.cache/essential-apps-shopify-test/bin/
+ * keyed by version so multiple test workspaces share the same download.
+ */
+import { chmodSync, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
+import { createGunzip } from 'node:zlib';
+import { Readable } from 'node:stream';
+import * as esbuild from 'esbuild';
+
+const execFileP = promisify(execFile);
+
+/**
+ * Pinned Javy version. Bumping = updating the URL pattern in
+ * `binaryUrlForJavy` AND verifying the `-C` flag interface hasn't
+ * changed across the bump (Javy did break flags between v0.x and v3+).
+ */
+export const JAVY_VERSION = 'v7.0.1';
+
+/**
+ * Pinned Shopify Functions Javy plugin wasm. The URL contains the
+ * major version (`_v3`) — if Shopify publishes a `_v4`, we explicitly
+ * decide whether to upgrade (the plugin's host ABI is what user JS
+ * sees via `@shopify/shopify_function`).
+ */
+export const PLUGIN_URL =
+  'https://cdn.shopify.com/shopifycloud/shopify-functions-javy-plugin/shopify_functions_javy_v3.wasm';
+
+/** Filename under the cache dir for the plugin (derived from URL). */
+const PLUGIN_FILENAME = 'shopify_functions_javy_v3.wasm';
+
+/** `world` name we declare in the synthesized WIT — must match the
+ * `wit-world` flag passed to `javy build`. The literal string is
+ * uninteresting (Javy uses it only to disambiguate worlds in the WIT
+ * file); we follow the CLI's value to minimize surprise. */
+const JAVY_WORLD_NAME = 'shopify-function';
+
+function cacheDir(): string {
+  const dir = join(homedir(), '.cache', 'essential-apps-shopify-test', 'bin');
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Map Node's `process.{platform,arch}` to the asset-name suffix
+ * bytecodealliance/javy uses in its GitHub releases. Mismatches here
+ * surface as 404s from the GitHub redirect, so it's worth keeping the
+ * list explicit rather than guessing.
+ *
+ * Known asset names at v7.0.1:
+ *   javy-arm-macos-v7.0.1.gz
+ *   javy-x86_64-macos-v7.0.1.gz
+ *   javy-arm-linux-v7.0.1.gz
+ *   javy-x86_64-linux-v7.0.1.gz
+ *   javy-x86_64-windows-v7.0.1.gz   (no arm-windows)
+ */
+function platformArch(): string {
+  const p = process.platform;
+  const a = process.arch;
+  const plat = p === 'darwin' ? 'macos' : p === 'linux' ? 'linux' : p === 'win32' ? 'windows' : null;
+  const arch = a === 'arm64' ? 'arm' : a === 'x64' ? 'x86_64' : null;
+  if (!plat || !arch) {
+    throw new Error(`Unsupported platform/arch for Javy: ${p}/${a}`);
+  }
+  if (plat === 'windows' && arch === 'arm') {
+    throw new Error(`Javy ${JAVY_VERSION} has no arm-windows build; install x86_64 Node or run under Rosetta.`);
+  }
+  return `${arch}-${plat}`;
+}
+
+function javyUrl(version: string): string {
+  return `https://github.com/bytecodealliance/javy/releases/download/${version}/javy-${platformArch()}-${version}.gz`;
+}
+
+/**
+ * Stream a remote .gz binary to a local file, decompressing on the
+ * way. Atomic via tmp + rename so concurrent test workers don't see
+ * partial files.
+ */
+async function downloadGz(url: string, dest: string): Promise<void> {
+  const tmp = `${dest}.tmp.${process.pid}`;
+  const r = await fetch(url);
+  if (!r.ok || !r.body) {
+    throw new Error(`Failed to download ${url} — HTTP ${r.status}`);
+  }
+  // `r.body` is a Web ReadableStream; convert to a Node Readable so
+  // we can pipe it through Node's gunzip + file sink.
+  const src = Readable.fromWeb(r.body as never);
+  await pipeline(src, createGunzip(), createWriteStream(tmp));
+  // chmod before rename so the executable bit is set atomically with
+  // the visible filename.
+  chmodSync(tmp, 0o755);
+  await import('node:fs/promises').then(({ rename }) => rename(tmp, dest));
+}
+
+/**
+ * Download a remote file as-is (no decompression). Used for the plugin
+ * wasm which is served uncompressed by Shopify's CDN.
+ */
+async function downloadFile(url: string, dest: string): Promise<void> {
+  const tmp = `${dest}.tmp.${process.pid}`;
+  const r = await fetch(url);
+  if (!r.ok || !r.body) {
+    throw new Error(`Failed to download ${url} — HTTP ${r.status}`);
+  }
+  const src = Readable.fromWeb(r.body as never);
+  await pipeline(src, createWriteStream(tmp));
+  await import('node:fs/promises').then(({ rename }) => rename(tmp, dest));
+}
+
+/**
+ * Return a path to the Javy binary, downloading it on first use.
+ * Idempotent — second call hits the on-disk cache. `JAVY_BIN`
+ * environment variable bypasses the download and points at a local
+ * build (useful when tracking Javy main).
+ */
+export async function ensureJavy(): Promise<string> {
+  const override = process.env['JAVY_BIN'];
+  if (override) {
+    if (!existsSync(override)) {
+      throw new Error(`JAVY_BIN points at non-existent file: ${override}`);
+    }
+    return override;
+  }
+  const dest = join(cacheDir(), `javy-${JAVY_VERSION}`);
+  if (existsSync(dest)) return dest;
+  const url = javyUrl(JAVY_VERSION);
+  console.log(`  ↓ Downloading Javy ${JAVY_VERSION} from ${url}`);
+  await downloadGz(url, dest);
+  return dest;
+}
+
+/**
+ * Return a path to the Shopify Functions Javy plugin wasm,
+ * downloading it on first use. `JAVY_PLUGIN_WASM` env overrides for
+ * local plugin development.
+ */
+export async function ensureJavyPlugin(): Promise<string> {
+  const override = process.env['JAVY_PLUGIN_WASM'];
+  if (override) {
+    if (!existsSync(override)) {
+      throw new Error(`JAVY_PLUGIN_WASM points at non-existent file: ${override}`);
+    }
+    return override;
+  }
+  const dest = join(cacheDir(), PLUGIN_FILENAME);
+  if (existsSync(dest)) return dest;
+  console.log(`  ↓ Downloading Shopify Functions Javy plugin from ${PLUGIN_URL}`);
+  await downloadFile(PLUGIN_URL, dest);
+  return dest;
+}
+
+/**
+ * One `[[extensions.targeting]]` block in a function's
+ * `shopify.extension.toml`. Maps to one exported function in the
+ * compiled wasm.
+ *
+ *   target       e.g. "cart.lines.discounts.generate.run"  (Shopify-defined)
+ *   export       e.g. "cart-lines-discounts-generate-run"  (what we name
+ *                the wasm export — Shopify's docs use kebab-case here)
+ *   input_query  path (relative to the function dir) of the GraphQL
+ *                query that produces the function's input — embedded
+ *                into the deploy manifest, NOT compiled into the wasm.
+ */
+export interface FunctionTarget {
+  target: string;
+  export: string;
+  inputQueryPath: string;
+}
+
+/**
+ * Subset of `shopify.extension.toml` that we care about for the build.
+ * We don't validate fields we don't use (e.g. `name`/`description`
+ * which come from locales) so this shape may grow as we touch more
+ * function deploys.
+ */
+export interface ParsedFunctionToml {
+  handle: string;
+  /** Stable per-extension UUID baked into the toml. Shopify uses it
+   * to correlate the manifest entry with the right folder inside the
+   * source zip (the zip layout is `<uid>/dist/function.wasm`). */
+  uid: string;
+  type: 'function';
+  apiVersion: string;
+  /** Each target becomes one exported function in the compiled wasm. */
+  targets: FunctionTarget[];
+  /** `[extensions.build].path` — defaults to `dist/function.wasm`. */
+  outputRelativePath: string;
+}
+
+/**
+ * Bespoke parser for the function's `shopify.extension.toml`. The
+ * minimal-toml reader in `deployAppVersion.ts` doesn't grok arrays of
+ * inline tables (`[[extensions.targeting]]`), so we do a tiny ad-hoc
+ * parse here. It's intentionally narrow — only handles the shape
+ * `shopify app function init` produces (essentially: a single
+ * `[[extensions]]` table containing N `[[extensions.targeting]]`
+ * sub-tables and one `[extensions.build]` sub-table).
+ *
+ * If/when we deploy a function with multiple top-level `[[extensions]]`
+ * entries (rare — usually one file per extension dir), this needs
+ * generalizing.
+ */
+export function parseFunctionToml(path: string): ParsedFunctionToml {
+  const txt = readFileSync(path, 'utf8');
+  const lines = txt.split('\n').map((l) => l.replace(/#.*$/, '').replace(/\s+$/, ''));
+
+  // We track the most-recently-opened table header so kv-lines are
+  // attached to the right place.
+  let section: 'extensions' | 'targeting' | 'build' | 'other' = 'other';
+
+  const targetingBlocks: Array<Partial<FunctionTarget>> = [];
+  let cur: Partial<FunctionTarget> | null = null;
+  const ext: { handle?: string; uid?: string; type?: string } = {};
+  let apiVersion = '';
+  const build: { path?: string } = {};
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line === '[[extensions]]') {
+      section = 'extensions';
+      continue;
+    }
+    if (line === '[[extensions.targeting]]') {
+      section = 'targeting';
+      cur = {};
+      targetingBlocks.push(cur);
+      continue;
+    }
+    if (line === '[extensions.build]') {
+      section = 'build';
+      continue;
+    }
+    if (line.startsWith('[')) {
+      section = 'other';
+      continue;
+    }
+    const m = line.match(/^([a-z_][a-z0-9_]*)\s*=\s*"(.*)"$/i);
+    if (!m) continue;
+    const [, k, v] = m;
+    if (section === 'targeting' && cur) {
+      if (k === 'target') cur.target = v!;
+      else if (k === 'export') cur.export = v!;
+      else if (k === 'input_query') cur.inputQueryPath = v!;
+    } else if (section === 'extensions') {
+      if (k === 'handle') ext.handle = v!;
+      else if (k === 'uid') ext.uid = v!;
+      else if (k === 'type') ext.type = v!;
+    } else if (section === 'build') {
+      if (k === 'path') build.path = v!;
+    } else if (section === 'other') {
+      if (k === 'api_version') apiVersion = v!;
+    }
+  }
+  if (!ext.handle || !ext.uid || ext.type !== 'function') {
+    throw new Error(
+      `Invalid function toml at ${path} — expected [[extensions]] with handle/uid/type=function. Got: ${JSON.stringify(ext)}`,
+    );
+  }
+  const targets: FunctionTarget[] = [];
+  for (const t of targetingBlocks) {
+    if (!t.target || !t.export || !t.inputQueryPath) {
+      throw new Error(
+        `Invalid [[extensions.targeting]] in ${path} — needs target/export/input_query. Got: ${JSON.stringify(t)}`,
+      );
+    }
+    targets.push(t as FunctionTarget);
+  }
+  if (targets.length === 0) {
+    throw new Error(`No [[extensions.targeting]] blocks in ${path} — at least one is required.`);
+  }
+  return {
+    handle: ext.handle,
+    uid: ext.uid,
+    type: 'function',
+    apiVersion: apiVersion || 'unknown',
+    targets,
+    outputRelativePath: build.path ?? 'dist/function.wasm',
+  };
+}
+
+/**
+ * The CLI's `ExportJavyBuilder` synthesises an esbuild entry that
+ * re-exports each `[[extensions.targeting]].export` as a top-level
+ * function, delegating to the user's symbol of the same name. We
+ * mirror that exactly — variable names are arbitrary internal
+ * identifiers, only the EXPORTED names matter (they're what Javy
+ * sees and what Shopify's runtime invokes).
+ *
+ * Why kebab-case in the export string matches the JS identifier:
+ * Shopify's convention uses kebab-case in toml. The matching JS
+ * identifier is the camelCase form (per the Shopify CLI's
+ * convention). We accept both spellings — fall back to camelCase if
+ * the source happens not to define the literal kebab name (which is
+ * not a valid JS identifier anyway when used directly).
+ */
+function jsIdent(exportName: string): string {
+  // kebab-case -> camelCase (Shopify CLI convention for the user-side
+  // entry symbol). `cart-lines-discounts-generate-run` →
+  // `cartLinesDiscountsGenerateRun`.
+  return exportName.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+function synthesizeEntry(targets: FunctionTarget[]): string {
+  // The exported NAME has to be the camelCase form of the WIT identifier.
+  // Javy translates WIT `%kebab-case-name` → JS export `camelCaseName` when
+  // resolving the world's exports. If the JS module exports the kebab-case
+  // string form, Javy fails with:
+  //   "JS module does not export camelCaseName"
+  // (Confirmed empirically — see commit history.) The user's source code
+  // also exports camelCase by convention.
+  const importLines: string[] = [
+    `import __runFunction from "@shopify/shopify_function/run";`,
+  ];
+  const exportLines: string[] = [];
+  for (let i = 0; i < targets.length; i++) {
+    const t = targets[i]!;
+    const ident = jsIdent(t.export);
+    importLines.push(
+      `import { ${ident} as __target${i} } from "user-function";`,
+    );
+    exportLines.push(
+      `export function ${ident}() { return __runFunction(__target${i}); }`,
+    );
+  }
+  return `${importLines.join('\n')}\n${exportLines.join('\n')}\n`;
+}
+
+/**
+ * Synthesize the WIT world file that Javy needs to know which
+ * exports to lift from the JS module. The CLI generates this on the
+ * fly per build; we follow suit.
+ */
+function synthesizeWit(targets: FunctionTarget[]): string {
+  const exports = targets
+    .map((t) => `  export %${t.export}: func();`)
+    .join('\n');
+  return `package shopify:function;\nworld ${JAVY_WORLD_NAME} {\n${exports}\n}\n`;
+}
+
+/** Identify the user-source entry path. Function dirs traditionally
+ *  use `src/index.ts` (TypeScript) or `src/index.js`. We accept both
+ *  — if neither exists, the error message points at the convention. */
+function findEntrySource(functionDir: string): string {
+  for (const candidate of ['src/index.ts', 'src/index.js']) {
+    const p = resolve(functionDir, candidate);
+    if (existsSync(p)) return p;
+  }
+  throw new Error(
+    `No function entry found in ${functionDir}. Expected one of: src/index.ts, src/index.js`,
+  );
+}
+
+export interface BuildFunctionWasmOptions {
+  /** Directory containing `shopify.extension.toml` + `src/index.{ts,js}`. */
+  functionDir: string;
+  /**
+   * Optional override for the input source file. Defaults to
+   * src/index.ts / src/index.js. Useful for tests.
+   */
+  entrySource?: string;
+}
+
+export interface BuildFunctionWasmResult {
+  wasmPath: string;
+  parsedToml: ParsedFunctionToml;
+}
+
+/**
+ * Build a deployable `.wasm` for a JS Shopify Function.
+ *
+ * Idempotent: rebuilds on every call (we don't try to be clever about
+ * stale-cache detection — esbuild + javy together are ~hundreds of
+ * milliseconds, fast enough that incremental caching is unnecessary
+ * for our use case).
+ */
+export async function buildFunctionWasm(
+  opts: BuildFunctionWasmOptions,
+): Promise<BuildFunctionWasmResult> {
+  const { functionDir } = opts;
+  const tomlPath = resolve(functionDir, 'shopify.extension.toml');
+  if (!existsSync(tomlPath)) {
+    throw new Error(`No shopify.extension.toml at ${tomlPath}`);
+  }
+  const toml = parseFunctionToml(tomlPath);
+  console.log(
+    `  • function ${toml.handle} (uid=${toml.uid}, ${toml.targets.length} target(s), api ${toml.apiVersion})`,
+  );
+
+  const entryPath = opts.entrySource ?? findEntrySource(functionDir);
+  const outputWasm = resolve(functionDir, toml.outputRelativePath);
+  const distDir = dirname(outputWasm);
+  mkdirSync(distDir, { recursive: true });
+
+  // Step 1: bundle JS with esbuild.
+  const bundledJs = resolve(distDir, 'function.js');
+  const entryContents = synthesizeEntry(toml.targets);
+  await esbuild.build({
+    stdin: {
+      contents: entryContents,
+      resolveDir: functionDir,
+      loader: 'ts',
+      sourcefile: 'shopify-function-entry.ts',
+    },
+    bundle: true,
+    format: 'esm',
+    target: 'es2022',
+    legalComments: 'none',
+    outfile: bundledJs,
+    alias: {
+      'user-function': entryPath,
+    },
+    // Node-side bundler. Functions don't have access to Node APIs
+    // (the runtime is QuickJS via Javy), so we set platform=neutral
+    // and don't try to polyfill anything Node-specific.
+    platform: 'neutral',
+    // QuickJS exposes a recent-ish JS surface but ECMAScript modules
+    // are handled by Javy's runtime — esbuild's `format: esm` output
+    // is what Javy expects.
+    mainFields: ['module', 'main'],
+    conditions: ['shopify_function', 'import', 'default'],
+  });
+
+  // Step 2: WIT + javy build.
+  const witPath = resolve(distDir, 'javy-world.wit');
+  writeFileSync(witPath, synthesizeWit(toml.targets), 'utf8');
+
+  const [javy, plugin] = await Promise.all([ensureJavy(), ensureJavyPlugin()]);
+  const javyArgs = [
+    'build',
+    '-C', 'dynamic',
+    '-C', `plugin=${plugin}`,
+    '-C', `wit=${witPath}`,
+    '-C', `wit-world=${JAVY_WORLD_NAME}`,
+    '-o', outputWasm,
+    bundledJs,
+  ];
+  // `cwd: functionDir` so Javy resolves any relative paths in its
+  // diagnostics (it doesn't, AFAICT, but parity with the CLI is
+  // cheap).
+  await execFileP(javy, javyArgs, { cwd: functionDir, maxBuffer: 50 * 1024 * 1024 });
+
+  return { wasmPath: outputWasm, parsedToml: toml };
+}

package/src/lib/neonWsProxy.ts

@@ -0,0 +1,124 @@
+import net from 'node:net';
+import { WebSocketServer, type WebSocket } from 'ws';
+
+export interface StartNeonWsProxyOptions {
+  /** Port to listen on (0 = OS-assigned). */
+  port?: number;
+  /** Listen host. Default 127.0.0.1. */
+  host?: string;
+  /** Postgres host to forward to. Default 127.0.0.1. */
+  targetHost?: string;
+  /** Postgres port to forward to. Default 5432. */
+  targetPort?: number;
+}
+
+export interface StartedNeonWsProxy {
+  /** Port the proxy listens on. */
+  port: number;
+  /** Stop the proxy + close all bridged sockets. */
+  close: () => Promise<void>;
+}
+
+/**
+ * Minimal WebSocket→TCP proxy implementing the transport the Neon
+ * serverless driver (`@neondatabase/serverless`) speaks to its
+ * `wsProxy`. It lets a consuming app's UNMODIFIED prisma client (which
+ * uses `new Pool()` from @neondatabase/serverless + `@prisma/adapter-neon`)
+ * talk to the offline-full suite's plain LOCAL Postgres — no app-source
+ * change, which is the whole point of zero-app-touch onboarding.
+ *
+ * Target resolution: when `wsProxy` is a custom function, the driver
+ * connects to `ws://<wsProxy()>` and does NOT append the DB address to
+ * the URL (verified empirically — `?address` is empty), so we forward to
+ * a CONFIGURED fixed Postgres (`targetHost`/`targetPort`). The Postgres
+ * wire-protocol startup packet (forwarded byte-for-byte) carries the
+ * user + database from the connection string, so a fixed server target
+ * is sufficient. We still honour `?address=` if a driver version sets it.
+ *
+ * `localhost` is normalised to `127.0.0.1`: some resolvers / Docker map
+ * localhost→::1 where Postgres may listen only on IPv4.
+ *
+ * Faithful passthrough by design: the REAL Neon driver runs unchanged;
+ * we only relocate its endpoint to local Postgres, avoiding the
+ * adapter-compat risk of swapping in a different pg driver.
+ */
+export async function startNeonWsProxy(
+  opts: StartNeonWsProxyOptions = {},
+): Promise<StartedNeonWsProxy> {
+  const host = opts.host ?? '127.0.0.1';
+  const norm = (h: string): string => (h === 'localhost' ? '127.0.0.1' : h);
+  const defaultTargetHost = norm(opts.targetHost ?? '127.0.0.1');
+  const defaultTargetPort = opts.targetPort ?? 5432;
+
+  return new Promise<StartedNeonWsProxy>((resolve, reject) => {
+    const wss = new WebSocketServer({ port: opts.port ?? 0, host });
+
+    wss.once('error', reject);
+    wss.once('listening', () => {
+      wss.off('error', reject);
+      const addr = wss.address();
+      const port = typeof addr === 'object' && addr ? addr.port : Number(opts.port ?? 0);
+      resolve({
+        port,
+        close: () =>
+          new Promise<void>((res) => {
+            for (const client of wss.clients) {
+              try {
+                client.terminate();
+              } catch {
+                /* ignore */
+              }
+            }
+            wss.close(() => res());
+          }),
+      });
+    });
+
+    wss.on('connection', (ws: WebSocket, req) => {
+      let targetHost = defaultTargetHost;
+      let targetPort = defaultTargetPort;
+      // Honour `?address=host:port` if the driver ever provides it;
+      // otherwise fall back to the configured fixed Postgres.
+      const address = new URL(req.url ?? '/', 'http://localhost').searchParams.get('address');
+      if (address) {
+        const i = address.lastIndexOf(':');
+        if (i > 0) {
+          targetHost = norm(address.slice(0, i));
+          targetPort = Number(address.slice(i + 1)) || defaultTargetPort;
+        }
+      }
+
+      // net.connect queues writes until connected, so we can wire
+      // `ws → tcp` immediately without racing the connect.
+      const tcp = net.connect({ host: targetHost, port: targetPort });
+
+      let closed = false;
+      const cleanup = (): void => {
+        if (closed) return;
+        closed = true;
+        try {
+          ws.close();
+        } catch {
+          /* ignore */
+        }
+        try {
+          tcp.destroy();
+        } catch {
+          /* ignore */
+        }
+      };
+
+      // `ws` server delivers binary frames as Buffer (binaryType
+      // 'nodebuffer'); the Postgres wire protocol is binary.
+      ws.on('message', (data: Buffer) => tcp.write(data));
+      tcp.on('data', (data) => {
+        if (ws.readyState === ws.OPEN) ws.send(data);
+      });
+
+      ws.on('close', cleanup);
+      ws.on('error', cleanup);
+      tcp.on('close', cleanup);
+      tcp.on('error', cleanup);
+    });
+  });
+}