@classytic/labs 0.2.0 → 0.3.0

package/dist/networking/presets.d.mts

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

package/dist/networking/presets.mjs

@@ -0,0 +1,302 @@
+//#region src/networking/presets.ts
+const HOME_NETWORK = {
+	schemaVersion: 1,
+	type: "network",
+	title: "From a home laptop to a web server",
+	devices: [
+		{
+			id: "laptop",
+			kind: "client",
+			label: "Laptop",
+			at: {
+				x: 80,
+				y: 150
+			},
+			interfaces: [{
+				id: "wifi0",
+				mac: "02:00:00:00:00:10",
+				addresses: ["192.168.1.20/24"]
+			}]
+		},
+		{
+			id: "wifi",
+			kind: "access-point",
+			label: "Wi-Fi AP",
+			at: {
+				x: 230,
+				y: 150
+			},
+			interfaces: [{ id: "lan1" }, { id: "lan2" }]
+		},
+		{
+			id: "router",
+			kind: "router",
+			label: "Home router",
+			at: {
+				x: 390,
+				y: 150
+			},
+			interfaces: [{
+				id: "lan",
+				addresses: ["192.168.1.1/24"]
+			}, {
+				id: "wan",
+				addresses: ["203.0.113.2/30"]
+			}]
+		},
+		{
+			id: "internet",
+			kind: "cloud",
+			label: "Internet",
+			at: {
+				x: 550,
+				y: 150
+			},
+			interfaces: [{ id: "edge1" }, { id: "edge2" }]
+		},
+		{
+			id: "web",
+			kind: "server",
+			label: "Web server",
+			at: {
+				x: 710,
+				y: 150
+			},
+			interfaces: [{
+				id: "eth0",
+				addresses: ["198.51.100.20/24"]
+			}],
+			services: [{
+				kind: "http",
+				port: 80
+			}]
+		}
+	],
+	links: [
+		{
+			id: "wifi-link",
+			a: {
+				deviceId: "laptop",
+				interfaceId: "wifi0"
+			},
+			b: {
+				deviceId: "wifi",
+				interfaceId: "lan1"
+			},
+			label: "Wi-Fi",
+			latencyMs: 4,
+			bandwidthMbps: 300
+		},
+		{
+			id: "lan-link",
+			a: {
+				deviceId: "wifi",
+				interfaceId: "lan2"
+			},
+			b: {
+				deviceId: "router",
+				interfaceId: "lan"
+			},
+			label: "LAN",
+			latencyMs: 1,
+			bandwidthMbps: 1e3
+		},
+		{
+			id: "isp-link",
+			a: {
+				deviceId: "router",
+				interfaceId: "wan"
+			},
+			b: {
+				deviceId: "internet",
+				interfaceId: "edge1"
+			},
+			label: "ISP",
+			latencyMs: 14,
+			bandwidthMbps: 100
+		},
+		{
+			id: "server-link",
+			a: {
+				deviceId: "internet",
+				interfaceId: "edge2"
+			},
+			b: {
+				deviceId: "web",
+				interfaceId: "eth0"
+			},
+			label: "datacenter",
+			latencyMs: 18,
+			bandwidthMbps: 1e3
+		}
+	]
+};
+const COMPANY_NETWORK = {
+	schemaVersion: 1,
+	type: "network",
+	title: "Company network with redundant routes",
+	devices: [
+		{
+			id: "employee",
+			kind: "client",
+			label: "Employee",
+			at: {
+				x: 70,
+				y: 150
+			},
+			interfaces: [{
+				id: "eth0",
+				addresses: ["10.20.1.25/24"]
+			}]
+		},
+		{
+			id: "access",
+			kind: "switch",
+			label: "Access switch",
+			at: {
+				x: 210,
+				y: 150
+			},
+			interfaces: [
+				{ id: "p1" },
+				{ id: "p2" },
+				{ id: "p3" }
+			]
+		},
+		{
+			id: "r1",
+			kind: "router",
+			label: "Router A",
+			at: {
+				x: 380,
+				y: 80
+			},
+			interfaces: [{ id: "lan" }, { id: "wan" }]
+		},
+		{
+			id: "r2",
+			kind: "router",
+			label: "Router B",
+			at: {
+				x: 380,
+				y: 220
+			},
+			interfaces: [{ id: "lan" }, { id: "wan" }]
+		},
+		{
+			id: "firewall",
+			kind: "firewall",
+			label: "Firewall",
+			at: {
+				x: 550,
+				y: 150
+			},
+			interfaces: [
+				{ id: "inside1" },
+				{ id: "inside2" },
+				{ id: "dmz" }
+			]
+		},
+		{
+			id: "api",
+			kind: "server",
+			label: "API server",
+			at: {
+				x: 720,
+				y: 150
+			},
+			interfaces: [{
+				id: "eth0",
+				addresses: ["10.30.0.10/24"]
+			}],
+			services: [{
+				kind: "https",
+				port: 443
+			}, {
+				kind: "websocket",
+				port: 443
+			}]
+		}
+	],
+	links: [
+		{
+			id: "employee-access",
+			a: {
+				deviceId: "employee",
+				interfaceId: "eth0"
+			},
+			b: {
+				deviceId: "access",
+				interfaceId: "p1"
+			},
+			latencyMs: 1
+		},
+		{
+			id: "access-r1",
+			a: {
+				deviceId: "access",
+				interfaceId: "p2"
+			},
+			b: {
+				deviceId: "r1",
+				interfaceId: "lan"
+			},
+			latencyMs: 2,
+			cost: 2
+		},
+		{
+			id: "access-r2",
+			a: {
+				deviceId: "access",
+				interfaceId: "p3"
+			},
+			b: {
+				deviceId: "r2",
+				interfaceId: "lan"
+			},
+			latencyMs: 4,
+			cost: 4
+		},
+		{
+			id: "r1-fw",
+			a: {
+				deviceId: "r1",
+				interfaceId: "wan"
+			},
+			b: {
+				deviceId: "firewall",
+				interfaceId: "inside1"
+			},
+			latencyMs: 2,
+			cost: 2
+		},
+		{
+			id: "r2-fw",
+			a: {
+				deviceId: "r2",
+				interfaceId: "wan"
+			},
+			b: {
+				deviceId: "firewall",
+				interfaceId: "inside2"
+			},
+			latencyMs: 2,
+			cost: 2
+		},
+		{
+			id: "fw-api",
+			a: {
+				deviceId: "firewall",
+				interfaceId: "dmz"
+			},
+			b: {
+				deviceId: "api",
+				interfaceId: "eth0"
+			},
+			latencyMs: 1
+		}
+	]
+};
+
+//#endregion
+export { COMPANY_NETWORK, HOME_NETWORK };

package/dist/networking/simulation.d.mts

@@ -0,0 +1,8 @@
+import { NetworkDoc, NetworkPacket, NetworkTrace } from "./contract.mjs";
+
+//#region src/networking/simulation.d.ts
+declare function createPacket(doc: NetworkDoc, from: string, to: string, protocol?: 'icmp' | 'http'): NetworkPacket;
+/** Small deterministic packet trace: topology/path truth is real, protocol narration is explicit. */
+declare function simulatePacket(doc: NetworkDoc, from: string, to: string, protocol?: 'icmp' | 'http'): NetworkTrace;
+//#endregion
+export { createPacket, simulatePacket };

package/dist/networking/simulation.mjs

@@ -0,0 +1,148 @@
+import { dijkstra, reconstructPath } from "../algorithms/graph.mjs";
+
+//#region src/networking/simulation.ts
+const primaryIp = (doc, deviceId) => doc.devices.find((d) => d.id === deviceId)?.interfaces.flatMap((i) => i.addresses ?? [])[0]?.split("/")[0] ?? deviceId;
+function createPacket(doc, from, to, protocol = "icmp") {
+	const sourceIp = primaryIp(doc, from);
+	const destinationIp = primaryIp(doc, to);
+	return {
+		id: `${protocol}-${from}-${to}`,
+		from,
+		to,
+		bytes: protocol === "http" ? 428 : 84,
+		layers: [
+			{
+				kind: "application",
+				protocol: protocol === "http" ? "HTTP" : "Ping",
+				summary: protocol === "http" ? "GET / HTTP/1.1" : "Echo request"
+			},
+			{
+				kind: "transport",
+				protocol: protocol === "http" ? "TCP" : "ICMP",
+				summary: protocol === "http" ? "49152 → 80" : "type 8, code 0",
+				fields: protocol === "http" ? {
+					sourcePort: 49152,
+					destinationPort: 80
+				} : { type: 8 }
+			},
+			{
+				kind: "network",
+				protocol: "IPv4",
+				summary: `${sourceIp} → ${destinationIp}`,
+				fields: {
+					source: sourceIp,
+					destination: destinationIp,
+					ttl: 64
+				}
+			},
+			{
+				kind: "data-link",
+				protocol: "Ethernet",
+				summary: "next-hop frame (MAC addresses change each routed hop)"
+			},
+			{
+				kind: "physical",
+				protocol: "Link",
+				summary: "bits transmitted over the selected medium"
+			}
+		]
+	};
+}
+/** Small deterministic packet trace: topology/path truth is real, protocol narration is explicit. */
+function simulatePacket(doc, from, to, protocol = "icmp") {
+	const packet = createPacket(doc, from, to, protocol);
+	const upLinks = doc.links.filter((link) => link.state !== "down");
+	const path = reconstructPath(dijkstra({
+		nodes: doc.devices.map((device, index) => ({
+			id: device.id,
+			x: index,
+			y: 0
+		})),
+		edges: upLinks.map((link) => ({
+			id: link.id,
+			from: link.a.deviceId,
+			to: link.b.deviceId,
+			weight: link.cost ?? link.latencyMs ?? 1
+		}))
+	}, from, to).previous, from, to);
+	const events = [{
+		type: "packet-created",
+		at: from,
+		packet,
+		message: `${protocol.toUpperCase()} packet created at ${from}.`
+	}];
+	if (!path.length) {
+		events.push({
+			type: "packet-dropped",
+			at: from,
+			reason: "unreachable",
+			message: `No available route from ${from} to ${to}.`
+		});
+		return {
+			delivered: false,
+			path: [],
+			totalLatencyMs: 0,
+			events
+		};
+	}
+	let totalLatencyMs = 0;
+	for (let i = 0; i < path.length - 1; i++) {
+		const at = path[i];
+		const next = path[i + 1];
+		const link = upLinks.find((candidate) => candidate.a.deviceId === at && candidate.b.deviceId === next || candidate.b.deviceId === at && candidate.a.deviceId === next);
+		if (!link) continue;
+		if (i === 0) {
+			events.push({
+				type: "arp-requested",
+				at,
+				target: next,
+				message: `${at} asks for the next hop's hardware address.`
+			});
+			events.push({
+				type: "arp-resolved",
+				at,
+				target: next,
+				message: `${next} answers; ${at} can now build the Ethernet frame.`
+			});
+		}
+		const device = doc.devices.find((d) => d.id === at);
+		if (device?.kind === "router") events.push({
+			type: "route-selected",
+			at,
+			next,
+			message: `${device.label} selects the lowest-cost available next hop: ${next}.`
+		});
+		events.push({
+			type: "frame-sent",
+			at,
+			linkId: link.id,
+			next,
+			packet,
+			message: `${at} sends the frame over ${link.label ?? link.id}.`
+		});
+		totalLatencyMs += link.latencyMs ?? 1;
+		events.push({
+			type: "frame-received",
+			at: next,
+			linkId: link.id,
+			from: at,
+			packet,
+			message: `${next} receives and inspects the frame.`
+		});
+	}
+	events.push({
+		type: "packet-delivered",
+		at: to,
+		packet,
+		message: `${packet.layers[0]?.protocol ?? "Packet"} delivered to ${to} in ${totalLatencyMs} ms simulated time.`
+	});
+	return {
+		delivered: true,
+		path,
+		totalLatencyMs,
+		events
+	};
+}
+
+//#endregion
+export { createPacket, simulatePacket };

package/dist/networking/subnet.mjs

@@ -0,0 +1,84 @@
+import { ipv4ToInt } from "./ip.mjs";
+
+//#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.
+*/
+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, sameNetwork, widestSharedPrefix };

package/dist/networking/switch.mjs

@@ -0,0 +1,155 @@
+//#region src/networking/switch.ts
+const linkUp = (port) => port.enabled && !!port.device;
+const portOf = (state, mac) => state.table.find((entry) => entry.mac === mac)?.port;
+const deviceName = (state, mac) => state.ports.find((port) => port.device?.mac === mac)?.device?.name ?? mac;
+/**
+* Send one frame in through `fromPort` and resolve what the switch does with it.
+*
+* Pure: returns the next state rather than mutating, so a lesson can step forward and back.
+*/
+function sendFrame(state, fromPort, dstMac) {
+	const events = [];
+	const ingress = state.ports.find((port) => port.id === fromPort);
+	const srcMac = ingress?.device?.mac ?? "";
+	if (!ingress || !ingress.enabled) {
+		events.push({
+			type: "drop",
+			reason: "port-down",
+			message: `Port ${fromPort} is disabled, so nothing can enter through it.`
+		});
+		return {
+			events,
+			next: state,
+			delivered: [],
+			flooded: false
+		};
+	}
+	if (!ingress.device) {
+		events.push({
+			type: "drop",
+			reason: "no-link",
+			message: `Port ${fromPort} has nothing plugged into it.`
+		});
+		return {
+			events,
+			next: state,
+			delivered: [],
+			flooded: false
+		};
+	}
+	events.push({
+		type: "ingress",
+		port: fromPort,
+		srcMac,
+		dstMac,
+		message: `A frame from ${ingress.device.name} arrives on port ${fromPort}, addressed to ${deviceName(state, dstMac)}.`
+	});
+	const known = state.table.find((entry) => entry.mac === srcMac);
+	const relearned = !!known && known.port !== fromPort;
+	const table = [...state.table.filter((entry) => entry.mac !== srcMac), {
+		mac: srcMac,
+		port: fromPort
+	}].sort((a, b) => a.port - b.port || a.mac.localeCompare(b.mac));
+	if (!known || relearned) events.push({
+		type: "learn",
+		mac: srcMac,
+		port: fromPort,
+		relearned,
+		message: relearned ? `${ingress.device.name} has moved. The table now says port ${fromPort}.` : `Learned: ${ingress.device.name} is reachable through port ${fromPort}.`
+	});
+	const next = {
+		ports: state.ports,
+		table
+	};
+	const target = portOf(next, dstMac);
+	if (target === fromPort) {
+		events.push({
+			type: "drop",
+			reason: "same-port",
+			message: `The destination is on the port the frame arrived from, so the switch does not send it back out.`
+		});
+		return {
+			events,
+			next,
+			delivered: [],
+			flooded: false
+		};
+	}
+	if (target !== void 0 && linkUp(state.ports.find((port) => port.id === target))) {
+		events.push({
+			type: "forward",
+			port: target,
+			message: `The table knows this address, so the frame goes out of port ${target} only. No other device sees it.`
+		});
+		return {
+			events,
+			next,
+			delivered: [target],
+			flooded: false
+		};
+	}
+	const flooded = next.ports.filter((port) => port.id !== fromPort && linkUp(port)).map((port) => port.id);
+	events.push({
+		type: "flood",
+		ports: flooded,
+		message: flooded.length ? `This address is not in the table, so the switch floods: out of every connected port except ${fromPort}.` : `This address is not in the table, and no other port has a link, so there is nowhere to flood.`
+	});
+	return {
+		events,
+		next,
+		delivered: flooded,
+		flooded: true
+	};
+}
+/** Toggle a port up or down. A port going down forgets what was learned through it. */
+function setPortEnabled(state, portId, enabled) {
+	return {
+		ports: state.ports.map((port) => port.id === portId ? {
+			...port,
+			enabled
+		} : port),
+		table: enabled ? state.table : state.table.filter((entry) => entry.port !== portId)
+	};
+}
+/** Clear the forwarding table, which returns the switch to the day it was unboxed. */
+const clearTable = (state) => ({
+	ports: state.ports,
+	table: []
+});
+const MACS = [
+	"AA:01",
+	"BB:02",
+	"CC:03",
+	"DD:04",
+	"EE:05",
+	"FF:06",
+	"11:07",
+	"22:08"
+];
+const NAMES = [
+	"Laptop",
+	"Desktop",
+	"Printer",
+	"Server",
+	"Phone",
+	"Camera",
+	"NAS",
+	"TV"
+];
+/** A switch with `size` ports, the first `connected` of them holding a device. */
+function makeSwitch(size = 8, connected = 4) {
+	return {
+		ports: Array.from({ length: size }, (_, index) => ({
+			id: index + 1,
+			enabled: true,
+			device: index < connected ? {
+				name: NAMES[index],
+				mac: MACS[index]
+			} : void 0
+		})),
+		table: []
+	};
+}
+
+//#endregion
+export { clearTable, linkUp, makeSwitch, sendFrame, setPortEnabled };