@feasibleone/blong-gogo 1.39.0 → 1.40.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.40.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.39.0...blong-gogo-v1.40.0) (2026-10-13)
+
+
+### Features
+
+* blong-kustomize improvements ([0a07e50](https://github.com/feasibleone/blong/commit/0a07e50275208a3fd8a23476e0abe9334ec3822d))
+* blong-kustomize operator UI ([2599dab](https://github.com/feasibleone/blong/commit/2599dab9c5ac734c9949f9af9b11fcb181eb8c7f))
+
+
+### Bug Fixes
+
+* flaky tests ([226d4a6](https://github.com/feasibleone/blong/commit/226d4a6c1bb912e2fff0919bda975ba487d3e060))
+
 ## [1.39.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.38.1...blong-gogo-v1.39.0) (2026-10-11)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },
@@ -83,7 +83,7 @@
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@feasibleone/blong-dev": "1.9.0",
+    "@feasibleone/blong-dev": "1.10.0",
     "@rushstack/heft": "^1.2.6",
     "@rushstack/heft-lint-plugin": "^1.2.6",
     "@rushstack/heft-typescript-plugin": "^1.3.1",

package/src/GatewayCodec.ts

@@ -39,6 +39,28 @@ export interface IGatewayCodec {
 export interface IConfig {
     client?: {tls?: {ca?: string | string[]; key?: string; cert?: string; crl?: string}};
     gateway?: object;
+    /**
+     * Whether a method must *not* be carried by the gateway this config names: `true` for every method,
+     * `false` for none, or a regular-expression *source* matched against the method name for the ones
+     * that belong here.
+     *
+     * The routing decision is made here — a gateway is where an *outside* caller reaches a process, and
+     * `gateway()` is what says whether a call is handed to one — so this is where a method that has to
+     * be answered at home is kept out of it. The name the framework needs it for is its own session
+     * check: `identity.checkInternal` is asked by the process that verified the token, from inside that
+     * verification, and a realm that answers its own login is one process. Routed through a gateway the
+     * call reached the gateway itself, was refused for a missing bearer and came back as a null the
+     * session step destructured (F-497) — a hardcoded name here until this setting replaced it, because
+     * a deployment that routes namespaces through a gateway is the one that knows which of its own
+     * methods have to stay home.
+     *
+     * A skipped method falls back to the ordinary path, and what that resolves to is the resolver's
+     * answer: `remote.canSkipSocket` decides whether the process answers it in-process or sends it to
+     * the namespace. The two settings compose rather than overlap — this one says "not through the
+     * gateway", that one says "answered here" — which is why the resolver asks its question only after
+     * this one has let the call through.
+     */
+    skipGateway?: boolean | string;
     protocol?: Protocol;
     host?: string;
     port?: string;
@@ -56,6 +78,14 @@ export default class GatewayCodecImpl implements IGatewayCodec {
     #config: IConfig;
     #tlsClient: object;
     #resolution: IResolution;
+    /**
+     * The `skipGateway` source as it was compiled, and the pattern — `null` for a source that did not
+     * compile.
+     *
+     * Kept beside the source for the reason the resolver keeps its own: `gateway()` runs for every
+     * outgoing call, and compiling the same expression per call is work that only the first call needs.
+     */
+    #skipGateway: {source: boolean | string; pattern: RegExp | null} | undefined;
 
     public verify!: IGatewayCodec['verify'];
 
@@ -170,8 +200,37 @@ export default class GatewayCodecImpl implements IGatewayCodec {
         this.verify = verify as IGatewayCodec['verify'];
     }
 
+    /**
+     * Whether this call is one the gateway must not carry ({@link IConfig.skipGateway}).
+     *
+     * A source that does not compile is treated as nothing matching rather than as every method: a typo
+     * in a config must not decide that no call is ever routed, and the alternative — refusing to start —
+     * would take a deployment down over a string. Nothing is logged here because this class has no
+     * logger: it is handed one by the caller that owns the logs, and the silent treatment is the same
+     * answer `Remote.canAnswerLocally` reports through its own.
+     */
+    private _skipsGateway(methodName: string): boolean {
+        const {skipGateway} = this.#config;
+        if (skipGateway === true) return true;
+        if (typeof skipGateway !== 'string') return false;
+        if (this.#skipGateway?.source !== skipGateway) {
+            let pattern: RegExp | null = null;
+            try {
+                pattern = new RegExp(skipGateway);
+            } catch {
+                pattern = null;
+            }
+            this.#skipGateway = {source: skipGateway, pattern};
+        }
+        return this.#skipGateway.pattern?.test(methodName) ?? false;
+    }
+
     public gateway($meta: IMeta, methodName: string = $meta.method!): object | void {
-        if (this.#config.gateway && methodName !== 'identity.checkInternal') {
+        // A skipped method does not reach a gateway at all, not even one the caller asked for in
+        // `$meta.gateway`: the setting says this process answers the call, and what answers it is the
+        // resolver's business (see `IConfig.skipGateway`).
+        if (this._skipsGateway(methodName)) return undefined;
+        if (this.#config.gateway) {
             const gw = this.#config.gateway as Record<string, unknown>;
             const [prefix, method] = methodName.split('/');
             if (method) {

package/src/Remote.ts

@@ -24,7 +24,18 @@ const errorMap: IErrorMap = {
 
 export default class Remote extends Internal implements IRemote {
     #config: {
-        canSkipSocket: boolean;
+        /**
+         * Whether a call may be answered in this process instead of through the transport: `true` for
+         * every method, `false` for none, or a regular-expression *source* matched against the method
+         * name for the ones that belong here ({@link canAnswerLocally}).
+         *
+         * A configured gateway still wins, and deliberately: a method a gateway is declared for is not
+         * this process's to answer, and a deployment that wants an exception says so on the other side
+         * — `GatewayCodec`'s `skipGateway` keeps the method out of the gateway, and this is what the
+         * fallback then resolves by. Asking the same question in two places would make the two settings
+         * disagreeable; asking it here only when nothing else claims the call keeps them composable.
+         */
+        canSkipSocket: boolean | string;
         requireMeta: 'trace' | 'debug' | 'warn' | 'error' | 'fatal' | 'info' | true;
     } = {
         canSkipSocket: false,
@@ -36,12 +47,21 @@ export default class Remote extends Internal implements IRemote {
     #errors: Errors<typeof errorMap>;
     #local: ILocal;
     #platform: IPlatformApi;
+    /**
+     * The compiled pattern of each `canSkipSocket` source seen, `null` for one that does not compile.
+     *
+     * Per source rather than one slot, because a reload replaces the config and a process may see more
+     * than one value in its life; the map is small enough that keeping the earlier ones costs nothing.
+     */
+    #skipPatterns = new Map<string, RegExp | null>();
 
     #brokerRequest: RemoteMethod;
     #brokerPublish: RemoteMethod;
 
     public constructor(
-        config: {logLevel?: Parameters<ILog['logger']>[0]},
+        // Declared rather than read off the caller's own interface, because a type that names only
+        // `logLevel` refuses the value the loader actually passes — `canSkipSocket` among them.
+        config: {logLevel?: Parameters<ILog['logger']>[0]; canSkipSocket?: boolean | string},
         {
             log,
             error,
@@ -202,9 +222,10 @@ export default class Remote extends Internal implements IRemote {
             if (!fn) {
                 // don't try skipping socket if there is a gateway configured
                 if (methodName && !this.gateway?.($applyMeta, methodName)) {
-                    if (this.#config.canSkipSocket) fn = this._findMethod(methodName, methodType);
+                    if (this.canAnswerLocally(methodName))
+                        fn = this._findMethod(methodName, methodType);
                     if (fn) unpack = true;
-                    else if (methodName && this.#config.canSkipSocket) {
+                    else if (this.canAnswerLocally(methodName)) {
                         // Visibility: under canSkipSocket every call is expected
                         // to resolve locally. A missing method (e.g. a derived
                         // handler name that doesn't match a registered file —
@@ -368,7 +389,7 @@ export default class Remote extends Internal implements IRemote {
             mtid = $meta.mtid;
             if (mtid === 'discard') return true;
             const handler =
-                this.#config.canSkipSocket &&
+                this.canAnswerLocally($meta.method) &&
                 this._findMethod($meta.method!, mtid === 'request' ? 'request' : 'publish');
             if (handler) {
                 return Promise.resolve(handler(...params));
@@ -392,6 +413,43 @@ export default class Remote extends Internal implements IRemote {
         return this._getPath(name).split('.').pop()!;
     }
 
+    /**
+     * Whether a method may be answered in this process rather than through the transport.
+     *
+     * `true` and `false` are the two ends — a process that carries everything answers everything, one
+     * that carries only its own realm answers nothing — and the string is the middle: a
+     * regular-expression *source*, read against the method name, for a process that serves some of what
+     * it can reach and has to send the rest out. The pattern is compiled once per value, because a
+     * reload replaces the config.
+     *
+     * A source that does not compile is not a reason to refuse every call: it is reported once and
+     * treated as nothing matching, which leaves the process dialling as it would have with `false`.
+     *
+     * The caller decides *when* to ask ({@link _getMethod} asks only where no gateway claims the call),
+     * so nothing here knows about gateways: this is the local half of the question and the routing half
+     * lives in the codec that actually routes.
+     */
+    protected canAnswerLocally(methodName: string | undefined): boolean {
+        const {canSkipSocket} = this.#config;
+        if (canSkipSocket === true) return true;
+        if (typeof canSkipSocket !== 'string' || !methodName) return false;
+        const cached = this.#skipPatterns.get(canSkipSocket);
+        if (cached !== undefined) return cached ? cached.test(methodName) : false;
+        try {
+            const pattern = new RegExp(canSkipSocket);
+            this.#skipPatterns.set(canSkipSocket, pattern);
+            return pattern.test(methodName);
+        } catch (error) {
+            this.#skipPatterns.set(canSkipSocket, null);
+            this.log?.warn?.({
+                $meta: {mtid: 'event', method: 'remote.canSkipSocket'},
+                message: `canSkipSocket is not a regular expression: ${canSkipSocket}`,
+                error,
+            });
+            return false;
+        }
+    }
+
     private _findMethod(methodName: string, type: 'request' | 'publish'): RemoteMethod {
         methodName = this._getPath(methodName);
         const key = ['ports', methodName, type].join('.');

package/src/RpcClient.ts

@@ -90,7 +90,17 @@ export default class RpcClientImpl extends RemoteImpl implements IRpcClient {
             'http',
             '8091',
             this.#errors,
-            this.sender('request'),
+            // The session step's own call — the one the codec makes while it verifies a caller's token
+            // (`identity.checkInternal`) — is asked through the *resolver* like every other call this
+            // process makes, which is what lets a process answer it itself. Handed the raw transport it
+            // could only ever dial: the routing question would be answered (the codec keeps the method
+            // out of a gateway, `skipGateway`) and then the call left for an `identity` namespace that a
+            // deployment answering its own login does not publish — refused for a missing bearer when it
+            // reached a gateway, and `ENOTFOUND` when it reached nothing (F-494, F-497). Asked through
+            // the resolver, `remote.canSkipSocket` decides: the process that verified the token answers
+            // the question, and a deployment that runs an identity service still reaches it.
+            (msg: unknown, $meta: unknown) =>
+                this.remote(($meta as IMeta)?.method ?? 'identity.checkInternal')(msg, $meta),
             this.#resolution,
         );
     }

package/src/busGateway.ts

@@ -35,6 +35,37 @@ export default ({
         encrypt: string;
     }>;
 }) => {
+    /**
+     * What could not be reached, in the message rather than in a cause nobody prints.
+     *
+     * `fetch failed` is all a `TypeError` from the transport says, and the method and the
+     * address it was fetching are not in it: diagnosing an unreachable namespace came down
+     * to reading the process's DNS names out of a log line that did not carry them (F-494).
+     * Every transport failure in this file therefore leaves through here, with the method,
+     * the address and the code the resolver or the socket returned.
+     */
+    const unreachable = async <T>(
+        target: string,
+        method: string,
+        call: () => Promise<T>,
+    ): Promise<T> => {
+        try {
+            return await call();
+        } catch (error) {
+            const cause = (error as {cause?: {code?: string; hostname?: string; syscall?: string}})
+                ?.cause;
+            const detail = cause
+                ? [cause.code, cause.syscall, cause.hostname].filter(Boolean).join(' ')
+                : '';
+            throw new Error(
+                `gateway codec could not reach ${target} for '${method}': ` +
+                    `${(error as Error)?.message ?? String(error)}` +
+                    `${detail ? ` (${detail})` : ''}`,
+                {cause: error as Error},
+            );
+        }
+    };
+
     const localCache: Record<
         string,
         {
@@ -193,10 +224,12 @@ export default ({
         const cache = (localCache[url] = localCache[url] || {});
 
         if (localKeys && !cache.remoteKeys) {
-            const body = await get(
-                `${url}/rpc/login/.well-known/mle`,
-                errors['bus.jsonRpcHttp'],
-                errors['bus.jsonRpcEmpty'],
+            const body = await unreachable(`${url}/rpc/login/.well-known/mle`, method, () =>
+                get(
+                    `${url}/rpc/login/.well-known/mle`,
+                    errors['bus.jsonRpcHttp'],
+                    errors['bus.jsonRpcEmpty'],
+                ),
             );
             if (body.sign && body.encrypt) cache.remoteKeys = body;
         }
@@ -230,7 +263,10 @@ export default ({
             return codec;
         }
 
-        if (!cache.auth) await login(cache, url, username, password, channel);
+        if (!cache.auth)
+            await unreachable(`${url}/rpc/login/identity`, method, () =>
+                login(cache, url, username, password, channel),
+            );
 
         const exp = Date.now();
 

package/src/codec/adapter/mle/ready.ts

@@ -176,7 +176,28 @@ export default handler<{
 
     return {
         async ready() {
-            let mleKey = null; // isBrowser && JSON.parse(window.localStorage.getItem('mle-jose') || 'null');
+            /**
+             * The pair is kept across a reload, which is what the write below has always assumed.
+             *
+             * A caller's session is opened with the pair it presented when it logged in — the realm
+             * that answers the session hands those two public keys back — and every later call is
+             * verified against the signing half of it. A reload that minted a new pair therefore
+             * signed with a key the session had never seen, and the gateway answered
+             * `Decryption failed` with `ERR_JWS_SIGNATURE_VERIFICATION_FAILED` underneath, on the
+             * first call of every page that logs in by reloading (F-497). The value is written below
+             * and was never read back, which is the shape of a half-finished feature rather than a
+             * decision: keeping it is now deliberate — a private JWK in `localStorage` is readable by
+             * any script on this origin, and the alternative is a session re-opened after every
+             * reload, which needs the caller's keys to travel with the call instead (D-530).
+             */
+            let mleKey = null;
+            if (isBrowser) {
+                try {
+                    mleKey = JSON.parse(window.localStorage.getItem('mle-jose') || 'null');
+                } catch {
+                    mleKey = null;
+                }
+            }
             if (!mleKey) {
                 const {body: {sign, encrypt} = {}}: {body?: {sign?: unknown; encrypt?: unknown}} =
                     (await (this as {exec?(...params: unknown[]): Promise<unknown>}).exec!(

package/src/frameworkRealms.test.ts

@@ -143,7 +143,7 @@ test('a realm the suite declares is loaded', async t => {
     try {
         await withAmbientResolution(dirname(fileURLToPath(url)), async () => {
             const registry = await load(suite(url) as never, 'declared', {}, ['cli']);
-            t.ok(registry.describe?.().realms.includes('server'), 'the declared realm is loaded');
+            t.ok(registry.describe?.().realms.includes('srv'), 'the declared realm is loaded');
         });
     } finally {
         dispose();
@@ -164,7 +164,7 @@ test('a trimmed manifest does not un-declare a realm', async t => {
                 ['cli'],
             );
             t.ok(
-                registry.describe?.().realms.includes('server'),
+                registry.describe?.().realms.includes('srv'),
                 'the file beside the suite still counts',
             );
         });

package/src/lib.ts

@@ -240,16 +240,39 @@ export async function requestGet(
     protocol: string,
     tls: Record<string, unknown> | undefined,
 ): Promise<unknown> {
-    const response = await ky.get(url, {
-        ...tls,
-        ...(headers && {
-            headers: {
-                'x-forwarded-proto': headers['x-forwarded-proto'] || protocol,
-                'x-forwarded-host': headers['x-forwarded-host'] || headers.host,
-            },
-        }),
-        throwHttpErrors: false,
-    });
+    let response;
+    try {
+        response = await ky.get(url, {
+            ...tls,
+            ...(headers && {
+                headers: {
+                    // Every header the caller named, not only the two forwarded-for ones. Dropping
+                    // the rest silently dropped the `authorization` an issuer's discovery is read
+                    // with, and the API server answered 401 for a request that presented nothing —
+                    // a failure with no trace of the cause it was given (F-494).
+                    ...(Object.fromEntries(
+                        Object.entries(headers).filter(([, value]) => value !== undefined),
+                    ) as Record<string, string>),
+                    'x-forwarded-proto': headers['x-forwarded-proto'] || protocol,
+                    'x-forwarded-host': headers['x-forwarded-host'] || headers.host,
+                },
+            }),
+            throwHttpErrors: false,
+        });
+    } catch (error) {
+        // Name what could not be fetched. A transport failure reaches the log as `fetch failed`
+        // and nothing else, so an unreachable dependency was diagnosed by reading DNS names out of
+        // the process the hard way (F-494); the address and the resolver's code belong in the
+        // message, where whoever reads the failure is already looking.
+        const cause = (error as {cause?: {code?: string; hostname?: string; syscall?: string}})
+            ?.cause;
+        const detail = cause ? [cause.code, cause.syscall, cause.hostname].filter(Boolean).join(' ') : '';
+        throw new Error(
+            `could not reach ${url}: ${(error as Error)?.message ?? String(error)}` +
+                `${detail ? ` (${detail})` : ''}`,
+            {cause: error as Error},
+        );
+    }
 
     const responseText = await response.text();
     let body: {[key: string]: unknown} | undefined;

package/src/load.ts

@@ -1360,7 +1360,7 @@ export default async function loadRealm<T extends TSchema>(
          */
         intents?: readonly string[];
     }> = [
-        {name: 'server', specifier: '@feasibleone/blong-server/server.ts'},
+        {name: 'srv', specifier: '@feasibleone/blong-server/server.ts'},
         {name: 'login', specifier: '@feasibleone/blong-login/server.ts'},
         {name: 'core', specifier: '@feasibleone/blong-core/server.ts'},
         {name: 'access', specifier: '@feasibleone/blong-access/server.ts'},

package/src/oidc.ts

@@ -1,7 +1,22 @@
 import type {Errors} from '@feasibleone/blong';
 import {createLocalJWKSet, decodeJwt, decodeProtectedHeader, jwtVerify} from 'jose';
+import {readFileSync} from 'node:fs';
 import {requestGet as get, loginService} from './lib.ts';
 
+/**
+ * The headers an issuer's own endpoints are read with.
+ *
+ * A cluster's discovery document and key set are not anonymous: the API server answers 401 unless
+ * the caller presents an identity it knows, so an issuer that names its credentials by file is read
+ * with them (`rpc.oidcHttp: OpenID returned HTTP error 401` is what an uncredentialed read looks
+ * like). The file is read per fetch rather than cached, because what lives in a projected
+ * service-account volume is rotated by the kubelet and the process is meant to pick the new one up.
+ */
+const issuerHeaders = (config: {tokenFile?: string} | undefined): Record<string, string> => {
+    if (!config?.tokenFile) return {};
+    return {authorization: `Bearer ${readFileSync(config.tokenFile, 'utf8').trim()}`};
+};
+
 export default ({
     issuers,
     tls = {},
@@ -55,9 +70,12 @@ export default ({
                 ) => Promise<{protocol: string; hostname: string; port: number}>,
             );
             issuer = `${loginProtocol}://${hostname}:${port}/rpc/login/.well-known/openid-configuration`;
-        } else {
-            headers = undefined;
         }
+        // The headers are kept for every issuer, not only for `blong-login`. A configured issuer
+        // is read with whatever the caller of this function brought, and for a cluster issuer that
+        // is the process's own credential: discarding it here turned the API server's answer into
+        // `rpc.oidcHttp: 401` for a request that presented nothing, with nothing in the message to
+        // say the credential had been dropped on the way (F-494).
         return await get(issuer, errorOidcHttp, errorOidcEmpty, headers, protocol ?? '', tls);
     }
 
@@ -155,6 +173,7 @@ export default ({
                             {
                                 ...((await openIdConfig(
                                     configuration || issuerUrl(issuerId, url),
+                                    issuerHeaders(rest as {tokenFile?: string}),
                                 )) as object),
                                 audience,
                                 issuerId,
@@ -220,11 +239,12 @@ export default ({
     }
 
     async function jwks(issuerId: string) {
+        const config = await issuerConfig(issuerId);
         return get(
-            (await issuerConfig(issuerId)).jwks_uri,
+            config.jwks_uri,
             errorOidcHttp,
             errorOidcEmpty,
-            {},
+            issuerHeaders(config as {tokenFile?: string}),
             '',
             tls,
         );
@@ -295,7 +315,21 @@ export default ({
         } catch (error) {
             throw errorInvalid({params: {message: (error as Error).message}, cause: error});
         }
-        if (session && audience === 'blong' && !decoded.ses) await session(decoded);
+        /**
+         * The session step, for the issuers that ask for one.
+         *
+         * It is what hands a caller its session — an actor, a session id and the MLE key pair its
+         * later calls are decrypted with — by asking the `identity` namespace, and the framework's
+         * own issuer asks for it by name. An issuer may ask too (`session: true`), which is how a
+         * realm that answers its own login keeps the framework's session contract without running
+         * the framework's login realm: it answers `identity.checkInternal` itself. An issuer that
+         * asks for nothing gets nothing — a cluster issuer answers for the caller by its signature
+         * alone — and asking an `identity` service that does not exist is what made a verified
+         * token fail with `ENOTFOUND identity.<namespace>.svc.cluster.local` (F-494).
+         */
+        const wantsSession =
+            (config as {session?: boolean})?.session ?? decoded.iss === 'blong-login';
+        if (session && wantsSession && !decoded.ses) await session(decoded);
         return {
             ...decoded,
             config,

package/src/remoteCanSkip.test.ts

@@ -0,0 +1,76 @@
+import {
+    type IErrorFactory,
+    type ILocal,
+    type ILog,
+    type IPlatformApi,
+} from '@feasibleone/blong/types';
+import tap from 'tap';
+
+import RemoteImpl from './Remote.ts';
+
+/**
+ * `canSkipSocket` in its three shapes each: all, none, and the pattern in between.
+ *
+ * A process that carries a whole suite answers most of what it can reach, and one that carries a single
+ * realm has no reason to answer anything — but a process that serves some of what it can reach and has
+ * to send the rest out is neither: the pattern is the middle, read against the method name, and as a
+ * *source* rather than a `RegExp` because a config is data.
+ *
+ * The check is `protected` so this can pin it: the alternative is a transport, and a test that dials
+ * localhost asserts on a machine's state rather than on the code. What it does *not* pin is when the
+ * question is asked — a configured gateway claims the call first, and a method kept out of the gateway
+ * is the codec's business (`skipGateway.test.ts`) — which is why nothing here is about gateways.
+ */
+class Probe extends RemoteImpl {
+    public answers(methodName: string | undefined): boolean {
+        return this.canAnswerLocally(methodName);
+    }
+}
+
+const build = (canSkipSocket: boolean | string): Probe =>
+    new Probe(
+        {canSkipSocket},
+        {
+            log: {logger: () => ({warn: () => undefined})} as unknown as ILog,
+            error: {register: () => ({})} as unknown as IErrorFactory,
+            local: {get: () => undefined, register: () => undefined} as unknown as ILocal,
+            platform: {} as unknown as IPlatformApi,
+        },
+    );
+
+tap.test('canSkipSocket=true answers any method', async t => {
+    const probe = build(true);
+    t.equal(probe.answers('kustomize.deployment.find'), true, 'a realm method');
+    t.equal(probe.answers('subject.object.schema'), true, 'another namespace');
+    t.equal(probe.answers(undefined), true, 'and the end of the scale is not a pattern');
+});
+
+tap.test('canSkipSocket=false answers none', async t => {
+    const probe = build(false);
+    t.equal(probe.answers('kustomize.deployment.find'), false, 'a realm method travels');
+    t.equal(probe.answers(undefined), false, 'and a nameless call travels');
+});
+
+tap.test('canSkipSocket as a pattern answers what it matches', async t => {
+    const probe = build('^(kustomize|srv)\\.');
+    t.equal(probe.answers('kustomize.deployment.find'), true, 'the realm serves this one');
+    t.equal(probe.answers('srv.db.queryBuilder'), true, 'and this one');
+    t.equal(
+        probe.answers('access.user.find'),
+        false,
+        'while another namespace is sent out, which is what the pattern is for',
+    );
+    t.equal(probe.answers(undefined), false, 'and a nameless call travels');
+});
+
+tap.test('canSkipSocket that is not a regular expression answers none', async t => {
+    // `(` on its own throws when it is compiled. Reported, and treated as nothing matching: a typo in
+    // a config must not decide where every call goes.
+    const probe = build('(');
+    t.equal(probe.answers('kustomize.deployment.find'), false, 'the call travels');
+    t.equal(
+        probe.answers('kustomize.deployment.find'),
+        false,
+        'and keeps travelling, not throwing',
+    );
+});

package/src/skipGateway.test.ts

@@ -0,0 +1,112 @@
+import type {IMeta} from '@feasibleone/blong/types';
+import tap from 'tap';
+
+import GatewayCodecImpl from './GatewayCodec.ts';
+
+/**
+ * `skipGateway` in its three shapes, pinned where the routing decision is made.
+ *
+ * A gateway is where an *outside* caller reaches a process, and `gateway()` is what answers whether a
+ * call is handed to one. A method that has to be answered at home therefore has to be kept out *here*:
+ * the resolver asks its own question (`remote.canSkipSocket`, `remoteCanSkip.test.ts`) only after this
+ * one has let the call through, which is the order that lets a deployment route a namespace through a
+ * gateway and still keep one of its own methods in-process. The framework's own session check is that
+ * method — `identity.checkInternal`, asked by the process that verified the token, from inside the
+ * verification — and it was a hardcoded name here until this setting replaced it (F-497).
+ *
+ * The codec is built for real rather than mocked: what is pinned is the answer of the public method, and
+ * a stub of the class would let the two disagree. Its OIDC client discovers nothing until a token is
+ * verified, so building one costs no network.
+ */
+const build = (config: {skipGateway?: boolean | string; gateway?: object}) =>
+    new GatewayCodecImpl(
+        config,
+        'http',
+        '8091',
+        {register: () => ({})} as never,
+        async () => undefined,
+        undefined as never,
+    );
+
+/** The address the configured gateway answers at, as `gateway()` hands it back. */
+const GATEWAY = {
+    deploy: {protocol: 'http', hostname: 'the-gateway', port: '8080'},
+    identity: {protocol: 'http', hostname: 'the-gateway', port: '8080'},
+};
+
+tap.test('nothing is skipped unless it is asked for', async t => {
+    const codec = build({gateway: GATEWAY});
+    t.same(
+        codec.gateway({method: 'identity.checkInternal'} as IMeta),
+        {...GATEWAY.identity, method: 'identity.checkInternal'},
+        'a namespace routed through the gateway still is',
+    );
+    t.equal(
+        codec.gateway({method: 'remote.unknown.nothing'} as IMeta),
+        undefined,
+        'and one the gateway does not name is not routed at all',
+    );
+});
+
+tap.test('skipGateway=true keeps every call at home', async t => {
+    const codec = build({gateway: GATEWAY, skipGateway: true});
+    t.equal(
+        codec.gateway({method: 'kustomize.deployment.find'} as IMeta),
+        undefined,
+        'even where the gateway names the namespace',
+    );
+    t.equal(
+        codec.gateway({method: 'identity.checkInternal'} as IMeta),
+        undefined,
+        'and the session',
+    );
+});
+
+tap.test('skipGateway as a pattern skips what it matches', async t => {
+    const codec = build({gateway: GATEWAY, skipGateway: '^identity\\.'});
+    t.equal(
+        codec.gateway({method: 'identity.checkInternal'} as IMeta),
+        undefined,
+        'the method the framework asks of the process that verified the token',
+    );
+    t.same(
+        codec.gateway({method: 'deploy.kustomize.deployment.find'} as IMeta),
+        {...GATEWAY.deploy, method: 'deploy.kustomize.deployment.find'},
+        'while the rest still goes through the gateway it is configured for',
+    );
+});
+
+tap.test('the setting beats a gateway the caller asked for', async t => {
+    // `$meta.gateway` is how a caller routes a call itself. A method named in `skipGateway` does not
+    // take that route either: the setting says this process answers it, and a caller's preference is
+    // not a reason for the session check to leave the process that holds the handshake.
+    const codec = build({skipGateway: 'identity.checkInternal'});
+    t.equal(
+        codec.gateway({
+            method: 'identity.checkInternal',
+            gateway: {hostname: 'somewhere-else'},
+        } as IMeta),
+        undefined,
+        'the skip wins',
+    );
+    t.same(
+        codec.gateway({method: 'other.method', gateway: {hostname: 'somewhere-else'}} as IMeta),
+        {hostname: 'somewhere-else', method: 'other.method'},
+        'and a call it does not name keeps the route it was given',
+    );
+});
+
+tap.test('a skip that is not a regular expression skips nothing', async t => {
+    // `(` throws when it is compiled, and a broken pattern must not decide that no call is ever routed:
+    // treated as nothing matching, which leaves the gateway doing what it did.
+    const codec = build({gateway: GATEWAY, skipGateway: '('});
+    t.same(
+        codec.gateway({method: 'identity.checkInternal'} as IMeta),
+        {...GATEWAY.identity, method: 'identity.checkInternal'},
+        'the call is routed as it would have been',
+    );
+    t.ok(
+        codec.gateway({method: 'deploy.kustomize.deployment.find'} as IMeta),
+        'and keeps routing, not throwing',
+    );
+});