75 lines
6.3 KiB
TypeScript
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. */ }
|
|
},
|
|
}
|
|
}
|