@tikoci/centrs 0.1.0 → 0.1.2

package/src/protocols/btest-session.ts

@@ -24,9 +24,15 @@
  * client↔server matrix is loopback-testable without a router; the CHR
  * integration test (`test/integration/btest.test.ts`) is the real-RouterOS gate.
  *
- * Scope: single TCP data connection + UDP. TCP multi-connection
- * (`connection-count > 1`) negotiates its session token here but the parallel
- * data-stream fan-out is owned by the orchestrator (a follow-up).
+ * Scope: UDP, plus TCP single- **and** multi-connection. For `connection-count > 1`
+ * the client reads the session token from the primary's OK, opens the extra data
+ * connections (each: read the server HELLO, send the 16-byte join
+ * `[token:u16 BE][0x02][0 …]`, then bulk data flows — the server sends **no** ack
+ * before data), and drives them into one shared `BandwidthCounters` so throughput
+ * aggregates. The secondary-join format is grounded byte-for-byte against RouterOS
+ * 7.23.1 (captured all directions; the `0x02` marker is direction-independent).
+ * Authenticated (EC-SRP5) multi-connection is not yet supported — the post-auth
+ * token is not captured — so those sessions stay single-stream.
  */
 
 import { createSocket } from "node:dgram";
@@ -44,6 +50,7 @@ import {
 	type BtestCommandOptions,
 	type BtestDirection,
 	type BtestProtocol,
+	type BtestStatus,
 	classifyAuthResponse,
 	clientUdpPort,
 	decodeCommand,
@@ -54,6 +61,7 @@ import {
 	encodeClientHello,
 	encodeCommand,
 	encodeConfirmation,
+	encodeSecondaryJoin,
 	encodeServerChallenge,
 	encodeStatus,
 	encodeUdpPacket,
@@ -534,10 +542,6 @@ export function speedFeedbackBps(bytesReceived: number): number {
 	return Math.min(Math.floor((bytesReceived * 8 * 3) / 2), 0xffffffff);
 }
 
-function isStatusMarker(buf: Uint8Array, i: number): boolean {
-	return buf[i] === BTEST_STATUS_MSG_TYPE && (buf[i + 1] as number) >= 0x80;
-}
-
 // ── Handshake ─────────────────────────────────────────────────────────────────
 
 /** What both sides agree on after the control handshake. */
@@ -860,6 +864,12 @@ interface RunContext {
 	serverUdpPort?: number;
 	/** Peer host for UDP (client: server host; server: client host). */
 	udpPeerHost?: string;
+	/**
+	 * Adapt this side's TX rate from peer status frames (client transmit / both).
+	 * Set so the merged-stream status reader in `tcpRxLoop` and the dedicated
+	 * `tcpStatusReaderLoop` share one feedback gate.
+	 */
+	adaptTxFromStatus?: boolean;
 	onInterval?: (sample: BtestIntervalSample) => void;
 }
 
@@ -884,6 +894,51 @@ function serverDirections(command: BtestCommand): RoleDirections {
 	};
 }
 
+/**
+ * Open one secondary TCP data connection that joins an existing multi-connection
+ * test. Grounded against RouterOS 7.23.1: the server sends the 4-byte HELLO, the
+ * client replies with the 16-byte join `[token:u16 BE][0x02][0 …]`
+ * ({@link encodeSecondaryJoin}), and bulk data then flows. The server sends **no**
+ * acknowledgement before the data — it waits for *all* connections to join before
+ * streaming — so the join must not block on a reply read, or the sequential opens
+ * would deadlock (the server stalls waiting for the rest while the client stalls
+ * waiting for a reply that never comes, and the server eventually drops the
+ * connection). The caller drives the returned channel into the primary session's
+ * shared counters so throughput aggregates across all streams.
+ */
+async function openSecondaryConnection(
+	connect: (host: string, port: number) => Promise<BtestControlChannel>,
+	host: string,
+	port: number,
+	token: number,
+): Promise<BtestControlChannel> {
+	const channel = await connect(host, port);
+	try {
+		await channel.readExact(4); // server HELLO (01 00 00 00)
+		await channel.write(encodeSecondaryJoin(token));
+		return channel;
+	} catch (error) {
+		channel.close();
+		throw error;
+	}
+}
+
+/**
+ * Run the bulk TX/RX loops for a secondary data connection. No status or report
+ * loops — the primary connection owns those; a secondary only moves bulk bytes
+ * into the shared counters. TX paces from the shared `counters.txSpeed` the primary
+ * adapts from server feedback.
+ */
+async function runSecondaryDataLoops(
+	ctx: RunContext,
+	dirs: RoleDirections,
+): Promise<void> {
+	const tasks: Promise<void>[] = [];
+	if (dirs.shouldTx) tasks.push(tcpTxLoop(ctx, false));
+	if (dirs.shouldRx) tasks.push(tcpRxLoop(ctx));
+	await Promise.all(tasks);
+}
+
 /** Bulk TCP send loop: writes `txSize` zero/random payloads until stopped. */
 async function tcpTxLoop(ctx: RunContext, sendStatus: boolean): Promise<void> {
 	await sleep(100);
@@ -932,7 +987,92 @@ async function tcpTxLoop(ctx: RunContext, sendStatus: boolean): Promise<void> {
 	}
 }
 
-/** Bulk TCP receive loop: counts bytes and scans for interleaved status. */
+/**
+ * Apply a decoded peer status to the counters: record the peer CPU and, when this
+ * side adapts (client transmit / both), retarget TX from the peer's `bytesReceived`
+ * speed-feedback. Shared by the dedicated `tcpStatusReaderLoop` (pure status stream)
+ * and the merged-stream demux in `tcpRxLoop`.
+ */
+function applyStatusFeedback(ctx: RunContext, status: BtestStatus): void {
+	const { counters } = ctx;
+	counters.remoteCpu = status.cpuLoad;
+	if (ctx.adaptTxFromStatus && status.bytesReceived > 0) {
+		counters.txSpeed = speedFeedbackBps(status.bytesReceived);
+		counters.txSpeedChanged = true;
+	}
+}
+
+/**
+ * Demux the most recent 12-byte status frame embedded in a bulk TCP chunk and apply
+ * it. In `direction=both` the peer interleaves status frames into the same bulk
+ * stream with no length framing, so they are found structurally: a frame is
+ * `[0x07][cpu][0x00][0x00][seq u32 LE][bytesReceived u32 LE]` — the two reserved
+ * bytes are always zero, making `0x07 ?? 00 00` a reliable marker in the default
+ * zero-filled payload, and it matches both client (CPU high-bit set) and RouterOS
+ * server (high-bit clear) frames. A `--random-data` payload can yield a rare false
+ * positive, and a frame split across a read boundary is missed, but TX speed is a
+ * soft pacing target that self-corrects on the next interval's frame. Only the last
+ * frame in the chunk is applied (the freshest feedback); the scan is in place, so it
+ * adds no copy on the RX hot path. The frame bytes stay counted in `rx` (matching
+ * RouterOS, which bills the overhead as stream bytes).
+ */
+/**
+ * Sanity ceiling for an embedded-status sequence number. Status frames are emitted
+ * once per `statusIntervalMs` (≥ 20 ms). We bound plausibility to a conservative
+ * long-session window: 6 hours at the minimum 20 ms cadence yields
+ * `(6 * 60 * 60 * 1000) / 20 = 1_080_000` frames, so any candidate sequence above
+ * that is treated as random-noise fallout from a false marker match.
+ */
+const BTEST_STATUS_MIN_INTERVAL_MS = 20;
+const BTEST_STATUS_MAX_RUN_HOURS = 6;
+const BTEST_STATUS_SEQ_SANE_MAX = Math.ceil(
+	(BTEST_STATUS_MAX_RUN_HOURS * 60 * 60 * 1000) / BTEST_STATUS_MIN_INTERVAL_MS,
+);
+
+/**
+ * Validate a candidate embedded-status window before trusting it. The structural
+ * marker `0x07 ?? 00 00` is only a 24-bit sentinel, so in a `--random-data` bulk
+ * stream it false-matches roughly once per 16 MB (~once/second at 100 Mb/s) — and a
+ * false frame would feed a garbage `bytesReceived` into `applyStatusFeedback`,
+ * rewriting `counters.txSpeed`. Two cheap, payload-independent invariants reject
+ * those: the CPU byte is a 0..100 percentage (decodeStatus *clamps* it, so check the
+ * raw byte), and the status sequence is a small monotonic counter, never a random
+ * 32-bit value (a bounded run can't reach `BTEST_STATUS_SEQ_SANE_MAX`). Together with
+ * the marker this drops the false-apply rate to negligible while leaving real frames
+ * untouched.
+ */
+function plausibleStatusFrame(frame: Uint8Array): boolean {
+	if (((frame[1] as number) & 0x7f) > 100) return false;
+	const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	return view.getUint32(4, true) <= BTEST_STATUS_SEQ_SANE_MAX;
+}
+
+export function applyEmbeddedStatus(ctx: RunContext, chunk: Uint8Array): void {
+	if (chunk.length < BTEST_STATUS_MSG_SIZE) return;
+	const limit = chunk.length - BTEST_STATUS_MSG_SIZE;
+	let lastValid: BtestStatus | undefined;
+	let i = 0;
+	while (i <= limit) {
+		const frame = chunk.subarray(i, i + BTEST_STATUS_MSG_SIZE);
+		if (
+			chunk[i] === BTEST_STATUS_MSG_TYPE &&
+			chunk[i + 2] === 0 &&
+			chunk[i + 3] === 0 &&
+			plausibleStatusFrame(frame)
+		) {
+			// A real status frame's own seq/bytes fields can contain `0x07 ?? 00 00`
+			// (e.g. seq 7), so consume the whole frame before scanning on — never
+			// re-match a matched frame's payload as a second, garbage frame.
+			lastValid = decodeStatus(frame);
+			i += BTEST_STATUS_MSG_SIZE;
+		} else {
+			i += 1;
+		}
+	}
+	if (lastValid) applyStatusFeedback(ctx, lastValid);
+}
+
+/** Bulk TCP receive loop: counts bytes and demuxes interleaved status frames. */
 async function tcpRxLoop(ctx: RunContext): Promise<void> {
 	const { counters } = ctx;
 	while (counters.running) {
@@ -942,14 +1082,7 @@ async function tcpRxLoop(ctx: RunContext): Promise<void> {
 			break;
 		}
 		counters.addRx(chunk.length);
-		if (chunk.length >= BTEST_STATUS_MSG_SIZE) {
-			for (let i = 0; i <= chunk.length - BTEST_STATUS_MSG_SIZE; i += 1) {
-				if (isStatusMarker(chunk, i)) {
-					counters.remoteCpu = Math.min((chunk[i + 1] as number) & 0x7f, 100);
-					break;
-				}
-			}
-		}
+		applyEmbeddedStatus(ctx, chunk);
 	}
 }
 
@@ -960,12 +1093,7 @@ async function tcpStatusReaderLoop(ctx: RunContext): Promise<void> {
 		const frame = await readExactOrStop(ctx, BTEST_STATUS_MSG_SIZE);
 		if (frame === null) break;
 		if (frame[0] !== BTEST_STATUS_MSG_TYPE) continue;
-		const status = decodeStatus(frame);
-		counters.remoteCpu = status.cpuLoad;
-		if (status.bytesReceived > 0) {
-			counters.txSpeed = speedFeedbackBps(status.bytesReceived);
-			counters.txSpeedChanged = true;
-		}
+		applyStatusFeedback(ctx, decodeStatus(frame));
 	}
 }
 
@@ -1024,6 +1152,8 @@ async function udpTxLoop(
 	// yields the event loop every iteration (sleep, or setImmediate when
 	// unlimited), so a slot's prior send has flushed long before we cycle back to
 	// it. The first allocation also runs encodeUdpPacket's size guard (≥ 4 bytes).
+	// Keep 8 slots so each buffer is only reused after multiple pace() yields;
+	// this gives node:dgram ample time to flush queued sends before a slot cycles.
 	const RING = 8;
 	const ring = Array.from({ length: RING }, (_, i) => {
 		const buf =
@@ -1157,6 +1287,8 @@ export interface BtestClientSessionOptions {
 	remoteTxSpeed?: number;
 	/** UDP per-packet size; TCP uses its bulk default. */
 	txSize?: number;
+	/** Parallel TCP data connections (TCP only); encoded in command byte 3. */
+	tcpConnectionCount?: number;
 	randomData?: boolean;
 	natMode?: boolean;
 	durationMs?: number;
@@ -1181,6 +1313,12 @@ export interface BtestRunSummary {
 	stopReason: BtestStopReason;
 	serverUdpPort?: number;
 	clientUdpPort?: number;
+	/**
+	 * TCP data connections actually driven (1 primary + joined secondaries). For a
+	 * `connection-count > 1` request this is the realized fan-out; it stays 1 when
+	 * the server negotiates no session token (e.g. authenticated sessions).
+	 */
+	activeConnections: number;
 }
 
 /** Run a full btest **client** session and return its aggregate summary. */
@@ -1200,6 +1338,9 @@ export async function runBtestClientSession(
 			? { randomData: options.randomData }
 			: {}),
 		...(options.txSize !== undefined ? { txSize: options.txSize } : {}),
+		...(options.tcpConnectionCount !== undefined
+			? { tcpConnectionCount: options.tcpConnectionCount }
+			: {}),
 		...(options.localTxSpeed !== undefined
 			? { localTxSpeed: options.localTxSpeed }
 			: {}),
@@ -1222,14 +1363,38 @@ export async function runBtestClientSession(
 	counters.txSpeed = options.localTxSpeed ?? 0;
 	const dirs = clientDirections(negotiated.command);
 
+	// Reuse the IP node already resolved for the TCP control connection as the UDP
+	// peer address. The client now addresses every datagram explicitly (no
+	// connect()), so passing a hostname here would make node:dgram run a DNS
+	// lookup per send on the UDP hot path; channel.remoteAddress is already an IP.
+	const udpPeerHost = channel.remoteAddress ?? options.host;
+
 	let udp: BtestUdpSocket | undefined;
 	if (options.protocol === "udp") {
 		udp = (options.createUdpSocket ?? createBtestUdpSocket)();
-		await udp.bind(negotiated.clientUdpPort as number, "0.0.0.0");
-		await udp.connect(negotiated.serverUdpPort as number, options.host);
-		if (options.natMode || dirs.shouldRx) {
-			// Originate a flow so the server's datagrams can return (NAT/SLIRP).
-			udp.send(new Uint8Array(0));
+		try {
+			await udp.bind(negotiated.clientUdpPort as number, "0.0.0.0");
+			// Do NOT connect() the socket: connect() installs a kernel receive filter
+			// that silently drops datagrams whose source port differs from the connected
+			// peer. RouterOS may send UDP data from a different source port than the
+			// negotiated serverUdpPort (separate TX socket), so the filter would discard
+			// all incoming packets and leave rx at 0 bps throughout. Instead, keep the
+			// socket unconnected (like the server side) and always address sends
+			// explicitly via udpTxLoop's target argument.
+			if (options.natMode || dirs.shouldRx) {
+				// Originate a flow so the server's datagrams can return (NAT/SLIRP).
+				udp.send(
+					new Uint8Array(0),
+					negotiated.serverUdpPort as number,
+					udpPeerHost,
+				);
+			}
+		} catch (error) {
+			// bind()/send() can throw before the normal close path runs; release the
+			// socket and the control channel so a UDP bootstrap failure leaks neither.
+			udp.close();
+			channel.close();
+			throw error;
 		}
 	}
 
@@ -1248,19 +1413,78 @@ export async function runBtestClientSession(
 		...(negotiated.serverUdpPort !== undefined
 			? { serverUdpPort: negotiated.serverUdpPort }
 			: {}),
-		udpPeerHost: options.host,
+		udpPeerHost,
 		...(options.onInterval ? { onInterval: options.onInterval } : {}),
 	};
 
-	const stopReason = await driveSession(ctx, dirs, "client", {
-		...(options.durationMs !== undefined
-			? { durationMs: options.durationMs }
-			: {}),
-		...(options.signal ? { signal: options.signal } : {}),
-	});
+	// TCP multi-connection fan-out: the server negotiated a session token, so open
+	// the requested extra data connections and drive them into the **shared**
+	// counters, concurrently with the primary, so throughput aggregates across all
+	// streams (grounded against RouterOS 7.23.1). A secondary that fails to open
+	// degrades to fewer streams rather than failing the test — the primary already
+	// carries the session. They share `counters.running`, so the primary's
+	// duration/abort stop unblocks them too.
+	const secondaryChannels: BtestControlChannel[] = [];
+	if (
+		options.protocol === "tcp" &&
+		negotiated.sessionToken !== undefined &&
+		(options.tcpConnectionCount ?? 1) > 1
+	) {
+		// Dial secondaries at the **same peer** the primary control socket resolved
+		// to, not a fresh `options.host` lookup: a hostname that load-balances across
+		// addresses could otherwise land a secondary on a different RouterOS, where
+		// the session token is unknown and the join fails.
+		const secondaryHost = channel.remoteAddress ?? options.host;
+		const extra = (options.tcpConnectionCount as number) - 1;
+		for (let i = 0; i < extra; i += 1) {
+			try {
+				secondaryChannels.push(
+					await openSecondaryConnection(
+						connect,
+						secondaryHost,
+						controlPort,
+						negotiated.sessionToken,
+					),
+				);
+			} catch {
+				break;
+			}
+		}
+	}
+	const secondaryLoops = secondaryChannels.map((secondaryChannel) =>
+		runSecondaryDataLoops(
+			{
+				channel: secondaryChannel,
+				command: negotiated.command,
+				counters,
+				txSize,
+				txSpeed: options.localTxSpeed ?? 0,
+				randomData: options.randomData ?? false,
+				statusIntervalMs: options.statusIntervalMs ?? BTEST_STATUS_INTERVAL_MS,
+			},
+			dirs,
+		),
+	);
 
-	udp?.close();
-	channel.close();
+	// Close every socket even if a loop throws — a rejected Promise.all must not leak
+	// the UDP socket or any open TCP channel.
+	let stopReason: BtestStopReason;
+	try {
+		const [primaryStopReason] = await Promise.all([
+			driveSession(ctx, dirs, "client", {
+				...(options.durationMs !== undefined
+					? { durationMs: options.durationMs }
+					: {}),
+				...(options.signal ? { signal: options.signal } : {}),
+			}),
+			...secondaryLoops,
+		]);
+		stopReason = primaryStopReason;
+	} finally {
+		udp?.close();
+		channel.close();
+		for (const secondaryChannel of secondaryChannels) secondaryChannel.close();
+	}
 
 	const sum = counters.summary();
 	const summary: BtestRunSummary = {
@@ -1273,6 +1497,7 @@ export async function runBtestClientSession(
 		intervals: sum.intervals,
 		durationMs: Date.now() - start,
 		stopReason,
+		activeConnections: 1 + secondaryChannels.length,
 	};
 	if (negotiated.username !== undefined) summary.username = negotiated.username;
 	if (negotiated.serverUdpPort !== undefined)
@@ -1430,20 +1655,28 @@ async function driveSession(
 
 	const tasks: Promise<void>[] = [];
 	if (ctx.command.protocol === "udp") {
-		// The client `connect()`s its socket (sends with no per-packet address); the
-		// server is unconnected and `send_to`s the client (so it can receive from a
-		// NAT-rewritten source). See the server's UDP setup.
-		const target =
-			role === "server" &&
-			ctx.clientUdpPort !== undefined &&
-			ctx.udpPeerHost !== undefined
-				? { port: ctx.clientUdpPort, host: ctx.udpPeerHost }
-				: undefined;
+		// Both client and server address sends explicitly (no connected-socket
+		// default): client → serverUdpPort, server → clientUdpPort. An unconnected
+		// socket accepts datagrams from any source, avoiding the BSD receive filter
+		// that connect() installs and that silently drops packets when RouterOS
+		// sends from an unexpected source port.
+		let target: { port: number; host: string } | undefined;
+		if (ctx.udpPeerHost !== undefined) {
+			if (role === "server" && ctx.clientUdpPort !== undefined) {
+				target = { port: ctx.clientUdpPort, host: ctx.udpPeerHost };
+			} else if (role === "client" && ctx.serverUdpPort !== undefined) {
+				target = { port: ctx.serverUdpPort, host: ctx.udpPeerHost };
+			}
+		}
 		if (dirs.shouldTx) tasks.push(udpTxLoop(ctx, target));
 		if (dirs.shouldRx) tasks.push(udpRxLoop(ctx));
 		tasks.push(udpStatusExchange(ctx, dirs));
 	} else {
-		// TCP: only the receiving server emits status frames; the client never does.
+		// A transmitting client paces its TX from the server's status feedback. For
+		// `transmit` that arrives on the dedicated status stream (tcpStatusReaderLoop);
+		// for `both` it is interleaved into the bulk RX stream (tcpRxLoop's demux).
+		// Either way this gate routes the feedback into counters.txSpeed.
+		ctx.adaptTxFromStatus = role === "client" && dirs.shouldTx;
 		if (dirs.shouldTx && dirs.shouldRx) {
 			tasks.push(tcpTxLoop(ctx, role === "server"));
 			tasks.push(tcpRxLoop(ctx));

package/src/protocols/btest.ts

@@ -254,14 +254,18 @@ export function sessionTokenFromResponse(buf: Uint8Array): number {
 
 /**
  * The 16-byte "command" a secondary TCP connection sends to join an existing
- * session — the token in bytes 0-1 (big-endian), the rest zero. The server
- * answers `01 <tokenHi> <tokenLo> 00` and the connection joins without auth.
+ * session — the token in bytes 0-1 (big-endian), a constant `0x02` join marker in
+ * byte 2, the rest zero. The connection joins without auth; the server sends **no**
+ * acknowledgement before it starts streaming bulk data, so the client must not
+ * await one. Grounded byte-for-byte against RouterOS 7.23.1 (`12 34 02 00 …`,
+ * direction-independent — see the btest-session.ts header).
  */
 export function encodeSecondaryJoin(sessionToken: number): Uint8Array {
 	assertField(sessionToken, U16_MAX, "session-token");
 	const buf = new Uint8Array(BTEST_COMMAND_SIZE);
 	buf[0] = (sessionToken >> 8) & 0xff;
 	buf[1] = sessionToken & 0xff;
+	buf[2] = 0x02;
 	return buf;
 }