@aikoql/client 0.0.0-stage → 0.2.4

package/tests/pool.test.ts

@@ -0,0 +1,297 @@
+// The §3.4 pool legs: ports of the Go suite (crates/sdk/go/pool_test.go).
+// The scripted-server legs pin the pool mechanics (exhaustion →
+// RESOURCE_EXHAUSTED, transaction pinning + session reset on release,
+// reuse after a cancelled call, min-idle fill); the real-server leg
+// (skipped without AIKOQL_MCP_BIN) pins reconnect and auth reset across a
+// server restart. The factory is the seam: each call must return a fully
+// established session for one connection.
+
+import assert from "node:assert/strict";
+import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { test, type TestContext } from "node:test";
+import { Client, McpError, Pool } from "../src/index.ts";
+import { scripted, sleep, toolResult, type Frame } from "./helpers.ts";
+
+interface TxnCall {
+  name: string;
+  args: Record<string, unknown>;
+}
+
+/** Answers every tool a pooled connection can issue and logs the call. */
+function poolResponder(log: TxnCall[]) {
+  return (req: Record<string, unknown>): Frame[] => {
+    const params = req["params"] as { name?: string; arguments?: Record<string, unknown> };
+    const call: TxnCall = { name: params.name ?? "", args: params.arguments ?? {} };
+    log.push(call);
+    let data: unknown;
+    switch (call.name) {
+      case "health":
+        data = { status: "ok" };
+        break;
+      case "aikoql":
+        data = { results: [] };
+        break;
+      case "txn_begin":
+        data = { txn_id: call.args["txn_id"], snapshot_ts: 1000 };
+        break;
+      case "txn_stage":
+        data = { staged: 1 };
+        break;
+      case "txn_rollback":
+        data = { rolled_back: true };
+        break;
+      default:
+        throw new Error(`unexpected tool ${call.name}`);
+    }
+    return [[toolResult(req["id"], data), 0]];
+  };
+}
+
+/** A factory that dials a fresh scripted server per call, and its dial
+ * counter. */
+function poolFactory(t: TestContext, respond: (req: Record<string, unknown>) => Frame[]) {
+  let n = 0;
+  return {
+    factory: async (): Promise<Client> => {
+      const addr = await scripted(t, respond);
+      n += 1;
+      return Client.dial(addr);
+    },
+    dials: () => n,
+  };
+}
+
+// healthCheckIntervalMs: 0 pings every borrow — even one in the same
+// millisecond as the release (a whole-millisecond clock skipped the ping,
+// handing back a connection whose server had just died: the restart-test
+// flake below).
+test("a zero health-check interval pings every borrow", async (t) => {
+  const log: TxnCall[] = [];
+  const { factory } = poolFactory(t, poolResponder(log));
+  const p = new Pool({ factory, maxConns: 1, healthCheckIntervalMs: 0 });
+  t.after(() => {
+    void p.close();
+  });
+  for (let i = 0; i < 20; i++) {
+    const pc = await p.acquire();
+    await pc.release();
+  }
+  // the first borrow dials (nothing idle to ping); each of the other 19 pings
+  assert.equal(log.filter((c) => c.name === "health").length, 19);
+});
+
+test("exhaustion waits then RESOURCE_EXHAUSTED; a freed connection goes to a waiter", async (t) => {
+  const log: TxnCall[] = [];
+  const { factory, dials } = poolFactory(t, poolResponder(log));
+  const p = new Pool({ factory, maxConns: 2, acquireTimeoutMs: 200 });
+  t.after(() => {
+    void p.close();
+  });
+  const a = await p.acquire();
+  const b = await p.acquire();
+  assert.equal(dials(), 2);
+  const start = Date.now();
+  await assert.rejects(
+    p.acquire(),
+    (e: unknown) => isCode(e, "RESOURCE_EXHAUSTED") && (e as McpError).retryable,
+  );
+  assert.ok(
+    Date.now() - start >= 190,
+    `acquire must wait for the timeout before failing, waited ${Date.now() - start}ms`,
+  );
+  assert.equal(dials(), 2, "an exhausted pool must not dial");
+  // A freed connection is handed to a waiter without a redial.
+  const waiter = p.acquire();
+  await sleep(50);
+  await a.release();
+  const c = await waiter;
+  assert.equal(dials(), 2, "handoff must not dial");
+  await c.release();
+  await b.release();
+});
+
+test("release rolls back the open transaction and the next borrower starts clean", async (t) => {
+  const log: TxnCall[] = [];
+  const { factory, dials } = poolFactory(t, poolResponder(log));
+  const p = new Pool({ factory, maxConns: 1 });
+  t.after(() => {
+    void p.close();
+  });
+  const pc = await p.acquire();
+  const tx = await pc.begin("abc");
+  await tx.execute({ action: "create", type_name: "person", properties: { name: "ada" } });
+  await pc.release();
+  // Session reset: the open transaction was rolled back on release.
+  const rolledBack = log.some(
+    (call) => call.name === "txn_rollback" && call.args["txn_id"] === "abc",
+  );
+  assert.ok(rolledBack, `release must roll back the open transaction, log: ${JSON.stringify(log)}`);
+  // The next borrower must NOT inherit the transaction (§21).
+  const pc2 = await p.acquire();
+  assert.equal(dials(), 1, "the connection must be reused");
+  const tx2 = await pc2.begin();
+  assert.notEqual(tx2.id(), "abc", "the next borrower must not inherit the transaction");
+  assert.equal(tx2.id().length, 32, "a fresh transaction id is 32 hex chars");
+  await pc2.release();
+});
+
+test("the connection is reusable after a cancelled call", async (t) => {
+  const log: TxnCall[] = [];
+  const { factory, dials } = poolFactory(t, poolResponder(log));
+  const p = new Pool({ factory, maxConns: 1 });
+  t.after(() => {
+    void p.close();
+  });
+  const pc = await p.acquire();
+  const ctrl = new AbortController();
+  ctrl.abort(); // a pre-aborted signal bounds the call
+  await assert.rejects(
+    pc.client().callTool("aikoql", { query: "MATCH person RETURN *" }, { signal: ctrl.signal }),
+    (e: unknown) => isCode(e, "TIMEOUT"),
+  );
+  await pc.release();
+  // The connection must be reusable (§21): same conn, no redial. The stale
+  // answer to the aborted call is skipped by id correlation.
+  const pc2 = await p.acquire();
+  assert.equal(dials(), 1, "the connection must be reused");
+  const raw = await pc2.client().aikoql("MATCH person RETURN *", "");
+  assert.deepEqual(raw, { results: [] });
+  await pc2.release();
+});
+
+test("fillMinIdle dials to the floor", async (t) => {
+  const log: TxnCall[] = [];
+  const { factory, dials } = poolFactory(t, poolResponder(log));
+  const p = new Pool({ factory, maxConns: 3, minIdle: 2 });
+  t.after(() => {
+    void p.close();
+  });
+  await p.fillMinIdle();
+  assert.deepEqual(p.stats(), { total: 2, idle: 2 });
+  assert.equal(dials(), 2, "fill must dial twice");
+});
+
+/** Spawns the binary on a fixed addr with a fixed db dir and waits for
+ * readiness, so a test can stop and respawn on the same addr over the same
+ * data. The returned stop is idempotent. */
+async function startRealServerOn(bin: string, addr: string, dbDir: string): Promise<() => Promise<void>> {
+  let stderr = "";
+  const child: ChildProcess = spawn(
+    bin,
+    ["serve", "--listen", addr, "--tcp-token", "s3cret:acme:admin", dbDir],
+    { stdio: ["ignore", "ignore", "pipe"], windowsHide: true },
+  );
+  child.stderr?.on("data", (d: Buffer) => {
+    stderr += d.toString("utf8");
+  });
+  const [host, portStr] = addr.split(":");
+  const deadline = Date.now() + 10_000;
+  for (;;) {
+    const up = await new Promise<boolean>((resolve) => {
+      const s = net.connect(Number(portStr), host!);
+      s.once("connect", () => {
+        s.destroy();
+        resolve(true);
+      });
+      s.once("error", () => resolve(false));
+    });
+    if (up) break;
+    if (Date.now() >= deadline) {
+      child.kill();
+      throw new Error(`server never came up on ${addr}\nstderr:\n${stderr}`);
+    }
+    await sleep(100);
+  }
+  let stopped = false;
+  return async () => {
+    if (stopped) return;
+    stopped = true;
+    child.kill();
+    await new Promise<void>((resolve) => {
+      if (child.exitCode !== null) {
+        resolve();
+        return;
+      }
+      child.once("exit", () => resolve());
+    });
+  };
+}
+
+test(
+  "reconnects after a server restart",
+  {
+    skip:
+      process.env.AIKOQL_MCP_BIN === undefined
+        ? "AIKOQL_MCP_BIN not set — real-server integration test skipped"
+        : false,
+  },
+  async (t) => {
+    const bin = process.env.AIKOQL_MCP_BIN!;
+    const probe = net.createServer();
+    await new Promise<void>((resolve, reject) => {
+      probe.once("error", reject);
+      probe.listen(0, "127.0.0.1", resolve);
+    });
+    const port = (probe.address() as net.AddressInfo).port;
+    await new Promise<void>((resolve) => probe.close(() => resolve()));
+    const addr = `127.0.0.1:${port}`;
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pool-test-"));
+    t.after(() => {
+      void fs.promises.rm(dir, { recursive: true, force: true }).catch(() => {});
+    });
+    const dbDir = path.join(dir, "kb");
+
+    const stop1 = await startRealServerOn(bin, addr, dbDir);
+    t.after(stop1);
+
+    // The factory re-establishes the full session: dial + initialize with
+    // the token (the auth reset on every reconnect).
+    const factory = async (): Promise<Client> => {
+      const c = await Client.dial(addr);
+      c.withToken("s3cret");
+      try {
+        await c.initialize();
+      } catch (e) {
+        await c.close().catch(() => {});
+        throw e;
+      }
+      return c;
+    };
+    // A zero health-check interval: every borrow pings, so a dead
+    // connection is caught and replaced at checkout.
+    const p = new Pool({ factory, maxConns: 1, acquireTimeoutMs: 10_000, healthCheckIntervalMs: 0 });
+    t.after(() => {
+      void p.close();
+    });
+
+    const pc = await p.acquire();
+    await pc.client().remember({ type_name: "person", properties: { name: "ada" } });
+    await pc.release();
+    await stop1(); // the server dies
+
+    // Borrow while the server is down: the pool keeps retrying the dial.
+    const acquireP = p.acquire();
+    const settled = await Promise.race([
+      acquireP.then(() => "completed" as const),
+      sleep(300).then(() => "still-waiting" as const),
+    ]);
+    assert.equal(settled, "still-waiting", "acquire must wait for the server to return");
+    const stop2 = await startRealServerOn(bin, addr, dbDir); // the server returns
+    t.after(stop2);
+    const pc2 = await acquireP;
+    const raw = await pc2.client().aikoql('MATCH person WHERE name == "ada" RETURN *', "");
+    assert.ok(
+      JSON.stringify(raw).includes("ada"),
+      `the db must survive the restart: ${JSON.stringify(raw)}`,
+    );
+    await pc2.release();
+  },
+);
+
+function isCode(e: unknown, code: string): boolean {
+  return e instanceof McpError && e.code === code;
+}

package/tests/tls.test.ts

@@ -0,0 +1,74 @@
+// The SDK over TLS against the real server started with --tls-cert /
+// --tls-key (the MCP crate's test certificates, SAN IP:127.0.0.1):
+// Client.dial(addr, { tls: { ca } }) initializes and round-trips a write; a
+// server outside the trust anchors is refused at the dial, before the token
+// is sent. Skipped without AIKOQL_MCP_BIN.
+
+import assert from "node:assert/strict";
+import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { test, type TestContext } from "node:test";
+import { fileURLToPath } from "node:url";
+import { Client } from "../src/index.ts";
+import { sleep } from "./helpers.ts";
+
+const FX = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../../services/api/mcp/tests/fixtures/tls",
+);
+const ca = (name: string) => fs.readFileSync(path.join(FX, name));
+const skip =
+  process.env.AIKOQL_MCP_BIN === undefined ? "AIKOQL_MCP_BIN not set — TLS real-server test skipped" : false;
+
+async function startTlsServer(t: TestContext): Promise<string> {
+  const probe = net.createServer();
+  await new Promise<void>((resolve) => probe.listen(0, "127.0.0.1", resolve));
+  const port = (probe.address() as net.AddressInfo).port;
+  await new Promise<void>((resolve) => probe.close(() => resolve()));
+  const addr = `127.0.0.1:${port}`;
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ts-tls-"));
+  const child: ChildProcess = spawn(
+    process.env.AIKOQL_MCP_BIN!,
+    [
+      "serve", "--listen", addr, "--tcp-token", "ts-tls::admin",
+      "--tls-cert", path.join(FX, "server.pem"), "--tls-key", path.join(FX, "server.key"),
+      path.join(dir, "kb"),
+    ],
+    { stdio: ["ignore", "ignore", "ignore"], windowsHide: true },
+  );
+  t.after(async () => {
+    child.kill();
+    if (child.exitCode === null) await new Promise<void>((resolve) => child.once("exit", () => resolve()));
+    await fs.promises.rm(dir, { recursive: true, force: true }).catch(() => {});
+  });
+  const deadline = Date.now() + 10_000;
+  for (;;) {
+    const up = await new Promise<boolean>((resolve) => {
+      const s = net.connect(port, "127.0.0.1");
+      s.once("connect", () => { s.destroy(); resolve(true); });
+      s.once("error", () => resolve(false));
+    });
+    if (up) return addr;
+    if (Date.now() >= deadline) throw new Error(`TLS server never came up on ${addr}`);
+    await sleep(100);
+  }
+}
+
+test("MCP over TLS", { skip }, async (t) => {
+  const addr = await startTlsServer(t);
+  const c = (await Client.dial(addr, { tls: { ca: ca("ca.pem") } })).withToken("ts-tls");
+  t.after(() => c.close());
+  await c.initialize();
+  const put = (await c.callTool("remember", { subject: "admin", type_name: "note", properties: { n: 7 } })) as { koid: string };
+  assert.ok(put.koid, "remember over TLS returns a koid");
+  const got = (await c.callTool("get", { subject: "admin", koid: put.koid })) as { properties: { n: number } };
+  assert.equal(got.properties.n, 7);
+});
+
+test("an untrusted server is refused at the dial", { skip }, async (t) => {
+  const addr = await startTlsServer(t);
+  await assert.rejects(Client.dial(addr, { tls: { ca: ca("other-ca.pem") } }));
+});

package/tests/wire.test.ts

@@ -0,0 +1,207 @@
+// The wire-layer legs: ports of the Rust client's scripted-server suite
+// (crates/sdk/rust/src/client.rs tests). Each test drives a fake server
+// through the frozen §3.3 semantics — id correlation, deadline → TIMEOUT,
+// closed client → UNAVAILABLE, the version contract, the stream frame
+// protocol, the transaction guard, and self-healing after a late frame.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { McpError, MIN_SERVER_VERSION, withDeadline } from "../src/index.ts";
+import { dial, respond, scripted, toolResult } from "./helpers.ts";
+
+function isCode(e: unknown, code: string): boolean {
+  return e instanceof McpError && e.code === code;
+}
+
+test("initialize sends the handshake", async (t) => {
+  const reqs: Record<string, unknown>[] = [];
+  const addr = await scripted(t, (req) => {
+    reqs.push(req);
+    return [[respond(req["id"], MIN_SERVER_VERSION), 0]];
+  });
+  const c = await dial(t, addr);
+  await c.initialize();
+  assert.equal(reqs.length, 1);
+  assert.equal(reqs[0]!["method"], "initialize");
+});
+
+test("skips stale and id-less frames", async (t) => {
+  const addr = await scripted(t, (req) => [
+    ["{}", 0], // id-less push
+    [JSON.stringify({ id: 0, result: {} }), 0], // stale
+    [respond(req["id"], MIN_SERVER_VERSION), 0],
+  ]);
+  const c = await dial(t, addr);
+  await c.initialize();
+});
+
+test("protocol error on a foreign id", async (t) => {
+  const addr = await scripted(t, () => [
+    [JSON.stringify({ id: 99, result: {} }), 0],
+  ]);
+  const c = await dial(t, addr);
+  await assert.rejects(c.initialize(), (e: unknown) => isCode(e, "PROTOCOL_ERROR"));
+});
+
+test("rpc error envelope", async (t) => {
+  const addr = await scripted(t, (req) => [
+    [JSON.stringify({ id: req["id"], error: { code: "NOT_FOUND", message: "nope" } }), 0],
+  ]);
+  const c = await dial(t, addr);
+  await assert.rejects(c.initialize(), (e: unknown) => isCode(e, "NOT_FOUND"));
+});
+
+test("noise frames are skipped", async (t) => {
+  const addr = await scripted(t, (req) => [
+    ["not json", 0],
+    [respond(req["id"], MIN_SERVER_VERSION), 0],
+  ]);
+  const c = await dial(t, addr);
+  await c.initialize();
+});
+
+test("a deadline maps to the retryable TIMEOUT", async (t) => {
+  const addr = await scripted(t, () => []); // accepts, never answers
+  const c = await dial(t, addr);
+  await assert.rejects(
+    withDeadline(200, (signal) => c.initialize({ signal })),
+    (e: unknown) => isCode(e, "TIMEOUT") && (e as McpError).retryable,
+  );
+});
+
+test("a closed client is UNAVAILABLE", async (t) => {
+  const addr = await scripted(t, () => []);
+  const c = await dial(t, addr);
+  await c.close();
+  await assert.rejects(c.callTool("health"), (e: unknown) => isCode(e, "UNAVAILABLE"));
+});
+
+test("a too-old server fails fast with VERSION_MISMATCH", async (t) => {
+  const addr = await scripted(t, (req) => [[respond(req["id"], "0.0.1"), 0]]);
+  const c = await dial(t, addr);
+  await assert.rejects(c.initialize(), (e: unknown) => isCode(e, "VERSION_MISMATCH"));
+});
+
+test("a single-chunk stream (total_chunks 1) yields the head and ends", async (t) => {
+  const addr = await scripted(t, (req) => [
+    [
+      JSON.stringify({
+        id: req["id"],
+        result: { stream_id: "s1", total_chunks: 1, results: [{ koid: "k1" }] },
+      }),
+      0,
+    ],
+  ]);
+  const c = await dial(t, addr);
+  const chunks: unknown[] = [];
+  for await (const chunk of c.queryStream("MATCH p RETURN *", "")) chunks.push(chunk);
+  assert.equal(chunks.length, 1);
+  const head = chunks[0] as { results?: Array<{ koid?: string }> };
+  assert.equal(head.results?.[0]?.koid, "k1");
+});
+
+test("a multi-chunk stream ends on done", async (t) => {
+  const addr = await scripted(t, (req) => [
+    [
+      JSON.stringify({
+        id: req["id"],
+        result: { stream_id: "s1", total_chunks: 2, results: [{ koid: "k1" }] },
+      }),
+      0,
+    ],
+    [
+      JSON.stringify({
+        method: "notifications/notify",
+        params: { stream_id: "s1", chunk: 2, done: true, results: [{ koid: "k2" }] },
+      }),
+      0,
+    ],
+  ]);
+  const c = await dial(t, addr);
+  const chunks: unknown[] = [];
+  for await (const chunk of c.queryStream("MATCH p RETURN *", "")) chunks.push(chunk);
+  assert.equal(chunks.length, 2);
+  const second = chunks[1] as { results?: Array<{ koid?: string }> };
+  assert.equal(second.results?.[0]?.koid, "k2");
+});
+
+test("an aborted stream releases the connection", async (t) => {
+  const addr = await scripted(t, (req) => {
+    if (req["method"] === "aikoql/stream") {
+      return [
+        [JSON.stringify({ id: req["id"], result: { stream_id: "s1", total_chunks: 2, results: [] } }), 0],
+      ];
+    }
+    return [[toolResult(req["id"], { status: "healthy" }), 0]];
+  });
+  const c = await dial(t, addr);
+  const ctrl = new AbortController();
+  const stream = c.queryStream("MATCH p RETURN *", "", { signal: ctrl.signal });
+  const first = await stream.next();
+  assert.equal((first.value as { stream_id?: string }).stream_id, "s1");
+  // Cancellation while blocked on a read goes through the abort signal
+  // (return() waits for the pending read to settle — the single-threaded
+  // stand-in for the Rust select on the dropped receiver). The abort
+  // surfaces as the frozen TIMEOUT and the finally releases the lock.
+  ctrl.abort();
+  await assert.rejects(stream.next(), (e: unknown) => isCode(e, "TIMEOUT"));
+  const health = await c.callTool("health");
+  assert.equal((health as { status?: string }).status, "healthy");
+});
+
+test("a closed transaction handle refuses further use", async (t) => {
+  const addr = await scripted(t, (req) => {
+    const name = ((req["params"] as Record<string, unknown> | undefined)?.["name"]) as
+      | string
+      | undefined;
+    switch (name) {
+      case "txn_begin":
+        return [[toolResult(req["id"], {}), 0]];
+      case "txn_commit":
+        return [[toolResult(req["id"], { results: [], deduped: false }), 0]];
+      default:
+        throw new Error(`unexpected tool call ${name}`);
+    }
+  });
+  const c = await dial(t, addr);
+  const tx = await c.begin();
+  const res = await tx.commit();
+  assert.equal(res.deduped, false);
+  await assert.rejects(
+    tx.execute({ action: "create" }),
+    (e: unknown) => isCode(e, "INVALID_ARGUMENT"),
+  );
+});
+
+test("a late response after a timeout is skipped (self-healing)", async (t) => {
+  let calls = 0;
+  const addr = await scripted(t, (req) => {
+    calls += 1;
+    const delay = calls === 1 ? 300 : 0;
+    return [[respond(req["id"], MIN_SERVER_VERSION), delay]];
+  });
+  const c = await dial(t, addr);
+  await assert.rejects(
+    withDeadline(50, (signal) => c.initialize({ signal })),
+    (e: unknown) => isCode(e, "TIMEOUT"),
+  );
+  // The late frame for request 1 arrives during this call and is skipped
+  // (id 1 < id 2); the real answer for id 2 lands.
+  await c.initialize();
+});
+
+// A line that is valid JSON but not an object (null, a number, a string, an
+// array) is a malformed frame: skipped, never read as the response — the
+// Python SDK's crash on `0` (fuzz estate) checked across the SDKs; here a
+// `null` line threw a TypeError at resp["id"].
+test("a frame that is JSON but not an object is skipped", async (t) => {
+  const addr = await scripted(t, (req) => [
+    ["null", 0],
+    ["0", 0],
+    ['"s"', 0],
+    ["[1]", 0],
+    [toolResult(req["id"], { ok: true }), 0],
+  ]);
+  const c = await dial(t, addr);
+  assert.deepEqual(await c.callTool("probe", {}), { ok: true });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": ["es2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}