@feasibleone/blong-gogo 1.22.0 → 1.23.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.23.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.22.0...blong-gogo-v1.23.0) (2026-05-14)
+
+
+### Features
+
+* expected errors ([57ab05e](https://github.com/feasibleone/blong/commit/57ab05ed66b86405561f519e395e30f43b4fffa2))
+
 ## [1.22.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.21.0...blong-gogo-v1.22.0) (2026-05-14)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },

package/src/AdapterBase.ts

@@ -14,6 +14,7 @@ import PQueue from 'p-queue';
 import merge from 'ut-function.merge';
 
 import ConfigRuntime from './ConfigRuntime.ts';
+import {isExpectedError} from './lib.ts';
 import loop from './loop.ts';
 
 const errorMap: IErrorMap = {
@@ -177,11 +178,12 @@ export class AdapterBase<T, C extends IContext> implements AdapterHandlerContext
     }
 
     error(error: ITypedError, $meta: IMeta): void {
-        if ((this.log as {error?: (...args: unknown[]) => void})?.error) {
-            if (error.type && $meta?.expect?.includes?.(error.type)) return;
-            if ($meta) error.method = $meta.method;
-            (this.log as {error: (...args: unknown[]) => void}).error(error);
+        if ($meta) error.method = $meta.method;
+        if (isExpectedError(error.type, $meta?.expect)) {
+            (this.log as {debug?: (...args: unknown[]) => void})?.debug?.(error);
+            return;
         }
+        (this.log as {error?: (...args: unknown[]) => void})?.error?.(error);
     }
 
     findValidation(): unknown {

package/src/Gateway.ts

@@ -20,7 +20,7 @@ import {v4} from 'uuid';
 import type {IResolution} from './Resolution.ts';
 import type {IRpcClient} from './RpcClient.ts';
 import jwt from './jwt.ts';
-import {methodParts, snakeToCamel} from './lib.ts';
+import {isExpectedError, methodParts, snakeToCamel} from './lib.ts';
 import type {IConfig as IConfigMLE} from './mle.ts';
 import swagger from './swagger.ts';
 
@@ -60,6 +60,15 @@ interface IConfig extends IConfigMLE {
     logLevel?: LevelWithSilent;
     cors?: unknown;
     debug?: boolean;
+    /**
+     * When true, the gateway accepts the `expect` field from JSON-RPC request
+     * bodies and uses it to suppress error-level log entries for declared
+     * expected errors (demoting them to `debug` level).
+     *
+     * Set to `true` in the `dev` intent.  Must be `false` (the default) in
+     * production to prevent callers from suppressing audit-level error logs.
+     */
+    expectedErrors?: boolean;
     errorFields: unknown[];
     jwt: {
         cache: object;
@@ -147,6 +156,7 @@ export default class Gateway extends Internal implements IGateway {
             encrypt: undefined,
         },
         debug: false,
+        expectedErrors: false,
         errorFields: [],
         jwt: {
             cache: {},
@@ -418,6 +428,13 @@ export default class Gateway extends Internal implements IGateway {
                                   timeout: false,
                                   expect: undefined,
                               };
+                    // Only honour `expect` from the request body when the gateway
+                    // is configured to allow it.  This prevents external callers
+                    // from suppressing error-level logs in production.
+                    const resolvedExpect =
+                        this.#config.expectedErrors && expect
+                            ? ([] as string[]).concat(expect)
+                            : undefined;
                     const methodName = isWildcard
                         ? new URL(request.url, 'http://localhost').pathname
                               .slice(5)
@@ -432,7 +449,7 @@ export default class Gateway extends Internal implements IGateway {
                             ...(timeout && {
                                 timeout: this.#platform.timing.after(timeout as number),
                             }),
-                            ...(expect && {expect: ([] as string[]).concat(expect)}),
+                            ...(resolvedExpect && {expect: resolvedExpect}),
                             ...this._meta(request, pkg?.version, methodName.split('.')[0]),
                         };
                         const notfound = (): unknown =>
@@ -483,10 +500,17 @@ export default class Gateway extends Internal implements IGateway {
                             httpResponse?: unknown;
                             [key: string]: unknown;
                         };
-                        request.log.error(
-                            {err: error, method: methodName},
-                            'gateway handler error',
-                        );
+                        if (isExpectedError(typedError.type as string | undefined, resolvedExpect)) {
+                            request.log.debug(
+                                {err: error, method: methodName},
+                                'gateway expected error',
+                            );
+                        } else {
+                            request.log.error(
+                                {err: error, method: methodName},
+                                'gateway handler error',
+                            );
+                        }
                         this._applyMeta(
                             reply
                                 .header('x-envoy-decorator-operation', methodName)

package/src/expected-errors.test.ts

@@ -0,0 +1,291 @@
+/**
+ * Unit tests for the "expected errors" feature.
+ *
+ * Covers:
+ *  - isExpectedError() matching rules (exact, array, wildcard)
+ *  - AdapterBase.error() log-level demotion for expected errors
+ *  - Gateway respects `expectedErrors` config flag
+ *  - Propagation: expect travels with $meta through the handler chain
+ */
+
+import assert from 'node:assert';
+import {describe, it} from 'node:test';
+
+import {isExpectedError} from './lib.ts';
+
+// ---------------------------------------------------------------------------
+// isExpectedError() — matching rules
+// ---------------------------------------------------------------------------
+
+describe('isExpectedError — matching rules', () => {
+    it('returns false when error type is undefined', () => {
+        assert.strictEqual(isExpectedError(undefined, 'foo.bar'), false);
+    });
+
+    it('returns false when expect is undefined', () => {
+        assert.strictEqual(isExpectedError('foo.bar', undefined), false);
+    });
+
+    it('returns false when expect is an empty array', () => {
+        assert.strictEqual(isExpectedError('foo.bar', []), false);
+    });
+
+    it('exact string — matches identical type', () => {
+        assert.strictEqual(isExpectedError('parking.invalidZone', 'parking.invalidZone'), true);
+    });
+
+    it('exact string — does not match different type', () => {
+        assert.strictEqual(isExpectedError('parking.rateLimit', 'parking.invalidZone'), false);
+    });
+
+    it('array — matches when type is in the list', () => {
+        assert.strictEqual(
+            isExpectedError('auth.unauthorized', ['parking.invalidZone', 'auth.unauthorized']),
+            true,
+        );
+    });
+
+    it('array — does not match when type is absent from the list', () => {
+        assert.strictEqual(
+            isExpectedError('payment.failed', ['parking.invalidZone', 'auth.unauthorized']),
+            false,
+        );
+    });
+
+    it('wildcard — matches any type with the given prefix', () => {
+        assert.strictEqual(isExpectedError('parking.invalidZone', 'parking.*'), true);
+        assert.strictEqual(isExpectedError('parking.rateLimit', 'parking.*'), true);
+    });
+
+    it('wildcard — does not match a different namespace', () => {
+        assert.strictEqual(isExpectedError('auth.unauthorized', 'parking.*'), false);
+    });
+
+    it('wildcard — does not match the prefix segment itself (no dot)', () => {
+        // 'parking' alone should NOT match 'parking.*' (requires the dot)
+        assert.strictEqual(isExpectedError('parking', 'parking.*'), false);
+    });
+
+    it('array with wildcard — matches when a wildcard entry covers the type', () => {
+        assert.strictEqual(
+            isExpectedError('parking.invalidZone', ['auth.*', 'parking.*']),
+            true,
+        );
+    });
+
+    it('wildcard at top of namespace — auth.*', () => {
+        assert.strictEqual(isExpectedError('auth.unauthorized', 'auth.*'), true);
+        assert.strictEqual(isExpectedError('auth.tokenExpired', 'auth.*'), true);
+        assert.strictEqual(isExpectedError('gateway.jwtMissingHeader', 'auth.*'), false);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// AdapterBase.error() — log-level demotion
+// ---------------------------------------------------------------------------
+
+describe('AdapterBase.error() — log-level demotion', () => {
+    /**
+     * Minimal stand-in for AdapterBase that exposes only the `error()` method
+     * under test.  We copy the implementation verbatim so we are testing the
+     * real logic without spinning up a full adapter.
+     */
+    function makeAdapter(log: Record<string, (...a: unknown[]) => void>) {
+        return {
+            log,
+            error(
+                error: {type?: string; method?: string},
+                $meta: {method?: string; expect?: string | string[]},
+            ) {
+                if ($meta) error.method = $meta.method;
+                if (isExpectedError(error.type, $meta?.expect)) {
+                    (this.log as Record<string, (...a: unknown[]) => void>).debug?.(error);
+                    return;
+                }
+                (this.log as Record<string, (...a: unknown[]) => void>).error?.(error);
+            },
+        };
+    }
+
+    it('logs at error level when expect is not set', () => {
+        const logged: {level: string; error: unknown}[] = [];
+        const adapter = makeAdapter({
+            error: e => logged.push({level: 'error', error: e}),
+            debug: e => logged.push({level: 'debug', error: e}),
+        });
+
+        adapter.error({type: 'parking.invalidZone'}, {method: 'parkingTest'});
+
+        assert.strictEqual(logged.length, 1);
+        assert.strictEqual(logged[0].level, 'error');
+    });
+
+    it('logs at debug level and does not log at error when error is expected', () => {
+        const logged: {level: string; error: unknown}[] = [];
+        const adapter = makeAdapter({
+            error: e => logged.push({level: 'error', error: e}),
+            debug: e => logged.push({level: 'debug', error: e}),
+        });
+
+        adapter.error(
+            {type: 'parking.invalidZone'},
+            {method: 'parkingTest', expect: 'parking.invalidZone'},
+        );
+
+        assert.strictEqual(logged.length, 1);
+        assert.strictEqual(logged[0].level, 'debug');
+    });
+
+    it('logs at debug level for wildcard match', () => {
+        const logged: {level: string; error: unknown}[] = [];
+        const adapter = makeAdapter({
+            error: e => logged.push({level: 'error', error: e}),
+            debug: e => logged.push({level: 'debug', error: e}),
+        });
+
+        adapter.error(
+            {type: 'parking.rateLimit'},
+            {method: 'parkingTest', expect: 'parking.*'},
+        );
+
+        assert.strictEqual(logged.length, 1);
+        assert.strictEqual(logged[0].level, 'debug');
+    });
+
+    it('logs at error level when the error type does not match expect', () => {
+        const logged: {level: string; error: unknown}[] = [];
+        const adapter = makeAdapter({
+            error: e => logged.push({level: 'error', error: e}),
+            debug: e => logged.push({level: 'debug', error: e}),
+        });
+
+        adapter.error(
+            {type: 'auth.unauthorized'},
+            {method: 'someMethod', expect: 'parking.invalidZone'},
+        );
+
+        assert.strictEqual(logged.length, 1);
+        assert.strictEqual(logged[0].level, 'error');
+    });
+
+    it('attaches $meta.method to the error object', () => {
+        const captured: unknown[] = [];
+        const adapter = makeAdapter({
+            error: e => captured.push(e),
+            debug: () => {},
+        });
+
+        const err: {type: string; method?: string} = {type: 'foo.bar'};
+        adapter.error(err, {method: 'someMethod'});
+
+        assert.strictEqual((captured[0] as typeof err).method, 'someMethod');
+    });
+
+    it('attaches $meta.method even when the error is expected', () => {
+        const captured: unknown[] = [];
+        const adapter = makeAdapter({
+            error: () => {},
+            debug: e => captured.push(e),
+        });
+
+        const err: {type: string; method?: string} = {type: 'parking.invalidZone'};
+        adapter.error(err, {method: 'parkingTest', expect: 'parking.invalidZone'});
+
+        assert.strictEqual((captured[0] as typeof err).method, 'parkingTest');
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Gateway expectedErrors flag
+// ---------------------------------------------------------------------------
+
+describe('Gateway — expectedErrors config flag', () => {
+    /**
+     * Simulate the gateway route-handler logic that builds `resolvedExpect`.
+     * Returns the value of `resolvedExpect` that the gateway would compute.
+     */
+    function buildResolvedExpect(
+        expectedErrorsEnabled: boolean,
+        expectFromBody: string | string[] | undefined,
+    ): string[] | undefined {
+        return expectedErrorsEnabled && expectFromBody
+            ? ([] as string[]).concat(expectFromBody)
+            : undefined;
+    }
+
+    it('resolves expect when expectedErrors is true and expect is provided', () => {
+        const result = buildResolvedExpect(true, 'parking.invalidZone');
+        assert.deepStrictEqual(result, ['parking.invalidZone']);
+    });
+
+    it('resolves expect array when expectedErrors is true', () => {
+        const result = buildResolvedExpect(true, ['parking.invalidZone', 'auth.unauthorized']);
+        assert.deepStrictEqual(result, ['parking.invalidZone', 'auth.unauthorized']);
+    });
+
+    it('returns undefined when expectedErrors is false (production)', () => {
+        const result = buildResolvedExpect(false, 'parking.invalidZone');
+        assert.strictEqual(result, undefined);
+    });
+
+    it('returns undefined when expect is not provided even if expectedErrors is true', () => {
+        const result = buildResolvedExpect(true, undefined);
+        assert.strictEqual(result, undefined);
+    });
+
+    it('with resolvedExpect=undefined, isExpectedError always returns false', () => {
+        assert.strictEqual(isExpectedError('parking.invalidZone', undefined), false);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Meta propagation — $meta.expect travels through handler chain
+// ---------------------------------------------------------------------------
+
+describe('$meta.expect propagation', () => {
+    /**
+     * Simulate a two-hop dispatch: caller → first handler → second handler.
+     * The second handler logs an error and the first handler propagates it.
+     * Verify that $meta.expect set by the caller controls log level at every hop.
+     */
+    it('expect set by caller controls log level at every handler in the chain', () => {
+        const logged: {level: string; type: string}[] = [];
+
+        function logError(error: {type: string}, $meta: {expect?: string | string[]}) {
+            if (isExpectedError(error.type, $meta?.expect)) {
+                logged.push({level: 'debug', type: error.type});
+            } else {
+                logged.push({level: 'error', type: error.type});
+            }
+        }
+
+        const callerMeta = {method: 'callerMethod', expect: 'foo.someError'};
+
+        // Simulate two handler hops both receiving the same $meta
+        logError({type: 'foo.someError'}, callerMeta); // hop 1
+        logError({type: 'foo.someError'}, callerMeta); // hop 2
+
+        assert.strictEqual(logged.length, 2);
+        assert.ok(logged.every(l => l.level === 'debug'), 'all hops should log at debug');
+    });
+
+    it('an error type not in expect is still logged at error level on all hops', () => {
+        const logged: {level: string; type: string}[] = [];
+
+        function logError(error: {type: string}, $meta: {expect?: string | string[]}) {
+            if (isExpectedError(error.type, $meta?.expect)) {
+                logged.push({level: 'debug', type: error.type});
+            } else {
+                logged.push({level: 'error', type: error.type});
+            }
+        }
+
+        const callerMeta = {method: 'callerMethod', expect: 'foo.someError'};
+
+        logError({type: 'bar.otherError'}, callerMeta); // unexpected on hop 1
+        logError({type: 'bar.otherError'}, callerMeta); // unexpected on hop 2
+
+        assert.strictEqual(logged.length, 2);
+        assert.ok(logged.every(l => l.level === 'error'), 'unexpected errors stay at error level');
+    });
+});

package/src/lib.ts

@@ -66,6 +66,28 @@ export function parseAnnotatedKey(key: string): {
     return {annotations, handlerName};
 }
 
+/**
+ * Returns true when an error type matches the `expect` declaration on `$meta`.
+ *
+ * Matching rules:
+ *  - Exact string: `'foo.bar'` matches only `foo.bar`
+ *  - Array of strings: any element that matches (exact or wildcard)
+ *  - Wildcard prefix: `'foo.*'` matches any type starting with `foo.`
+ */
+export function isExpectedError(
+    errorType: string | undefined,
+    expect: string | string[] | undefined,
+): boolean {
+    if (!errorType || !expect) return false;
+    const patterns = ([] as string[]).concat(expect);
+    return patterns.some(pattern => {
+        if (pattern.endsWith('.*')) {
+            return errorType.startsWith(pattern.slice(0, -1));
+        }
+        return errorType === pattern;
+    });
+}
+
 let loginCache: Promise<{protocol: string; hostname: string; port: number}> | null = null;
 export async function loginService(
     discovery: (service: string) => Promise<{protocol: string; hostname: string; port: number}>,