@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/src/core/fanout.ts

@@ -20,7 +20,10 @@ import type {
 	CommonSettingsMeta,
 	EnvelopeTargetMeta,
 	FanoutData,
+	FanoutMemberOperation,
 	FanoutSummary,
+	SettingSource,
+	ValidationTrace,
 	Warning,
 } from "./envelope.ts";
 
@@ -81,6 +84,59 @@ export function isRetryableFanoutError(error: unknown): boolean {
 	return (FANOUT_RETRYABLE_CODES as readonly string[]).includes(error.code);
 }
 
+/**
+ * Transport failures that prove the request never reached RouterOS (or reached
+ * it and was refused before running): the local client, connection, name,
+ * route, trust or login failed. Any other transport failure after a send is
+ * ambiguous.
+ */
+export const NOT_SENT_TRANSPORT_CODES: readonly string[] = [
+	"transport/auth-failed",
+	"transport/connection-refused",
+	"transport/dns",
+	"transport/host-key-mismatch",
+	"transport/insecure-trust",
+	"transport/local-tool-missing",
+	"transport/provider-trust",
+	"transport/tls-certificate",
+	"transport/unreachable",
+];
+
+/**
+ * #448: a write whose request was already sent when a transport failure ended
+ * it may have run on the router. It is never retried, and its error envelope
+ * says the outcome is unknown rather than implying nothing happened.
+ */
+export function sentWriteWarnings(
+	write: boolean,
+	error: unknown,
+	trace: ValidationTrace | undefined,
+): Warning[] {
+	if (!write || !trace?.dispatched) return [];
+	if (
+		!(error instanceof CentrsError) ||
+		!error.code.startsWith("transport/") ||
+		NOT_SENT_TRANSPORT_CODES.includes(error.code)
+	) {
+		return [];
+	}
+	return [
+		{
+			code: "transport/write-outcome-unknown",
+			message: `The write was sent before it failed with ${error.code}, so it may have run on the router. centrs does not retry a write it has sent; check the router's state before running it again.`,
+			context: { cause: error.code },
+		},
+	];
+}
+
+/** A fan-out retry veto: never replay a write whose request was sent (#448). */
+export function mayRetryUnsentWrite(
+	write: boolean,
+	trace: ValidationTrace | undefined,
+): boolean {
+	return !write || trace?.dispatched !== true;
+}
+
 /** Count inner `ok`/`failed` across a completed target set. */
 export function summarizeFanout(
 	targets: readonly { ok: boolean }[],
@@ -128,9 +184,11 @@ export async function runBoundedPool<I, O>(
 
 /**
  * Run `run`, retrying only {@link isRetryableFanoutError} failures up to
- * `maxRetries` times with jittered backoff. A non-retryable error, or the final
- * exhausted attempt, is converted to a value via `recover` (so a fan-out target
- * yields an inner error envelope instead of throwing out of the batch).
+ * `maxRetries` times with jittered backoff. `mayRetry` vetoes a retry the
+ * allowlist would allow, e.g. a write that was already sent (#448). A
+ * non-retryable error, or the final exhausted attempt, is converted to a value
+ * via `recover` (so a fan-out target yields an inner error envelope instead of
+ * throwing out of the batch).
  */
 export async function runWithRetry<T>(
 	run: () => Promise<T>,
@@ -138,6 +196,7 @@ export async function runWithRetry<T>(
 	options: {
 		sleep?: (ms: number) => Promise<void>;
 		maxRetries?: number;
+		mayRetry?: (error: unknown) => boolean;
 	} = {},
 ): Promise<T> {
 	const sleep = options.sleep ?? defaultFanoutSleep;
@@ -147,7 +206,11 @@ export async function runWithRetry<T>(
 		try {
 			return await run();
 		} catch (error) {
-			if (attempt < maxRetries && isRetryableFanoutError(error)) {
+			if (
+				attempt < maxRetries &&
+				isRetryableFanoutError(error) &&
+				(options.mayRetry?.(error) ?? true)
+			) {
 				attempt += 1;
 				await sleep(fanoutBackoffMs(attempt));
 				continue;
@@ -173,9 +236,10 @@ export function defaultFanoutSleep(ms: number): Promise<void> {
  * per-target plan, and the inner envelope type. Mirrors the original
  * `retrieveGroup` worker exactly: resolve each member (a resolve failure becomes
  * an inner error envelope, never a throw out of the batch); run the resolved
- * request through {@link runWithRetry} (a retryable transient drop is retried,
- * everything else recovers to an inner error envelope). Results are returned in
- * input (record-index) order via {@link runBoundedPool}.
+ * request through {@link runWithRetry} (a retryable transient drop is retried
+ * unless `mayRetry` vetoes it, everything else recovers to an inner error
+ * envelope). Results are returned in input (record-index) order via
+ * {@link runBoundedPool}.
  */
 export async function runFanout<Member, Resolved, Env>(opts: {
 	members: readonly Member[];
@@ -184,6 +248,8 @@ export async function runFanout<Member, Resolved, Env>(opts: {
 	onResolveError: (member: Member, error: unknown) => Env;
 	execute: (resolved: Resolved, member: Member) => Promise<Env>;
 	onExecuteError: (resolved: Resolved, member: Member, error: unknown) => Env;
+	/** Veto a retry for this target, e.g. a write that was already sent. */
+	mayRetry?: (resolved: Resolved, error: unknown) => boolean;
 	sleep?: (ms: number) => Promise<void>;
 }): Promise<Env[]> {
 	return runBoundedPool(opts.members, opts.concurrency, async (member) => {
@@ -196,7 +262,12 @@ export async function runFanout<Member, Resolved, Env>(opts: {
 		return runWithRetry<Env>(
 			() => opts.execute(resolved, member),
 			(error) => opts.onExecuteError(resolved, member, error),
-			{ sleep: opts.sleep },
+			{
+				sleep: opts.sleep,
+				mayRetry: opts.mayRetry
+					? (error) => opts.mayRetry?.(resolved, error) ?? true
+					: undefined,
+			},
 		);
 	});
 }
@@ -241,29 +312,151 @@ export function commonVia(
 	return via ?? null;
 }
 
+/** The part of an outer fan-out `operation` its targets may share. */
+interface SharedOperation {
+	request?: unknown;
+	auth?: unknown;
+}
+
+/**
+ * Write shared meta once (#461): the outer envelope keeps the run's settings,
+ * request and auth, and each target keeps only what differs from them. A
+ * settings key the outer envelope lacks, and the `auth`, move out when every
+ * target that reached an operation agrees on them. A target's `settings`
+ * keeps the keys whose source differs from the outer key's; its
+ * `request`/`auth` are dropped when equal to the outer ones.
+ */
+export function compactFanoutTargets<Data, Op, OuterOp extends object>(
+	settings: CommonSettingsMeta,
+	operation: OuterOp,
+	targets: readonly CentrsEnvelope<Data, Op>[],
+): {
+	settings: CommonSettingsMeta;
+	operation: OuterOp;
+	targets: CentrsEnvelope<Data, FanoutMemberOperation<Op>>[];
+} {
+	// A target that failed before it had an operation (a resolve failure)
+	// has no settings or auth to agree or disagree with.
+	const reached = targets.flatMap((target) => {
+		const inner = target.meta.operation as SharedOperation | undefined;
+		return inner ? [{ settings: target.meta.settings, auth: inner.auth }] : [];
+	});
+	const agreed = (value: (member: (typeof reached)[number]) => unknown) => {
+		const first = reached[0] && value(reached[0]);
+		return first !== undefined &&
+			reached.every((member) => Bun.deepEquals(value(member), first))
+			? first
+			: undefined;
+	};
+	const outerSettings: CommonSettingsMeta = { ...settings };
+	for (const key of Object.keys(reached[0]?.settings ?? {})) {
+		if (outerSettings[key] !== undefined) continue;
+		const source = agreed((member) => member.settings[key]);
+		if (source !== undefined) outerSettings[key] = source as SettingSource;
+	}
+	const outer = operation as SharedOperation;
+	const auth = outer.auth === undefined ? agreed((m) => m.auth) : undefined;
+	const shared: SharedOperation =
+		auth === undefined ? outer : { ...outer, auth };
+	return {
+		settings: outerSettings,
+		operation: shared as OuterOp,
+		targets: targets.map((target) => {
+			const own: CommonSettingsMeta = {};
+			// An `undefined` source is never written: JSON drops it, so a direct
+			// and a serialized reader would disagree on what the target inherits.
+			for (const [key, source] of Object.entries(target.meta.settings)) {
+				if (source !== undefined && !Bun.deepEquals(source, outerSettings[key]))
+					own[key] = source;
+			}
+			const meta = { ...target.meta, settings: own };
+			const inner = target.meta.operation as
+				| (Record<string, unknown> & SharedOperation)
+				| undefined;
+			if (inner) {
+				const { request, auth, ...rest } = inner;
+				// `auth` is shared only when every reached target has the same
+				// defined one, and every inner operation type requires `request`,
+				// so an omitted field always means "equal to the outer one".
+				const differs = (value: unknown, outer: unknown) =>
+					value !== undefined && !Bun.deepEquals(value, outer);
+				meta.operation = {
+					...rest,
+					...(differs(request, shared.request) ? { request } : {}),
+					...(differs(auth, shared.auth) ? { auth } : {}),
+				} as Op;
+			}
+			return { ...target, meta } as CentrsEnvelope<
+				Data,
+				FanoutMemberOperation<Op>
+			>;
+		}),
+	};
+}
+
+/**
+ * The inverse of {@link compactFanoutTargets}: a target's full meta, read as
+ * `target ?? outer` (per key for settings). A target that failed before it
+ * had an operation gets no operation.
+ */
+export function expandFanoutTarget<Data, Op>(
+	outer: { meta: { settings: CommonSettingsMeta; operation?: unknown } },
+	target: CentrsEnvelope<Data, FanoutMemberOperation<Op>>,
+): CentrsEnvelope<Data, Op> {
+	const shared = (outer.meta.operation ?? {}) as SharedOperation;
+	const inner = target.meta.operation as
+		| (Record<string, unknown> & SharedOperation)
+		| undefined;
+	const settings: CommonSettingsMeta = { ...outer.meta.settings };
+	for (const [key, source] of Object.entries(target.meta.settings)) {
+		if (source !== undefined) settings[key] = source;
+	}
+	const operation = inner && {
+		...inner,
+		...(inner.request === undefined && shared.request !== undefined
+			? { request: shared.request }
+			: {}),
+		...(inner.auth === undefined && shared.auth !== undefined
+			? { auth: shared.auth }
+			: {}),
+	};
+	return {
+		...target,
+		meta: { ...target.meta, settings, ...(operation ? { operation } : {}) },
+	} as CentrsEnvelope<Data, Op>;
+}
+
 /**
  * Assemble the locked fan-out success envelope: `data = { summary, targets }`,
  * outer `ok: true` = orchestration succeeded. The command owns its outer
- * `operation` meta shape and passes it in.
+ * `operation` meta shape and passes it in; shared meta is hoisted out of the
+ * targets by {@link compactFanoutTargets}. `target` is the outer target, set
+ * only when the fan-out runs through one router (a CMR controller).
  */
-export function buildFanoutEnvelope<Data, Op, OuterOp>(input: {
+export function buildFanoutEnvelope<Data, Op, OuterOp extends object>(input: {
 	summary: FanoutSummary;
 	targets: readonly CentrsEnvelope<Data, Op>[];
 	warnings: readonly Warning[];
 	settings: CommonSettingsMeta;
 	via: RouterOsProtocol | null;
 	operation: OuterOp;
+	target?: EnvelopeTargetMeta;
 }): CentrsSuccessEnvelope<FanoutData<Data, Op>, OuterOp> {
+	const { settings, operation, targets } = compactFanoutTargets(
+		input.settings,
+		input.operation,
+		input.targets,
+	);
 	return {
 		ok: true,
-		data: { summary: input.summary, targets: input.targets },
+		data: { summary: input.summary, targets },
 		warnings: input.warnings,
 		tips: [],
 		meta: {
-			target: {},
+			target: input.target ?? {},
 			via: input.via,
-			settings: input.settings,
-			operation: input.operation,
+			settings,
+			operation,
 		},
 	};
 }

package/src/errors.ts

@@ -17,6 +17,7 @@ export type CentrsErrorCode =
 	| `wait/${string}`
 	| `auth/${string}`
 	| `cdb/${string}`
+	| `cmr/${string}`
 	| `discover/${string}`
 	| `identity/${string}`
 	| `input/${string}`
@@ -264,11 +265,12 @@ export function serializeUnknownError(error: unknown): unknown {
 		return serializeCentrsError(error);
 	}
 
+	// No `stack`: it is raw exception text with local install paths, and the
+	// constitution summarizes those rather than embedding them (#476).
 	if (error instanceof Error) {
 		return {
 			name: error.name,
 			message: error.message,
-			stack: error.stack,
 			code: extractErrorCode(error),
 		};
 	}