All files / core/blong-gogo/src callTrace.ts

97.18% Statements 138/142
92% Branches 23/25
75% Functions 6/8
97.18% Lines 138/142

Press n or j to go to the next uncovered block, b, p or k for the previous block.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 1431x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 95x 81x 81x 81x 14x 14x 14x 14x 14x 14x 14x 95x 95x 95x 1x 1x 1x 5x 5x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 2x 2x 2x 1x   12x       11x 11x 12x 12x 12x 1x 1x 1x 1x 1x 1x 1x 1x 1x 572x 4x 4x 572x 572x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 8287x 8287x  
/**
 * Whether a flow's calls are recorded, and the record a phase produces.
 *
 * The *decision* is no longer made here. It is a capability — a per-execution switch — and lukaot
 * owns those (`@feasibleone/lukaot`): the switch lives in its ambient scope, travels with the identity
 * in the `cap` field of `x-semantic-trace`, and is read back where a record would be produced.
 * What this module keeps is everything that is the *framework's* rather than the
 * emitter's:
 *
 * - the configuration the decision falls back to (`log.calls.*`), and the entry
 *   patterns a high-throughput flow is opted out by;
 * - the envelope a call record carries — `$meta` with `mtid: 'event'` and a method
 *   naming the leg and the phase, which is what the ledger reads a call out of;
 * - the header a grant token arrives in.
 *
 * The line between the two is worth stating, because it is the line between the packages: lukaot knows
 * what a call *is* (a leg, its target, its position, its phases), and blong knows how this runtime names
 * things and what its records look like.
 */
 
import type {CallPhase} from '@feasibleone/blong/types';
 
/**
 * The capability that switches the call channel.
 *
 * The same name lukaot's `createCallChannel` asks for — it is defined there too, and
 * `callTrace.test.ts` pins the two together, because a value that had to agree across packages by
 * convention is a value that would stop agreeing silently.
 */
export const CALLS_CAPABILITY = 'calls';
 
/** The header a short-lived grant token arrives in. Never forwarded. */
export const GRANT_HEADER = 'x-blong-grant';
 
/**
 * What the framework may be told about call recording.
 *
 * Declared here rather than in the log implementation because both of them honour
 * it — the decision belongs to the framework, not to whichever logger a process
 * happens to run.
 */
export interface CallTraceConfig {
    /** Produce call records at all. On unless this is `false`. */
    enabled?: boolean;
    /**
     * Entry methods whose flows record nothing, matched against the name the flow
     * was minted with (the gateway's method, e.g. `payment.transfer.prepare`).
     *
     * `payment` and `payment.*` both match the whole namespace; an exact name
     * matches only that entry. The point is the high-throughput flows: recording
     * them costs a record per call, and the picture they would draw is the one a
     * reader already has.
     */
    off?: string[];
    /**
     * Print call records to stdout. Off unless asked for: the records are retained
     * and sent to the cluster either way, and a person watching a terminal is
     * reading the level log, not the call ledger.
     */
    stdout?: boolean;
}
 
let config: CallTraceConfig = {};
 
/** Install the configuration. Called by whichever log implementation loaded. */
export function configureCallTrace(next: CallTraceConfig | undefined): void {
    if (next === undefined) {
        config = {};
        return;
    }
    // `off` normalised to a list, because the CLI is one of the two ways this is
    // configured: `--log.calls.off=payment` arrives as a string and
    // `--log.calls.off=payment --log.calls.off=ledger` as an array, and a
    // configuration that only worked when it was repeated twice would be a trap.
    const off = next.off as string | string[] | undefined;
    config = {
        ...next,
        ...(off === undefined ? {} : {off: Array.isArray(off) ? off : [off]}),
    };
}
 
/** The configuration in force, for a caller that has to explain it. */
export function callTraceConfig(): CallTraceConfig {
    return config;
}
 
/**
 * Change part of the configuration, now.
 *
 * The switch a **running** process needs. The whole block is replaced once at load
 * (`configureCallTrace`, from `log.calls`) and a value that can only change then is a value an
 * operator cannot use to quiet a noisy deployment without restarting it — which for a flows-based
 * ledger means the only choice was between everything and nothing.
 *
 * This is also the seam a source other than configuration will push through: a deployment that
 * keeps the decision in its database, or an endpoint an operator calls, sends a patch here and
 * nothing else in the package learns about that source (@@D-941). `off` is **replaced** rather than
 * merged, because a list that merged could never lose an entry — the patch says what it wants, and
 * a caller that only means to add a namespace sends the whole list.
 */
export function patchCallTrace(next: Partial<CallTraceConfig>): CallTraceConfig {
    configureCallTrace({...config, ...next});
    return config;
}
 
/** Does `pattern` name this entry method? */
function matches(pattern: string, entry: string): boolean {
    if (pattern.length === 0) return false;
    if (pattern === entry) return true;
    // `payment` and `payment.*` mean the same thing — the whole namespace — and a
    // bare name is what a configuration usually writes; the glob form exists so a
    // pattern can end in `*` where that reads better.
    const prefix = pattern.endsWith('.*') ? pattern.slice(0, -2) : pattern;
    return entry === prefix || entry.startsWith(`${prefix}.`);
}
 
/**
 * What the configuration says about an entry, when nothing else has decided.
 *
 * Only the configuration half of the decision: a capability already published for
 * the flow settles the question before this is reached, and `responseContext.ts`
 * is where the two are put in order.
 */
export function callsPermitted(entry: string): boolean {
    if (config.enabled === false) {
        return false;
    }
    return !(config.off ?? []).some(pattern => matches(pattern, entry));
}
 
/**
 * The envelope a call record carries.
 *
 * What it was when these records were written through the level API — `$meta` with
 * `mtid: 'event'` and a method naming the leg and the phase — so nothing downstream
 * of the channel had to learn a new format, and the ledger still reads a call out
 * of the same two fields. The line beside it belongs to lukaot, which hands
 * it to the writer on the event; nothing here names a phase in prose.
 */
export function callRecord(leg: string, phase: CallPhase): Record<string, unknown> {
    return {$meta: {mtid: 'event', method: `${leg}.${phase}`}};
}