chain-client-sdk-ts/test/client_against_fake.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

277 lines
10 KiB
TypeScript

// The client against the fake hub: hermetic, no hub binary, no
// module, no model. Every case here is one a portal gateway has to
// survive.
import assert from 'node:assert/strict';
import { after, before, beforeEach, describe, it } from 'node:test';
import { ChainClient, ChainError, asJson, asText } from '../src/index.js';
import { FakeHub } from '../src/fake_hub.js';
const FLOW = `name: verbrauchsausweis
inputs:
consumption: { type: json }
steps:
- id: score
uses: geg.verbrauch@^1
outputs:
report: $steps.score.text
`;
describe('client against the fake hub', () => {
let hub: FakeHub;
let client: ChainClient;
before(async () => {
hub = new FakeHub();
const address = await hub.start();
client = new ChainClient({ address, project: 'helloeco', deadlineMs: 5_000 });
});
after(async () => {
client.close();
await hub.close();
});
beforeEach(() => {
hub.setFallback({ type: 'succeed', outputs: {} });
hub.setHealth('SERVING');
});
it('reports health', async () => {
const health = await client.health();
assert.equal(health.state, 'SERVING');
});
it('runs a flow and reads its outputs', async () => {
hub.succeeds({ report: 'Endenergiebedarf 128 kWh/(m²·a)', data: { json: { class: 'D' } } });
const result = await client.submit({
flowYaml: FLOW,
inputs: { consumption: { json: { kwh: 15400 } } },
});
assert.equal(asText(result.outputs.report), 'Endenergiebedarf 128 kWh/(m²·a)');
assert.deepEqual(asJson(result.outputs.data), { class: 'D' });
assert.match(result.invocationId, /^run-/);
const seen = hub.submits.at(-1);
assert.equal(seen?.project, 'helloeco');
assert.deepEqual(seen?.inputs.consumption, { kind: 'json', json: { kwh: 15400 } });
});
it('follows a run step by step', async () => {
hub.succeeds({ report: 'done' }, ['check', 'score', 'render']);
const events = [];
for await (const event of client.submitStream({ flowYaml: FLOW })) {
events.push(event);
}
const started = events.filter((e) => e.type === 'stepStarted').map((e) => e.step);
assert.deepEqual(started, ['check', 'score', 'render']);
const last = events.at(-1);
assert.equal(last?.type, 'result');
if (last?.type === 'result') {
assert.equal(asText(last.result.outputs.report), 'done');
}
});
it('classifies an overloaded hub as retryable without blaming the request', async () => {
hub.fails('overloaded', 'too many runs in flight');
const err = await client.submit({ flowYaml: FLOW }).then(
() => undefined,
(e: unknown) => e as ChainError,
);
assert.ok(err instanceof ChainError);
assert.equal(err.kind, 'overloaded');
assert.equal(err.family, 'overloaded');
assert.equal(err.retryable, true);
assert.equal(err.reachedHub, true);
});
it('classifies a refused request as not retryable', async () => {
hub.fails('flow_rejected', "missing value '$inputs.consumption'");
const err = (await client.submit({ flowYaml: FLOW }).catch((e) => e)) as ChainError;
assert.equal(err.kind, 'flow_rejected');
assert.equal(err.retryable, false);
});
it('carries the class out of a stream too', async () => {
hub.fails('step_failed', "step 'render' failed: template has no page size");
const err = await (async () => {
try {
for await (const _event of client.submitStream({ flowYaml: FLOW })) {
// drain
}
return undefined;
} catch (e) {
return e as ChainError;
}
})();
assert.ok(err instanceof ChainError);
assert.equal(err.kind, 'step_failed');
assert.equal(err.family, 'failed');
assert.equal(err.step, 'render');
});
it('returns the same run for the same idempotency key', async () => {
hub.succeeds({ report: 'first' });
hub.succeeds({ report: 'second' });
const first = await client.submit({ flowYaml: FLOW, idempotencyKey: 'stripe-evt-1' });
const again = await client.submit({ flowYaml: FLOW, idempotencyKey: 'stripe-evt-1' });
assert.equal(again.invocationId, first.invocationId);
assert.equal(asText(again.outputs.report), 'first');
// The second submit must not have consumed the next scripted run.
const third = await client.submit({ flowYaml: FLOW, idempotencyKey: 'stripe-evt-2' });
assert.equal(asText(third.outputs.report), 'second');
assert.notEqual(third.invocationId, first.invocationId);
});
it('waits for an approval, then finishes with the reviewer on record', async () => {
hub.waitsForApproval({
prompt: 'Registriernummer 4711 vergeben und Ausweis zustellen?',
stepId: 'freigabe',
outputs: { report: 'zugestellt' },
});
const run = client.submit({ flowYaml: FLOW });
const pending = await waitFor(async () => {
const list = await client.listApprovals({ project: 'helloeco' });
return list.length > 0 ? list : undefined;
});
assert.equal(pending[0]?.prompt, 'Registriernummer 4711 vergeben und Ausweis zustellen?');
assert.equal(pending[0]?.stepId, 'freigabe');
await client.decideApproval({
approvalId: pending[0]!.approvalId,
approve: true,
reviewer: 'aussteller@example.org',
});
const result = await run;
assert.equal(asText(result.outputs.report), 'zugestellt');
assert.equal(hub.decisions.at(-1)?.reviewer, 'aussteller@example.org');
});
it('fails the run when the reviewer declines, with the reason', async () => {
hub.waitsForApproval({ prompt: 'Ausweis zustellen?', outputs: {} });
// The catch is attached right away: the run rejects while the
// test is still waiting for the approval row, and an unhandled
// rejection in between would fail the test for the wrong reason.
const run = client.submit({ flowYaml: FLOW }).catch((e: unknown) => e as ChainError);
const pending = await waitFor(async () => {
const list = await client.listApprovals();
return list.length > 0 ? list : undefined;
});
await client.decideApproval({
approvalId: pending[0]!.approvalId,
approve: false,
reviewer: 'aussteller@example.org',
reason: 'Verbrauchswerte unplausibel',
});
const err = (await run) as ChainError;
assert.equal(err.kind, 'approval_rejected');
assert.match(err.message, /unplausibel/);
});
it('refuses a rejection without a reason', async () => {
hub.waitsForApproval({ prompt: 'Ausweis zustellen?', outputs: {} });
const run = client.submit({ flowYaml: FLOW }).catch((e: unknown) => e as ChainError);
const pending = await waitFor(async () => {
const list = await client.listApprovals();
return list.length > 0 ? list : undefined;
});
const err = (await client
.decideApproval({ approvalId: pending[0]!.approvalId, approve: false })
.catch((e) => e)) as ChainError;
assert.equal(err.kind, 'flow_rejected');
await client.decideApproval({
approvalId: pending[0]!.approvalId,
approve: false,
reason: 'aufgeräumt',
});
await run;
});
it('follows a detached run by id', async () => {
hub.succeeds({ report: 'spät' });
const started = await client.submit({ flowYaml: FLOW, detach: true });
assert.deepEqual(started.outputs, {});
const status = await client.getStatus(started.invocationId);
assert.equal(status.phase, 'SUCCEEDED');
const result = await client.getResult(started.invocationId);
assert.equal(asText(result.outputs.report), 'spät');
});
it('says not_found for an invocation the hub never had', async () => {
const err = (await client.getStatus('run-does-not-exist').catch((e) => e)) as ChainError;
assert.equal(err.kind, 'not_found');
assert.equal(err.family, 'rejected');
});
});
describe('client against a hub that is not there', () => {
it('says the hub was never reached, not that a dependency failed', async () => {
const hub = new FakeHub();
const address = await hub.start();
const client = new ChainClient({ address, deadlineMs: 2_000 });
await client.health();
await hub.stop();
const err = (await client.health().catch((e) => e)) as ChainError;
assert.equal(err.family, 'unreachable');
assert.equal(err.reachedHub, false);
assert.equal(err.retryable, true);
client.close();
await hub.close();
});
});
describe('a hub restart while a run waits for an approval', () => {
it('loses the run, keeps the approval, and says so', async () => {
// This is today's platform behaviour, not a wish: run state lives
// in memory, approvals live in SQLite. A gateway must therefore
// treat "approval still pending after a restart" as a run it has
// to start again.
const hub = new FakeHub();
const address = await hub.start();
const client = new ChainClient({ address, project: 'helloeco', deadlineMs: 5_000 });
hub.waitsForApproval({ prompt: 'Ausweis zustellen?', outputs: { report: 'zugestellt' } });
const run = client.submit({ flowYaml: FLOW }).catch((e: unknown) => e as ChainError);
const pending = await waitFor(async () => {
const list = await client.listApprovals({ project: 'helloeco' });
return list.length > 0 ? list : undefined;
});
const approvalId = pending[0]!.approvalId;
await hub.restart();
const err = (await run) as ChainError;
assert.equal(err.family, 'unreachable');
// The decision still lands, and still has nothing to resume.
const stillPending = await client.listApprovals({ project: 'helloeco' });
assert.equal(stillPending.length, 1);
assert.equal(stillPending[0]?.approvalId, approvalId);
const decided = await client.decideApproval({
approvalId,
approve: true,
reviewer: 'aussteller@example.org',
});
assert.equal(decided.status, 'APPROVED');
const gone = (await client.getStatus(pending[0]!.flowExecution).catch((e) => e)) as ChainError;
assert.equal(gone.kind, 'not_found');
client.close();
await hub.close();
});
});
/** Poll until the producer returns something, or give up. */
async function waitFor<T>(produce: () => Promise<T | undefined>, timeoutMs = 3_000): Promise<T> {
const until = Date.now() + timeoutMs;
for (;;) {
const value = await produce();
if (value !== undefined) return value;
if (Date.now() > until) throw new Error('timed out waiting for the fake hub');
await new Promise((resolve) => setTimeout(resolve, 20));
}
}