@malloy-publisher/server 0.0.198 → 0.0.200

package/src/service/package_worker_path.spec.ts

@@ -0,0 +1,196 @@
+/**
+ * Integration test: exercise `Package.create` with the package-load
+ * worker pool enabled (PACKAGE_LOAD_WORKERS=1).
+ *
+ * Validates that the worker-load path:
+ *   - reads the manifest, probes embedded databases, and compiles
+ *     every model in a single off-thread job
+ *   - produces a live `Package` whose `Model`s have populated
+ *     `modelDef` / `sources` / `queries`
+ *   - hydrates the `ModelMaterializer` from `modelDef` on first
+ *     query (no recompile) — verified end-to-end by running a
+ *     query through the resulting Model and getting a result
+ *
+ * Kept separate from `package.spec.ts` so the existing tests keep
+ * running on the in-process path without paying worker startup cost.
+ *
+ * Pool reuse strategy: one `PackageLoadPool` shared across all
+ * cases in this file. Spawning a fresh worker per test crashes Bun
+ * (segfault) because DuckDB's native bindings don't tolerate being
+ * loaded concurrently into multiple worker isolates of the same Bun
+ * process. Production uses one pool; this matches.
+ */
+import {
+   afterAll,
+   afterEach,
+   beforeAll,
+   beforeEach,
+   describe,
+   expect,
+   it,
+} from "bun:test";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+   PackageLoadPool,
+   __setPackageLoadPoolForTests,
+} from "../package_load/package_load_pool";
+import { Package } from "./package";
+
+const ORIGINAL_ENV = process.env.PACKAGE_LOAD_WORKERS;
+
+describe("Package.create via worker pool", () => {
+   let tempDir: string;
+   let pool: PackageLoadPool;
+
+   beforeAll(async () => {
+      process.env.PACKAGE_LOAD_WORKERS = "1";
+      pool = new PackageLoadPool(1);
+      // Wire our pool into the module-level singleton so Package.create
+      // picks it up via getPackageLoadPool().
+      await __setPackageLoadPoolForTests(pool);
+   });
+
+   afterAll(async () => {
+      await __setPackageLoadPoolForTests(null);
+      if (ORIGINAL_ENV === undefined) {
+         delete process.env.PACKAGE_LOAD_WORKERS;
+      } else {
+         process.env.PACKAGE_LOAD_WORKERS = ORIGINAL_ENV;
+      }
+   });
+
+   beforeEach(() => {
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "publisher-pkg-worker-"));
+   });
+
+   afterEach(() => {
+      if (tempDir) {
+         // tempDir gets wiped by Package.create on failure (it's the
+         // staging-cleanup path); ignore ENOENT here.
+         try {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+         } catch {
+            /* already gone */
+         }
+         tempDir = "";
+      }
+   });
+
+   async function makeMalloyConfig(): Promise<{
+      malloyConfig: import("@malloydata/malloy").MalloyConfig;
+      duckdb: { close: () => Promise<void> };
+   }> {
+      const { MalloyConfig, FixedConnectionMap } = await import(
+         "@malloydata/malloy"
+      );
+      const { DuckDBConnection } = await import("@malloydata/db-duckdb");
+      const duckdb = new DuckDBConnection("duckdb", ":memory:");
+      const connections = new FixedConnectionMap(
+         new Map([["duckdb", duckdb]]),
+         "duckdb",
+      );
+      const malloyConfig = new MalloyConfig({ connections: {} });
+      malloyConfig.wrapConnections(() => connections);
+      return { malloyConfig, duckdb };
+   }
+
+   function writeManifest(): void {
+      fs.writeFileSync(
+         path.join(tempDir, "publisher.json"),
+         JSON.stringify({ name: "pkg", description: "test package" }),
+      );
+   }
+
+   it("loads a package end-to-end and serves a query through the hydrated materializer", async () => {
+      writeManifest();
+      // Define `total_v` as a *view* on the source so the query
+      // builder's `run: nums -> total_v` form resolves. (Top-level
+      // queries take the `run: total_q` form — orthogonal path that
+      // the in-process tests already cover.)
+      fs.writeFileSync(
+         path.join(tempDir, "trivial.malloy"),
+         `source: nums is duckdb.sql("select 1 as a, 2 as b") extend {
+  measure: total is a.sum()
+  view: total_v is { aggregate: total }
+}`,
+      );
+
+      const { malloyConfig, duckdb } = await makeMalloyConfig();
+      try {
+         const pkg = await Package.create("env", "pkg", tempDir, malloyConfig);
+         expect(pkg).toBeInstanceOf(Package);
+         expect(pkg.getModelPaths()).toEqual(["trivial.malloy"]);
+
+         const model = pkg.getModel("trivial.malloy");
+         expect(model).toBeDefined();
+         const apiModel = (await model!.getModel()) as {
+            modelDef?: string;
+            sources?: { name?: string }[];
+         };
+         expect(apiModel.modelDef).toBeDefined();
+         expect(apiModel.sources?.[0]?.name).toBe("nums");
+
+         // First query against the package — hydrates the
+         // ModelMaterializer from the worker's modelDef without a
+         // recompile, then runs the SQL against the *main thread's*
+         // DuckDB connection (the only one with the in-memory `nums`
+         // source loaded via duckdb.sql()).
+         const { result } = await model!.getQueryResults(
+            "nums",
+            "total_v",
+            undefined,
+         );
+         expect(result.data).toBeDefined();
+      } finally {
+         await duckdb.close();
+      }
+   });
+
+   it("propagates a per-model compile failure as a thrown error from Package.create", async () => {
+      writeManifest();
+      fs.writeFileSync(
+         path.join(tempDir, "broken.malloy"),
+         `source: bad is duckdb.sql("select 1 as a") extend {
+  measure: oops is THIS_FUNC_DOES_NOT_EXIST(a)
+}`,
+      );
+
+      const { malloyConfig, duckdb } = await makeMalloyConfig();
+      try {
+         await expect(
+            Package.create("env", "pkg", tempDir, malloyConfig),
+         ).rejects.toBeInstanceOf(Error);
+      } finally {
+         await duckdb.close();
+      }
+   });
+
+   // NB: kept last in this describe — swapping the singleton for a
+   // pre-shutdown pool also tears down the shared `pool` (the swap
+   // implementation shuts down the outgoing singleton). Subsequent
+   // tests in this describe would see a dead pool. afterAll only
+   // resets the singleton to null, so this is safe at the tail.
+   it("rewraps pool-infrastructure failures as ServiceUnavailableError (HTTP 503)", async () => {
+      writeManifest();
+      fs.writeFileSync(
+         path.join(tempDir, "trivial.malloy"),
+         `source: nums is duckdb.sql("select 1 as a")`,
+      );
+
+      const deadPool = new PackageLoadPool(1);
+      await deadPool.shutdown();
+      await __setPackageLoadPoolForTests(deadPool);
+
+      const { ServiceUnavailableError } = await import("../errors");
+      const { malloyConfig, duckdb } = await makeMalloyConfig();
+      try {
+         await expect(
+            Package.create("env", "pkg", tempDir, malloyConfig),
+         ).rejects.toBeInstanceOf(ServiceUnavailableError);
+      } finally {
+         await duckdb.close();
+      }
+   });
+});

package/src/service/path_injection.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "bun:test";
+import { BadRequestError } from "../errors";
+import { deleteDuckLakeConnectionFile } from "./connection";
+
+const TRAVERSAL_NAMES: ReadonlyArray<readonly [string, string]> = [
+   ["leading traversal", "../etc"],
+   ["embedded traversal", "foo/../../bar"],
+   ["slash in name", "foo/bar"],
+   ["backslash in name", "foo\\bar"],
+   ["leading dot", ".staging"],
+   ["bare dot-dot", ".."],
+   ["bare dot", "."],
+   ["empty", ""],
+   ["NUL byte", "foo\0bar"],
+   ["oversized", "a".repeat(256)],
+   ["absolute", "/etc/passwd"],
+] as const;
+
+describe("deleteDuckLakeConnectionFile path-injection guards", () => {
+   it.each(TRAVERSAL_NAMES)(
+      "rejects %s as connectionName (%p)",
+      async (_label, connectionName) => {
+         await expect(
+            deleteDuckLakeConnectionFile(connectionName, "/tmp/env"),
+         ).rejects.toBeInstanceOf(BadRequestError);
+      },
+   );
+
+   it.each([
+      ["relative", "relative/path"],
+      ["traversal", "/var/lib/../../etc"],
+      ["NUL byte", "/var/lib/env\0"],
+      ["bare dot-dot", ".."],
+   ])("rejects %s as environmentPath (%p)", async (_label, environmentPath) => {
+      await expect(
+         deleteDuckLakeConnectionFile("conn", environmentPath),
+      ).rejects.toBeInstanceOf(BadRequestError);
+   });
+});

package/src/stream_helpers.spec.ts

@@ -0,0 +1,280 @@
+import type {
+   QueryRecord,
+   RunSQLOptions,
+   StreamingConnection,
+} from "@malloydata/malloy";
+import { describe, expect, it } from "bun:test";
+
+import { PayloadTooLargeError } from "./errors";
+import { isStreamingConnection, streamSqlWithBudget } from "./stream_helpers";
+
+/**
+ * Build a fake StreamingConnection backed by a fixed row array. The
+ * fake records the abort signal so tests can confirm
+ * `streamSqlWithBudget` actually signaled the driver to stop —
+ * client-side counting alone is not enough; the whole point of the
+ * helper is to terminate fetching early.
+ */
+function fakeStreamingConnection(opts: {
+   rows: QueryRecord[];
+   /**
+    * When true (the default), the fake honors `RunSQLOptions.rowLimit`
+    * by slicing — same as real Postgres/DuckDB. Set false to drive
+    * the helper's own overflow detection (the (cap+1)-th row check).
+    */
+   honorRowLimit?: boolean;
+   /**
+    * Test hook: set to `true` when the fake observes `signal.aborted`
+    * flip via the listener it installed at the start of streaming.
+    */
+   abortObserved?: { value: boolean };
+   /**
+    * Test hook: captures the options the helper passed to
+    * `runSQLStream`, so tests can assert it preserved caller-supplied
+    * `rowLimit` (and the abortSignal it wired in).
+    */
+   capturedOptions?: { value: RunSQLOptions | undefined };
+}): StreamingConnection {
+   const { rows, honorRowLimit = true, abortObserved, capturedOptions } = opts;
+   return {
+      canStream(): true {
+         return true;
+      },
+      async *runSQLStream(
+         _sql: string,
+         options?: RunSQLOptions,
+      ): AsyncIterableIterator<QueryRecord> {
+         if (capturedOptions) capturedOptions.value = options;
+         if (abortObserved) {
+            options?.abortSignal?.addEventListener("abort", () => {
+               abortObserved.value = true;
+            });
+         }
+         const limit =
+            honorRowLimit && typeof options?.rowLimit === "number"
+               ? options.rowLimit
+               : rows.length;
+         for (let i = 0; i < Math.min(rows.length, limit); i += 1) {
+            yield rows[i];
+         }
+      },
+   } as unknown as StreamingConnection;
+}
+
+describe("isStreamingConnection", () => {
+   it("returns true for a connection whose canStream() returns true", () => {
+      const conn = fakeStreamingConnection({ rows: [] });
+      expect(isStreamingConnection(conn)).toBe(true);
+   });
+
+   it("returns false for a connection without canStream", () => {
+      expect(isStreamingConnection({} as never)).toBe(false);
+   });
+
+   it("returns false for a connection whose canStream() returns false", () => {
+      const conn = {
+         canStream() {
+            return false;
+         },
+      } as never;
+      expect(isStreamingConnection(conn)).toBe(false);
+   });
+});
+
+describe("streamSqlWithBudget", () => {
+   it("returns all rows when both budgets are comfortably above the stream", async () => {
+      const rows: QueryRecord[] = [{ a: 1 }, { a: 2 }, { a: 3 }];
+      const conn = fakeStreamingConnection({ rows });
+      const result = await streamSqlWithBudget(
+         conn,
+         "SELECT a FROM t",
+         { rowLimit: 10 },
+         { maxRows: 10, maxBytes: 1_000_000 },
+      );
+      expect(result.rows).toEqual(rows);
+      expect(result.totalRows).toBe(3);
+   });
+
+   it("forwards caller-supplied runSQLOptions (rowLimit) to the driver", async () => {
+      const captured = { value: undefined as RunSQLOptions | undefined };
+      const conn = fakeStreamingConnection({
+         rows: [{ a: 1 }, { a: 2 }],
+         capturedOptions: captured,
+      });
+      await streamSqlWithBudget(
+         conn,
+         "SELECT 1",
+         { rowLimit: 6 },
+         { maxRows: 5, maxBytes: 0 },
+      );
+      expect(captured.value?.rowLimit).toBe(6);
+      // abortSignal must be wired in so the helper can abort the
+      // iterator on overflow.
+      expect(captured.value?.abortSignal).toBeDefined();
+   });
+
+   it("composes the caller-supplied abortSignal with its internal cap-abort signal", async () => {
+      // Step 5: the caller's signal is the query timeout. Composing
+      // both sources means EITHER an external timeout OR an internal
+      // cap overflow terminates the iterator. The combined signal
+      // must be a fresh AbortSignal (not either input by reference);
+      // aborting either input must mark the composed signal aborted.
+      const captured = { value: undefined as RunSQLOptions | undefined };
+      const callerAc = new AbortController();
+      const conn = fakeStreamingConnection({
+         rows: [{ a: 1 }],
+         capturedOptions: captured,
+      });
+      await streamSqlWithBudget(
+         conn,
+         "SELECT 1",
+         { rowLimit: 10, abortSignal: callerAc.signal },
+         { maxRows: 5, maxBytes: 0 },
+      );
+      const observed = captured.value?.abortSignal;
+      expect(observed).toBeInstanceOf(AbortSignal);
+      // Composed signal is a new object (`AbortSignal.any` returns a
+      // fresh signal), not the caller's signal by reference.
+      expect(observed).not.toBe(callerAc.signal);
+      expect(observed?.aborted).toBe(false);
+   });
+
+   it("composed signal aborts when the caller's signal aborts", async () => {
+      // Drive the external (caller) signal manually and confirm the
+      // composed signal that reached the driver tracks it. This is the
+      // half of composition that runWithQueryTimeout depends on for
+      // 504 to actually cancel an in-flight query.
+      if (typeof AbortSignal.any !== "function") return;
+      const captured = { value: undefined as RunSQLOptions | undefined };
+      const callerAc = new AbortController();
+      const conn = fakeStreamingConnection({
+         rows: [{ a: 1 }],
+         capturedOptions: captured,
+      });
+      await streamSqlWithBudget(
+         conn,
+         "SELECT 1",
+         { rowLimit: 10, abortSignal: callerAc.signal },
+         { maxRows: 5, maxBytes: 0 },
+      );
+      const observed = captured.value?.abortSignal;
+      expect(observed?.aborted).toBe(false);
+      callerAc.abort();
+      expect(observed?.aborted).toBe(true);
+   });
+
+   it("throws PayloadTooLargeError and aborts the iterator on the (cap+1)-th row", async () => {
+      const rows: QueryRecord[] = [
+         { a: 1 },
+         { a: 2 },
+         { a: 3 },
+         { a: 4 },
+         { a: 5 },
+      ];
+      const abortObserved = { value: false };
+      const conn = fakeStreamingConnection({
+         rows,
+         abortObserved,
+         honorRowLimit: false,
+      });
+      await expect(
+         streamSqlWithBudget(
+            conn,
+            "SELECT a FROM t",
+            {},
+            { maxRows: 2, maxBytes: 1_000_000 },
+         ),
+      ).rejects.toBeInstanceOf(PayloadTooLargeError);
+      await expect(
+         streamSqlWithBudget(
+            conn,
+            "SELECT a FROM t",
+            {},
+            { maxRows: 2, maxBytes: 1_000_000 },
+         ),
+      ).rejects.toThrow("more than 2 rows");
+      // The helper must have fired the abort signal so a real driver
+      // (pg-query-stream / duckdb) would stop producing rows server-
+      // side, not just be discarded client-side.
+      expect(abortObserved.value).toBe(true);
+   });
+
+   it("throws PayloadTooLargeError when summed JSON byte size exceeds the cap", async () => {
+      const big = "x".repeat(40);
+      const rows: QueryRecord[] = [{ s: big }, { s: big }, { s: big }];
+      const abortObserved = { value: false };
+      const conn = fakeStreamingConnection({
+         rows,
+         abortObserved,
+         honorRowLimit: false,
+      });
+      await expect(
+         streamSqlWithBudget(
+            conn,
+            "SELECT s FROM t",
+            {},
+            { maxRows: 100, maxBytes: 60 },
+         ),
+      ).rejects.toThrow("exceeded 60 bytes");
+      expect(abortObserved.value).toBe(true);
+   });
+
+   it("returns all rows when the byte cap is disabled (maxBytes = 0)", async () => {
+      const big = "x".repeat(10_000);
+      const rows: QueryRecord[] = Array.from({ length: 3 }, () => ({ s: big }));
+      const conn = fakeStreamingConnection({ rows, honorRowLimit: false });
+      const result = await streamSqlWithBudget(
+         conn,
+         "SELECT s FROM t",
+         {},
+         { maxRows: 100, maxBytes: 0 },
+      );
+      expect(result.rows.length).toBe(3);
+   });
+
+   it("returns all rows when the row cap is disabled (maxRows = 0)", async () => {
+      const rows: QueryRecord[] = Array.from({ length: 50 }, (_, i) => ({
+         a: i,
+      }));
+      const conn = fakeStreamingConnection({ rows, honorRowLimit: false });
+      const result = await streamSqlWithBudget(
+         conn,
+         "SELECT a FROM t",
+         {},
+         { maxRows: 0, maxBytes: 1_000_000 },
+      );
+      expect(result.rows.length).toBe(50);
+   });
+
+   it("returns rows when count equals the cap exactly (not an overflow)", async () => {
+      const rows: QueryRecord[] = [{ a: 1 }, { a: 2 }, { a: 3 }];
+      const conn = fakeStreamingConnection({ rows, honorRowLimit: false });
+      const result = await streamSqlWithBudget(
+         conn,
+         "SELECT a FROM t",
+         {},
+         { maxRows: 3, maxBytes: 1_000_000 },
+      );
+      expect(result.rows.length).toBe(3);
+   });
+
+   it("re-throws non-overflow errors from the driver", async () => {
+      const conn = {
+         canStream(): true {
+            return true;
+         },
+         // eslint-disable-next-line require-yield
+         async *runSQLStream(): AsyncIterableIterator<QueryRecord> {
+            throw new Error("connection reset");
+         },
+      } as unknown as StreamingConnection;
+      await expect(
+         streamSqlWithBudget(
+            conn,
+            "SELECT 1",
+            {},
+            { maxRows: 10, maxBytes: 1_000 },
+         ),
+      ).rejects.toThrow("connection reset");
+   });
+});

package/src/stream_helpers.ts

@@ -0,0 +1,162 @@
+/**
+ * Helpers for streaming the ad-hoc connection SQL endpoints
+ * (`/environments/.../connections/.../sqlQuery`) so the publisher
+ * process never has to hold a whole result set in memory before
+ * returning it.
+ *
+ * The Step 1 row cap (`PUBLISHER_MAX_QUERY_ROWS`) is necessary but
+ * not sufficient: row count is a poor proxy for memory pressure
+ * because a single 10 MB JSON column blows past the 100k-row cap's
+ * safe envelope. The byte cap (`PUBLISHER_MAX_RESPONSE_BYTES`) is
+ * the actual memory bound, and bytes can only be enforced by
+ * iterating row-at-a-time on `runSQLStream` — `runSQL` returns a
+ * fully-buffered result, so by the time we'd count bytes the
+ * connector has already done the damage.
+ *
+ * On streaming-capable connections (Postgres, DuckDB, ...) the
+ * controller routes here. On other connections it stays on the
+ * Step 1 path; client-side byte counting after the fact would be
+ * security theatre.
+ */
+
+import type {
+   Connection,
+   MalloyQueryData,
+   QueryRecord,
+   RunSQLOptions,
+   StreamingConnection,
+} from "@malloydata/malloy";
+
+import { PayloadTooLargeError } from "./errors";
+import { recordQueryCapExceeded } from "./query_cap_metrics";
+
+/**
+ * Runtime check + type narrow for streaming-capable connections.
+ * `Connection.canStream` is declared as `this is StreamingConnection`
+ * by the Malloy SDK, so a positive result is enough to safely call
+ * `runSQLStream`.
+ */
+export function isStreamingConnection(
+   connection: Connection,
+): connection is StreamingConnection {
+   return (
+      typeof (connection as { canStream?: () => boolean }).canStream ===
+         "function" && (connection as StreamingConnection).canStream()
+   );
+}
+
+export interface StreamBudget {
+   /**
+    * Maximum number of rows to return. A value of `0` disables the
+    * row cap (the caller-supplied `rowLimit` in `runSQLOptions` may
+    * still bound the stream, but the helper will not raise on
+    * overflow).
+    */
+   maxRows: number;
+   /**
+    * Maximum aggregate JSON-serialized byte size of returned rows.
+    * `0` disables the byte cap. Measured as the sum of
+    * `Buffer.byteLength(JSON.stringify(row))` for each yielded row
+    * — the same bytes the eventual response will contain inside
+    * `result.rows`.
+    */
+   maxBytes: number;
+}
+
+/**
+ * Drain `runSQLStream` into a `MalloyQueryData`-shaped buffer,
+ * enforcing both a row cap and a byte cap. Aborts the underlying
+ * iterator via an internal `AbortController` the moment either cap
+ * is breached so the driver stops producing rows immediately
+ * (Postgres' `pg-query-stream` and DuckDB's streaming iterator both
+ * honor `abortSignal`).
+ *
+ * The row cap is detected by the `cap + 1` sentinel pattern: the
+ * controller has already clamped `runSQLOptions.rowLimit` to
+ * `min(callerLimit, cap + 1)`, so receiving `cap + 1` rows
+ * unambiguously means the request would have overflowed. This
+ * matches the non-streaming path's overflow detection so behavior
+ * is identical regardless of which connector served the request.
+ *
+ * On overflow the helper throws `PayloadTooLargeError` directly —
+ * the message includes the relevant env-var name so the operator
+ * sees a self-contained tuning hint without having to cross-
+ * reference the controller.
+ */
+export async function streamSqlWithBudget(
+   connection: StreamingConnection,
+   sql: string,
+   runSQLOptions: RunSQLOptions,
+   budget: StreamBudget,
+): Promise<MalloyQueryData> {
+   const { maxRows, maxBytes } = budget;
+   const capAc = new AbortController();
+   const rows: QueryRecord[] = [];
+   let byteTotal = 0;
+   let overflowMessage: string | undefined;
+
+   // Compose two abort sources so a caller-supplied signal (the
+   // publisher's query timeout) and the internal cap-abort signal
+   // *both* cancel the underlying iterator:
+   //
+   //   - If the caller's signal fires first, the controller's
+   //     `runWithQueryTimeout` will throw `QueryTimeoutError` → 504.
+   //   - If the cap-abort fires first, we throw
+   //     `PayloadTooLargeError` → 413.
+   //
+   // Without composition the streaming branch would silently drop
+   // the caller's signal — historically the only way to abort here
+   // was the cap, so the legacy controller cleared
+   // `runSQLOptions.abortSignal`. Step 5 reverses that: the caller's
+   // signal is now authoritative.
+   //
+   // `AbortSignal.any` is widely available (Node 20+); guard with a
+   // typeof check so a stale runtime falls back to the legacy
+   // cap-only behavior instead of crashing at module load.
+   const externalSignal = runSQLOptions.abortSignal;
+   const composedSignal: AbortSignal =
+      externalSignal && typeof AbortSignal.any === "function"
+         ? AbortSignal.any([externalSignal, capAc.signal])
+         : capAc.signal;
+
+   try {
+      for await (const row of connection.runSQLStream(sql, {
+         ...runSQLOptions,
+         abortSignal: composedSignal,
+      })) {
+         rows.push(row);
+         if (maxBytes > 0) {
+            // Measure exactly what the eventual response body will
+            // contain for this row. O(rowSize) per row, duplicated
+            // against the final `JSON.stringify(result)` — the
+            // early-abort win on overflow dwarfs the bookkeeping
+            // cost in the bounded-success case.
+            byteTotal += Buffer.byteLength(JSON.stringify(row), "utf8");
+            if (byteTotal > maxBytes) {
+               recordQueryCapExceeded("bytes", "connection_sql");
+               overflowMessage = `Query response exceeded ${maxBytes} bytes (had at least ${byteTotal}). Refine the query (project fewer columns, add a LIMIT, or filter wide values) or raise PUBLISHER_MAX_RESPONSE_BYTES.`;
+               capAc.abort();
+               break;
+            }
+         }
+         if (maxRows > 0 && rows.length > maxRows) {
+            recordQueryCapExceeded("rows", "connection_sql");
+            overflowMessage = `Query returned more than ${maxRows} rows. Refine the query (add a LIMIT or more selective WHERE) or raise PUBLISHER_MAX_QUERY_ROWS.`;
+            capAc.abort();
+            break;
+         }
+      }
+   } catch (err) {
+      // `pg-query-stream` surfaces `query.destroy()` (which our
+      // abort handler triggers) as a synthetic error in some
+      // versions. Swallow it iff we triggered the abort ourselves —
+      // otherwise it's a real connection error (or the caller's
+      // timeout, which the controller's runWithQueryTimeout will
+      // surface as a 504) that the controller must see.
+      if (!overflowMessage) throw err;
+   }
+
+   if (overflowMessage) throw new PayloadTooLargeError(overflowMessage);
+
+   return { rows, totalRows: rows.length };
+}