@classytic/labs 0.3.0 → 0.4.0

package/dist/networking/encapsulation.mjs

@@ -1,130 +0,0 @@
-//#region src/networking/encapsulation.ts
-/** Outermost last: this is the order the headers are ADDED going down the stack. */
-const HEADERS = [
-	{
-		kind: "application",
-		protocol: "HTTP",
-		bytes: 0,
-		addressing: null,
-		answers: "What is being asked for. This is the message itself, not a wrapper."
-	},
-	{
-		kind: "transport",
-		protocol: "TCP",
-		bytes: 20,
-		addressing: "port",
-		answers: "Which program on the machine, and where this piece fits in the stream."
-	},
-	{
-		kind: "network",
-		protocol: "IPv4",
-		bytes: 20,
-		addressing: "IP address",
-		answers: "Which machine, anywhere. Set once by the sender and carried the whole way."
-	},
-	{
-		kind: "data-link",
-		protocol: "Ethernet",
-		bytes: 18,
-		trailerBytes: 4,
-		addressing: "MAC address",
-		answers: "Which box on THIS wire takes it next. Replaced at every routed hop."
-	}
-];
-const OVERHEAD_BYTES = HEADERS.reduce((sum, header) => sum + header.bytes, 0);
-/** Wrap a payload in the first `depth` headers. Full depth is the frame that goes on the wire. */
-function encapsulate(payloadBytes, depth = HEADERS.length) {
-	const applied = HEADERS.slice(0, Math.max(0, Math.min(depth, HEADERS.length)));
-	const overheadBytes = applied.reduce((sum, header) => sum + header.bytes, 0);
-	const onWireBytes = payloadBytes + overheadBytes;
-	return {
-		payloadBytes,
-		headers: applied,
-		depth: applied.length,
-		onWireBytes,
-		overheadBytes,
-		overheadShare: onWireBytes === 0 ? 0 : overheadBytes / onWireBytes
-	};
-}
-/** How deep a device opens the frame before it can do its job. */
-const opensTo = (kind) => kind === "switch" ? "data-link" : kind === "router" ? "network" : "application";
-/**
-* Split a path at its layer-3 boundaries. A switch forwards a frame without terminating it, so it
-* does not start a new segment. A router does, because it builds a brand new frame for the next
-* wire. The number of segments is therefore routers + 1, however many switches are in the way.
-*/
-function segmentsOf(path) {
-	const boundaries = path.filter((node) => node.kind !== "switch");
-	const segments = [];
-	for (let index = 0; index < boundaries.length - 1; index++) {
-		const from = boundaries[index];
-		const to = boundaries[index + 1];
-		const through = path.slice(path.indexOf(from) + 1, path.indexOf(to)).filter((n) => n.kind === "switch");
-		segments.push({
-			from,
-			to,
-			fromMac: from.mac,
-			toMac: to.mac,
-			through
-		});
-	}
-	return segments;
-}
-function frameOn(segment, source, destination) {
-	const rebuilt = segment.from.kind === "router";
-	return {
-		segment,
-		mac: {
-			from: segment.fromMac,
-			to: segment.toMac
-		},
-		ip: {
-			from: source.ip ?? "",
-			to: destination.ip ?? ""
-		},
-		note: rebuilt ? `${segment.from.name} threw away the frame it received and built a new one for this wire. Same packet inside, new MAC addresses outside.` : `${segment.from.name} addresses the frame to ${segment.to.name}, the next box on this wire, not to the far end.`
-	};
-}
-/** Every frame the message travels in, end to end. */
-const journey = (path) => {
-	const source = path[0];
-	const destination = path[path.length - 1];
-	return segmentsOf(path).map((segment) => frameOn(segment, source, destination));
-};
-const DEFAULT_PATH = [
-	{
-		id: "laptop",
-		name: "Laptop",
-		kind: "host",
-		mac: "AA:01",
-		ip: "10.1.0.20"
-	},
-	{
-		id: "switch",
-		name: "Switch",
-		kind: "switch",
-		mac: "SW:00"
-	},
-	{
-		id: "r1",
-		name: "Router 1",
-		kind: "router",
-		mac: "BB:11"
-	},
-	{
-		id: "r2",
-		name: "Router 2",
-		kind: "router",
-		mac: "CC:22"
-	},
-	{
-		id: "server",
-		name: "Server",
-		kind: "host",
-		mac: "DD:33",
-		ip: "10.9.0.7"
-	}
-];
-
-//#endregion
-export { DEFAULT_PATH, HEADERS, encapsulate, journey, opensTo };

package/dist/networking/ip.d.mts

@@ -1,12 +0,0 @@
-import { NetworkRoute } from "./contract.mjs";
-
-//#region src/networking/ip.d.ts
-declare function ipv4ToInt(ip: string): number | undefined;
-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, ipv4ToInt, longestPrefixMatch, parseCidr };

package/dist/networking/ip.mjs

@@ -1,30 +0,0 @@
-//#region src/networking/ip.ts
-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);
-}
-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((a, b) => (parseCidr(b.prefix)?.prefix ?? -1) - (parseCidr(a.prefix)?.prefix ?? -1) || (a.metric ?? 0) - (b.metric ?? 0))[0];
-}
-
-//#endregion
-export { cidrContains, ipv4ToInt, longestPrefixMatch, parseCidr };

package/dist/networking/media.mjs

@@ -1,183 +0,0 @@
-//#region src/networking/media.ts
-/**
-* Real wire colours, so they are fixed rather than themed. A green wire is green in both themes
-* for the same reason the link LED is green: the colour IS the information, and a student matching
-* this against a cable in their hand needs it to agree.
-*/
-const WIRE_INK = {
-	"white-orange": "oklch(0.72 0.16 55)",
-	orange: "oklch(0.68 0.19 48)",
-	"white-green": "oklch(0.70 0.15 150)",
-	green: "oklch(0.58 0.17 148)",
-	"white-blue": "oklch(0.70 0.13 250)",
-	blue: "oklch(0.55 0.18 255)",
-	"white-brown": "oklch(0.62 0.07 60)",
-	brown: "oklch(0.45 0.08 55)"
-};
-/** A striped wire is the pale half of its pair. */
-const isStriped = (wire) => wire.startsWith("white-");
-const WIRE_LABEL = {
-	"white-orange": "white / orange",
-	orange: "orange",
-	"white-green": "white / green",
-	green: "green",
-	"white-blue": "white / blue",
-	blue: "blue",
-	"white-brown": "white / brown",
-	brown: "brown"
-};
-/** Pin 1 to pin 8, left to right with the clip facing away from you. */
-const PINOUTS = {
-	T568B: [
-		"white-orange",
-		"orange",
-		"white-green",
-		"blue",
-		"white-blue",
-		"green",
-		"white-brown",
-		"brown"
-	],
-	T568A: [
-		"white-green",
-		"green",
-		"white-orange",
-		"blue",
-		"white-blue",
-		"orange",
-		"white-brown",
-		"brown"
-	]
-};
-/** The four twisted pairs, by the colour they are named after. */
-const PAIRS = [
-	{
-		name: "orange",
-		wires: ["white-orange", "orange"]
-	},
-	{
-		name: "green",
-		wires: ["white-green", "green"]
-	},
-	{
-		name: "blue",
-		wires: ["white-blue", "blue"]
-	},
-	{
-		name: "brown",
-		wires: ["white-brown", "brown"]
-	}
-];
-/** Which pair a wire belongs to, 0-based, or -1 if the colour is not a pair member. */
-const pairOf = (wire) => PAIRS.findIndex((pair) => pair.wires.includes(wire));
-/** The pin positions (1-based) each pair occupies under a standard. */
-function pairPins(standard, pairName) {
-	const order = PINOUTS[standard];
-	const pair = PAIRS.find((item) => item.name === pairName);
-	if (!pair) return [];
-	return order.map((wire, index) => pair.wires.includes(wire) ? index + 1 : 0).filter((pin) => pin > 0);
-}
-/** Compare an attempt against a standard. Empty slots count as not yet placed, not as wrong. */
-function checkPinout(attempt, standard) {
-	const target = PINOUTS[standard];
-	const wrong = [];
-	let placed = 0;
-	target.forEach((wire, index) => {
-		const got = attempt[index];
-		if (!got) return;
-		placed++;
-		if (got !== wire) wrong.push(index + 1);
-	});
-	return {
-		correct: placed === 8 && wrong.length === 0,
-		wrong,
-		placed
-	};
-}
-/**
-* A cable with the same standard at both ends is straight-through; different ends make a crossover.
-* Modern gear auto-detects, which is worth saying, because it is why crossover cables have
-* essentially disappeared and why the distinction still appears in every exam.
-*/
-const cableKind = (endA, endB) => endA === endB ? "straight-through" : "crossover";
-const MEDIA = [
-	{
-		id: "copper",
-		label: "Twisted pair copper",
-		carrier: "a changing voltage along a wire",
-		maxMetres: 100,
-		typicalGbps: 1,
-		emiImmune: false,
-		broadcast: false,
-		note: "Cheap, and every device already has the socket. The 100 m limit is the reason wiring closets exist."
-	},
-	{
-		id: "fibre",
-		label: "Optical fibre",
-		carrier: "pulses of light in a glass core",
-		maxMetres: 4e4,
-		typicalGbps: 10,
-		emiImmune: true,
-		broadcast: false,
-		note: "Light carries no current, so it ignores electrical noise entirely and can cross a city."
-	},
-	{
-		id: "radio",
-		label: "Radio (Wi-Fi)",
-		carrier: "radio waves through open air",
-		maxMetres: 40,
-		typicalGbps: 1,
-		emiImmune: false,
-		broadcast: true,
-		note: "No cable at all, and the medium is shared: everyone in range competes for it and can hear it."
-	}
-];
-const SCENARIOS = [
-	{
-		id: "desk",
-		need: "A desktop to the switch in the same room",
-		metres: 15,
-		noisy: false,
-		mustMove: false,
-		best: "copper",
-		why: "Short, fixed and cheap. Copper is already on both ends and there is nothing to gain by paying for anything else."
-	},
-	{
-		id: "buildings",
-		need: "Between two buildings 800 m apart",
-		metres: 800,
-		noisy: false,
-		mustMove: false,
-		best: "fibre",
-		why: "Copper stops working at about 100 m. Distance alone rules it out before any other argument."
-	},
-	{
-		id: "factory",
-		need: "Across a factory floor beside large motors",
-		metres: 60,
-		noisy: true,
-		mustMove: false,
-		best: "fibre",
-		why: "The distance suits copper, but motors throw electrical noise into it. Light carries no current, so the interference cannot reach the signal."
-	},
-	{
-		id: "phone",
-		need: "A phone carried around a café",
-		metres: 20,
-		noisy: false,
-		mustMove: true,
-		best: "radio",
-		why: "Nothing that moves can stay plugged in. That decides it before speed or cost are even considered."
-	}
-];
-/** Is a medium usable for a scenario at all, and if not, why not. */
-function ruleOut(medium, scenario) {
-	if (scenario.mustMove && !scenario.metres) return null;
-	if (scenario.mustMove && medium.id !== "radio") return "a moving device cannot stay plugged into a cable";
-	if (scenario.metres > medium.maxMetres) return `the run is longer than ${medium.maxMetres} m`;
-	if (scenario.noisy && !medium.emiImmune) return "electrical noise from the machinery would corrupt the signal";
-	return null;
-}
-
-//#endregion
-export { MEDIA, PAIRS, PINOUTS, SCENARIOS, WIRE_INK, WIRE_LABEL, cableKind, checkPinout, isStriped, pairOf, pairPins, ruleOut };

package/dist/networking/presets.d.mts

@@ -1,7 +0,0 @@
-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

@@ -1,302 +0,0 @@
-//#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

@@ -1,8 +0,0 @@
-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 };