Expected Errors
Problem
During automated testing it is common to assert that a given call should fail with a known error type. Consider a test that verifies a parking handler rejects an invalid zone:
await assert.rejects(parkingTest({zone: 'red'}, $meta), {type: 'parking.invalidZone'});
When this test runs, the framework has no way to distinguish the thrown parking.invalidZone from a
genuinely unexpected failure. Both are logged at error level. In a CI run with dozens of test
cases, each expected error produces a stack trace in the output, making it hard to notice the one
real error buried among the noise.
Three related problems arise:
-
Log pollution — expected errors produce
error-level log entries indistinguishable from bugs. Developers learn to ignore error output during tests, which defeats the purpose of having error logs. -
Missing context for test failures — when an expected error does occur, the framework sometimes swallows useful detail (like additional fields on the error object) before returning it to the test assertion.
-
Microservice transparency — in microservice mode the test call passes through multiple service boundaries. Each boundary independently decides whether to log the error at
errorlevel, regardless of what the originating test intended. There is no mechanism for the original caller's intent to travel with the request.
Solution
A first-class expect field on $meta lets the caller declare which error types are intentional
for a given call. The framework uses this declaration to:
- Demote expected errors to
debuglevel inAdapterBase.error()and in the gateway's error handler, preventing them from appearing in theerrorstream. - Keep error propagation intact — expected errors still propagate normally as thrown exceptions;
the caller's
assert.rejectsworks as before. - Carry the intent across service boundaries —
$metais serialised as the last element of the internal RPCparamsarray on every microservice-to-microservice call, soexpectreaches every adapter in the chain without any additional work.
The feature is guarded by a gateway.expectedErrors flag that is false by default. The flag only
gates whether the public API (external callers) is allowed to supply an expect field. Test
handlers that set $meta.expect programmatically are unaffected and work in any environment.
Two places consult the declaration — the adapter that first sees the error and the gateway that returns it — and both ask the same question, so the answer cannot disagree:
Why $meta and Not a Header
The initial proposal suggested using the HTTP baggage header (W3C Trace Context) for propagation.
This was rejected for two reasons:
-
$metais already the authoritative propagation vehicle for all request-scoped metadata in Blong. Introducing a parallel channel for a single field would add complexity without benefit. -
For the dominant test use-case — same-process dispatch — there is no HTTP layer at all. A header-based approach would require special-casing the in-process path.
$meta.expect therefore uses the same transport as every other metadata field: it is part of the
params array for internal RPC and part of the JSON-RPC body for the public API.
Why a Gateway Flag
The expectedErrors gateway flag exists for one reason: security. If the public API accepted the
expect field unconditionally, a malicious client could selectively suppress error-level audit
logs for chosen error types (e.g., auth.unauthorized) without the operator knowing. Setting
gateway.expectedErrors: true is therefore a conscious decision that operators make for development
and test environments, and it is excluded from production configuration by default.
Why debug Level (Not Silent)
An earlier implementation silently skipped all logging for expected errors. This made it impossible
to confirm — during test debugging — that the expected error path was actually taken. Logging at
debug level retains the information for developers running with verbose logging while keeping the
default output clean.
Wildcard Matching
Supporting a prefix.* wildcard alongside exact string matches was chosen over full regex syntax
for two reasons:
- A wildcard is sufficient for the common cases: "any error from the parking namespace"
(
parking.*) or "any auth error" (auth.*). - Regex strings stored in JSON cannot be distinguished from plain strings without a convention. The
trailing
.*convention is unambiguous and aligns with glob-style pattern matching familiar to most developers.
Design
The feature touches three locations in blong-gogo:
-
AdapterBase.error()— when$meta.expectmatches the error type, log atdebuginstead oferrorand continue (do not return early and silently drop the log entry). -
Gatewayroute handler catch block — when$meta.expectwas set by the caller and the thrown error type matches, log atdebuginstead oferror. The error is still returned to the client as a JSON-RPC error object; only the log level changes. -
Gatewayroute handler setup —expectis extracted from the JSON-RPC request body only whenthis.#config.expectedErrorsistrue. When the flag isfalse,expectis alwaysundefinedand the caller cannot influence log levels through the public API.
The IMeta.expect field type (string | string[]) is already defined in @feasibleone/blong/types
and therefore requires no type-level changes.