@classytic/stage 0.3.0 → 0.4.0

package/dist/networking/topology/presets.mjs

@@ -0,0 +1,302 @@
+//#region src/networking/topology/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/topology/simulation.d.mts

@@ -0,0 +1,8 @@
+import { NetworkDoc, NetworkPacket, NetworkTrace } from "./contract.mjs";
+
+//#region src/networking/topology/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/topology/simulation.mjs

@@ -0,0 +1,179 @@
+//#region src/networking/topology/simulation.ts
+function shortestPaths(nodes, edges, source) {
+	const distances = Object.fromEntries(nodes.map((id) => [id, id === source ? 0 : Infinity]));
+	const previous = {};
+	const remaining = new Set(nodes);
+	while (remaining.size) {
+		const current = [...remaining].reduce((best, id) => (distances[id] ?? Infinity) < (distances[best] ?? Infinity) ? id : best);
+		remaining.delete(current);
+		for (const edge of edges) {
+			const next = edge.from === current ? edge.to : edge.to === current ? edge.from : void 0;
+			if (!next || !remaining.has(next)) continue;
+			const candidate = (distances[current] ?? Infinity) + edge.weight;
+			if (candidate < (distances[next] ?? Infinity)) {
+				distances[next] = candidate;
+				previous[next] = current;
+			}
+		}
+	}
+	return {
+		distances,
+		previous
+	};
+}
+function reconstructPath(previous, from, to) {
+	const path = [];
+	let current = to;
+	while (current) {
+		path.unshift(current);
+		if (current === from) return path;
+		current = previous[current];
+	}
+	return [];
+}
+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 graph = {
+		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
+		}))
+	};
+	const path = reconstructPath(shortestPaths(graph.nodes.map((node) => node.id), graph.edges, from).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/wireless.d.mts

@@ -0,0 +1,11 @@
+//#region src/networking/wireless.d.ts
+interface ContentionResult {
+  readonly offered: number;
+  readonly contenders: number;
+  readonly collisionPercent: number;
+  readonly usefulPercent: number;
+  readonly hiddenPenalty: number;
+}
+declare function simulateContention(stations: number, backoffSlots: number, hidden: boolean): ContentionResult;
+//#endregion
+export { ContentionResult, simulateContention };

package/dist/networking/wireless.mjs

@@ -0,0 +1,17 @@
+//#region src/networking/wireless.ts
+function simulateContention(stations, backoffSlots, hidden) {
+	const contenders = Math.max(1, Math.round(stations));
+	const baseCollision = contenders === 1 ? 0 : 1 - Math.pow(1 - 1 / Math.max(1, Math.round(backoffSlots)), contenders - 1);
+	const hiddenPenalty = hidden && contenders > 1 ? Math.min(.45, (contenders - 1) * .07) : 0;
+	const collision = Math.min(.92, baseCollision + hiddenPenalty);
+	return {
+		offered: contenders,
+		contenders,
+		collisionPercent: Math.round(collision * 100),
+		usefulPercent: Math.round((1 - collision) * 100),
+		hiddenPenalty: Math.round(hiddenPenalty * 100)
+	};
+}
+
+//#endregion
+export { simulateContention };