feat: Ethernet frames (#78)

Author: MegaRedHand

package-lock.json

@@ -1,17 +1,17 @@
 {
   "dependencies": {
     "@pixi/filter-outline": "^5.2.0",
+    "@tsxper/crc32": "^2.1.3",
     "pixi-viewport": "^5.0.3",
     "pixi.js": "^8.4.1"
   },
   "name": "netsim",
   "version": "1.0.0",
   "private": true,
   "devDependencies": {
-    "@eslint/js": "^9.14.0",
+    "@eslint/js": "9.18.0",
     "@types/eslint__js": "^8.42.3",
     "@types/jest": "^29.5.14",
-    "@types/pixi.js": "^5.0.0",
     "css-loader": "7.1.2",
     "eslint": "^9.14.0",
     "html-webpack-plugin": "^5.6.0",

package.json

@@ -0,0 +1,122 @@
+import { CRC32 } from "@tsxper/crc32";
+
+// From https://en.wikipedia.org/wiki/EtherType
+export const IP_PROTOCOL_TYPE = 0x0800;
+export const ARP_PROTOCOL_TYPE = 0x0806;
+export const IPV6_PROTOCOL_TYPE = 0x86dd;
+
+/// Medium Access Control (MAC) address
+export class MacAddress {
+  // 6 bytes
+  octets: Uint8Array;
+
+  constructor(octets: Uint8Array) {
+    if (octets.length !== 6) {
+      throw new Error("Invalid MAC address");
+    }
+    this.octets = octets;
+  }
+
+  // Parse MAC address from a string representation (00:1b:63:84:45:e6)
+  static parse(addrString: string): MacAddress {
+    const octets = new Uint8Array(6);
+    addrString.split(":").forEach((octet, i) => {
+      const octetInt = parseInt(octet, 16);
+      if (isNaN(octetInt) || octetInt < 0 || octetInt > 255) {
+        throw new Error(`Invalid MAC address: ${addrString}`);
+      }
+      octets[i] = octetInt;
+    });
+    return new this(octets);
+  }
+
+  // Turn to string
+  toString(): string {
+    return Array.from(this.octets)
+      .map((d) => d.toString(16))
+      .join(":");
+  }
+
+  // Check if two MAC addresses are equal.
+  equals(other: MacAddress): boolean {
+    return this.octets.every((octet, index) => octet === other.octets[index]);
+  }
+}
+
+const crc32 = new CRC32();
+
+const MINIMUM_PAYLOAD_SIZE = 46;
+
+export class EthernetFrame {
+  // Info taken from Computer Networking: A Top-Down Approach
+
+  // 8 bytes
+  // 7 bytes preamble and 1 byte start of frame delimiter
+  // Used to synchronize the communication
+  // TODO: should we mention this somewhere?
+  // readonly preamble = new Uint8Array([
+  //   0b10101010, 0b10101010, 0b10101010, 0b10101010, 0b10101010, 0b10101010,
+  //   0b10101010, 0b10101011,
+  // ]);
+
+  // 6 bytes
+  // Destination MAC address
+  destination: MacAddress;
+  // 6 bytes
+  // Source MAC address
+  source: MacAddress;
+  // 2 bytes
+  // The payload's type
+  type: number;
+  // 46-1500 bytes
+  // If the payload is smaller than 46 bytes, it is padded.
+  // TODO: make this an interface
+  // The payload
+  payload: FramePayload;
+  // 4 bytes
+  // Cyclic Redundancy Check (CRC)
+  get crc(): number {
+    // Computation doesn't include preamble
+    const frameBytes = this.toBytes({
+      withChecksum: false,
+    });
+    return crc32.forBytes(frameBytes);
+  }
+
+  constructor(
+    source: MacAddress,
+    destination: MacAddress,
+    payload: FramePayload,
+  ) {
+    this.destination = destination;
+    this.source = source;
+    this.type = payload.type();
+    this.payload = payload;
+  }
+
+  toBytes({ withChecksum = true }: { withChecksum?: boolean } = {}) {
+    let checksum: number[] = [];
+    if (withChecksum) {
+      const crc = this.crc;
+      checksum = [crc & 0xff, (crc >> 8) & 0xff, (crc >> 16) & 0xff, crc >> 24];
+    }
+    let payload = this.payload.toBytes();
+    if (payload.length < MINIMUM_PAYLOAD_SIZE) {
+      const padding = new Array(MINIMUM_PAYLOAD_SIZE - payload.length);
+      payload = Uint8Array.from([...payload, ...padding]);
+    }
+    return Uint8Array.from([
+      ...this.destination.octets,
+      ...this.source.octets,
+      this.type >> 8,
+      this.type & 0xff,
+      ...payload,
+      ...checksum,
+    ]);
+  }
+}
+
+export interface FramePayload {
+  toBytes(): Uint8Array;
+  type(): number;
+}

src/packets/ethernet.ts

@@ -1,3 +1,5 @@
+import { FramePayload, IP_PROTOCOL_TYPE } from "./ethernet";
+
 export const ICMP_PROTOCOL_NUMBER = 1;
 export const TCP_PROTOCOL_NUMBER = 6;
 export const UDP_PROTOCOL_NUMBER = 17;
@@ -11,7 +13,10 @@ export class EmptyPayload implements IpPayload {
   }
 }
 
+/// Internet Protocol (IP) address
+// TODO: support IPv6?
 export class IpAddress {
+  // 4 bytes
   octets: Uint8Array;
 
   constructor(octets: Uint8Array) {
@@ -117,7 +122,7 @@ export interface IpPayload {
 //  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 //  |                    Options                    |    Padding    |
 //  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-export class IPv4Packet {
+export class IPv4Packet implements FramePayload {
   // IP version field
   // 4 bits
   readonly version = 4;
@@ -189,7 +194,7 @@ export class IPv4Packet {
   }: {
     withChecksum?: boolean;
     withPayload?: boolean;
-  }) {
+  } = {}) {
     let checksum = 0;
     if (withChecksum) {
       checksum = this.headerChecksum;
@@ -228,6 +233,10 @@ export class IPv4Packet {
     const result = computeIpChecksum(octets);
     return result === 0;
   }
+
+  type(): number {
+    return IP_PROTOCOL_TYPE;
+  }
 }
 
 export function computeIpChecksum(octets: Uint8Array): number {