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>
105 lines
4.5 KiB
TypeScript
105 lines
4.5 KiB
TypeScript
import assert from 'node:assert/strict';
|
|
import { describe, it } from 'node:test';
|
|
|
|
import { status as GrpcStatus, Metadata } from '@grpc/grpc-js';
|
|
import type { ServiceError } from '@grpc/grpc-js';
|
|
|
|
import { ChainError, chainErrorFrom, kindForCode } from '../src/errors.js';
|
|
|
|
function serviceError(code: number, details: string, kind?: string): ServiceError {
|
|
const metadata = new Metadata();
|
|
if (kind) metadata.set('chain-error-kind', kind);
|
|
const err = new Error(details) as ServiceError;
|
|
err.code = code;
|
|
err.details = details;
|
|
err.metadata = metadata;
|
|
return err;
|
|
}
|
|
|
|
describe('error classification', () => {
|
|
it('prefers the class the hub sent over the gRPC code', () => {
|
|
// Both arrive as INVALID_ARGUMENT. Only the class separates
|
|
// "fix your request" from "the module ran and said no".
|
|
const rejected = chainErrorFrom(
|
|
serviceError(GrpcStatus.INVALID_ARGUMENT, "missing value '$inputs.x'", 'flow_rejected'),
|
|
);
|
|
const failed = chainErrorFrom(
|
|
serviceError(GrpcStatus.INVALID_ARGUMENT, "step 'render' failed", 'step_failed'),
|
|
);
|
|
assert.equal(rejected.kind, 'flow_rejected');
|
|
assert.equal(rejected.family, 'rejected');
|
|
assert.equal(failed.kind, 'step_failed');
|
|
assert.equal(failed.family, 'failed');
|
|
assert.equal(failed.step, 'render');
|
|
});
|
|
|
|
it('tells a hub that is not reachable from a dependency that is down', () => {
|
|
const noHub = chainErrorFrom(serviceError(GrpcStatus.UNAVAILABLE, 'No connection established'));
|
|
const hubSaysSo = chainErrorFrom(
|
|
serviceError(GrpcStatus.UNAVAILABLE, "service 'ollama' did not answer", 'unavailable'),
|
|
);
|
|
assert.equal(noHub.reachedHub, false);
|
|
assert.equal(hubSaysSo.reachedHub, true);
|
|
// Both are retryable, but only one is the hub's own fault.
|
|
assert.equal(noHub.retryable, true);
|
|
assert.equal(hubSaysSo.retryable, true);
|
|
});
|
|
|
|
it('reads a cancellation it did not cause as a lost hub', () => {
|
|
// grpc-js reports CANCELLED when the transport drops a call in
|
|
// flight. Without a class the hub never produced that status, and
|
|
// a gateway must not read it as "I cancelled this myself".
|
|
const err = chainErrorFrom(serviceError(GrpcStatus.CANCELLED, 'Call cancelled'));
|
|
assert.equal(err.kind, 'unavailable');
|
|
assert.equal(err.family, 'unreachable');
|
|
assert.equal(err.reachedHub, false);
|
|
// A cancellation the hub itself reports keeps its class.
|
|
const fromHub = chainErrorFrom(
|
|
serviceError(GrpcStatus.CANCELLED, 'cancelled by the caller', 'cancelled'),
|
|
);
|
|
assert.equal(fromHub.kind, 'cancelled');
|
|
});
|
|
|
|
it('keeps an unknown class from a newer hub instead of crashing', () => {
|
|
const err = chainErrorFrom(
|
|
serviceError(GrpcStatus.INTERNAL, 'something new', 'quantum_entanglement'),
|
|
);
|
|
assert.equal(err.kind, 'unknown');
|
|
assert.equal(err.family, 'internal');
|
|
assert.equal(err.reachedHub, true);
|
|
});
|
|
|
|
it('maps every gRPC code a hub can send', () => {
|
|
assert.equal(kindForCode(GrpcStatus.INVALID_ARGUMENT), 'flow_rejected');
|
|
assert.equal(kindForCode(GrpcStatus.NOT_FOUND), 'not_found');
|
|
assert.equal(kindForCode(GrpcStatus.ALREADY_EXISTS), 'conflict');
|
|
assert.equal(kindForCode(GrpcStatus.FAILED_PRECONDITION), 'precondition');
|
|
assert.equal(kindForCode(GrpcStatus.UNAVAILABLE), 'unavailable');
|
|
assert.equal(kindForCode(GrpcStatus.RESOURCE_EXHAUSTED), 'overloaded');
|
|
assert.equal(kindForCode(GrpcStatus.DEADLINE_EXCEEDED), 'timeout');
|
|
assert.equal(kindForCode(GrpcStatus.PERMISSION_DENIED), 'forbidden');
|
|
assert.equal(kindForCode(GrpcStatus.UNAUTHENTICATED), 'unauthenticated');
|
|
assert.equal(kindForCode(GrpcStatus.CANCELLED), 'cancelled');
|
|
assert.equal(kindForCode(GrpcStatus.INTERNAL), 'internal');
|
|
});
|
|
|
|
it('only marks the three families a retry can help', () => {
|
|
const retryable = ['unavailable', 'overloaded', 'timeout'] as const;
|
|
for (const kind of retryable) {
|
|
assert.equal(new ChainError('x', { kind, code: 0, reachedHub: true }).retryable, true, kind);
|
|
}
|
|
for (const kind of ['flow_rejected', 'step_failed', 'forbidden', 'internal'] as const) {
|
|
assert.equal(new ChainError('x', { kind, code: 0, reachedHub: true }).retryable, false, kind);
|
|
}
|
|
});
|
|
|
|
it('logs one line without the payload', () => {
|
|
const err = new ChainError("step 'render' failed", {
|
|
kind: 'step_failed',
|
|
code: 3,
|
|
reachedHub: true,
|
|
step: 'render',
|
|
});
|
|
assert.equal(String(err), "ChainError[step_failed/failed] step 'render' failed step=render");
|
|
});
|
|
});
|