@limrun/api 0.45.2 → 0.45.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limrun/api",
-  "version": "0.45.2",
+  "version": "0.45.4",
   "description": "The official TypeScript library for the Limrun API",
   "author": "Limrun <contact@limrun.com>",
   "types": "./index.d.ts",
@@ -34,7 +34,7 @@
     "https-proxy-agent": "7.0.6",
     "ignore": "^7.0.5",
     "proxy-from-env": "^2.1.0",
-    "undici": "7.24.7",
+    "undici": "7.28.0",
     "ws": "^8.18.3",
     "yauzl": "^3.4.0"
   },
@@ -198,6 +198,16 @@
     "./ios-client.mjs": {
       "default": "./ios-client.mjs"
     },
+    "./ios-maestro": {
+      "import": "./ios-maestro.mjs",
+      "require": "./ios-maestro.js"
+    },
+    "./ios-maestro.js": {
+      "default": "./ios-maestro.js"
+    },
+    "./ios-maestro.mjs": {
+      "default": "./ios-maestro.mjs"
+    },
     "./ios-shim": {
       "import": "./ios-shim.mjs",
       "require": "./ios-shim.js"

package/src/http-proxy.ts

@@ -1,5 +1,6 @@
 import http from 'http';
 import https from 'https';
+import { pipeline } from 'stream';
 
 export type HttpProxy = {
   port: number;
@@ -12,6 +13,10 @@ export type StartHttpProxyOptions = {
   headers?: Record<string, string>;
 };
 
+/**
+ * Legacy origin-form reverse proxy: forwards every request on the local port
+ * to `remoteBaseUrl`. New callers should prefer `startForwardHttpProxy`.
+ */
 export async function startHttpProxy({
   localPort = 0,
   remoteBaseUrl,
@@ -58,6 +63,139 @@ export async function startHttpProxy({
   };
 }
 
+export type StartForwardHttpProxyOptions = {
+  /** Loopback requests to this port are rewritten to remoteBaseUrl; everything else passes through. */
+  matchPort: number;
+  remoteBaseUrl: string;
+  headers?: Record<string, string>;
+};
+
+// Hop-by-hop headers must not be forwarded by an HTTP proxy (RFC 9110 §7.6.1).
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection',
+  'proxy-connection',
+  'keep-alive',
+  'proxy-authorization',
+  'proxy-authenticate',
+  'te',
+  'trailer',
+  'upgrade',
+]);
+
+function withoutHopByHop(headers: http.IncomingHttpHeaders): http.IncomingHttpHeaders {
+  return Object.fromEntries(Object.entries(headers).filter(([name]) => !HOP_BY_HOP_HEADERS.has(name)));
+}
+
+/**
+ * Single-destination HTTP forward proxy (absolute-form request targets, as sent
+ * by clients configured with e.g. JVM -Dhttp.proxyHost). Loopback requests on
+ * `matchPort` are forwarded to `remoteBaseUrl`; every other target is refused,
+ * so the proxy can only ever reach the destination it was configured with.
+ */
+export async function startForwardHttpProxy({
+  matchPort,
+  remoteBaseUrl,
+  headers = {},
+}: StartForwardHttpProxyOptions): Promise<HttpProxy> {
+  const base = trimTrailingSlashes(remoteBaseUrl);
+  // The driver polls the runner continuously, so upstream connections must be
+  // reused instead of paying a TCP/TLS handshake per driver call.
+  const agents = {
+    'http:': new http.Agent({ keepAlive: true }),
+    'https:': new https.Agent({ keepAlive: true }),
+  };
+  const server = http.createServer((req, res) => {
+    let target: URL | undefined;
+    try {
+      target = new URL(req.url ?? '');
+    } catch {
+      // Falls through to the guard below.
+    }
+    if (!target || (target.protocol !== 'http:' && target.protocol !== 'https:')) {
+      res.writeHead(400, { 'content-type': 'text/plain' });
+      res.end('Limrun forward proxy only accepts absolute-form request targets.');
+      return;
+    }
+
+    // matchPort is always explicit (an ephemeral port or 7001), so a target
+    // without a port can never match. Anything else is refused rather than
+    // forwarded: the requested host never selects the destination, so this
+    // proxy cannot be pointed at another host.
+    if (!isLoopbackHost(target.hostname) || Number(target.port) !== matchPort) {
+      res.writeHead(403, { 'content-type': 'text/plain' });
+      res.end(`Limrun forward proxy only forwards 127.0.0.1:${matchPort}.`);
+      return;
+    }
+
+    const upstreamUrl = new URL(`${base}${target.pathname}${target.search}`);
+    const transport = upstreamUrl.protocol === 'https:' ? https : http;
+    const upstream = transport.request(
+      upstreamUrl,
+      {
+        agent: agents[upstreamUrl.protocol as keyof typeof agents],
+        method: req.method,
+        headers: {
+          ...withoutHopByHop(req.headers),
+          host: upstreamUrl.host,
+          ...headers,
+        },
+      },
+      (upstreamResponse) => {
+        res.writeHead(upstreamResponse.statusCode ?? 502, withoutHopByHop(upstreamResponse.headers));
+        // pipeline tears down whichever side is still alive when the other one
+        // dies, instead of leaking it or raising an unhandled 'error'.
+        pipeline(upstreamResponse, res, () => {});
+      },
+    );
+
+    upstream.on('error', (error) => {
+      if (res.headersSent) {
+        // Mid-stream failure: abort instead of appending error text to a
+        // partial body.
+        res.destroy(error);
+        return;
+      }
+      res.writeHead(502, { 'content-type': 'text/plain' });
+      res.end(error.message);
+    });
+    // A client that aborts mid-call must not leak the upstream socket.
+    res.on('close', () => {
+      if (!res.writableFinished) {
+        upstream.destroy();
+      }
+    });
+    pipeline(req, upstream, () => {});
+  });
+
+  // HTTPS clients open CONNECT tunnels; we deliberately keep TLS traffic off this
+  // proxy (only http.proxyHost is set on the JVM side), so refuse loudly instead
+  // of tunneling blind.
+  server.on('connect', (_req, socket) => {
+    socket.end('HTTP/1.1 501 Not Implemented\r\n\r\nLimrun forward proxy does not tunnel CONNECT.\r\n');
+  });
+
+  await listen(server, 0);
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('Failed to start HTTP forward proxy.');
+  }
+  return {
+    port: address.port,
+    close: async () => {
+      await closeServer(server);
+      agents['http:'].destroy();
+      agents['https:'].destroy();
+    },
+  };
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  // URL.hostname keeps brackets around IPv6 hosts.
+  return (
+    hostname === 'localhost' || hostname === '[::1]' || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)
+  );
+}
+
 function trimTrailingSlashes(value: string): string {
   return value.replace(/\/+$/, '');
 }

package/src/index.ts

@@ -8,7 +8,22 @@ export { Limrun, type ClientOptions } from './client';
 export { PagePromise } from './core/pagination';
 export * from './instance-client';
 export * as Ios from './ios-client';
-export { startHttpProxy, type HttpProxy, type StartHttpProxyOptions } from './http-proxy';
+export {
+  startHttpProxy,
+  startForwardHttpProxy,
+  type HttpProxy,
+  type StartHttpProxyOptions,
+  type StartForwardHttpProxyOptions,
+} from './http-proxy';
+export {
+  prepareMaestroRun,
+  isMaestroRunnerRunning,
+  waitForMaestroRunner,
+  maestroSpawnOptions,
+  MAESTRO_RUNNER_BUNDLE_ID,
+  MAESTRO_RUNNER_PORT,
+  type MaestroRun,
+} from './ios-maestro';
 export { buildSettingKeyPattern, parseBuildSettingEntries, validateBuildSettings } from './build-settings';
 export {
   exec,

package/src/ios-client.ts

@@ -10,7 +10,11 @@ import { createIgnoreFn } from './folder-sync-ignore';
 import { prepareAppBundlePath, watchAppArchive } from './app-archive';
 import { downloadFileToLocalPath } from './internal/download-file';
 import { nodeProxyTransport } from './internal/proxy-transport';
-import { startHttpProxy as startLocalHttpProxy } from './http-proxy';
+import {
+  startHttpProxy as startLocalHttpProxy,
+  startForwardHttpProxy as startLocalForwardHttpProxy,
+  type StartForwardHttpProxyOptions,
+} from './http-proxy';
 import { startXcrunShim as startClientXcrunShim } from './ios-shim';
 
 /**
@@ -210,6 +214,8 @@ export type HttpProxyOptions = {
   localPort: number;
 };
 
+export type ForwardHttpProxyOptions = Omit<StartForwardHttpProxyOptions, 'headers'>;
+
 /**
  * Targets a file operation at an installed app's container instead of the
  * sandbox staging folder. Mirrors `simctl get_app_container` semantics.
@@ -749,6 +755,16 @@ export type InstanceClient = {
    */
   startHttpProxy: (options: HttpProxyOptions) => Promise<number>;
 
+  /**
+   * Start a local HTTP forward proxy (for clients driven by JVM/system proxy
+   * settings, like Maestro) that rewrites loopback requests on `matchPort` to a
+   * port exposed by the iOS instance and passes other targets through.
+   *
+   * Returns the local port the proxy is listening on. The proxy is closed when
+   * the client disconnects.
+   */
+  startForwardHttpProxy: (options: ForwardHttpProxyOptions) => Promise<number>;
+
   /**
    * Disconnect from the Limrun instance
    */
@@ -1861,6 +1877,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             softReset,
             startReverseTunnel,
             startHttpProxy,
+            startForwardHttpProxy,
             disconnect,
             getConnectionState,
             onConnectionStateChange,
@@ -2507,6 +2524,20 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return proxy.port;
     };
 
+    const startForwardHttpProxy = async (proxyOptions: ForwardHttpProxyOptions): Promise<number> => {
+      assertPort(proxyOptions.matchPort, 'matchPort', 1, 65535);
+
+      const proxy = await startLocalForwardHttpProxy({
+        matchPort: proxyOptions.matchPort,
+        remoteBaseUrl: proxyOptions.remoteBaseUrl,
+        headers: {
+          authorization: `Bearer ${options.token}`,
+        },
+      });
+      httpProxyCleanups.push(proxy.close);
+      return proxy.port;
+    };
+
     const disconnect = (): void => {
       intentionalDisconnect = true;
       cleanup();

package/src/ios-maestro.ts

@@ -0,0 +1,154 @@
+import path from 'path';
+import net from 'net';
+import { execFile } from 'child_process';
+
+import type { InstanceClient } from './ios-client';
+
+export const MAESTRO_RUNNER_BUNDLE_ID = 'dev.mobile.maestro-driver-iosUITests.xctrunner';
+/** Port the patched Maestro XCTest runner listens on inside the simulator. */
+export const MAESTRO_RUNNER_PORT = 22087;
+
+// Maestro installs as a .bat/.cmd wrapper on Windows, which spawn can only
+// execute through a shell.
+export const maestroSpawnOptions = { shell: process.platform === 'win32' } as const;
+
+export type MaestroRun = {
+  maestroVersion: string;
+  driverPort: number;
+  /** Environment overrides for the `maestro` process; merge over process.env. */
+  env: Record<string, string>;
+  /** Arguments to place between `maestro test` and the flow arguments. */
+  args: string[];
+};
+
+/**
+ * Wire a locally installed stock Maestro CLI to this instance's remote XCTest
+ * runner: starts the xcrun shim and an HTTP forward proxy, and returns the
+ * environment and `maestro test` arguments that route the driver traffic to
+ * the remote runner. Both are torn down when the client disconnects.
+ *
+ * Maestro's driver talks plain HTTP to 127.0.0.1:<driverPort>. Nothing listens
+ * there: the JVM proxy settings route those requests (absolute-form) to the
+ * forward proxy, which rewrites them to the remote runner and passes other
+ * targets through.
+ */
+export async function prepareMaestroRun(
+  client: InstanceClient,
+  options: { runnerUrl: string },
+): Promise<MaestroRun> {
+  const [maestroVersion, shimDir] = await Promise.all([detectMaestroVersion(), client.startXcrunShim()]);
+  // Maestro 2.5.x hardcodes driver port 7001 and has no --driver-host-port
+  // flag; 2.6+ picks a random port unless the flag is passed.
+  const withDriverHostPortFlag = supportsDriverHostPort(maestroVersion);
+  const driverPort = withDriverHostPortFlag ? await findFreePort() : 7001;
+  const proxyPort = await client.startForwardHttpProxy({
+    remoteBaseUrl: options.runnerUrl,
+    matchPort: driverPort,
+  });
+  const maestroOpts = [
+    process.env['MAESTRO_OPTS'],
+    `-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=${proxyPort} -Dhttp.nonProxyHosts=`,
+  ]
+    .filter(Boolean)
+    .join(' ');
+  return {
+    maestroVersion,
+    driverPort,
+    env: {
+      MAESTRO_OPTS: maestroOpts,
+      PATH: `${shimDir}${path.delimiter}${process.env['PATH'] ?? ''}`,
+      USE_XCODE_TEST_RUNNER: '1',
+    },
+    args: [
+      '--platform',
+      'ios',
+      '--device',
+      client.deviceInfo.udid,
+      '--no-reinstall-driver',
+      ...(withDriverHostPortFlag ? ['--driver-host-port', String(driverPort)] : []),
+    ],
+  };
+}
+
+/** Poll the remote Maestro XCTest runner until it responds, e.g. right after launching it. */
+export async function waitForMaestroRunner(
+  runnerUrl: string,
+  token: string,
+  timeoutMs = 15000,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isMaestroRunnerRunning(runnerUrl, token)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  return false;
+}
+
+/** Probe the remote Maestro XCTest runner's /status endpoint. */
+export async function isMaestroRunnerRunning(runnerUrl: string, token: string): Promise<boolean> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+  try {
+    const response = await fetch(`${runnerUrl}/status`, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: controller.signal,
+    });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    // Also on failure: a pending timer keeps the event loop alive.
+    clearTimeout(timeout);
+  }
+}
+
+function detectMaestroVersion(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile('maestro', ['--version'], { encoding: 'utf8', ...maestroSpawnOptions }, (error, stdout) => {
+      if (error) {
+        reject(
+          new Error(
+            'Failed to run `maestro --version`. Install the Maestro CLI first: https://docs.maestro.dev/getting-started/installing-maestro',
+          ),
+        );
+        return;
+      }
+      // stdout only: update notices can also start with a version string and
+      // land on stderr or after the real version.
+      const version = stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => /^\d+\.\d+\.\d+/.test(line));
+      if (!version) {
+        reject(new Error('Could not parse the Maestro CLI version from `maestro --version` output.'));
+        return;
+      }
+      resolve(version);
+    });
+  });
+}
+
+function supportsDriverHostPort(version: string): boolean {
+  const [major = 0, minor = 0] = version.split('.').map((part) => Number.parseInt(part, 10) || 0);
+  return major > 2 || (major === 2 && minor >= 6);
+}
+
+// Finds a free port and releases it immediately: Maestro validates that the
+// driver port is bindable, so it must stay unbound on our side.
+function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        server.close();
+        reject(new Error('Failed to find a free port.'));
+        return;
+      }
+      server.close(() => resolve(address.port));
+    });
+  });
+}

package/src/ios-shim.ts

@@ -100,6 +100,9 @@ async function handleShimmedXcrun(
   udid: string,
   args: string[],
 ): Promise<IosShimSimctlResult> {
+  if (args[0] === 'devicectl') {
+    return devicectlListDevices(args);
+  }
   if (args[0] !== 'simctl') {
     return { code: 127, stdout: '', stderr: `unsupported xcrun command: ${args.join(' ')}` };
   }
@@ -148,6 +151,43 @@ async function handleShimmedXcrun(
   return await client.simctl(simctlArgs).wait();
 }
 
+// There are never physical devices behind the shim, so `devicectl list
+// devices` gets an empty device list in the shape Maestro's picker parses.
+// Flags can precede the subcommand (devicectl --json-output <path> list
+// devices), so match on positionals.
+function devicectlListDevices(args: string[]): IosShimSimctlResult {
+  const positionals: string[] = [];
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--json-output') {
+      i++;
+      continue;
+    }
+    if (args[i]!.startsWith('-')) continue;
+    positionals.push(args[i]!);
+  }
+  if (positionals[0] !== 'list' || positionals[1] !== 'devices') {
+    return { code: 127, stdout: '', stderr: `unsupported devicectl command: ${args.join(' ')}` };
+  }
+  const payload = JSON.stringify({ result: { devices: [] } });
+  const jsonOutIndex = args.indexOf('--json-output');
+  const jsonOutPath = jsonOutIndex === -1 ? undefined : args[jsonOutIndex + 1];
+  if (jsonOutPath && jsonOutPath !== '-') {
+    try {
+      fs.writeFileSync(jsonOutPath, payload);
+    } catch (error) {
+      return {
+        code: 1,
+        stdout: '',
+        stderr: `could not write devicectl output to ${jsonOutPath}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      };
+    }
+    return { code: 0, stdout: '', stderr: '' };
+  }
+  return { code: 0, stdout: `${payload}\n`, stderr: '' };
+}
+
 function simctlList(udid: string, simctlArgs: string[]): IosShimSimctlResult {
   if (!simctlArgs.includes('-j')) {
     return { code: 64, stdout: '', stderr: 'limrun xcrun shim only supports `xcrun simctl list -j`.' };
@@ -269,8 +309,9 @@ function toSimctlListApps(
 
 function xcrunShimSource(options?: { shimUrl: string; udid: string }): string {
   // Keep the executable tiny: it decides whether this is a Limrun-targeted
-  // simctl call, then asks the local shim server to perform the real work.
-  // Non-Limrun calls still delegate to the host xcrun.
+  // simctl call (or a devicectl device enumeration), then asks the local shim
+  // server to perform the real work. Non-Limrun calls still delegate to the
+  // host xcrun.
   const embeddedShimUrl = options ? JSON.stringify(options.shimUrl) : 'process.env.LIMRUN_XCRUN_SHIM_URL';
   const embeddedUdid = options ? JSON.stringify(options.udid) : 'process.env.LIMRUN_IOS_UDID';
   return `#!/usr/bin/env node
@@ -294,7 +335,26 @@ function fail(message) {
   process.exit(64);
 }
 
-if (args[0] !== 'simctl') {
+// Physical-device enumeration (e.g. Maestro's device picker) is answered by
+// the shim server; real devicectl does not exist off macOS. Every other
+// devicectl subcommand delegates. Flags can precede the subcommand
+// (devicectl --json-output <path> list devices), so match on positionals.
+function devicectlPositionals(args) {
+  const positionals = [];
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--json-output') {
+      i++;
+      continue;
+    }
+    if (args[i].startsWith('-')) continue;
+    positionals.push(args[i]);
+  }
+  return positionals;
+}
+const devicectlSubcommand = args[0] === 'devicectl' ? devicectlPositionals(args) : [];
+const isDevicectlListDevices = devicectlSubcommand[0] === 'list' && devicectlSubcommand[1] === 'devices';
+
+if (args[0] !== 'simctl' && !isDevicectlListDevices) {
   delegate();
 }
 
@@ -304,21 +364,23 @@ if (!shimUrl || !udid) {
   fail('LIMRUN_XCRUN_SHIM_URL and LIMRUN_IOS_UDID are required.');
 }
 
-const simctlArgs = args.slice(1);
-const command = simctlArgs[0];
 function simctlTarget(command, simctlArgs) {
   if (command === 'launch') {
     return simctlArgs.slice(1).find((arg) => !arg.startsWith('-'));
   }
   return simctlArgs[1];
 }
-const target = simctlTarget(command, simctlArgs);
 function isLimrunTarget(value) {
   return value === udid || value === 'booted';
 }
 
-if (command !== 'list' && !isLimrunTarget(target)) {
-  delegate();
+if (args[0] === 'simctl') {
+  const simctlArgs = args.slice(1);
+  const command = simctlArgs[0];
+  const target = simctlTarget(command, simctlArgs);
+  if (command !== 'list' && !isLimrunTarget(target)) {
+    delegate();
+  }
 }
 
 const parsed = new URL(shimUrl);

package/src/tunnel.ts

@@ -108,6 +108,12 @@ export interface ReverseTcpTunnelOptions {
    * @default 16777216
    */
   maxPendingBytesPerConnection?: number;
+  /**
+   * Maximum bytes queued in the WebSocket before local reads pause. Bounds
+   * memory when the local service produces data faster than the tunnel drains.
+   * @default 4194304
+   */
+  maxBufferedBytes?: number;
   /**
    * Local TCP connect timeout in milliseconds.
    * @default 10000
@@ -167,6 +173,9 @@ export async function startReverseTcpTunnel(
   const logLevel = options.logLevel ?? 'info';
   const maxConnections = options.maxConnections ?? 64;
   const maxPendingBytesPerConnection = options.maxPendingBytesPerConnection ?? 16 * 1024 * 1024;
+  const maxBufferedBytes = options.maxBufferedBytes ?? 4 * 1024 * 1024;
+  // Hysteresis: resume well below the pause threshold to avoid flapping.
+  const resumeBelowBufferedBytes = maxBufferedBytes / 4;
   const connectTimeoutMs = options.connectTimeoutMs ?? 10_000;
 
   const logger = {
@@ -200,6 +209,8 @@ export async function startReverseTcpTunnel(
     let connectionState: TunnelConnectionState = 'connecting';
     let hasResolved = false;
     let remoteAddress: ReverseTunnel['remoteAddress'] | undefined;
+    // The WebSocket is shared by all connections, so backpressure is tunnel-wide.
+    let pausedForBackpressure = false;
 
     const updateConnectionState = (newState: TunnelConnectionState): void => {
       if (connectionState !== newState) {
@@ -217,7 +228,31 @@ export async function startReverseTcpTunnel(
 
     const sendCloseSignal = (connId: number): void => {
       if (ws && ws.readyState === WebSocket.OPEN) {
-        ws.send(encodeConnectionHeader(connId));
+        // The drain check on completion keeps resume reachable even when the
+        // last frames in the queue are close signals rather than data.
+        ws.send(encodeConnectionHeader(connId), () => resumeIfDrained());
+      }
+    };
+
+    const pauseForBackpressure = (): void => {
+      if (pausedForBackpressure) return;
+      pausedForBackpressure = true;
+      logger.debug('WebSocket send buffer full, pausing local reads');
+      for (const socket of connections.values()) {
+        if (!socket.destroyed) socket.pause();
+      }
+    };
+
+    // Called from ws.send completion callbacks. Sends and callbacks are 1:1
+    // and pausing happens after at least one send is queued, so the callback
+    // that observes a drained buffer is guaranteed to exist; no polling needed.
+    const resumeIfDrained = (): void => {
+      if (!pausedForBackpressure) return;
+      if (!ws || ws.bufferedAmount >= resumeBelowBufferedBytes) return;
+      pausedForBackpressure = false;
+      logger.debug('WebSocket send buffer drained, resuming local reads');
+      for (const socket of connections.values()) {
+        if (!socket.destroyed) socket.resume();
       }
     };
 
@@ -266,6 +301,7 @@ export async function startReverseTcpTunnel(
       for (const connId of Array.from(connections.keys())) {
         removeConnection(connId, false);
       }
+      pausedForBackpressure = false;
       connections.clear();
       connecting.clear();
       pendingPerConn.clear();
@@ -372,6 +408,11 @@ export async function startReverseTcpTunnel(
       connecting.add(connId);
 
       const socket = net.createConnection({ host: localHost, port: localPort });
+      // Self-heal a stale pause before applying it to the new socket.
+      resumeIfDrained();
+      if (pausedForBackpressure) {
+        socket.pause();
+      }
       connections.set(connId, socket);
       const connectTimer = setTimeout(() => {
         logger.error(`Local TCP connect timed out conn=${connId} after ${connectTimeoutMs}ms`);
@@ -387,13 +428,22 @@ export async function startReverseTcpTunnel(
         flushPending(connId, socket);
       });
 
+      const header = encodeConnectionHeader(connId);
+      const onSent = (err?: Error): void => {
+        if (err) {
+          logger.error(`Failed to send conn=${connId} data: ${err.message}`);
+        }
+        resumeIfDrained();
+      };
       socket.on('data', (chunk: Buffer) => {
         if (ws && ws.readyState === WebSocket.OPEN) {
-          ws.send(Buffer.concat([encodeConnectionHeader(connId), chunk]), (err) => {
-            if (err) {
-              logger.error(`Failed to send conn=${connId} data: ${err.message}`);
-            }
-          });
+          const framed = Buffer.allocUnsafe(4 + chunk.length);
+          header.copy(framed, 0);
+          chunk.copy(framed, 4);
+          ws.send(framed, onSent);
+          if (!pausedForBackpressure && ws.bufferedAmount > maxBufferedBytes) {
+            pauseForBackpressure();
+          }
         }
       });
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.45.2'; // x-release-please-version
+export const VERSION = '0.45.4'; // x-release-please-version

package/tunnel.d.mts

@@ -96,6 +96,12 @@ export interface ReverseTcpTunnelOptions {
      * @default 16777216
      */
     maxPendingBytesPerConnection?: number;
+    /**
+     * Maximum bytes queued in the WebSocket before local reads pause. Bounds
+     * memory when the local service produces data faster than the tunnel drains.
+     * @default 4194304
+     */
+    maxBufferedBytes?: number;
     /**
      * Local TCP connect timeout in milliseconds.
      * @default 10000