@aikoql/client 0.2.3 → 0.2.4

package/README.md

@@ -5,7 +5,9 @@ The first-party TypeScript client for the [aikoql](https://github.com/anckursing
 ```ts
 import { Client } from "@aikoql/client";
 
-const client = await Client.dial("127.0.0.1:9090", { token: "s3cret" });
+const client = (await Client.dial("127.0.0.1:9090")).withToken("s3cret");
+// a server started with --tls-cert/--tls-key ({} for a public CA):
+// await Client.dial("db.internal:9090", { tls: { ca: readFileSync("ca.pem") } })
 const agent = await client.agent();
 await agent.remember("person", { name: "ada" });
 for await (const row of client.queryStream("MATCH person RETURN *")) { /* ... */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikoql/client",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Aikoql — the TypeScript SDK for the agent-first knowledge database. Node + browser-compatible core, async/await, AsyncIterable streaming, AbortSignal, pool. Zero runtime dependencies.",
   "license": "Apache-2.0",
   "author": {

package/src/client.ts

@@ -10,6 +10,7 @@
 // transport changes).
 
 import { randomBytes } from "node:crypto";
+import type { ConnectionOptions } from "node:tls";
 import { readFileSync } from "node:fs";
 import { McpError } from "./error.ts";
 import { TcpTransport, type Transport } from "./tcp.ts";
@@ -28,7 +29,7 @@ import { Tx } from "./tx.ts";
  * The oldest aikoql-mcp server this SDK will talk to (the ND-12 version
  * contract, mirrored from the Go, Python and Rust SDKs).
  */
-export const MIN_SERVER_VERSION = "0.2.3";
+export const MIN_SERVER_VERSION = "0.2.4";
 
 /** The SDK's own package version, advertised as the client identity:
  * read from package.json so the manifest, not a literal, owns it. */
@@ -98,6 +99,19 @@ export function streamNotify(frame: Record<string, unknown>, streamId: string):
   return p;
 }
 
+/** One wire line as a JSON object, or undefined for noise: not JSON, or
+ * JSON that is not an object (null, a number, a string, an array) — never
+ * a response, never a notify. */
+function parseFrame(line: string): Record<string, unknown> | undefined {
+  let v: unknown;
+  try {
+    v = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+}
+
 /**
  * One MCP JSON-RPC connection to an aikoql-mcp server. One in-flight call
  * per connection (a stream holds the connection for its whole life); calls
@@ -113,17 +127,26 @@ export class Client {
   // The open stream's release (null when none): close() cancels a
   // mid-stream close through it (§17).
   private streamGate: (() => void) | null = null;
+  // The TCP address dialed (undefined for other transports) — moved by a
+  // NOT_LEADER leader hint (MRFC-0080 R5b).
+  private addr: string | undefined;
+  // The TLS options a leader hint is re-dialed with too (none: plaintext).
+  private tls: ConnectionOptions | undefined;
 
-  private constructor(transport: Transport) {
+  private constructor(transport: Transport, addr?: string, tlsOptions?: ConnectionOptions) {
     this.transport = transport;
+    this.addr = addr;
+    this.tls = tlsOptions;
   }
 
   /** Opens a TCP connection ("host:port"). The handshake is separate
    * (initialize) so a pooled client can dial first and authenticate later;
-   * every aikoql-mcp TCP server requires the token. */
-  static async dial(addr: string): Promise<Client> {
-    const transport = await TcpTransport.connect(addr, DIAL_TIMEOUT_MS);
-    return new Client(transport);
+   * every aikoql-mcp TCP server requires the token. `opts.tls` (Node's
+   * tls.ConnectionOptions — e.g. `{ ca }` for a private CA; `{}` for the
+   * system roots) dials a server started with --tls-cert/--tls-key. */
+  static async dial(addr: string, opts: { tls?: ConnectionOptions } = {}): Promise<Client> {
+    const transport = await TcpTransport.connect(addr, DIAL_TIMEOUT_MS, opts.tls);
+    return new Client(transport, addr, opts.tls);
   }
 
   /** Sends the --tcp-token credential in the initialize handshake
@@ -192,12 +215,8 @@ export class Client {
           this.closed = true;
           throw McpError.io("connection closed by the server");
         }
-        let resp: Record<string, unknown>;
-        try {
-          resp = JSON.parse(line) as Record<string, unknown>;
-        } catch {
-          continue; // tolerate non-JSON noise frames
-        }
+        const resp = parseFrame(line);
+        if (resp === undefined) continue; // non-JSON or non-object noise
         const rid = resp["id"] ?? 0;
         if (typeof rid !== "number") continue; // not our numeric correlation
         switch (classifyID(id, rid)) {
@@ -243,11 +262,42 @@ export class Client {
   }
 
   /** Calls any registered MCP tool by name and returns its data payload —
-   * the escape hatch for tools without a typed wrapper here. */
+   * the escape hatch for tools without a typed wrapper here.
+   *
+   * MRFC-0080 R5b: refused with NOT_LEADER and a leader hint, a TCP
+   * client reconnects to that leader, re-runs initialize and retries the
+   * call once; it then stays on the leader. sessionInit identity is not
+   * replayed. */
   async callTool(
     name: string,
     args?: unknown,
     opts: { signal?: AbortSignal } = {},
+  ): Promise<unknown> {
+    try {
+      return await this.callToolOnce(name, args, opts);
+    } catch (e) {
+      if (!(e instanceof McpError) || e.code !== "NOT_LEADER" || !e.leader || this.addr === undefined) throw e;
+      await this.follow(e.leader, opts.signal);
+      return this.callToolOnce(name, args, opts);
+    }
+  }
+
+  /** Replaces the connection with one to the leader at `addr` and
+   * re-runs the handshake. */
+  private async follow(addr: string, signal?: AbortSignal): Promise<void> {
+    const next = await TcpTransport.connect(addr, DIAL_TIMEOUT_MS, this.tls);
+    await this.withLock(async () => {
+      this.transport.close();
+      this.transport = next;
+      this.addr = addr;
+    });
+    await this.initialize({ signal });
+  }
+
+  private async callToolOnce(
+    name: string,
+    args?: unknown,
+    opts: { signal?: AbortSignal } = {},
   ): Promise<unknown> {
     const params: Record<string, unknown> = { name };
     if (args !== undefined) params.arguments = args;
@@ -270,12 +320,14 @@ export class Client {
           message?: string;
           retryable?: boolean;
           suggestion?: string;
+          leader?: string;
         };
         throw new McpError(
           e.code ?? "INTERNAL",
           e.message ?? "",
           e.retryable ?? false,
           e.suggestion ?? "",
+          e.leader,
         );
       }
       throw new McpError(
@@ -336,12 +388,8 @@ export class Client {
           this.closed = true;
           throw McpError.io("connection closed by the server");
         }
-        let resp: Record<string, unknown>;
-        try {
-          resp = JSON.parse(line) as Record<string, unknown>;
-        } catch {
-          continue;
-        }
+        const resp = parseFrame(line);
+        if (resp === undefined) continue; // non-JSON or non-object noise
         const rid = resp["id"] ?? 0;
         if (typeof rid === "number" && rid === id) {
           if (resp["error"] !== undefined) {

package/src/error.ts

@@ -17,13 +17,16 @@ export class McpError extends Error {
   code: string;
   retryable: boolean;
   suggestion: string;
+  /** The leader's client address on a NOT_LEADER refusal (MRFC-0080 R4d). */
+  leader?: string;
 
-  constructor(code: string, message: string, retryable = false, suggestion = "") {
+  constructor(code: string, message: string, retryable = false, suggestion = "", leader?: string) {
     super(`[${code}] ${message}`);
     this.name = "McpError";
     this.code = code;
     this.retryable = retryable;
     this.suggestion = suggestion;
+    if (leader !== undefined) this.leader = leader;
   }
 
   /** The frozen TIMEOUT (retryable): a deadline elapsed before a response. */

package/src/pool.ts

@@ -56,6 +56,9 @@ export class PooledConn {
   private p: Pool;
   private c: Client;
   private tx: Tx | null = null;
+  // performance.now() milliseconds (monotonic, sub-ms): a borrow in the same
+  // millisecond as the release still sees time pass, so healthCheckIntervalMs
+  // 0 pings every borrow
   createdAt: number;
   lastUsed: number;
   broken = false;
@@ -144,7 +147,7 @@ export class Pool {
           await pc.client().close().catch(() => {});
           continue;
         }
-        const now = Date.now();
+        const now = performance.now();
         if (now - pc.lastUsed > this.cfg.healthCheckIntervalMs) {
           // Ping: a dead connection is dropped and replaced by a fresh
           // dial (the reconnect leg of §21).
@@ -170,7 +173,7 @@ export class Pool {
           this.total--;
           throw e;
         }
-        const now = Date.now();
+        const now = performance.now();
         return new PooledConn(this, c, now);
       }
       // Exhausted: wait for a return or the acquire timeout.
@@ -200,7 +203,7 @@ export class Pool {
    * reconnect leg: a dead server keeps the borrow pending and succeeds
    * once the server returns. */
   private async dialRetry(): Promise<Client> {
-    const deadline = Date.now() + this.cfg.acquireTimeoutMs;
+    const deadline = performance.now() + this.cfg.acquireTimeoutMs;
     let lastErr: unknown;
     for (;;) {
       try {
@@ -208,7 +211,7 @@ export class Pool {
       } catch (e) {
         lastErr = e;
       }
-      if (Date.now() >= deadline) {
+      if (performance.now() >= deadline) {
         throw new McpError(
           "UNAVAILABLE",
           `could not connect to the server: ${String(lastErr)}`,
@@ -223,7 +226,7 @@ export class Pool {
   /** Whether an idle connection was reaped by the idle or lifetime
    * timeout. */
   private expired(pc: PooledConn): boolean {
-    const now = Date.now();
+    const now = performance.now();
     return (
       now - pc.lastUsed > this.cfg.idleTimeoutMs ||
       now - pc.createdAt > this.cfg.maxLifetimeMs
@@ -235,7 +238,7 @@ export class Pool {
    * dropped instead. Public only for PooledConn — the stand-in for Go's
    * same-package access. */
   put(pc: PooledConn): void {
-    const now = Date.now();
+    const now = performance.now();
     pc.lastUsed = now;
     const drop =
       this.closedFlag || pc.broken || now - pc.createdAt > this.cfg.maxLifetimeMs;
@@ -270,7 +273,7 @@ export class Pool {
         this.total--;
         throw e;
       }
-      this.put(new PooledConn(this, c, Date.now()));
+      this.put(new PooledConn(this, c, performance.now()));
     }
   }
 

package/src/tcp.ts

@@ -4,6 +4,7 @@
 // D-15 native protocol replacement likewise swaps only the Transport.
 
 import net from "node:net";
+import tls from "node:tls";
 import { McpError } from "./error.ts";
 
 /** §19: a malicious server cannot cause unbounded client memory — an
@@ -69,16 +70,27 @@ export class TcpTransport implements Transport {
     socket.on("error", () => {});
   }
 
-  /** Connects, bounding the dial by the frozen TIMEOUT (the Go/Rust shape). */
-  static connect(addr: string, timeoutMs: number): Promise<TcpTransport> {
+  /** Connects, bounding the dial by the frozen TIMEOUT (the Go/Rust shape).
+   * With `tlsOptions` (a server started with --tls-cert/--tls-key) the
+   * handshake verifies the certificate for `host` — an IP against the SAN,
+   * a DNS name also sent as SNI — before resolving, so the token is never
+   * sent to an unverified peer. */
+  static connect(addr: string, timeoutMs: number, tlsOptions?: tls.ConnectionOptions): Promise<TcpTransport> {
     return new Promise((resolve, reject) => {
       const [host, port] = addr.split(":");
-      const socket = net.connect(Number(port), host!);
+      const socket = tlsOptions
+        ? tls.connect({
+            host,
+            port: Number(port),
+            ...(net.isIP(host!) ? {} : { servername: host }),
+            ...tlsOptions,
+          })
+        : net.connect(Number(port), host!);
       const timer = setTimeout(() => {
         socket.destroy();
         reject(McpError.deadline());
       }, timeoutMs);
-      socket.once("connect", () => {
+      socket.once(tlsOptions ? "secureConnect" : "connect", () => {
         clearTimeout(timer);
         resolve(new TcpTransport(socket));
       });

package/tests/fuzz-estate.test.ts

@@ -176,7 +176,8 @@ test("the envelope property", async () => {
         async (addr) => {
           const c = await Client.dial(addr);
           try {
-            assert.deepEqual(await c.callTool("probe"), env);
+            // what JSON can carry: jsonValue() may yield -0, which encodes as 0
+            assert.deepEqual(await c.callTool("probe"), JSON.parse(JSON.stringify(env)));
           } finally {
             await c.close().catch(() => {});
           }

package/tests/leader-hint.test.ts

@@ -0,0 +1,50 @@
+// MRFC-0080 R5b — the client follows a NOT_LEADER leader hint: a fenced
+// server refuses a write with NOT_LEADER and the newer leader's client
+// address; the call is retried once against that leader over a fresh,
+// initialized connection, and the client stays there.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { McpError, MIN_SERVER_VERSION } from "../src/index.ts";
+import { dial, respond, scripted, toolResult } from "./helpers.ts";
+
+function notLeader(id: unknown, leader?: string): string {
+  const error: Record<string, unknown> = { code: "NOT_LEADER", message: "not leader", retryable: true };
+  if (leader !== undefined) error.leader = leader;
+  return JSON.stringify({
+    id,
+    result: { content: [{ text: JSON.stringify({ ok: false, error }) }], isError: true },
+  });
+}
+
+test("NOT_LEADER follows the leader hint", async (t) => {
+  const saw: string[] = [];
+  const leader = await scripted(t, (req) => {
+    saw.push(req["method"] as string);
+    return req["method"] === "initialize"
+      ? [[respond(req["id"], MIN_SERVER_VERSION), 0]]
+      : [[toolResult(req["id"], { koid: "ko-1" }), 0]];
+  });
+  const fenced = await scripted(t, (req) =>
+    req["method"] === "initialize"
+      ? [[respond(req["id"], MIN_SERVER_VERSION), 0]]
+      : [[notLeader(req["id"], leader), 0]],
+  );
+  const c = (await dial(t, fenced)).withToken("t");
+  await c.initialize();
+  assert.deepEqual(await c.callTool("remember", { type_name: "note" }), { koid: "ko-1" });
+  await c.callTool("remember", { type_name: "note" });
+  assert.deepEqual(saw, ["initialize", "tools/call", "tools/call"]);
+});
+
+test("NOT_LEADER without a hint is thrown", async (t) => {
+  const addr = await scripted(t, (req) => [[notLeader(req["id"]), 0]]);
+  const c = await dial(t, addr);
+  await assert.rejects(c.callTool("remember", {}), (e: unknown) => {
+    assert.ok(e instanceof McpError);
+    assert.equal(e.code, "NOT_LEADER");
+    assert.equal(e.retryable, true);
+    assert.equal(e.leader, undefined);
+    return true;
+  });
+});

package/tests/pool.test.ts

@@ -65,6 +65,25 @@ function poolFactory(t: TestContext, respond: (req: Record<string, unknown>) =>
   };
 }
 
+// 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));
@@ -242,9 +261,9 @@ test(
       }
       return c;
     };
-    // A near-zero health-check interval: every borrow pings, so a dead
+    // 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: 1 });
+    const p = new Pool({ factory, maxConns: 1, acquireTimeoutMs: 10_000, healthCheckIntervalMs: 0 });
     t.after(() => {
       void p.close();
     });

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

@@ -189,3 +189,19 @@ test("a late response after a timeout is skipped (self-healing)", async (t) => {
   // (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 });
+});