@classytic/stage 0.3.0 → 0.4.0

package/dist/networking/queue.mjs

@@ -0,0 +1,18 @@
+//#region src/networking/queue.ts
+function queueAtTime(arrivalPps, servicePps, bufferPackets, elapsedSeconds) {
+	const accumulated = Math.max(0, arrivalPps - servicePps) * Math.max(0, elapsedSeconds);
+	const queued = Math.min(Math.max(0, bufferPackets), accumulated);
+	const dropped = Math.max(0, accumulated - Math.max(0, bufferPackets));
+	return {
+		queued,
+		dropped,
+		delayMs: servicePps > 0 ? Math.round(queued / servicePps * 1e3) : 0,
+		state: dropped > 0 ? "dropping" : queued > 0 ? "building" : "clear"
+	};
+}
+function bottleneckQueue(arrivalPps, servicePps, bufferPackets) {
+	return queueAtTime(arrivalPps, servicePps, bufferPackets, 2);
+}
+
+//#endregion
+export { bottleneckQueue, queueAtTime };

package/dist/networking/route-learning.d.mts

@@ -0,0 +1,23 @@
+//#region src/networking/route-learning.d.ts
+interface OspfLink {
+  from: string;
+  to: string;
+  cost: number;
+}
+interface LearnedRoute {
+  path: readonly string[];
+  metric: number;
+  reason: string;
+}
+declare function learnOspfRoute(source: string, destination: string, links: readonly OspfLink[]): LearnedRoute | null;
+interface BgpCandidate {
+  id: string;
+  asPath: readonly number[];
+  localPreference: number;
+  allowed: boolean;
+}
+declare function selectBgpRoute(candidates: readonly BgpCandidate[]): (BgpCandidate & {
+  reason: string;
+}) | null;
+//#endregion
+export { BgpCandidate, LearnedRoute, OspfLink, learnOspfRoute, selectBgpRoute };

package/dist/networking/route-learning.mjs

@@ -0,0 +1,43 @@
+//#region src/networking/route-learning.ts
+function learnOspfRoute(source, destination, links) {
+	const nodes = new Set(links.flatMap((link) => [link.from, link.to]));
+	if (!nodes.has(source) || !nodes.has(destination)) return null;
+	const distance = new Map([[source, 0]]);
+	const previous = /* @__PURE__ */ new Map();
+	const unvisited = new Set(nodes);
+	while (unvisited.size > 0) {
+		const current = [...unvisited].sort((a, b) => (distance.get(a) ?? Infinity) - (distance.get(b) ?? Infinity) || a.localeCompare(b))[0];
+		unvisited.delete(current);
+		if (current === destination) break;
+		const currentDistance = distance.get(current);
+		if (currentDistance == null) break;
+		for (const link of links.filter((item) => item.from === current || item.to === current)) {
+			const neighbor = link.from === current ? link.to : link.from;
+			if (!unvisited.has(neighbor)) continue;
+			const candidate = currentDistance + Math.max(1, link.cost);
+			if (candidate < (distance.get(neighbor) ?? Infinity)) {
+				distance.set(neighbor, candidate);
+				previous.set(neighbor, current);
+			}
+		}
+	}
+	const metric = distance.get(destination);
+	if (metric == null) return null;
+	const path = [destination];
+	while (path[0] !== source) path.unshift(previous.get(path[0]));
+	return {
+		path,
+		metric,
+		reason: `Lowest accumulated link cost: ${metric}.`
+	};
+}
+function selectBgpRoute(candidates) {
+	const selected = candidates.filter((candidate) => candidate.allowed).sort((a, b) => b.localPreference - a.localPreference || a.asPath.length - b.asPath.length || a.id.localeCompare(b.id))[0];
+	return selected ? {
+		...selected,
+		reason: "Policy preference wins first; AS-path length breaks the tie."
+	} : null;
+}
+
+//#endregion
+export { learnOspfRoute, selectBgpRoute };

package/dist/networking/routing.d.mts

@@ -0,0 +1,11 @@
+import { NetworkRoute } from "./topology/contract.mjs";
+
+//#region src/networking/routing.d.ts
+declare function parseCidr(cidr: string): {
+  network: number;
+  prefix: number;
+} | undefined;
+declare function cidrContains(cidr: string, ip: string): boolean;
+declare function longestPrefixMatch(routes: readonly NetworkRoute[], destinationIp: string): NetworkRoute | undefined;
+//#endregion
+export { cidrContains, longestPrefixMatch, parseCidr };

package/dist/networking/routing.mjs

@@ -0,0 +1,25 @@
+import { ipv4ToInt } from "./subnet.mjs";
+
+//#region src/networking/routing.ts
+function parseCidr(cidr) {
+	const [ip, rawPrefix] = cidr.split("/");
+	const value = ipv4ToInt(ip ?? "");
+	const prefix = Number(rawPrefix);
+	if (value == null || !Number.isInteger(prefix) || prefix < 0 || prefix > 32) return void 0;
+	return {
+		network: value & (prefix === 0 ? 0 : 4294967295 << 32 - prefix >>> 0),
+		prefix
+	};
+}
+function cidrContains(cidr, ip) {
+	const parsed = parseCidr(cidr);
+	const value = ipv4ToInt(ip);
+	if (!parsed || value == null) return false;
+	return (value & (parsed.prefix === 0 ? 0 : 4294967295 << 32 - parsed.prefix >>> 0)) === parsed.network;
+}
+function longestPrefixMatch(routes, destinationIp) {
+	return routes.filter((route) => cidrContains(route.prefix, destinationIp)).sort((left, right) => (parseCidr(right.prefix)?.prefix ?? -1) - (parseCidr(left.prefix)?.prefix ?? -1) || (left.metric ?? 0) - (right.metric ?? 0))[0];
+}
+
+//#endregion
+export { cidrContains, longestPrefixMatch, parseCidr };

package/dist/networking/signals.d.mts

@@ -0,0 +1,26 @@
+//#region src/networking/signals.d.ts
+type ModulationScheme = "ask" | "bpsk";
+interface ModulationResult {
+  readonly bits: string;
+  readonly recovered: string;
+  readonly errors: number;
+  readonly symbols: readonly {
+    bit: "0" | "1";
+    amplitude: number;
+    phase: number;
+  }[];
+}
+declare function modulate(bits: string, scheme: ModulationScheme, noisePercent: number): ModulationResult;
+type MediaKind = "voice" | "video";
+type MediaQuality = "efficient" | "detailed";
+interface EncodingResult {
+  readonly bitrateKbps: number;
+  readonly units: number;
+  readonly packets: number;
+  readonly received: number;
+  readonly lost: number;
+  readonly fidelity: number;
+}
+declare function encodeMedia(kind: MediaKind, quality: MediaQuality, lossPercent: number): EncodingResult;
+//#endregion
+export { EncodingResult, MediaKind, MediaQuality, ModulationResult, ModulationScheme, encodeMedia, modulate };

package/dist/networking/signals.mjs

@@ -0,0 +1,35 @@
+//#region src/networking/signals.ts
+function modulate(bits, scheme, noisePercent) {
+	const clean = bits.replace(/[^01]/g, "").slice(0, 8) || "0";
+	const errorBudget = noisePercent < 20 ? 0 : noisePercent < 35 ? 1 : Math.min(2, clean.length);
+	const errorIndexes = new Set(Array.from({ length: errorBudget }, (_, index) => clean.length - 1 - index * 2));
+	return {
+		bits: clean,
+		recovered: [...clean].map((bit, index) => errorIndexes.has(index) ? bit === "1" ? "0" : "1" : bit).join(""),
+		errors: errorBudget,
+		symbols: [...clean].map((bit) => ({
+			bit,
+			amplitude: scheme === "ask" ? bit === "1" ? 1 : .35 : 1,
+			phase: scheme === "bpsk" && bit === "0" ? Math.PI : 0
+		}))
+	};
+}
+function encodeMedia(kind, quality, lossPercent) {
+	const detailed = quality === "detailed";
+	const bitrateKbps = kind === "voice" ? detailed ? 64 : 16 : detailed ? 2500 : 500;
+	const units = kind === "voice" ? detailed ? 16 : 8 : detailed ? 12 : 6;
+	const packets = kind === "voice" ? 8 : 12;
+	const lost = Math.min(packets, Math.round(packets * Math.max(0, lossPercent) / 100));
+	const received = packets - lost;
+	return {
+		bitrateKbps,
+		units,
+		packets,
+		received,
+		lost,
+		fidelity: Math.max(0, Math.round(received / packets * (detailed ? 100 : 78)))
+	};
+}
+
+//#endregion
+export { encodeMedia, modulate };

package/dist/networking/subnet.d.mts

@@ -0,0 +1,49 @@
+//#region src/networking/subnet.d.ts
+/**
+ * Subnetting, reduced to the one question it actually answers.
+ *
+ * "Are these two addresses on the same network?" is the whole of it, and the answer is mechanical:
+ * compare the first `prefix` bits. Same, and the two can talk directly. Different, and everything
+ * has to go through a router. Every other subnetting fact (mask, network address, broadcast, usable
+ * count) falls out of where that boundary sits.
+ *
+ * Students drown here because it is taught in dotted decimal, where the boundary is invisible. In
+ * binary it is a vertical line, and the moment it crosses the first differing bit the answer flips.
+ * That is the thing to show.
+ */
+declare function ipv4ToInt(ip: string): number | undefined;
+declare const intToIpv4: (value: number) => string;
+/** The mask for a prefix, as a 32-bit unsigned value. /0 is all zeros. */
+declare const maskFor: (prefix: number) => number;
+interface Bit {
+  value: 0 | 1;
+  /** True while this bit is inside the network portion. */
+  network: boolean;
+}
+/** The 32 bits of an address, flagged by which side of the prefix boundary they fall. */
+declare function bitsOf(address: string, prefix: number): Bit[] | null;
+interface SubnetInfo {
+  address: string;
+  prefix: number;
+  mask: string;
+  network: string;
+  broadcast: string;
+  firstUsable: string | null;
+  lastUsable: string | null;
+  /** Addresses that can be given to a device. Excludes network and broadcast. */
+  usableHosts: number;
+  bits: Bit[];
+}
+declare function describe(address: string, prefix: number): SubnetInfo | null;
+/** Do two addresses share a network under this prefix? */
+declare function sameNetwork(a: string, b: string, prefix: number): boolean | null;
+/**
+ * The index (0-based from the left) of the first bit where two addresses differ, or -1 when they
+ * are identical. This is the number the whole lab turns on: any prefix at or below it puts the two
+ * on the same network, and any prefix above it separates them.
+ */
+declare function firstDifferingBit(a: string, b: string): number;
+/** The largest prefix that still keeps both addresses together. */
+declare function widestSharedPrefix(a: string, b: string): number;
+//#endregion
+export { Bit, SubnetInfo, bitsOf, describe, firstDifferingBit, intToIpv4, ipv4ToInt, maskFor, sameNetwork, widestSharedPrefix };

package/dist/networking/subnet.mjs

@@ -0,0 +1,89 @@
+//#region src/networking/subnet.ts
+/**
+* Subnetting, reduced to the one question it actually answers.
+*
+* "Are these two addresses on the same network?" is the whole of it, and the answer is mechanical:
+* compare the first `prefix` bits. Same, and the two can talk directly. Different, and everything
+* has to go through a router. Every other subnetting fact (mask, network address, broadcast, usable
+* count) falls out of where that boundary sits.
+*
+* Students drown here because it is taught in dotted decimal, where the boundary is invisible. In
+* binary it is a vertical line, and the moment it crosses the first differing bit the answer flips.
+* That is the thing to show.
+*/
+function ipv4ToInt(ip) {
+	const parts = ip.split(".");
+	if (parts.length !== 4) return void 0;
+	const nums = parts.map(Number);
+	if (nums.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return void 0;
+	return nums.reduce((acc, n) => acc * 256 + n >>> 0, 0);
+}
+const intToIpv4 = (value) => [
+	24,
+	16,
+	8,
+	0
+].map((shift) => value >>> shift & 255).join(".");
+/** The mask for a prefix, as a 32-bit unsigned value. /0 is all zeros. */
+const maskFor = (prefix) => prefix <= 0 ? 0 : prefix >= 32 ? 4294967295 : 4294967295 << 32 - prefix >>> 0;
+/** The 32 bits of an address, flagged by which side of the prefix boundary they fall. */
+function bitsOf(address, prefix) {
+	const value = ipv4ToInt(address);
+	if (value == null) return null;
+	return Array.from({ length: 32 }, (_, index) => ({
+		value: value >>> 31 - index & 1,
+		network: index < prefix
+	}));
+}
+function describe(address, prefix) {
+	const value = ipv4ToInt(address);
+	const bits = bitsOf(address, prefix);
+	if (value == null || !bits || prefix < 0 || prefix > 32) return null;
+	const mask = maskFor(prefix);
+	const network = (value & mask) >>> 0;
+	const broadcast = (network | ~mask >>> 0) >>> 0;
+	const total = 2 ** (32 - prefix);
+	const usableHosts = total > 2 ? total - 2 : 0;
+	return {
+		address,
+		prefix,
+		mask: intToIpv4(mask),
+		network: intToIpv4(network),
+		broadcast: intToIpv4(broadcast),
+		firstUsable: usableHosts ? intToIpv4(network + 1) : null,
+		lastUsable: usableHosts ? intToIpv4(broadcast - 1) : null,
+		usableHosts,
+		bits
+	};
+}
+/** Do two addresses share a network under this prefix? */
+function sameNetwork(a, b, prefix) {
+	const left = ipv4ToInt(a);
+	const right = ipv4ToInt(b);
+	if (left == null || right == null) return null;
+	const mask = maskFor(prefix);
+	return (left & mask) >>> 0 === (right & mask) >>> 0;
+}
+/**
+* The index (0-based from the left) of the first bit where two addresses differ, or -1 when they
+* are identical. This is the number the whole lab turns on: any prefix at or below it puts the two
+* on the same network, and any prefix above it separates them.
+*/
+function firstDifferingBit(a, b) {
+	const left = ipv4ToInt(a);
+	const right = ipv4ToInt(b);
+	if (left == null || right == null) return -1;
+	for (let index = 0; index < 32; index++) {
+		const shift = 31 - index;
+		if ((left >>> shift & 1) !== (right >>> shift & 1)) return index;
+	}
+	return -1;
+}
+/** The largest prefix that still keeps both addresses together. */
+function widestSharedPrefix(a, b) {
+	const differing = firstDifferingBit(a, b);
+	return differing === -1 ? 32 : differing;
+}
+
+//#endregion
+export { bitsOf, describe, firstDifferingBit, intToIpv4, ipv4ToInt, maskFor, sameNetwork, widestSharedPrefix };

package/dist/networking/tcp-reliability.d.mts

@@ -0,0 +1,24 @@
+//#region src/networking/tcp-reliability.d.ts
+type TcpFeedback = "ack" | "triple-duplicate-ack" | "timeout";
+interface TcpSenderOptions {
+  congestionWindow: number;
+  receiverWindow: number;
+  slowStartThreshold: number;
+  feedback: TcpFeedback;
+}
+interface TcpSenderResult {
+  sendWindow: number;
+  nextCongestionWindow: number;
+  nextSlowStartThreshold: number;
+  phase: "slow-start" | "congestion-avoidance" | "fast-recovery" | "timeout-recovery";
+  retransmit: boolean;
+  reason: string;
+}
+declare function advanceTcpSender({
+  congestionWindow,
+  receiverWindow,
+  slowStartThreshold,
+  feedback
+}: TcpSenderOptions): TcpSenderResult;
+//#endregion
+export { TcpFeedback, TcpSenderOptions, TcpSenderResult, advanceTcpSender };

package/dist/networking/tcp-reliability.mjs

@@ -0,0 +1,38 @@
+//#region src/networking/tcp-reliability.ts
+function advanceTcpSender({ congestionWindow, receiverWindow, slowStartThreshold, feedback }) {
+	const cwnd = Math.max(1, Math.floor(congestionWindow));
+	const rwnd = Math.max(0, Math.floor(receiverWindow));
+	const threshold = Math.max(2, Math.floor(slowStartThreshold));
+	const sendWindow = Math.min(cwnd, rwnd);
+	if (feedback === "timeout") return {
+		sendWindow,
+		nextCongestionWindow: 1,
+		nextSlowStartThreshold: Math.max(2, Math.floor(cwnd / 2)),
+		phase: "timeout-recovery",
+		retransmit: true,
+		reason: "A timeout is strong congestion evidence: retransmit and restart cautiously."
+	};
+	if (feedback === "triple-duplicate-ack") {
+		const halved = Math.max(2, Math.floor(cwnd / 2));
+		return {
+			sendWindow,
+			nextCongestionWindow: halved,
+			nextSlowStartThreshold: halved,
+			phase: "fast-recovery",
+			retransmit: true,
+			reason: "Duplicate acknowledgements identify a gap while later data is still arriving."
+		};
+	}
+	const slowStart = cwnd < threshold;
+	return {
+		sendWindow,
+		nextCongestionWindow: slowStart ? cwnd * 2 : cwnd + 1,
+		nextSlowStartThreshold: threshold,
+		phase: slowStart ? "slow-start" : "congestion-avoidance",
+		retransmit: false,
+		reason: slowStart ? "Acknowledgements rapidly grow the congestion window." : "Acknowledgements grow the window cautiously after the threshold."
+	};
+}
+
+//#endregion
+export { advanceTcpSender };

package/dist/networking/topology/contract.d.mts

@@ -0,0 +1,123 @@
+//#region src/networking/topology/contract.d.ts
+type NetworkDeviceKind = "client" | "server" | "switch" | "router" | "access-point" | "firewall" | "load-balancer" | "dns" | "broker" | "cloud";
+interface NetworkInterface {
+  id: string;
+  label?: string;
+  mac?: string;
+  addresses?: string[];
+}
+interface NetworkDevice {
+  id: string;
+  kind: NetworkDeviceKind;
+  label: string;
+  at: {
+    x: number;
+    y: number;
+  };
+  interfaces: NetworkInterface[];
+  services?: {
+    kind: "dhcp" | "dns" | "http" | "https" | "ftp" | "websocket";
+    port?: number;
+    label?: string;
+  }[];
+}
+interface NetworkEndpoint {
+  deviceId: string;
+  interfaceId: string;
+}
+interface NetworkLink {
+  id: string;
+  a: NetworkEndpoint;
+  b: NetworkEndpoint;
+  label?: string;
+  cost?: number;
+  latencyMs?: number;
+  bandwidthMbps?: number;
+  loss?: number;
+  mtu?: number;
+  state?: "up" | "down";
+}
+interface NetworkRoute {
+  id: string;
+  deviceId: string;
+  prefix: string;
+  via?: string;
+  interfaceId: string;
+  metric?: number;
+}
+interface NetworkDoc {
+  schemaVersion: 1;
+  type: "network";
+  devices: NetworkDevice[];
+  links: NetworkLink[];
+  routes?: NetworkRoute[];
+  title?: string;
+}
+type PacketLayerKind = "application" | "transport" | "network" | "data-link" | "physical";
+interface PacketLayer {
+  kind: PacketLayerKind;
+  protocol: string;
+  summary: string;
+  fields?: Record<string, string | number>;
+}
+interface NetworkPacket {
+  id: string;
+  from: string;
+  to: string;
+  bytes: number;
+  layers: PacketLayer[];
+}
+type NetworkEvent = {
+  type: "packet-created";
+  at: string;
+  packet: NetworkPacket;
+  message: string;
+} | {
+  type: "arp-requested";
+  at: string;
+  target: string;
+  message: string;
+} | {
+  type: "arp-resolved";
+  at: string;
+  target: string;
+  message: string;
+} | {
+  type: "route-selected";
+  at: string;
+  next: string;
+  prefix?: string;
+  message: string;
+} | {
+  type: "frame-sent";
+  at: string;
+  linkId: string;
+  next: string;
+  packet: NetworkPacket;
+  message: string;
+} | {
+  type: "frame-received";
+  at: string;
+  linkId: string;
+  from: string;
+  packet: NetworkPacket;
+  message: string;
+} | {
+  type: "packet-dropped";
+  at: string;
+  reason: "unreachable" | "link-down" | "loss" | "mtu";
+  message: string;
+} | {
+  type: "packet-delivered";
+  at: string;
+  packet: NetworkPacket;
+  message: string;
+};
+interface NetworkTrace {
+  delivered: boolean;
+  path: string[];
+  totalLatencyMs: number;
+  events: NetworkEvent[];
+}
+//#endregion
+export { NetworkDevice, NetworkDeviceKind, NetworkDoc, NetworkEndpoint, NetworkEvent, NetworkInterface, NetworkLink, NetworkPacket, NetworkRoute, NetworkTrace, PacketLayer, PacketLayerKind };

package/dist/networking/topology/index.d.mts

@@ -0,0 +1,4 @@
+import { NetworkDevice, NetworkDeviceKind, NetworkDoc, NetworkEndpoint, NetworkEvent, NetworkInterface, NetworkLink, NetworkPacket, NetworkRoute, NetworkTrace, PacketLayer, PacketLayerKind } from "./contract.mjs";
+import { COMPANY_NETWORK, HOME_NETWORK } from "./presets.mjs";
+import { createPacket, simulatePacket } from "./simulation.mjs";
+export { COMPANY_NETWORK, HOME_NETWORK, NetworkDevice, NetworkDeviceKind, NetworkDoc, NetworkEndpoint, NetworkEvent, NetworkInterface, NetworkLink, NetworkPacket, NetworkRoute, NetworkTrace, PacketLayer, PacketLayerKind, createPacket, simulatePacket };

package/dist/networking/topology/index.mjs

@@ -0,0 +1,4 @@
+import { COMPANY_NETWORK, HOME_NETWORK } from "./presets.mjs";
+import { createPacket, simulatePacket } from "./simulation.mjs";
+
+export { COMPANY_NETWORK, HOME_NETWORK, createPacket, simulatePacket };

package/dist/networking/topology/presets.d.mts

@@ -0,0 +1,7 @@
+import { NetworkDoc } from "./contract.mjs";
+
+//#region src/networking/topology/presets.d.ts
+declare const HOME_NETWORK: NetworkDoc;
+declare const COMPANY_NETWORK: NetworkDoc;
+//#endregion
+export { COMPANY_NETWORK, HOME_NETWORK };