chain-client-sdk-ts/test/real_hub.test.ts
Dr. Stefan Flemming b6c6cc8295 feat: TypeScript client for Node, with a scriptable fake hub
A service in front of a hub needs four things: start a flow, follow
it, read what a detached run produced, and decide approvals. This is
that surface, plus the part a gateway cannot test without: a fake hub
that speaks the same service from the same .proto files and can be
scripted into every failure a real hub produces.

Errors carry the hub's own class (chain-error-kind), a coarse family,
and reachedHub, which separates a refused connection from a hub that
reports a dependency as down. Both arrive as gRPC UNAVAILABLE, and a
gateway that shows 'service not reachable' for the second one lies to
its users.

The .proto files are carried verbatim and loaded at runtime, so no
generated code can drift from the contract; two guards hold the
copies in place, and a skew suite runs the same client against a real
hub binary.

32 hermetic tests plus 4 against a real hub.

Signed-off-by: Dr. Stefan Flemming <sf@flemming.it>
2026-10-27 00:59:57 +01:00

127 lines
4.6 KiB
TypeScript

// The client against a real hub binary.
//
// This is the skew gate for the TypeScript client: it proves that the
// shapes this client encodes are the shapes the hub decodes, which a
// fake can never prove. It needs a built `chain` binary and therefore
// skips when there is none; CI and release work set `CHAIN_BIN`.
//
// CHAIN_BIN=../fai_chain/target/debug/chain npm test
import assert from 'node:assert/strict';
import { spawn, type ChildProcess } from 'node:child_process';
import { existsSync, mkdtempSync, rmSync } from 'node:fs';
import { createServer } from 'node:net';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { after, before, describe, it } from 'node:test';
import { ChainClient, ChainError, asText, protoDir } from '../src/index.js';
// `protoDir` is found by searching, so it is the one path that holds
// whether this runs from `src`, `dist` or a test build.
const sdkRoot = resolve(protoDir, '..');
const platformRepo = resolve(
process.env.CHAIN_PLATFORM_REPO ?? join(sdkRoot, '..', 'fai_chain'),
);
const hubBinary = resolve(process.env.CHAIN_BIN ?? join(platformRepo, 'target', 'debug', 'chain'));
const modulesDir = join(platformRepo, 'modules');
const echoWasm = join(modulesDir, 'echo', 'target', 'wasm32-wasip2', 'release', 'echo.wasm');
const available = existsSync(hubBinary) && existsSync(echoWasm);
const HELLO = `name: hello
inputs:
name: text
steps:
- id: greet
use: debug.echo@^0
with:
message: "Hello, $inputs.name"
outputs:
greeting: $greet.echoed
`;
async function freePort(): Promise<number> {
return new Promise((resolvePort, reject) => {
const server = createServer();
server.on('error', reject);
server.listen(0, '127.0.0.1', () => {
const address = server.address();
const port = typeof address === 'object' && address ? address.port : 0;
server.close(() => resolvePort(port));
});
});
}
describe('client against a real hub', { skip: available ? false : `no hub binary at ${hubBinary}` }, () => {
let hub: ChildProcess | undefined;
let client: ChainClient;
let dataDir = '';
before(async () => {
const port = await freePort();
dataDir = mkdtempSync(join(tmpdir(), 'chain-ts-e2e-'));
hub = spawn(
hubBinary,
['serve', '--bind', `127.0.0.1:${port}`, '--modules-dir', modulesDir, '--data-dir', join(dataDir, 'chain.db')],
{ stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, CHAIN_DATA_DIR: dataDir } },
);
client = new ChainClient({ address: `127.0.0.1:${port}`, deadlineMs: 20_000 });
const until = Date.now() + 30_000;
for (;;) {
try {
const health = await client.health(2_000);
if (health.state === 'SERVING') break;
} catch {
// not up yet
}
if (Date.now() > until) throw new Error('the hub did not start');
await new Promise((r) => setTimeout(r, 200));
}
});
after(async () => {
client?.close();
hub?.kill('SIGTERM');
if (dataDir) rmSync(dataDir, { recursive: true, force: true });
});
it('runs the hello flow and reads the output', async () => {
const result = await client.submit({ flowYaml: HELLO, inputs: { name: 'Ch∆In' } });
assert.equal(asText(result.outputs.greeting), 'Hello, Ch∆In');
});
it('follows the same flow step by step', async () => {
const steps: string[] = [];
let greeting: string | undefined;
for await (const event of client.submitStream({ flowYaml: HELLO, inputs: { name: 'stream' } })) {
if (event.type === 'stepStarted') steps.push(event.step);
if (event.type === 'result') greeting = asText(event.result.outputs.greeting);
}
assert.deepEqual(steps, ['greet']);
assert.equal(greeting, 'Hello, stream');
});
it('gets the real error class out of a real refusal', async () => {
const err = (await client
.submit({ flowYaml: 'this is not a flow [' })
.catch((e: unknown) => e)) as ChainError;
assert.ok(err instanceof ChainError);
assert.equal(err.kind, 'flow_rejected');
assert.equal(err.reachedHub, true);
assert.equal(err.retryable, false);
});
it('refuses a flow whose module is not installed, as not_found', async () => {
const err = (await client
.submit({
flowYaml: `name: nowhere\nsteps:\n - id: x\n use: nothing.at.all/missing@^1\noutputs:\n out: $x.text\n`,
})
.catch((e: unknown) => e)) as ChainError;
assert.ok(err instanceof ChainError);
assert.equal(err.reachedHub, true);
assert.ok(
err.kind === 'not_found' || err.kind === 'flow_rejected',
`an unknown capability reads as not_found or flow_rejected, got ${err.kind}`,
);
});
});