Files
MikrotikManager/backend/src/services/vrf-execution-diagnostic.ts
T

75 lines
6.3 KiB
TypeScript

import { types } from "node:util"
import { readVrfTransitionRefusal, type VrfTransitionRefusalTag } from "./vrf-transition-refusal.js"
export const VRF_EXECUTION_STAGES = [
"runtime-policy-entry", "executor-entry", "runtime-policy-exit",
"initial-authorization", "sealing-key", "history-load", "raw-before", "original-dependencies", "history-provenance", "supported-shape", "ticket-lookup", "ticket-claim", "checkpoint-before", "install-predispatch",
"explicit-predispatch-authorization", "explicit-predispatch-dependencies", "explicit-predispatch-read", "explicit-predispatch-admission", "explicit-predispatch-final-authorization",
"dispatch-source", "client-call", "installed-predispatch-authorization", "installed-predispatch-dependencies", "installed-predispatch-read", "installed-predispatch-admission", "installed-predispatch-final-authorization",
"ack-identity", "ack-journal", "post-ack-authorization", "raw-after", "transition-classification", "post-ack-dependencies", "post-ack-final-authorization", "checkpoint-after",
] as const
export type VrfExecutionStage = typeof VRF_EXECUTION_STAGES[number]
export const VRF_READ_BOUNDARIES = ["authority-before", "native-get", "authority-after", "shape", "snapshot-validation", "final-authority"] as const
export interface VrfRawReadObservation { serverId: number; catalog?: string; boundary: typeof VRF_READ_BOUNDARIES[number] }
const catalogs = new Set(["bridge", "bridge_port", "bridge_vlan", "vrf", "ipv4_address", "ipv6_address", "ipv4_route", "ipv6_route", "routing_table", "ethernet", "ip_filter", "ipv6_filter", "routing_rule", "ip_settings", "ipv6_settings", "interface_inventory", "interface_list_members", "vlan", "bonding", "wireguard", "wireguard_peer", "gre", "ipip", "eoip", "vxlan", "vxlan_vtep", "pppoe_client"])
const classes = [[Error.prototype, "Error"], [TypeError.prototype, "TypeError"], [RangeError.prototype, "RangeError"], [SyntaxError.prototype, "SyntaxError"], [ReferenceError.prototype, "ReferenceError"], [URIError.prototype, "URIError"], [EvalError.prototype, "EvalError"]] as const
const categories = Object.freeze({ ECONNRESET: "reset", ECONNREFUSED: "refused", ETIMEDOUT: "timeout", ENOTFOUND: "dns", EAI_AGAIN: "dns", EPIPE: "pipe", ABORT_ERR: "aborted", ERR_STREAM_DESTROYED: "stream", "40001": "pg-serialization", "40P01": "pg-deadlock", "57014": "pg-cancelled", "08003": "pg-connection", "08006": "pg-connection", "57P01": "pg-connection" } as const)
export interface VrfExecutionDiagnostic {
event: "mcp.vrf.execution-failed"
operationId: string
action: "create" | "patch" | "delete"
stage: VrfExecutionStage
errorClass: "Error" | "TypeError" | "RangeError" | "SyntaxError" | "ReferenceError" | "URIError" | "EvalError" | "OtherNativeError" | "NonError"
category: "other" | typeof categories[keyof typeof categories]
/** Executor response observation only, never write-fence/dispatch proof. */
executorAckObserved: boolean
read?: VrfRawReadObservation
transition?: VrfTransitionRefusalTag
}
/** Closed private diagnostic only. Never read error messages, stacks, getters,
* causes, request bodies, SQL or native values. No outcome/authority is minted. */
export function vrfExecutionDiagnostic(operationId: string, action: string, stage: VrfExecutionStage, error: unknown, executorAckObserved: boolean, read?: VrfRawReadObservation): VrfExecutionDiagnostic | undefined {
if (typeof operationId !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(operationId) || !["create", "patch", "delete"].includes(action) || !VRF_EXECUTION_STAGES.includes(stage) || typeof executorAckObserved !== "boolean") return undefined
const result: VrfExecutionDiagnostic = { event: "mcp.vrf.execution-failed", operationId, action: action as VrfExecutionDiagnostic["action"], stage, errorClass: "NonError", category: "other", executorAckObserved }
if (types.isNativeError(error)) {
result.errorClass = classes.find(([prototype]) => Object.getPrototypeOf(error) === prototype)?.[1] ?? "OtherNativeError"
const descriptor = Object.getOwnPropertyDescriptor(error, "code")
if (descriptor && Object.hasOwn(descriptor, "value") && typeof descriptor.value === "string" && Object.hasOwn(categories, descriptor.value)) result.category = categories[descriptor.value as keyof typeof categories]
}
if (read && Number.isSafeInteger(read.serverId) && read.serverId > 0 && VRF_READ_BOUNDARIES.includes(read.boundary) && (read.catalog === undefined || typeof read.catalog === "string" && catalogs.has(read.catalog))) result.read = { serverId: read.serverId, boundary: read.boundary, ...(read.catalog === undefined ? {} : { catalog: read.catalog }) }
const transition = readVrfTransitionRefusal(error)
if (transition) result.transition = transition
return result
}
/** Observers are in-process only and cannot fail, await, or replace the work. */
export function notifyVrfDiagnostic<T>(observer: ((value: T) => unknown) | undefined, value: T): void {
try {
if (!observer) return
const result = observer(value)
if (types.isPromise(result)) void Promise.prototype.then.call(result, undefined, () => {})
} catch { /* Private observation never changes the original control flow. */ }
}
/** Private per-step fallback for failures before the executor's own try or in
* its surrounding policy context. Executor diagnostics always take precedence.
* Runtime discards this object immediately when the policy wrapper succeeds. */
export function createVrfRuntimeDiagnosticBoundary(operationId: string, action: string, observer: (value: VrfExecutionDiagnostic) => unknown) {
let stage: VrfExecutionStage = "runtime-policy-entry", emitted = false, executorAckObserved = false
return {
executorEntered() { stage = "executor-entry" },
executorReturned() { stage = "runtime-policy-exit"; executorAckObserved = true },
observed(value: VrfExecutionDiagnostic) {
if (value.operationId !== operationId || value.action !== action || emitted) return
emitted = true
notifyVrfDiagnostic(observer, value)
},
failure(error: unknown) {
if (emitted) return
emitted = true
try {
const value = vrfExecutionDiagnostic(operationId, action, stage, error, executorAckObserved)
if (value) notifyVrfDiagnostic(observer, value)
} catch { /* Fallback logging cannot replace the outer runtime error. */ }
},
}
}