@compforge/harness-toolbox 0.1.1 → 0.1.2

package/README.md

@@ -1,5 +1,9 @@
 # Harness Toolbox
 
+Client, DataSource and ClientManager are owned by the sibling TypeScript package
+`@compforge/harness-common`. Toolbox provides protocol implementations and transports;
+its lifecycle entrypoints re-export the same common symbols.
+
 Shared infrastructure for diagnostic tools, test runners and business adapters. Use the same
 clients to access Kubernetes, MySQL, Redis, OpenSearch and S3-compatible object storage without depending on a particular
 command, plugin protocol, test model or verdict.
@@ -81,3 +85,17 @@ for mapped routes; direct endpoints also support virtual-hosted buckets. Signed
 identity remain the logical endpoint, not the forwarded address. Private CAs may be supplied
 explicitly with `ca`; certificate verification stays enabled. Initialization prepares the client
 and route without listing buckets or claiming that credentials have been validated.
+
+## Bounded MySQL reads
+
+`MysqlClient.database.queryReadonly(target, sql, values, { timeoutMs, maxRows, maxBytes })` uses
+the shared query slot and a disposable native session with `NO_BACKSLASH_ESCAPES`, a SELECT deadline,
+and a READ ONLY transaction. Prepared execution binds values and retains rows incrementally,
+returning `rows`, `columns`, `bytes`, `truncated`, and `truncation`. An extra row proves row truncation;
+a row exceeding the remaining byte budget is not retained.
+
+Callers own SQL classification, function policy, and least-privilege identities: READ ONLY alone
+is not an arbitrary-SQL sandbox. This API requires MySQL 5.7.8+ `max_execution_time` and does not
+fall back to Pod Python. Completion, truncation, timeout, and cancellation destroy the disposable
+session without replay or changes to ordinary borrowed sessions. Disconnect does not prove immediate
+server cancellation. The byte budget limits retained JSON rows, not individual wire packets or fields.

package/dist/{chunk-9j36zvn4.js → chunk-94anqtxh.js}

@@ -1,6 +1,6 @@
 import {
   dataSourceKey
-} from "./chunk-hqx7j9xe.js";
+} from "./chunk-fnc291vk.js";
 import {
   S3Client
 } from "./chunk-zp1s833x.js";

package/dist/{chunk-sry9e02n.js → chunk-9x1apyp4.js}

@@ -1,6 +1,10 @@
 import {
   queryMysqlViaPod
 } from "./chunk-s06hs7a8.js";
+import {
+  queryReadonlySession,
+  validateQueryLimits
+} from "./chunk-kbewz29a.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";
@@ -24,6 +28,19 @@ class MysqlDatabase {
   query(target, sql, values) {
     return this.#queries.run(() => this.#query(target, sql, values), this.options.signal);
   }
+  queryReadonly(target, sql, values, limits) {
+    validateQueryLimits(limits);
+    return this.#queries.run(async () => {
+      const session = await this.#open(target);
+      if (session.kind !== "tcp")
+        throw new Error("Bounded readonly MySQL queries require a native TCP transport");
+      try {
+        return await queryReadonlySession(session.connection, sql, values, limits, this.options.signal);
+      } finally {
+        session.connection.destroy();
+      }
+    }, this.options.signal);
+  }
   initialize(target) {
     return this.#queries.run(async () => {
       await this.#session(target);

package/dist/chunk-fnc291vk.js

@@ -0,0 +1,4 @@
+// src/datasource.ts
+import { dataSourceKey, ClientManager } from "@compforge/harness-common";
+
+export { dataSourceKey, ClientManager };

package/dist/chunk-kbewz29a.js

@@ -0,0 +1,95 @@
+// src/mysql/readonly.ts
+function validateQueryLimits(limits) {
+  for (const name of ["timeoutMs", "maxRows", "maxBytes"]) {
+    const value = limits[name];
+    if (!Number.isSafeInteger(value) || value < 1 || value > 2147483647) {
+      throw new Error(`${name} must be a positive integer <= 2147483647`);
+    }
+  }
+}
+async function queryReadonlySession(connection, sql, values, limits, signal) {
+  validateQueryLimits(limits);
+  signal?.throwIfAborted();
+  let timer;
+  let abort;
+  try {
+    return await Promise.race([
+      (async () => {
+        await connection.query("SET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_BACKSLASH_ESCAPES'");
+        await connection.query(`SET SESSION max_execution_time = ${limits.timeoutMs}`);
+        await connection.query("START TRANSACTION READ ONLY");
+        signal?.throwIfAborted();
+        return await collectRows(connection, sql, values, limits);
+      })(),
+      new Promise((_resolve, reject) => {
+        const fail = (reason) => {
+          connection.destroy();
+          reject(reason);
+        };
+        abort = () => fail(signal?.reason ?? new Error("MySQL query cancelled"));
+        signal?.addEventListener("abort", abort, { once: true });
+        timer = setTimeout(() => fail(new Error("MySQL readonly query timed out")), limits.timeoutMs);
+        if (signal?.aborted)
+          abort();
+      })
+    ]);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+    if (abort)
+      signal?.removeEventListener("abort", abort);
+    connection.destroy();
+  }
+}
+function collectRows(connection, sql, values, limits) {
+  const native = connection.connection;
+  return new Promise((resolve, reject) => {
+    const result = { rows: [], columns: [], bytes: 0, truncated: false };
+    let settled = false;
+    const finish = (truncation) => {
+      if (settled)
+        return;
+      settled = true;
+      result.truncated = !!truncation;
+      if (truncation)
+        result.truncation = truncation;
+      resolve(result);
+    };
+    const query = native.execute({ sql, values: [...values], timeout: limits.timeoutMs });
+    query.on("fields", (fields) => {
+      result.columns = fields?.map((field) => field.name) ?? [];
+    });
+    query.on("result", (row) => {
+      if (settled)
+        return;
+      if (result.rows.length >= limits.maxRows) {
+        finish("rows");
+        connection.destroy();
+        return;
+      }
+      try {
+        const bytes = Buffer.byteLength(JSON.stringify(row));
+        if (result.bytes + bytes > limits.maxBytes) {
+          finish("bytes");
+          connection.destroy();
+          return;
+        }
+        result.rows.push(row);
+        result.bytes += bytes;
+      } catch (error) {
+        settled = true;
+        connection.destroy();
+        reject(error);
+      }
+    });
+    query.on("error", (error) => {
+      if (!settled) {
+        settled = true;
+        reject(error);
+      }
+    });
+    query.on("end", () => finish());
+  });
+}
+
+export { validateQueryLimits, queryReadonlySession };

package/dist/{chunk-1at7zs0z.js → chunk-vjsr2jb3.js}

@@ -10,7 +10,7 @@ import {
 } from "./chunk-1vfwvgkj.js";
 import {
   dataSourceKey
-} from "./chunk-hqx7j9xe.js";
+} from "./chunk-fnc291vk.js";
 
 // src/kubernetes/pod-log-client.ts
 import { copyFileSync, mkdtempSync, rmSync } from "node:fs";

package/dist/client-manager.d.ts

@@ -1,14 +1 @@
-import type { Client } from "./client";
-import type { DataSource } from "./datasource";
-/** Consumers borrow clients; only the root owner receives the disposal capability. */
-export interface ClientProvider {
-    get<C extends Client>(source: DataSource<C>): Promise<C>;
-}
-/** @spec One root execution shares successful initialization per identity and closes clients at finalize. */
-export declare class ClientManager implements ClientProvider {
-    #private;
-    readonly signal: AbortSignal;
-    constructor(signal?: AbortSignal);
-    get<C extends Client>(source: DataSource<C>): Promise<C>;
-    dispose(): Promise<void>;
-}
+export { ClientManager, type ClientProvider } from "@compforge/harness-common";

package/dist/client-manager.js

@@ -1,6 +1,5 @@
-import {
-  ClientManager
-} from "./chunk-3dt25p98.js";
+// src/client-manager.ts
+import { ClientManager } from "@compforge/harness-common";
 export {
   ClientManager
 };

package/dist/client.d.ts

@@ -1,5 +1 @@
-/** A protocol client owns its initialization and idempotent cleanup, including partial initialization. */
-export interface Client {
-    initialize(): Promise<void>;
-    dispose(): Promise<void>;
-}
+export type { Client } from "@compforge/harness-common";

package/dist/datasource.d.ts

@@ -1,13 +1,5 @@
-export type { Client } from "./client";
-export { ClientManager, type ClientProvider } from "./client-manager";
-import type { Client } from "./client";
+export { dataSourceKey, ClientManager, type Client, type ClientProvider, type DataSource, type ServiceDataSource } from "@compforge/harness-common";
 import type { Transport } from "./transport";
-/** Identity must include protocol, target, configuration and credentials; never an object address. */
-export interface DataSource<C extends Client> {
-    readonly key: string;
-    /** Construct only; Client.initialize owns external work. */
-    createClient(signal: AbortSignal): C;
-}
 /** Resolution owns configuration semantics; transports preserve the resolved target and identity. */
 export interface ConnectionSource<Target> {
     resolve(): Promise<Target>;
@@ -22,5 +14,3 @@ export interface ClientLifecycle {
         reason?: string;
     }) => void;
 }
-/** Stable in-memory identity; connection credentials must not appear in observable cache keys. */
-export declare function dataSourceKey(protocol: string, configuration: unknown): string;

package/dist/datasource.js

@@ -1,9 +1,7 @@
 import {
+  ClientManager,
   dataSourceKey
-} from "./chunk-hqx7j9xe.js";
-import {
-  ClientManager
-} from "./chunk-3dt25p98.js";
+} from "./chunk-fnc291vk.js";
 export {
   dataSourceKey,
   ClientManager

package/dist/kubernetes/client.js

@@ -1,13 +1,13 @@
 import {
   ServicePortForwarder
-} from "../chunk-p097seg7.js";
-import"../chunk-j46x7j7c.js";
-import"../chunk-6fnhzhdb.js";
+} from "../chunk-205a4vma.js";
 import"../chunk-hv2kx47y.js";
 import {
   KubectlExecutor
 } from "../chunk-0rs1aacd.js";
 import"../chunk-ztenxgjv.js";
+import"../chunk-j46x7j7c.js";
+import"../chunk-6fnhzhdb.js";
 
 // src/kubernetes/client.ts
 class KubernetesClient {

package/dist/kubernetes/pod-log-client.js

@@ -1,11 +1,10 @@
 import {
   PodLogClient
-} from "../chunk-1at7zs0z.js";
+} from "../chunk-vjsr2jb3.js";
 import"../chunk-8nm9f0hh.js";
 import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
-import"../chunk-hqx7j9xe.js";
-import"../chunk-3dt25p98.js";
+import"../chunk-fnc291vk.js";
 import"../chunk-v3hxvnrc.js";
 export {
   PodLogClient

package/dist/kubernetes/pod-log-datasource.js

@@ -1,13 +1,12 @@
 import {
   PodLogClient
-} from "../chunk-1at7zs0z.js";
+} from "../chunk-vjsr2jb3.js";
 import"../chunk-8nm9f0hh.js";
 import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
 import {
   dataSourceKey
-} from "../chunk-hqx7j9xe.js";
-import"../chunk-3dt25p98.js";
+} from "../chunk-fnc291vk.js";
 import"../chunk-v3hxvnrc.js";
 
 // src/kubernetes/pod-log-datasource.ts

package/dist/kubernetes/service-port-forward.js

@@ -1,11 +1,11 @@
 import {
   ServicePortForwarder
-} from "../chunk-p097seg7.js";
-import"../chunk-j46x7j7c.js";
-import"../chunk-6fnhzhdb.js";
+} from "../chunk-205a4vma.js";
 import"../chunk-hv2kx47y.js";
 import"../chunk-0rs1aacd.js";
 import"../chunk-ztenxgjv.js";
+import"../chunk-j46x7j7c.js";
+import"../chunk-6fnhzhdb.js";
 export {
   ServicePortForwarder
 };

package/dist/mysql/client.d.ts

@@ -1,6 +1,6 @@
 import type { Client } from "../client";
 import { type Connection, type ConnectionOptions } from "mysql2/promise";
-import type { Database, DatabaseTarget, DatabaseRow } from "./types";
+import type { Database, DatabaseTarget, DatabaseRow, DatabaseQueryLimits, DatabaseQueryResult } from "./types";
 import type { ConnectionSource, ClientLifecycle } from "../datasource";
 import { type Transport } from "../transport";
 export interface MysqlDatabaseOptions extends ClientLifecycle {
@@ -16,6 +16,8 @@ export declare class MysqlDatabase implements Database {
     private readonly connect;
     constructor(transports: readonly Transport[], options: MysqlDatabaseOptions, connect?: ConnectionFactory);
     query(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow[]>;
+    /** Bounded, single-statement prepared execution on an isolated READ ONLY session (native only). */
+    queryReadonly(target: DatabaseTarget, sql: string, values: readonly unknown[], limits: DatabaseQueryLimits): Promise<DatabaseQueryResult>;
     initialize(target: DatabaseTarget): Promise<void>;
     queryOne(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow | undefined>;
     close(): Promise<void>;
@@ -28,7 +30,7 @@ export declare class MysqlClient<Target extends DatabaseTarget = DatabaseTarget>
     readonly signal: AbortSignal;
     constructor(source: ConnectionSource<Target>, options: MysqlDatabaseOptions);
     initialize(): Promise<void>;
-    get database(): Database;
+    get database(): MysqlDatabase;
     get target(): Target;
     dispose(): Promise<void>;
 }

package/dist/mysql/client.js

@@ -2,8 +2,9 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-sry9e02n.js";
+} from "../chunk-9x1apyp4.js";
 import"../chunk-s06hs7a8.js";
+import"../chunk-kbewz29a.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-xy4g56g4.js";
 export {

package/dist/mysql/index.js

@@ -6,8 +6,9 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-sry9e02n.js";
+} from "../chunk-9x1apyp4.js";
 import"../chunk-s06hs7a8.js";
+import"../chunk-kbewz29a.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-xy4g56g4.js";
 export {

package/dist/mysql/readonly.d.ts

@@ -0,0 +1,9 @@
+import type { Connection } from "mysql2/promise";
+import type { DatabaseQueryLimits, DatabaseQueryResult } from "./types";
+export declare function validateQueryLimits(limits: DatabaseQueryLimits): void;
+/**
+ * Owns a disposable session: setup, execution and cancellation cannot affect another borrower.
+ * Caller must classify SQL and use a least-privilege identity. READ ONLY is not a SQL sandbox
+ * (for example routines and temporary tables need additional caller policy).
+ */
+export declare function queryReadonlySession(connection: Connection, sql: string, values: readonly unknown[], limits: DatabaseQueryLimits, signal?: AbortSignal): Promise<DatabaseQueryResult>;

package/dist/mysql/readonly.js

@@ -0,0 +1,8 @@
+import {
+  queryReadonlySession,
+  validateQueryLimits
+} from "../chunk-kbewz29a.js";
+export {
+  validateQueryLimits,
+  queryReadonlySession
+};

package/dist/mysql/types.d.ts

@@ -8,6 +8,19 @@ export interface DatabaseTarget extends DatabaseIdentity {
     database: string;
 }
 export type DatabaseRow = Record<string, unknown>;
+export interface DatabaseQueryLimits {
+    timeoutMs: number;
+    maxRows: number;
+    /** Maximum retained UTF-8 JSON row bytes, not a limit on an individual wire packet. */
+    maxBytes: number;
+}
+export interface DatabaseQueryResult {
+    rows: DatabaseRow[];
+    columns: string[];
+    bytes: number;
+    truncated: boolean;
+    truncation?: "rows" | "bytes";
+}
 /** Storage-neutral operations shared by infrastructure consumers. */
 export interface Database {
     query(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow[]>;

package/dist/s3/datasource.js

@@ -1,8 +1,7 @@
 import {
   S3DataSource
-} from "../chunk-9j36zvn4.js";
-import"../chunk-hqx7j9xe.js";
-import"../chunk-3dt25p98.js";
+} from "../chunk-94anqtxh.js";
+import"../chunk-fnc291vk.js";
 import"../chunk-zp1s833x.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-x4ntb898.js";

package/dist/s3/index.js

@@ -1,8 +1,7 @@
 import {
   S3DataSource
-} from "../chunk-9j36zvn4.js";
-import"../chunk-hqx7j9xe.js";
-import"../chunk-3dt25p98.js";
+} from "../chunk-94anqtxh.js";
+import"../chunk-fnc291vk.js";
 import {
   S3Client
 } from "../chunk-zp1s833x.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -83,6 +83,7 @@
     "README.md"
   ],
   "dependencies": {
+    "@compforge/harness-common": "0.0.1",
     "@aws-sdk/client-s3": "3.1133.0",
     "@kubernetes/client-node": "1.4.0",
     "@opensearch-project/opensearch": "3.6.0",

package/dist/chunk-3dt25p98.js

@@ -1,59 +0,0 @@
-// src/client-manager.ts
-class ClientManager {
-  #controller = new AbortController;
-  signal;
-  #clients = new Map;
-  #ready = [];
-  #disposal;
-  constructor(signal) {
-    this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
-  }
-  get(source) {
-    this.signal.throwIfAborted();
-    const existing = this.#clients.get(source.key);
-    if (existing)
-      return existing;
-    const pending = Promise.resolve().then(async () => {
-      this.signal.throwIfAborted();
-      const client = source.createClient(this.signal);
-      try {
-        await client.initialize();
-        this.signal.throwIfAborted();
-        this.#ready.push(client);
-        return client;
-      } catch (error) {
-        try {
-          await client.dispose();
-        } catch (cleanup) {
-          throw new AggregateError([error, cleanup], "Client initialization and cleanup failed");
-        }
-        throw error;
-      }
-    });
-    this.#clients.set(source.key, pending);
-    pending.catch(() => {
-      if (this.#clients.get(source.key) === pending)
-        this.#clients.delete(source.key);
-    });
-    return pending;
-  }
-  dispose() {
-    return this.#disposal ??= (async () => {
-      this.#controller.abort(new Error("Client manager disposed"));
-      const settled = await Promise.allSettled(this.#clients.values());
-      this.#clients.clear();
-      const errors = settled.flatMap((result) => result.status === "rejected" && result.reason instanceof AggregateError ? [result.reason] : []);
-      for (const client of this.#ready.splice(0).reverse()) {
-        try {
-          await client.dispose();
-        } catch (error) {
-          errors.push(error);
-        }
-      }
-      if (errors.length)
-        throw new AggregateError(errors, "Client cleanup failed");
-    })();
-  }
-}
-
-export { ClientManager };

package/dist/chunk-hqx7j9xe.js

@@ -1,14 +0,0 @@
-// src/datasource.ts
-import { createHash } from "node:crypto";
-function dataSourceKey(protocol, configuration) {
-  const canonical = (value) => {
-    if (Array.isArray(value))
-      return value.map(canonical);
-    if (value && typeof value === "object")
-      return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)]));
-    return value;
-  };
-  return `${protocol}:${createHash("sha256").update(JSON.stringify(canonical(configuration))).digest("hex")}`;
-}
-
-export { dataSourceKey };

package/dist/{chunk-p097seg7.js → chunk-205a4vma.js}

@@ -1,3 +1,6 @@
+import {
+  PortForwardScope
+} from "./chunk-hv2kx47y.js";
 import {
   findPodsForService,
   findService,
@@ -6,9 +9,6 @@ import {
 import {
   findPod
 } from "./chunk-6fnhzhdb.js";
-import {
-  PortForwardScope
-} from "./chunk-hv2kx47y.js";
 
 // src/kubernetes/service-port-forward.ts
 class ServicePortForwarder {