Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

networking: add a tunnel mode that follows the host's route

Botef93c2970de8
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift
index 5af48b10..28ad0f27 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift
@@ -212,7 +212,7 @@ struct VPhoneVirtualMachineConfigCommand: ParsableCommand {
@Argument(help: "VM name") var name: String?
@Option(name: .shortAndLong, help: "CPU cores") var cpu: UInt?
@Option(name: .shortAndLong, help: "Memory (MB)") var memory: UInt64?
- @Option(name: [.customShort("n"), .long], help: "Network mode: nat | bridged | none") var network: String?
+ @Option(name: [.customShort("n"), .long], help: "Network mode: nat | bridged | tunnel | none") var network: String?
@Option(name: .long, help: "Host interface to bridge (bridged mode; auto-picks first if omitted)")
var bridgeInterface: String?
@@ -240,11 +240,12 @@ struct VPhoneVirtualMachineConfigCommand: ParsableCommand {
switch s.lowercased() {
case "nat": return .nat
case "bridged": return .bridged
+ case "tunnel": return .tunnel
case "none", "off": return .off
case "hostonly", "host-only":
- throw ValidationError("Host-only networking is not supported. Use nat, bridged, or none.")
+ throw ValidationError("Host-only networking is not supported. Use nat, bridged, tunnel, or none.")
default:
- throw ValidationError("Unknown network mode '\(s)'. Use nat, bridged, or none.")
+ throw ValidationError("Unknown network mode '\(s)'. Use nat, bridged, tunnel, or none.")
}
}
}
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
index 22d19dd4..9923b4e7 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
@@ -13,6 +13,9 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {
private var serialOutputReadHandle: FileHandle?
/// Synthetic battery source for runtime charge/connectivity updates.
private var batterySource: AnyObject?
+ /// The in-process network backing `.tunnel` mode; nil for every other mode.
+ /// Held because the sockets live only as long as this reference does.
+ private var userspaceNetwork: VPhoneUserspaceNetwork?
struct Options {
var configURL: URL
@@ -169,12 +172,14 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {
let attachment = try VZDiskImageStorageDeviceAttachment(url: options.diskURL, readOnly: false)
config.storageDevices = [VZVirtioBlockDeviceConfiguration(attachment: attachment)]
- // Network (mode + MAC from the bundle manifest; nat/bridged/none)
- if let net = try VPhoneNetworking.makeNetworkDevice(manifest.networkConfig) {
- config.networkDevices = [net]
+ // Network (mode + MAC from the bundle manifest; nat/bridged/tunnel/none)
+ let (networkDevice, networkBackend) = try VPhoneNetworking.makeNetworkDevice(manifest.networkConfig)
+ if let networkDevice {
+ config.networkDevices = [networkDevice]
} else {
config.networkDevices = []
}
+ userspaceNetwork = networkBackend
// Serial port (PL011 UART - pipes for input/output with boot detection)
if let serialPort = Dynamic._VZPL011SerialPortConfiguration().asObject
@@ -363,6 +368,9 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {
Dynamic(opts)._setStopInIBootStage1(false)
Dynamic(opts)._setStopInIBootStage2(false)
print("[vphone] Starting\(forceDFU ? " DFU" : "")...")
+ // Start draining before the framework touches the device, or the guest's
+ // first DHCP request is sent into a socket nobody is reading.
+ userspaceNetwork?.start()
nonisolated(unsafe) let vm = virtualMachine
try await vm.start(options: opts)
if forceDFU {
diff --git a/VPhoneKit/VPhoneCoreKit/Network/VPhoneInternetProtocol.swift b/VPhoneKit/VPhoneCoreKit/Network/VPhoneInternetProtocol.swift
new file mode 100644
index 00000000..f04221e4
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKit/Network/VPhoneInternetProtocol.swift
@@ -0,0 +1,482 @@
+import Foundation
+
+// MARK: - Addresses
+
+/// An IPv4 address held in host order. Deliberately not `Network`/`NWAddress`:
+/// this type only has to round-trip through byte arrays.
+public struct VPhoneIPv4Address: Sendable, Equatable, Hashable, CustomStringConvertible {
+ public var raw: UInt32
+
+ public init(_ raw: UInt32) { self.raw = raw }
+
+ public init(_ a: UInt8, _ b: UInt8, _ c: UInt8, _ d: UInt8) {
+ raw = UInt32(a) << 24 | UInt32(b) << 16 | UInt32(c) << 8 | UInt32(d)
+ }
+
+ public var bytes: [UInt8] {
+ [UInt8(truncatingIfNeeded: raw >> 24), UInt8(truncatingIfNeeded: raw >> 16),
+ UInt8(truncatingIfNeeded: raw >> 8), UInt8(truncatingIfNeeded: raw)]
+ }
+
+ public var description: String { bytes.map(String.init).joined(separator: ".") }
+
+ /// `255.255.255.255`
+ public static let broadcast = VPhoneIPv4Address(255, 255, 255, 255)
+ /// `0.0.0.0`
+ public static let any = VPhoneIPv4Address(0, 0, 0, 0)
+}
+
+// MARK: - Configuration
+
+/// Addressing for the userspace network.
+///
+/// The subnet deliberately differs from vmnet's `192.168.64.0/24` so `tunnel`
+/// and `nat` can coexist on one host without their DHCP servers answering each
+/// other. It also sits inside `192.168.0.0/16`, which every mainstream VPN keeps
+/// out of its tunnel.
+public struct VPhoneUserspaceNetworkConfiguration: Sendable, Equatable {
+ /// The address the host answers ARP for, serves DHCP from, and later
+ /// appears to be the DNS resolver. Also the DHCP `server-id`.
+ public var hostAddress: VPhoneIPv4Address
+ /// The lease handed to the guest. One address is enough: one guest per VM.
+ public var guestAddress: VPhoneIPv4Address
+ /// Advertised through DHCP option 26, and the ceiling for everything we send
+ /// the guest.
+ ///
+ /// 1500, not the 1280 the v1.x tunnel work used. That 1280 was chosen so the
+ /// guest's segments would fit a VPN tunnel without fragmenting -- but the
+ /// guest's frames reach the host over a socket pair and leave through a host
+ /// socket whose kernel does its own segmentation, so the tunnel's MTU never
+ /// applied here. Copying it had a real cost: QUIC sends 1280-byte payloads,
+ /// which with UDP and IP headers come to 1308, past the advertised 1280. Every
+ /// one of them was too big to hand the guest, and Safari -- which prefers
+ /// HTTP/3 -- spent its time retrying rather than loading.
+ public var mtu: Int
+
+ public static let `default` = VPhoneUserspaceNetworkConfiguration(
+ hostAddress: VPhoneIPv4Address(192, 168, 127, 1),
+ guestAddress: VPhoneIPv4Address(192, 168, 127, 3),
+ mtu: 1500,
+ )
+
+ public init(hostAddress: VPhoneIPv4Address, guestAddress: VPhoneIPv4Address, mtu: Int = 1500) {
+ self.hostAddress = hostAddress
+ self.guestAddress = guestAddress
+ self.mtu = mtu
+ }
+}
+
+/// A 48-bit Ethernet address. The host side uses a locally administered address
+/// of its own; the guest's is learned from the first frame it sends, because
+/// Virtualization.framework assigns the MAC and never tells us what it picked.
+public struct VPhoneMACAddress: Sendable, Equatable, Hashable {
+ public var bytes: [UInt8]
+
+ public init(_ bytes: [UInt8]) { self.bytes = bytes }
+
+ /// The gateway's address. Locally administered, unicast, and unlikely to
+ /// collide with anything.
+ public static let gateway = VPhoneMACAddress([0x02, 0x00, 0x00, 0x00, 0x00, 0x01])
+
+ var hexString: String { bytes.map { String(format: "%02x", $0) }.joined(separator: ":") }
+}
+
+// MARK: - Checksums
+
+enum VPhoneInternetChecksum {
+ /// RFC 1071 internet checksum. `seed` carries a pseudo-header for UDP/TCP.
+ static func compute(_ bytes: [UInt8], seed: UInt32 = 0) -> UInt16 {
+ var sum = seed
+ var index = 0
+ while index + 1 < bytes.count {
+ sum += UInt32(bytes[index]) << 8 | UInt32(bytes[index + 1])
+ index += 2
+ }
+ if index < bytes.count { sum += UInt32(bytes[index]) << 8 }
+ while sum >> 16 != 0 { sum = (sum & 0xFFFF) + (sum >> 16) }
+ return UInt16(~sum & 0xFFFF)
+ }
+}
+
+// MARK: - Ethernet
+
+enum VPhoneEtherType: UInt16 {
+ case ipv4 = 0x0800
+ case arp = 0x0806
+}
+
+struct VPhoneEthernetFrame {
+ var destination: VPhoneMACAddress
+ var source: VPhoneMACAddress
+ var etherType: UInt16
+ var payload: [UInt8]
+
+ init(destination: VPhoneMACAddress, source: VPhoneMACAddress, etherType: VPhoneEtherType, payload: [UInt8]) {
+ self.destination = destination
+ self.source = source
+ self.etherType = etherType.rawValue
+ self.payload = payload
+ }
+
+ var bytes: [UInt8] {
+ destination.bytes + source.bytes + [UInt8(etherType >> 8), UInt8(etherType & 0xFF)] + payload
+ }
+
+ /// Parse, or nil if the frame is malformed or too short to address.
+ init?(bytes: [UInt8]) {
+ guard bytes.count >= 14 else { return nil }
+ destination = VPhoneMACAddress(Array(bytes[0 ..< 6]))
+ source = VPhoneMACAddress(Array(bytes[6 ..< 12]))
+ etherType = UInt16(bytes[12]) << 8 | UInt16(bytes[13])
+ payload = Array(bytes[14...])
+ }
+}
+
+// MARK: - IPv4
+
+enum VPhoneIPProtocol: UInt8 {
+ case icmp = 1
+ case tcp = 6
+ case udp = 17
+}
+
+struct VPhoneIPv4Packet {
+ var source: VPhoneIPv4Address
+ var destination: VPhoneIPv4Address
+ var proto: UInt8
+ var ttl: UInt8
+ var identification: UInt16
+ var payload: [UInt8]
+
+ /// Fragment offset in eight-byte units. Non-zero only in fragments after the
+ /// first.
+ var fragmentOffset: UInt16 = 0
+ /// Set on every fragment but the last.
+ var moreFragments = false
+
+ init(
+ source: VPhoneIPv4Address,
+ destination: VPhoneIPv4Address,
+ proto: VPhoneIPProtocol,
+ ttl: UInt8 = 64,
+ identification: UInt16 = 0,
+ payload: [UInt8],
+ ) {
+ self.source = source
+ self.destination = destination
+ self.proto = proto.rawValue
+ self.ttl = ttl
+ self.identification = identification
+ self.payload = payload
+ }
+
+ /// Split so every fragment's IP datagram fits `mtu`.
+ ///
+ /// Only the sending side implements this: the guest reassembles, and it is
+ /// the only side that has to. Slices are multiples of eight because the
+ /// header's offset field counts eight-byte units, and the last fragment
+ /// carries the payload's remainder however it falls.
+ func fragmented(toFit mtu: Int) -> [[UInt8]] {
+ let headerSize = 20
+ guard totalLength > mtu, !payload.isEmpty else { return [bytes] }
+ let maxSlice = ((mtu - headerSize) / 8) * 8
+ guard maxSlice > 0 else { return [bytes] }
+
+ let identifier = identification == 0 ? UInt16.random(in: 1 ... UInt16.max) : identification
+ var fragments: [[UInt8]] = []
+ var offset = 0
+ while offset < payload.count {
+ let end = min(offset + maxSlice, payload.count)
+ let isLast = end >= payload.count
+ var fragment = VPhoneIPv4Packet(
+ source: source,
+ destination: destination,
+ proto: VPhoneIPProtocol(rawValue: proto) ?? .icmp,
+ ttl: ttl,
+ identification: identifier,
+ payload: Array(payload[offset ..< end]),
+ )
+ fragment.fragmentOffset = UInt16(offset / 8)
+ fragment.moreFragments = !isLast
+ fragments.append(fragment.bytes)
+ offset = end
+ }
+ return fragments
+ }
+
+ var totalLength: Int { 20 + payload.count }
+
+ /// True when this is one piece of a larger datagram. Nothing here reassembles,
+ /// so such a packet cannot be handled and has to be dropped rather than
+ /// misread: only the first fragment even carries the transport header.
+ var isFragment: Bool { moreFragments || fragmentOffset != 0 }
+
+ /// Bit 0x2000 marks a fragment that is not the last; bits 0..12 hold the
+ /// offset in eight-byte units. A single unfragmented packet leaves both zero.
+ private var flagsAndFragmentOffset: UInt16 {
+ (moreFragments ? 0x2000 : 0) | (fragmentOffset & 0x1FFF)
+ }
+
+ var bytes: [UInt8] {
+ var header: [UInt8] = [
+ 0x45, 0x00,
+ UInt8(truncatingIfNeeded: totalLength >> 8), UInt8(truncatingIfNeeded: totalLength),
+ UInt8(truncatingIfNeeded: identification >> 8), UInt8(truncatingIfNeeded: identification),
+ UInt8((flagsAndFragmentOffset) >> 8), UInt8(truncatingIfNeeded: flagsAndFragmentOffset),
+ ttl, proto,
+ ]
+ header += [0, 0] // checksum placeholder
+ header += source.bytes + destination.bytes
+ let sum = VPhoneInternetChecksum.compute(header)
+ header[10] = UInt8(sum >> 8)
+ header[11] = UInt8(sum & 0xFF)
+ return header + payload
+ }
+
+ /// Parse, or nil for anything we cannot answer: fragments, options, IPv6.
+ init?(bytes: [UInt8]) {
+ guard bytes.count >= 20, bytes[0] >> 4 == 4 else { return nil }
+ let headerLength = Int(bytes[0] & 0x0F) * 4
+ guard headerLength >= 20, bytes.count >= headerLength else { return nil }
+ // Fragments are parsed rather than refused, so that the fields survive a
+ // round trip and the caller decides. Carrying one is not something this
+ // side can do -- nothing here reassembles -- so whoever handles the
+ // packet has to drop a fragment it cannot complete.
+ fragmentOffset = UInt16(bytes[6] & 0x1F) << 8 | UInt16(bytes[7])
+ moreFragments = bytes[6] & 0x20 != 0
+ let declared = Int(UInt16(bytes[2]) << 8 | UInt16(bytes[3]))
+ guard declared >= headerLength, bytes.count >= declared else { return nil }
+
+ source = VPhoneIPv4Address(UInt32(bytes[12]) << 24 | UInt32(bytes[13]) << 16 | UInt32(bytes[14]) << 8 | UInt32(bytes[15]))
+ destination = VPhoneIPv4Address(UInt32(bytes[16]) << 24 | UInt32(bytes[17]) << 16 | UInt32(bytes[18]) << 8 | UInt32(bytes[19]))
+ proto = bytes[9]
+ ttl = bytes[8]
+ identification = UInt16(bytes[4]) << 8 | UInt16(bytes[5])
+ payload = Array(bytes[headerLength ..< declared])
+ }
+}
+
+// MARK: - UDP
+
+struct VPhoneUDPDatagram {
+ var sourcePort: UInt16
+ var destinationPort: UInt16
+ var payload: [UInt8]
+
+ init(sourcePort: UInt16, destinationPort: UInt16, payload: [UInt8]) {
+ self.sourcePort = sourcePort
+ self.destinationPort = destinationPort
+ self.payload = payload
+ }
+
+ func bytes(source: VPhoneIPv4Address, destination: VPhoneIPv4Address) -> [UInt8] {
+ let length = 8 + payload.count
+ var header: [UInt8] = [
+ UInt8(sourcePort >> 8), UInt8(truncatingIfNeeded: sourcePort),
+ UInt8(destinationPort >> 8), UInt8(truncatingIfNeeded: destinationPort),
+ UInt8(truncatingIfNeeded: length >> 8), UInt8(truncatingIfNeeded: length),
+ 0, 0,
+ ]
+ let datagram = header + payload
+ let sum = VPhoneInternetChecksum.compute(
+ datagram,
+ seed: VPhoneInternetChecksum.pseudoHeader(source: source, destination: destination, proto: 17, length: length),
+ )
+ // A computed zero is transmitted as all ones (RFC 768).
+ header[6] = UInt8((sum == 0 ? 0xFFFF : sum) >> 8)
+ header[7] = UInt8((sum == 0 ? 0xFFFF : sum) & 0xFF)
+ return header + payload
+ }
+
+ init?(bytes: [UInt8]) {
+ guard bytes.count >= 8 else { return nil }
+ sourcePort = UInt16(bytes[0]) << 8 | UInt16(bytes[1])
+ destinationPort = UInt16(bytes[2]) << 8 | UInt16(bytes[3])
+ let length = Int(UInt16(bytes[4]) << 8 | UInt16(bytes[5]))
+ guard length >= 8, bytes.count >= length else { return nil }
+ payload = Array(bytes[8 ..< length])
+ }
+}
+
+extension VPhoneInternetChecksum {
+ /// The UDP/TCP pseudo-header, folded into the running sum.
+ static func pseudoHeader(source: VPhoneIPv4Address, destination: VPhoneIPv4Address, proto: UInt8, length: Int) -> UInt32 {
+ var sum: UInt32 = 0
+ let sourceBytes = source.bytes
+ let destinationBytes = destination.bytes
+ for index in stride(from: 0, to: 4, by: 2) {
+ sum += UInt32(sourceBytes[index]) << 8 | UInt32(sourceBytes[index + 1])
+ sum += UInt32(destinationBytes[index]) << 8 | UInt32(destinationBytes[index + 1])
+ }
+ sum += UInt32(proto)
+ sum += UInt32(length)
+ return sum
+ }
+}
+
+// MARK: - TCP
+
+/// The control bits this stack looks at, as they appear in the segment's flags
+/// byte.
+enum VPhoneTCPFlags {
+ static let fin: UInt8 = 0x01
+ static let syn: UInt8 = 0x02
+ static let rst: UInt8 = 0x04
+ static let psh: UInt8 = 0x08
+ static let ack: UInt8 = 0x10
+}
+
+/// A TCP segment, header and payload.
+///
+/// Only the fields this stack needs. Incoming options are parsed past but not
+/// retained: a guest is free to send SACK-permitted or a timestamp, and the
+/// correct response from a peer that never offered them is to ignore them —
+/// which is what discarding them amounts to. We never send options.
+struct VPhoneTCPSegment {
+ var sourcePort: UInt16
+ var destinationPort: UInt16
+ var sequenceNumber: UInt32
+ var acknowledgmentNumber: UInt32
+ var flags: UInt8
+ var windowSize: UInt16
+ var payload: [UInt8]
+ /// The peer's maximum segment size, when its SYN carried option 2.
+ ///
+ /// Not optional by accident: without it we have to assume RFC 1122's default
+ /// of 536, which is safe but slow. With it we know how large a segment the
+ /// guest will accept, which is the whole reason this stack can send anything
+ /// larger than one MTU at a time.
+ var maximumSegmentSize: Int?
+ /// Our own MSS, advertised on SYN-ACK. Set when we build the handshake.
+ var advertisedMSS: Int?
+ /// The peer's window scale, when its SYN carried option 3.
+ ///
+ /// Window scaling exists because a 16-bit field cannot express a window large
+ /// enough for a fat, long path. Both ends must offer it or neither uses it,
+ /// so a peer that finds no option 3 in our SYN-ACK has to keep its receive
+ /// window under 65535 -- and that ceiling, divided by the round-trip time, is
+ /// the most this connection can ever carry.
+ var windowScale: Int?
+ /// Our own window scale, advertised on SYN-ACK so the guest may use a large
+ /// window. Only set when the guest offered one too.
+ var advertisedWindowScale: Int?
+
+ init(
+ sourcePort: UInt16,
+ destinationPort: UInt16,
+ sequenceNumber: UInt32,
+ acknowledgmentNumber: UInt32,
+ flags: UInt8,
+ windowSize: UInt16,
+ payload: [UInt8] = [],
+ maximumSegmentSize: Int? = nil,
+ advertisedMSS: Int? = nil,
+ windowScale: Int? = nil,
+ advertisedWindowScale: Int? = nil,
+ ) {
+ self.sourcePort = sourcePort
+ self.destinationPort = destinationPort
+ self.sequenceNumber = sequenceNumber
+ self.acknowledgmentNumber = acknowledgmentNumber
+ self.flags = flags
+ self.windowSize = windowSize
+ self.payload = payload
+ self.maximumSegmentSize = maximumSegmentSize
+ self.advertisedMSS = advertisedMSS
+ self.windowScale = windowScale
+ self.advertisedWindowScale = advertisedWindowScale
+ }
+
+ var hasSYN: Bool { flags & VPhoneTCPFlags.syn != 0 }
+ var hasACK: Bool { flags & VPhoneTCPFlags.ack != 0 }
+ var hasFIN: Bool { flags & VPhoneTCPFlags.fin != 0 }
+ var hasRST: Bool { flags & VPhoneTCPFlags.rst != 0 }
+
+ /// Sequence space this segment occupies. A SYN or FIN each cost one, which
+ /// matters when acknowledging them.
+ var sequenceLength: UInt32 {
+ UInt32(payload.count) + (hasSYN ? 1 : 0) + (hasFIN ? 1 : 0)
+ }
+
+ func bytes(source: VPhoneIPv4Address, destination: VPhoneIPv4Address) -> [UInt8] {
+ // Option 2 (maximum segment size) and option 3 (window scale), each only
+ // when asked. The list is padded to a 32-bit boundary, which is what the
+ // data offset counts in.
+ var options: [UInt8] = []
+ if let advertisedMSS {
+ options += [2, 4, UInt8(truncatingIfNeeded: advertisedMSS >> 8), UInt8(truncatingIfNeeded: advertisedMSS)]
+ }
+ if let advertisedWindowScale {
+ options += [3, 3, UInt8(truncatingIfNeeded: advertisedWindowScale)]
+ while options.count % 4 != 0 { options.append(1) } // NOP padding
+ }
+ let headerLength = 20 + options.count
+ var header: [UInt8] = [
+ UInt8(sourcePort >> 8), UInt8(truncatingIfNeeded: sourcePort),
+ UInt8(destinationPort >> 8), UInt8(truncatingIfNeeded: destinationPort),
+ UInt8(truncatingIfNeeded: sequenceNumber >> 24), UInt8(truncatingIfNeeded: sequenceNumber >> 16),
+ UInt8(truncatingIfNeeded: sequenceNumber >> 8), UInt8(truncatingIfNeeded: sequenceNumber),
+ UInt8(truncatingIfNeeded: acknowledgmentNumber >> 24), UInt8(truncatingIfNeeded: acknowledgmentNumber >> 16),
+ UInt8(truncatingIfNeeded: acknowledgmentNumber >> 8), UInt8(truncatingIfNeeded: acknowledgmentNumber),
+ UInt8(headerLength / 4) << 4, // data offset, in 32-bit words
+ flags,
+ UInt8(windowSize >> 8), UInt8(truncatingIfNeeded: windowSize),
+ 0, 0, // checksum
+ 0, 0, // urgent pointer
+ ]
+ header += options
+ let whole = header + payload
+ let sum = VPhoneInternetChecksum.compute(
+ whole,
+ seed: VPhoneInternetChecksum.pseudoHeader(source: source, destination: destination, proto: 6, length: whole.count),
+ )
+ // A computed zero is transmitted as all ones (RFC 793).
+ let checksum = sum == 0 ? 0xFFFF : sum
+ header[16] = UInt8(checksum >> 8)
+ header[17] = UInt8(checksum & 0xFF)
+ return header + payload
+ }
+
+ init?(bytes: [UInt8]) {
+ guard bytes.count >= 20 else { return nil }
+ sourcePort = UInt16(bytes[0]) << 8 | UInt16(bytes[1])
+ destinationPort = UInt16(bytes[2]) << 8 | UInt16(bytes[3])
+ sequenceNumber = UInt32(bytes[4]) << 24 | UInt32(bytes[5]) << 16 | UInt32(bytes[6]) << 8 | UInt32(bytes[7])
+ acknowledgmentNumber = UInt32(bytes[8]) << 24 | UInt32(bytes[9]) << 16 | UInt32(bytes[10]) << 8 | UInt32(bytes[11])
+ let headerLength = Int(bytes[12] >> 4) * 4
+ guard headerLength >= 20, bytes.count >= headerLength else { return nil }
+ flags = bytes[13]
+ windowSize = UInt16(bytes[14]) << 8 | UInt16(bytes[15])
+ payload = Array(bytes[headerLength...])
+ let parsed = Self.options(in: Array(bytes[20 ..< headerLength]))
+ maximumSegmentSize = parsed.mss
+ windowScale = parsed.windowScale
+ }
+
+ /// The options we care about, read in one pass.
+ ///
+ /// Option 2 carries the peer's MSS and option 3 its window scale; everything
+ /// else is skipped by its length. A malformed list ends the walk rather than
+ /// guessing -- a peer that sends a broken option gets the RFC 1122 MSS
+ /// default and no window scaling, which is the safe direction both times.
+ private static func options(in options: [UInt8]) -> (mss: Int?, windowScale: Int?) {
+ var mss: Int?
+ var windowScale: Int?
+ var index = 0
+ while index < options.count {
+ let kind = options[index]
+ if kind == 0 { break } // end of options
+ if kind == 1 { index += 1; continue } // no-op padding
+ guard index + 1 < options.count else { break }
+ let length = Int(options[index + 1])
+ guard length >= 2, index + length <= options.count else { break }
+ if kind == 2, length == 4 {
+ mss = Int(UInt16(options[index + 2]) << 8 | UInt16(options[index + 3]))
+ } else if kind == 3, length == 3 {
+ windowScale = Int(options[index + 2])
+ }
+ index += length
+ }
+ return (mss, windowScale)
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKit/Network/VPhoneTCPForwarder.swift b/VPhoneKit/VPhoneCoreKit/Network/VPhoneTCPForwarder.swift
new file mode 100644
index 00000000..eb1ef3db
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKit/Network/VPhoneTCPForwarder.swift
@@ -0,0 +1,800 @@
+import Foundation
+import os
+
+// MARK: - Flow
+
+/// One guest TCP flow, named by the guest's view of both ends.
+struct VPhoneTCPFlow: Hashable {
+ let sourceAddress: VPhoneIPv4Address
+ let sourcePort: UInt16
+ let destinationAddress: VPhoneIPv4Address
+ let destinationPort: UInt16
+ /// The guest's MAC, learned from the frame, so a reply can be addressed.
+ let guestHardware: VPhoneMACAddress
+
+ var key: VPhoneTCPFlowKey {
+ VPhoneTCPFlowKey(
+ sourceAddress: sourceAddress, sourcePort: sourcePort,
+ destinationAddress: destinationAddress, destinationPort: destinationPort,
+ )
+ }
+}
+
+struct VPhoneTCPFlowKey: Hashable {
+ let sourceAddress: VPhoneIPv4Address
+ let sourcePort: UInt16
+ let destinationAddress: VPhoneIPv4Address
+ let destinationPort: UInt16
+}
+
+// MARK: - Forwarder
+
+/// Terminates the guest's TCP and carries it over an ordinary host socket.
+///
+/// This is the stage where `tunnel` stops being a shim and becomes a peer: the
+/// guest's TCP belongs to us, the server's TCP belongs to the host kernel, and
+/// the two sequence spaces are kept apart. That is more work than stage 2's
+/// datagram relay, and it is deliberate — the alternative is doing the
+/// translation inside the kernel, which needs a utun and therefore privilege.
+///
+/// Deliberate simplifications, each defensible because the guest-facing link is a
+/// local socketpair that neither reorders nor drops:
+///
+/// - **No options are sent.** No SACK, no timestamps, no window scaling, so the
+/// advertised window is capped at 65535. A guest that offers them gets no
+/// reply, which is the correct behaviour for a peer that did not.
+/// - **No retransmission.** Our writes to the guest do not need it. If one is
+/// lost anyway the guest retransmits, and `sequence == expected` handling
+/// treats the copy as a duplicate.
+/// - **No congestion control.** The path is host memory.
+///
+/// Threading: every field is touched only on `queue`. The read sources for the
+/// host sockets and the frame loop that calls in both run there, so no lock is
+/// needed. That is the invariant behind `@unchecked Sendable`.
+final class VPhoneTCPForwarder: @unchecked Sendable {
+ /// Delivers one segment back toward the guest.
+ typealias Deliver = (VPhoneTCPFlow, VPhoneTCPSegment) -> Void
+
+ /// Same rationale as the UDP forwarder: UDP has no teardown, so a timer is
+ /// the only bound. TCP does have one, but a peer that vanishes mid-connection
+ /// leaves a session behind until this fires.
+ private static let idleTimeout: TimeInterval = 120
+ /// A ceiling, so a guest that opens sockets in a loop cannot exhaust the
+ /// host. Well above what a VM needs.
+ private static let maximumConnections = 256
+ /// What we tell the guest it may send us before waiting. Fixed: we do not
+ /// advertise window scaling, so this is the whole window.
+ private static let advertisedWindow: UInt16 = 65535
+ /// Largest segment we will send the guest: the DHCP-advertised MTU less the
+ /// IPv4 and TCP headers. Sent as option 2 in the SYN-ACK. Keep in step with
+ /// `VPhoneUserspaceNetworkConfiguration.default.mtu`.
+ private static let ourMSS = 1460
+ /// The shift we offer for window scaling, when the guest offers it too.
+ ///
+ /// A 16-bit window over a path with any latency is the throughput ceiling:
+ /// 64 KiB at 100 ms is 640 KiB/s no matter how fast the link is. Offering a
+ /// scale lets the guest advertise a window it could not otherwise express,
+ /// which is what lets a download run at the link's speed instead of
+ /// 65535/RTT.
+ private static let ourWindowScaleShift = 7
+ /// What to assume when the guest's SYN carries no MSS option. RFC 1122's
+ /// floor, chosen so an unadvertised peer never gets an oversized segment.
+ private static let defaultPeerMSS = 536
+ /// One read at a time from the host. Larger than an MSS on purpose: fewer
+ /// syscalls, and the split into segments happens below anyway.
+ private static let readCapacity = 65536
+ /// Cap on data buffered for a guest whose window is closed. The host socket's
+ /// own receive buffer applies backpressure beyond this: we stop draining it,
+ /// so the kernel stops acknowledging the server and the server stops sending.
+ private static let maxPendingToGuest = 1 << 20
+ /// How long to wait for an acknowledgment before sending the data again.
+ ///
+ /// Has to clear the guest's delayed-acknowledgment timer *and* a round trip
+ /// over whatever the host is tunnelling through; WARP alone can be 200 ms,
+ /// and retransmitting into a healthy connection wastes the bandwidth this
+ /// exists to protect. Still far below the thirty-second client-side timeouts
+ /// that a stalled transfer otherwise ends in.
+ private static let retransmitInterval: TimeInterval = 1.5
+ private static let log = Logger(subsystem: "com.vphone.tunnel", category: "tcp")
+
+ private enum State {
+ /// SYN seen, host connect in flight.
+ case connecting
+ /// Host is connected, SYN-ACK sent, waiting for the guest's ACK.
+ case synAcknowledged
+ /// Both directions open.
+ case established
+ /// FIN seen from one side; the other may still have data in flight.
+ case closing
+ }
+
+ private final class Connection {
+ let flow: VPhoneTCPFlow
+ let socket: Int32
+ let readSource: DispatchSourceRead
+ /// Fires when the non-blocking connect completes (or fails).
+ var writeSource: DispatchSourceWrite?
+ var state: State
+ /// Next sequence number we will send to the guest.
+ var localSequence: UInt32
+ /// Next sequence number we expect from the guest.
+ var remoteSequence: UInt32
+ /// Guest payload that arrived before the host was connected.
+ var pendingFromGuest: [UInt8] = []
+ /// Set once the guest has sent FIN, so we do not act on it twice.
+ var guestClosed = false
+ /// Set once we have sent the guest a FIN.
+ var hostClosed = false
+ var lastActivity = Date()
+ /// The guest's MSS from its SYN, or the RFC floor when it sent none.
+ /// Every segment we build is split to fit it.
+ var peerMSS: Int
+ /// How far to shift the guest's window field. Zero unless scaling was
+ /// negotiated; reading an unscaled window as if it were scaled would
+ /// badly overestimate the room available.
+ var peerWindowScale: Int
+ /// True when both ends offered window scaling, so our own advertised
+ /// window is shifted on the way out and the guest's is shifted on the
+ /// way in.
+ var windowScaleNegotiated = false
+
+ // MARK: Sending toward the guest
+ //
+ // The link to the guest is local and does not lose packets, so the only
+ // way data can go missing is by sending more than the guest has buffer
+ // for. The send side therefore tracks the guest's advertised window and
+ // never runs past it. That is not an optimisation: without it the guest
+ // drops the overflow silently, never acknowledges it, and the transfer
+ // stops dead -- which is what "downloads crawl and then hang" was.
+
+ /// Right edge of the guest's advertised receive window, i.e. the highest
+ /// sequence number we may send. Starts at `localSequence` so nothing goes
+ /// out until the guest's first ACK says how much room there is.
+ var sendWindowRight: UInt32
+ /// Earliest sequence number the guest has not acknowledged.
+ var sendUna: UInt32
+ /// Bytes sent toward the guest that it has never acknowledged. A number
+ /// that stays large while nothing moves is the signature of a stalled
+ /// transfer: the peer is waiting for a segment we are not sending again.
+ var unacknowledgedBytes: Int {
+ Int(Int32(bitPattern: localSequence &- sendUna))
+ }
+ /// When the guest's acknowledgment last moved, so a stalled connection
+ /// can be told from a slow one.
+ var lastAckAdvance = Date()
+ /// Read from the host, not yet sent, because the window had no room.
+ var pendingToGuest: [UInt8] = []
+ /// A FIN queued behind `pendingToGuest`.
+ var pendingFIN = false
+ /// Everything sent toward the guest that it has not acknowledged, oldest
+ /// first, with the sequence number the first byte went out under.
+ ///
+ /// Kept because the link not losing packets is not the same as every
+ /// segment arriving: one unacknowledged segment stops the connection
+ /// where it stands, and nothing here sends it again. That is what turned
+ /// a lost segment into a thirty-second timeout.
+ var sentNotAcked: [UInt8] = []
+ var sentNotAckedSequence: UInt32 = 0
+ var retransmitTimer: DispatchSourceTimer?
+ /// Set while the host read source is suspended because the buffer above
+ /// is full. Sources are level-triggered, so one that is not drained has
+ /// to be suspended or it spins.
+ var readSuspended = false
+
+ // MARK: Sending toward the host
+ //
+ // The mirror of the problem above: the host's send buffer can fill too,
+ // when the guest uploads faster than the server accepts. Waiting for
+ // writability is the only correct response; retrying in a loop would hold
+ // the serial queue and stall every other connection with it.
+
+ /// Guest payload not yet written to the host, waiting on its send buffer.
+ var pendingToHost: [UInt8] = []
+ /// When the connection opened, for the closing summary.
+ let openedAt = Date()
+ /// Delivered in each direction, for the closing summary.
+ var bytesToHost = 0
+ var bytesToGuest = 0
+ /// Set by `finish`, so a connection is summarised and torn down once.
+ var isClosed = false
+ /// Set once we have told the guest our window is shut, so a window update
+ /// follows the moment the backlog clears.
+ var guestWindowClosed = false
+
+ init(flow: VPhoneTCPFlow, socket: Int32, readSource: DispatchSourceRead, state: State, localSequence: UInt32, remoteSequence: UInt32, peerMSS: Int, peerWindowScale: Int) {
+ self.flow = flow
+ self.socket = socket
+ self.readSource = readSource
+ self.state = state
+ self.localSequence = localSequence
+ self.remoteSequence = remoteSequence
+ self.peerMSS = peerMSS
+ self.peerWindowScale = peerWindowScale
+ self.sendWindowRight = localSequence
+ self.sendUna = localSequence
+ }
+ }
+
+ private let queue: DispatchQueue
+ private let deliver: Deliver
+ private var connections: [VPhoneTCPFlowKey: Connection] = [:]
+ private var reaper: DispatchSourceTimer?
+ private var isStopped = false
+ /// Source of initial sequence numbers. Only has to be unpredictable enough
+ /// that two connections to the same peer do not look alike.
+ private var sequenceCounter: UInt32 = UInt32.random(in: 0 ... UInt32.max)
+
+ /// Marks `queue` as ours, so `connectionCount` can tell whether it is already
+ /// on it rather than deadlocking against itself.
+ private static let queueKey = DispatchSpecificKey<Void>()
+
+ init(queue: DispatchQueue, deliver: @escaping Deliver) {
+ self.queue = queue
+ self.deliver = deliver
+ queue.setSpecific(key: Self.queueKey, value: ())
+ }
+
+ /// Live connections, for tests and diagnostics.
+ ///
+ /// The only member callable from any thread: off the queue it hops on, on the
+ /// queue it reads directly. Hopping unconditionally is what deadlocked
+ /// `start()` in the UDP forwarder.
+ var connectionCount: Int {
+ if DispatchQueue.getSpecific(key: Self.queueKey) != nil { return connections.count }
+ return queue.sync { connections.count }
+ }
+
+ func start() {
+ dispatchPrecondition(condition: .onQueue(queue))
+ guard !isStopped, reaper == nil else { return }
+ let timer = DispatchSource.makeTimerSource(queue: queue)
+ timer.schedule(deadline: .now() + Self.idleTimeout, repeating: Self.idleTimeout)
+ timer.setEventHandler { [weak self] in self?.reapIdle() }
+ timer.resume()
+ reaper = timer
+ }
+
+ func stop() {
+ dispatchPrecondition(condition: .onQueue(queue))
+ guard !isStopped else { return }
+ isStopped = true
+ reaper?.cancel()
+ reaper = nil
+ for connection in connections.values { close(connection) }
+ connections.removeAll()
+ }
+
+ /// Handle one segment from the guest. On `queue`.
+ func receive(_ segment: VPhoneTCPSegment, for flow: VPhoneTCPFlow) {
+ dispatchPrecondition(condition: .onQueue(queue))
+ handle(segment, flow: flow)
+ }
+
+ // MARK: - Segment handling
+
+ private func handle(_ segment: VPhoneTCPSegment, flow: VPhoneTCPFlow) {
+ guard !isStopped else { return }
+
+ if segment.hasRST {
+ if let connection = connections[flow.key] {
+ close(connection)
+ connections[flow.key] = nil
+ }
+ return
+ }
+
+ if segment.hasSYN, !segment.hasACK {
+ openConnection(for: flow, segment: segment)
+ return
+ }
+
+ guard let connection = connections[flow.key] else {
+ // Nothing here knows this flow. A bare ACK is stale; anything else
+ // gets a RST so the guest stops waiting.
+ if !segment.hasACK || segment.hasFIN || !segment.payload.isEmpty {
+ sendReset(for: flow, inReplyTo: segment)
+ }
+ return
+ }
+ connection.lastActivity = Date()
+
+ switch connection.state {
+ case .connecting:
+ // The host has not connected yet, so we cannot answer. Remember the
+ // payload; the handshake will flush it.
+ if !segment.payload.isEmpty, segment.sequenceNumber == connection.remoteSequence {
+ connection.remoteSequence &+= segment.sequenceLength
+ connection.pendingFromGuest += segment.payload
+ }
+
+ case .synAcknowledged:
+ guard segment.hasACK, segment.acknowledgmentNumber == connection.localSequence else { return }
+ connection.state = .established
+ connection.sendWindowRight = segment.acknowledgmentNumber &+ Self.expand(segment.windowSize, by: connection.peerWindowScale)
+ connection.sendUna = segment.acknowledgmentNumber
+ flushPending(connection)
+
+ case .established, .closing:
+ consume(segment, connection: connection)
+ }
+ }
+
+ private func openConnection(for flow: VPhoneTCPFlow, segment: VPhoneTCPSegment) {
+ guard connections[flow.key] == nil else { return }
+ guard connections.count < Self.maximumConnections else {
+ sendReset(for: flow, inReplyTo: segment)
+ return
+ }
+
+ let descriptor = socket(AF_INET, SOCK_STREAM, 0)
+ guard descriptor >= 0 else {
+ sendReset(for: flow, inReplyTo: segment)
+ return
+ }
+
+ var address = sockaddr_in()
+ address.sin_len = UInt8(MemoryLayout<sockaddr_in>.size)
+ address.sin_family = sa_family_t(AF_INET)
+ address.sin_port = flow.destinationPort.bigEndian
+ let octets = flow.destinationAddress.bytes
+ // Network order, as in the UDP forwarder: host order asks for a
+ // different address entirely.
+ let hostOrder = UInt32(octets[0]) << 24 | UInt32(octets[1]) << 16 | UInt32(octets[2]) << 8 | UInt32(octets[3])
+ address.sin_addr = in_addr(s_addr: hostOrder.bigEndian)
+
+ _ = fcntl(descriptor, F_SETFL, fcntl(descriptor, F_GETFL, 0) | O_NONBLOCK)
+ var one: Int32 = 1
+ _ = setsockopt(descriptor, IPPROTO_TCP, TCP_NODELAY, &one, socklen_t(MemoryLayout<Int32>.size))
+
+ let readSource = DispatchSource.makeReadSource(fileDescriptor: descriptor, queue: queue)
+ let connection = Connection(
+ flow: flow,
+ socket: descriptor,
+ readSource: readSource,
+ state: .connecting,
+ localSequence: nextSequence(),
+ // A SYN occupies one sequence number.
+ remoteSequence: segment.sequenceNumber &+ 1,
+ peerMSS: segment.maximumSegmentSize ?? Self.defaultPeerMSS,
+ peerWindowScale: segment.windowScale ?? 0,
+ )
+ connection.windowScaleNegotiated = segment.windowScale != nil
+ readSource.setEventHandler { [weak self] in self?.drainHost(connection) }
+ // Qualified: the type has its own `close` for tearing a connection down.
+ readSource.setCancelHandler { Darwin.close(descriptor) }
+
+ let connected = withUnsafePointer(to: &address) { pointer in
+ pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+ connect(descriptor, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+ }
+ }
+ if connected == 0 {
+ // Connected straight away; no need to wait for writability.
+ connection.state = .synAcknowledged
+ sendSynAcknowledgment(connection)
+ } else if errno == EINPROGRESS {
+ // Usual case. Writability means the attempt finished, either way.
+ let writeSource = DispatchSource.makeWriteSource(fileDescriptor: descriptor, queue: queue)
+ writeSource.setEventHandler { [weak self] in self?.finishConnect(connection) }
+ writeSource.resume()
+ connection.writeSource = writeSource
+ } else {
+ readSource.cancel()
+ sendReset(for: flow, inReplyTo: segment)
+ return
+ }
+
+ readSource.resume()
+ connections[flow.key] = connection
+ }
+
+ private func finishConnect(_ connection: Connection) {
+ connection.writeSource?.cancel()
+ connection.writeSource = nil
+
+ var error: Int32 = 0
+ var length = socklen_t(MemoryLayout<Int32>.size)
+ _ = getsockopt(connection.socket, SOL_SOCKET, SO_ERROR, &error, &length)
+ guard error == 0 else {
+ sendReset(for: connection.flow, inReplyTo: nil)
+ finish(connection)
+ return
+ }
+ connection.state = .synAcknowledged
+ sendSynAcknowledgment(connection)
+ }
+
+ /// Data (or a FIN) in one direction or the other.
+ private func consume(_ segment: VPhoneTCPSegment, connection: Connection) {
+ // The guest's ACK is also its window advertisement, and therefore the
+ // only thing that tells the send side how much room there is. Reading it
+ // here is what keeps a transfer moving instead of stalling after the
+ // first burst.
+ if segment.hasACK {
+ connection.sendWindowRight = segment.acknowledgmentNumber &+ Self.expand(segment.windowSize, by: connection.peerWindowScale)
+ if Self.isAfter(segment.acknowledgmentNumber, connection.sendUna) {
+ connection.sendUna = segment.acknowledgmentNumber
+ connection.lastAckAdvance = Date()
+ }
+ // Release the copy of anything the guest has taken, so a healthy
+ // connection holds nothing.
+ let acknowledged = Int(Int32(bitPattern: segment.acknowledgmentNumber &- connection.sentNotAckedSequence))
+ if acknowledged > 0 {
+ let drop = min(acknowledged, connection.sentNotAcked.count)
+ connection.sentNotAcked.removeFirst(drop)
+ connection.sentNotAckedSequence &+= UInt32(drop)
+ }
+ flushToGuest(connection)
+ }
+
+ if !segment.payload.isEmpty {
+ if segment.sequenceNumber == connection.remoteSequence {
+ writeToHost(segment.payload, connection: connection)
+ connection.remoteSequence &+= UInt32(segment.payload.count)
+ // Acknowledge what we just took, so the guest can send more.
+ send(.init(
+ sourcePort: connection.flow.destinationPort,
+ destinationPort: connection.flow.sourcePort,
+ sequenceNumber: connection.localSequence,
+ acknowledgmentNumber: connection.remoteSequence,
+ flags: VPhoneTCPFlags.ack,
+ windowSize: advertisedWindowField(connection),
+ ), connection: connection)
+ } else {
+ // Already seen (a duplicate) or out of order. The link to us is a
+ // socketpair and does not reorder, so re-acknowledging what we do
+ // expect is the right answer to both.
+ send(.init(
+ sourcePort: connection.flow.destinationPort,
+ destinationPort: connection.flow.sourcePort,
+ sequenceNumber: connection.localSequence,
+ acknowledgmentNumber: connection.remoteSequence,
+ flags: VPhoneTCPFlags.ack,
+ windowSize: advertisedWindowField(connection),
+ ), connection: connection)
+ }
+ }
+
+ if segment.hasFIN, !connection.guestClosed {
+ connection.guestClosed = true
+ connection.remoteSequence &+= 1
+ // Half-close: the guest is done sending, but still wants our data.
+ shutdown(connection.socket, SHUT_WR)
+ sendAcknowledgment(connection)
+ connection.state = .closing
+ finishIfBothClosed(connection)
+ }
+ }
+
+ /// Tear down only once neither side has anything left to deliver.
+ ///
+ /// The earlier version closed as soon as a FIN was seen in both directions,
+ /// which threw away data still queued for the guest.
+ private func finishIfBothClosed(_ connection: Connection) {
+ guard connection.hostClosed, connection.guestClosed else { return }
+ guard connection.pendingToGuest.isEmpty, !connection.pendingFIN else { return }
+ finish(connection)
+ }
+
+ /// Send as much queued data as the guest's window allows.
+ ///
+ /// Two limits apply to every segment: the guest's MSS, so it fits in one MTU,
+ /// and the guest's window, so it fits in the guest's buffer. Both were
+ /// learned from the guest. Running past either one loses the data silently.
+ private func flushToGuest(_ connection: Connection) {
+ while !connection.pendingToGuest.isEmpty {
+ let room = Int(Int32(bitPattern: connection.sendWindowRight &- connection.localSequence))
+ guard room > 0 else { break }
+ let chunk = min(room, min(connection.peerMSS, connection.pendingToGuest.count))
+ let data = Array(connection.pendingToGuest.prefix(chunk))
+ connection.pendingToGuest.removeFirst(chunk)
+ connection.bytesToGuest += chunk
+ send(.init(
+ sourcePort: connection.flow.destinationPort,
+ destinationPort: connection.flow.sourcePort,
+ sequenceNumber: connection.localSequence,
+ acknowledgmentNumber: connection.remoteSequence,
+ flags: VPhoneTCPFlags.ack | VPhoneTCPFlags.psh,
+ windowSize: advertisedWindowField(connection),
+ payload: data,
+ ), connection: connection)
+ }
+
+ if connection.pendingToGuest.isEmpty, connection.pendingFIN {
+ connection.pendingFIN = false
+ send(.init(
+ sourcePort: connection.flow.destinationPort,
+ destinationPort: connection.flow.sourcePort,
+ sequenceNumber: connection.localSequence,
+ acknowledgmentNumber: connection.remoteSequence,
+ flags: VPhoneTCPFlags.ack | VPhoneTCPFlags.fin,
+ windowSize: advertisedWindowField(connection),
+ ), connection: connection)
+ finishIfBothClosed(connection)
+ if connection.state == .closing, connection.pendingToGuest.isEmpty { return }
+ }
+
+ // Room again: resume a source that was paused for backpressure.
+ if connection.readSuspended, connection.pendingToGuest.count < Self.maxPendingToGuest {
+ connection.readSource.resume()
+ connection.readSuspended = false
+ }
+ }
+
+ private func flushPending(_ connection: Connection) {
+ guard !connection.pendingFromGuest.isEmpty else { return }
+ let payload = connection.pendingFromGuest
+ connection.pendingFromGuest = []
+ writeToHost(payload, connection: connection)
+ sendAcknowledgment(connection)
+ }
+
+ private func writeToHost(_ payload: [UInt8], connection: Connection) {
+ connection.bytesToHost += payload.count
+ connection.pendingToHost += payload
+ flushToHost(connection)
+ }
+
+ /// Write what we can toward the host, then wait for writability.
+ ///
+ /// The previous version retried on EAGAIN in a tight loop. That is not a slow
+ /// path, it is a hang: the loop never yields, so the serial queue it runs on
+ /// stops serving every other connection -- downloads included -- and the CPU
+ /// spins until the host's buffer drains.
+ private func flushToHost(_ connection: Connection) {
+ while !connection.pendingToHost.isEmpty {
+ let written = connection.pendingToHost.withUnsafeBytes { raw -> Int in
+ guard let base = raw.baseAddress else { return -1 }
+ return Darwin.send(connection.socket, base, raw.count, 0)
+ }
+ if written > 0 {
+ connection.pendingToHost.removeFirst(written)
+ continue
+ }
+ if written < 0, errno == EAGAIN || errno == EINTR {
+ // Full. Arm a write source and come back when there is room.
+ connection.guestWindowClosed = true
+ if connection.writeSource == nil {
+ let source = DispatchSource.makeWriteSource(fileDescriptor: connection.socket, queue: queue)
+ source.setEventHandler { [weak self] in self?.flushToHost(connection) }
+ source.resume()
+ connection.writeSource = source
+ }
+ return
+ }
+ sendReset(for: connection.flow, inReplyTo: nil)
+ finish(connection)
+ return
+ }
+
+ // Backlog cleared: stop watching for writability, and reopen the window
+ // if the guest was told it had shut.
+ if let source = connection.writeSource {
+ source.cancel()
+ connection.writeSource = nil
+ }
+ if connection.guestWindowClosed {
+ connection.guestWindowClosed = false
+ sendAcknowledgment(connection)
+ }
+ }
+
+ /// The window field we advertise to the guest, in the units the handshake
+ /// agreed on.
+ ///
+ /// Shut while data is still queued toward the host, so the guest stops
+ /// sending instead of piling more into a queue that cannot drain; a window
+ /// update goes out once the backlog clears (see `flushToHost`).
+ private func advertisedWindowField(_ connection: Connection) -> UInt16 {
+ let window = connection.pendingToHost.isEmpty ? Self.advertisedWindow : 0
+ guard connection.windowScaleNegotiated else { return window }
+ return window >> UInt16(Self.ourWindowScaleShift)
+ }
+
+ /// Widest window that shift can express.
+ private static func expand(_ field: UInt16, by shift: Int) -> UInt32 {
+ shift == 0 ? UInt32(field) : UInt32(field) << UInt32(shift)
+ }
+
+ // MARK: - Host to guest
+
+ private func drainHost(_ connection: Connection) {
+ // Stop draining the host while the guest's window is closed. Leaving the
+ // data in the kernel is the point: its receive buffer fills, it stops
+ // acknowledging the server, and the server stops sending.
+ if connection.pendingToGuest.count >= Self.maxPendingToGuest {
+ if !connection.readSuspended {
+ connection.readSource.suspend()
+ connection.readSuspended = true
+ }
+ return
+ }
+
+ var buffer = [UInt8](repeating: 0, count: Self.readCapacity)
+ while true {
+ let received = buffer.withUnsafeMutableBytes { raw in
+ recv(connection.socket, raw.baseAddress, raw.count, 0)
+ }
+ if received > 0 {
+ connection.lastActivity = Date()
+ connection.pendingToGuest += buffer[0 ..< received]
+ flushToGuest(connection)
+ if connection.pendingToGuest.count >= Self.maxPendingToGuest { break }
+ continue
+ }
+ if received == 0 {
+ // The host closed. The FIN goes out behind whatever is still
+ // queued, so the guest does not see it before the data.
+ connection.lastActivity = Date()
+ if !connection.hostClosed {
+ connection.hostClosed = true
+ connection.pendingFIN = true
+ flushToGuest(connection)
+ }
+ finishIfBothClosed(connection)
+ return
+ }
+ // EAGAIN. A real error is indistinguishable here from a closed peer,
+ // so treat anything else as the end of the connection.
+ if errno != EAGAIN, errno != EINTR {
+ sendReset(for: connection.flow, inReplyTo: nil)
+ finish(connection)
+ }
+ return
+ }
+ }
+
+ // MARK: - Emitting
+
+ private func sendSynAcknowledgment(_ connection: Connection) {
+ send(.init(
+ sourcePort: connection.flow.destinationPort,
+ destinationPort: connection.flow.sourcePort,
+ sequenceNumber: connection.localSequence,
+ acknowledgmentNumber: connection.remoteSequence,
+ flags: VPhoneTCPFlags.syn | VPhoneTCPFlags.ack,
+ windowSize: advertisedWindowField(connection),
+ advertisedMSS: Self.ourMSS,
+ advertisedWindowScale: connection.windowScaleNegotiated ? Self.ourWindowScaleShift : nil,
+ ), connection: connection)
+ }
+
+ private func sendAcknowledgment(_ connection: Connection) {
+ send(.init(
+ sourcePort: connection.flow.destinationPort,
+ destinationPort: connection.flow.sourcePort,
+ sequenceNumber: connection.localSequence,
+ acknowledgmentNumber: connection.remoteSequence,
+ flags: VPhoneTCPFlags.ack,
+ windowSize: advertisedWindowField(connection),
+ ), connection: connection)
+ }
+
+ private func send(_ segment: VPhoneTCPSegment, connection: Connection) {
+ if !segment.payload.isEmpty {
+ if connection.sentNotAcked.isEmpty { connection.sentNotAckedSequence = segment.sequenceNumber }
+ connection.sentNotAcked += segment.payload
+ connection.localSequence &+= UInt32(segment.payload.count)
+ armRetransmission(connection)
+ }
+ if segment.hasSYN || segment.hasFIN { connection.localSequence &+= 1 }
+ deliver(connection.flow, segment)
+ }
+
+ /// Send a copy of already-sent data, without touching our send sequence.
+ private func resend(_ data: [UInt8], sequence: UInt32, connection: Connection) {
+ deliver(connection.flow, VPhoneTCPSegment(
+ sourcePort: connection.flow.destinationPort,
+ destinationPort: connection.flow.sourcePort,
+ sequenceNumber: sequence,
+ acknowledgmentNumber: connection.remoteSequence,
+ flags: VPhoneTCPFlags.ack | VPhoneTCPFlags.psh,
+ windowSize: advertisedWindowField(connection),
+ payload: data,
+ ))
+ }
+
+ /// Nudge the oldest unacknowledged segment, once.
+ ///
+ /// Only the oldest, and only one segment's worth. The point is to break a
+ /// stall; resending the whole unacknowledged range spends the connection's
+ /// bandwidth on copies. That distinction matters because the common case here
+ /// is not loss at all -- the link to the guest drops nothing -- but the
+ /// guest's acknowledgment simply being late, and a peer that really did lose
+ /// something answers with duplicate acknowledgments, which prompt more
+ /// nudges.
+ private func retransmit(_ connection: Connection) {
+ connection.retransmitTimer?.cancel()
+ connection.retransmitTimer = nil
+ guard !connection.isClosed, !connection.sentNotAcked.isEmpty else { return }
+
+ let count = min(connection.peerMSS, connection.sentNotAcked.count)
+ Self.log.info(
+ "nudging :\(connection.flow.sourcePort, privacy: .public) with \(count, privacy: .public)B, \(connection.sentNotAcked.count, privacy: .public)B unacknowledged for \(String(format: "%.1f", Date().timeIntervalSince(connection.lastAckAdvance)), privacy: .public)s",
+ )
+ resend(Array(connection.sentNotAcked[0 ..< count]), sequence: connection.sentNotAckedSequence, connection: connection)
+ armRetransmission(connection)
+ }
+
+ private func armRetransmission(_ connection: Connection) {
+ guard connection.retransmitTimer == nil, !connection.sentNotAcked.isEmpty, !connection.isClosed else { return }
+ let timer = DispatchSource.makeTimerSource(queue: queue)
+ timer.schedule(deadline: .now() + Self.retransmitInterval)
+ timer.setEventHandler { [weak self] in self?.retransmit(connection) }
+ timer.resume()
+ connection.retransmitTimer = timer
+ }
+
+ /// A RST for a flow we are not going to serve.
+ private func sendReset(for flow: VPhoneTCPFlow, inReplyTo segment: VPhoneTCPSegment?) {
+ // RFC 793 section 3.4: if the offending segment carried an ACK, the reset
+ // borrows its acknowledgment number and carries no ACK of its own.
+ // Otherwise sequence 0 plus an ACK naming what we did receive.
+ let acknowledging = segment?.hasACK == true
+ let reset = VPhoneTCPSegment(
+ sourcePort: flow.destinationPort,
+ destinationPort: flow.sourcePort,
+ sequenceNumber: acknowledging ? (segment?.acknowledgmentNumber ?? 0) : 0,
+ acknowledgmentNumber: acknowledging
+ ? 0
+ : (segment.map { $0.sequenceNumber &+ $0.sequenceLength } ?? 0),
+ flags: acknowledging ? VPhoneTCPFlags.rst : (VPhoneTCPFlags.rst | VPhoneTCPFlags.ack),
+ windowSize: 0,
+ )
+ deliver(flow, reset)
+ }
+
+ /// Tear a connection down and say what it did.
+ ///
+ /// Idempotent: several paths can decide a connection is finished, and the
+ /// earlier version logged and tore down once per decision, which made the
+ /// log look like connections were being closed in pairs.
+ private func finish(_ connection: Connection) {
+ guard !connection.isClosed else { return }
+ connection.isClosed = true
+ let lifetime = Date().timeIntervalSince(connection.openedAt)
+ let sinceAck = Date().timeIntervalSince(connection.lastAckAdvance)
+ Self.log.debug(
+ "\(connection.flow.destinationAddress, privacy: .public):\(connection.flow.destinationPort, privacy: .public) <- :\(connection.flow.sourcePort, privacy: .public) closed after \(String(format: "%.1f", lifetime), privacy: .public)s up \(connection.bytesToHost, privacy: .public)B down \(connection.bytesToGuest, privacy: .public)B unacked \(connection.unacknowledgedBytes, privacy: .public)B lastAck \(String(format: "%.1f", sinceAck), privacy: .public)s ago",
+ )
+ close(connection)
+ connections[connection.flow.key] = nil
+ }
+
+ private func close(_ connection: Connection) {
+ connection.writeSource?.cancel()
+ connection.writeSource = nil
+ connection.retransmitTimer?.cancel()
+ connection.retransmitTimer = nil
+ // A suspended source must be resumed before it can be cancelled;
+ // libdispatch aborts the process for releasing a suspended object.
+ if connection.readSuspended {
+ connection.readSource.resume()
+ connection.readSuspended = false
+ }
+ // The cancel handler closes the descriptor, but only once no handler is
+ // running, which is what keeps `drainHost` from touching a freed fd.
+ connection.readSource.cancel()
+ }
+
+ // MARK: - Housekeeping
+
+ private func reapIdle() {
+ let now = Date()
+ for (key, connection) in connections where now.timeIntervalSince(connection.lastActivity) >= Self.idleTimeout {
+ close(connection)
+ connections[key] = nil
+ }
+ }
+
+ /// Wrap-safe TCP sequence comparison: is `a` after `b`?
+ private static func isAfter(_ a: UInt32, _ b: UInt32) -> Bool {
+ Int32(bitPattern: a &- b) > 0
+ }
+
+ private func nextSequence() -> UInt32 {
+ // A simple step is enough: it only has to differ between connections.
+ sequenceCounter &+= 0x9E37_79B9
+ return sequenceCounter
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKit/Network/VPhoneUDPForwarder.swift b/VPhoneKit/VPhoneCoreKit/Network/VPhoneUDPForwarder.swift
new file mode 100644
index 00000000..875b7e75
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKit/Network/VPhoneUDPForwarder.swift
@@ -0,0 +1,261 @@
+import Foundation
+import SystemConfiguration
+import os
+
+// MARK: - Host resolver lookup
+
+/// The host's own DNS servers, so the guest's lookups can be forwarded to the
+/// same place the host would use.
+///
+/// Read through `SystemConfiguration` rather than a file because that is what
+/// changes when the VPN connects: the point of `tunnel` is that the guest's
+/// egress follows the host's, and the resolver follows the same switch.
+enum VPhoneHostResolver {
+ static func addresses() -> [VPhoneIPv4Address] {
+ guard
+ let store = SCDynamicStoreCreate(nil, "com.vphone.tunnel" as CFString, nil, nil),
+ let value = SCDynamicStoreCopyValue(store, "State:/Network/Global/DNS" as CFString),
+ let dictionary = value as? [String: Any],
+ let servers = dictionary[kSCPropNetDNSServerAddresses as String] as? [String]
+ else { return [] }
+ return servers.compactMap(VPhoneIPv4Address.init(dotted:))
+ }
+
+ /// The first usable resolver, or nil when the host has none configured.
+ static func preferred() -> VPhoneIPv4Address? {
+ addresses().first
+ }
+}
+
+extension VPhoneIPv4Address {
+ /// Parse `a.b.c.d`, or nil for anything else (including IPv6, which this
+ /// stack deliberately does not carry).
+ init?(dotted: String) {
+ let parts = dotted.split(separator: ".", omittingEmptySubsequences: false)
+ guard parts.count == 4 else { return nil }
+ var octets: [UInt8] = []
+ for part in parts {
+ guard let value = UInt8(part) else { return nil }
+ octets.append(value)
+ }
+ self.init(octets[0], octets[1], octets[2], octets[3])
+ }
+}
+
+// MARK: - Forwarder
+
+/// Carries the guest's UDP to the host and the answers back.
+///
+/// One connected `SOCK_DGRAM` socket per flow, so the kernel does the demultiplex
+/// for us: a reply can only arrive from the address we sent to, which is the
+/// whole of the security story for an unprivileged forwarder. The socket is
+/// non-blocking and drained on the same serial queue as the frame loop, so
+/// nothing here needs its own locking.
+///
+/// Threading: every field is touched only on `queue`, which the owner supplies.
+/// That is the invariant behind `@unchecked Sendable`.
+final class VPhoneUDPForwarder: @unchecked Sendable {
+ /// Delivers one datagram back toward the guest.
+ typealias Deliver = (VPhoneUDPFlow, [UInt8]) -> Void
+
+ /// Flows are forgotten after this long without traffic. UDP has no teardown,
+ /// so this is the only thing that bounds the session table.
+ private static let idleTimeout: TimeInterval = 30
+ /// Largest datagram read from the host in one call. Responses that exceed the
+ /// guest's MTU are fragmented on the way in (see `VPhoneUserspaceNetwork`),
+ /// so nothing is dropped for size here.
+ private static let datagramCapacity = 65535
+
+ private final class Session {
+ let socket: Int32
+ let source: DispatchSourceRead
+ let flow: VPhoneUDPFlow
+ /// Where this flow's datagrams actually go. Differs from the guest's
+ /// destination only for DNS, which we answer ourselves.
+ let destination: (address: VPhoneIPv4Address, port: UInt16)
+ var lastActivity: Date
+
+ init(socket: Int32, source: DispatchSourceRead, flow: VPhoneUDPFlow, destination: (VPhoneIPv4Address, UInt16), lastActivity: Date) {
+ self.socket = socket
+ self.source = source
+ self.flow = flow
+ self.destination = destination
+ self.lastActivity = lastActivity
+ }
+ }
+
+ private let queue: DispatchQueue
+ private let configuration: VPhoneUserspaceNetworkConfiguration
+ private let deliver: Deliver
+ private var sessions: [VPhoneUDPFlowKey: Session] = [:]
+ private var reaper: DispatchSourceTimer?
+ private var isStopped = false
+ /// Reused for every read. Allocating and zeroing a maximum-sized datagram on
+ /// each burst is real work at QUIC rates, where hundreds of packets a second
+ /// is ordinary. Only touched on `queue`.
+ private var readBuffer = [UInt8](repeating: 0, count: VPhoneUDPForwarder.datagramCapacity)
+
+ /// Marks `queue` as ours, so `sessionCount` can tell whether it is already on
+ /// it rather than deadlocking against itself.
+ private static let queueKey = DispatchSpecificKey<Void>()
+ private static let log = Logger(subsystem: "com.vphone.tunnel", category: "udp")
+
+ init(configuration: VPhoneUserspaceNetworkConfiguration, queue: DispatchQueue, deliver: @escaping Deliver) {
+ self.configuration = configuration
+ self.queue = queue
+ self.deliver = deliver
+ queue.setSpecific(key: Self.queueKey, value: ())
+ }
+
+ /// Number of live flows. Exposed for tests and diagnostics.
+ ///
+ /// The only member callable from any thread: off the queue it hops on, on the
+ /// queue it reads directly. Hopping unconditionally would deadlock, which is
+ /// exactly the bug `start()` had.
+ var sessionCount: Int {
+ if DispatchQueue.getSpecific(key: Self.queueKey) != nil { return sessions.count }
+ return queue.sync { sessions.count }
+ }
+
+ func start() {
+ dispatchPrecondition(condition: .onQueue(queue))
+ guard !isStopped, reaper == nil else { return }
+ let timer = DispatchSource.makeTimerSource(queue: queue)
+ timer.schedule(deadline: .now() + Self.idleTimeout, repeating: Self.idleTimeout)
+ timer.setEventHandler { [weak self] in self?.reapIdleSessions() }
+ timer.resume()
+ reaper = timer
+ }
+
+ func stop() {
+ dispatchPrecondition(condition: .onQueue(queue))
+ guard !isStopped else { return }
+ isStopped = true
+ reaper?.cancel()
+ reaper = nil
+ for session in sessions.values { closeSession(session) }
+ sessions.removeAll()
+ }
+
+ /// Send one guest datagram onward. `flow` names both ends. On `queue`.
+ func send(_ payload: [UInt8], for flow: VPhoneUDPFlow) {
+ dispatchPrecondition(condition: .onQueue(queue))
+ guard !isStopped else { return }
+ guard let session = session(for: flow) else { return }
+ session.lastActivity = Date()
+ let sent = payload.withUnsafeBytes { raw in
+ // Qualified: the type has its own `send` for guest payloads.
+ Darwin.send(session.socket, raw.baseAddress, raw.count, 0)
+ }
+ if sent != payload.count {
+ // EAGAIN (the host's buffer is full) or EMSGSIZE (the datagram is
+ // larger than this socket will carry). Either way the datagram is
+ // gone, and a silent drop here looks like the network misbehaving.
+ Self.log.error("udp to host failed: \(sent, privacy: .public)/\(payload.count, privacy: .public)B errno \(errno, privacy: .public)")
+ }
+ }
+
+ // MARK: - Sessions
+
+ private func session(for flow: VPhoneUDPFlow) -> Session? {
+ let key = flow.key
+ if let existing = sessions[key] {
+ // A new request on the same flow is what keeps it alive.
+ if existing.flow.guestHardware.bytes != flow.guestHardware.bytes {
+ // The guest came back with a different MAC (a re-created NIC).
+ // Rebuild rather than answer to the wrong address.
+ closeSession(existing)
+ sessions[key] = nil
+ } else {
+ return existing
+ }
+ }
+ return createSession(for: flow, key: key)
+ }
+
+ private func createSession(for flow: VPhoneUDPFlow, key: VPhoneUDPFlowKey) -> Session? {
+ let destination = resolveDestination(for: flow)
+ let descriptor = socket(AF_INET, SOCK_DGRAM, 0)
+ guard descriptor >= 0 else { return nil }
+
+ var address = sockaddr_in()
+ address.sin_len = UInt8(MemoryLayout<sockaddr_in>.size)
+ address.sin_family = sa_family_t(AF_INET)
+ address.sin_port = destination.port.bigEndian
+ let octets = destination.address.bytes
+ // Both fields are network order: leaving sin_addr in host order asks for
+ // a different address entirely (EADDRNOTAVAIL on 127.0.0.1).
+ let hostOrder = UInt32(octets[0]) << 24 | UInt32(octets[1]) << 16 | UInt32(octets[2]) << 8 | UInt32(octets[3])
+ address.sin_addr = in_addr(s_addr: hostOrder.bigEndian)
+
+ // A connected UDP socket: the kernel drops datagrams from anyone else, so
+ // the guest cannot be reached by an unrelated sender.
+ let connected = withUnsafePointer(to: &address) { pointer in
+ pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+ connect(descriptor, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+ }
+ }
+ guard connected == 0 else {
+ close(descriptor)
+ return nil
+ }
+
+ let flags = fcntl(descriptor, F_GETFL, 0)
+ _ = fcntl(descriptor, F_SETFL, flags | O_NONBLOCK)
+ var bufferSize: Int32 = 256 << 10
+ _ = setsockopt(descriptor, SOL_SOCKET, SO_SNDBUF, &bufferSize, socklen_t(MemoryLayout<Int32>.size))
+ _ = setsockopt(descriptor, SOL_SOCKET, SO_RCVBUF, &bufferSize, socklen_t(MemoryLayout<Int32>.size))
+
+ let source = DispatchSource.makeReadSource(fileDescriptor: descriptor, queue: queue)
+ let session = Session(
+ socket: descriptor,
+ source: source,
+ flow: flow,
+ destination: (destination.address, destination.port),
+ lastActivity: Date(),
+ )
+ source.setEventHandler { [weak self] in self?.drain(session) }
+ source.setCancelHandler { close(descriptor) }
+ source.resume()
+ sessions[key] = session
+ return session
+ }
+
+ /// Where a flow's datagrams actually go.
+ ///
+ /// The guest is told its resolver is the gateway (`192.168.127.1`), so a
+ /// lookup arrives addressed to us. Send it to the host's resolver instead —
+ /// the same one the host itself would use, VPN or not.
+ private func resolveDestination(for flow: VPhoneUDPFlow) -> (address: VPhoneIPv4Address, port: UInt16) {
+ guard flow.destinationAddress == configuration.hostAddress, flow.destinationPort == 53 else {
+ return (flow.destinationAddress, flow.destinationPort)
+ }
+ guard let resolver = VPhoneHostResolver.preferred() else {
+ return (flow.destinationAddress, flow.destinationPort)
+ }
+ return (resolver, 53)
+ }
+
+ private func drain(_ session: Session) {
+ while true {
+ let received = readBuffer.withUnsafeMutableBytes { raw in
+ recv(session.socket, raw.baseAddress, raw.count, 0)
+ }
+ if received <= 0 { return } // EAGAIN, or an ICMP error on the flow
+ session.lastActivity = Date()
+ deliver(session.flow, Array(readBuffer[0 ..< received]))
+ }
+ }
+
+ private func reapIdleSessions() {
+ let now = Date()
+ for (key, session) in sessions where now.timeIntervalSince(session.lastActivity) >= Self.idleTimeout {
+ closeSession(session)
+ sessions[key] = nil
+ }
+ }
+
+ private func closeSession(_ session: Session) {
+ session.source.cancel()
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKit/Network/VPhoneUserspaceNetwork.swift b/VPhoneKit/VPhoneCoreKit/Network/VPhoneUserspaceNetwork.swift
new file mode 100644
index 00000000..d2f2b529
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKit/Network/VPhoneUserspaceNetwork.swift
@@ -0,0 +1,267 @@
+import Foundation
+import Virtualization
+import os
+
+// MARK: - Errors
+
+public enum VPhoneUserspaceNetworkError: Error, Equatable {
+ /// `socketpair(2)` failed.
+ case socketPairFailed(errno: Int32)
+ /// The attachment was asked for before `start()`, or after `stop()`.
+ case notRunning
+}
+
+extension VPhoneUserspaceNetworkError: CustomStringConvertible, LocalizedError {
+ public var description: String {
+ switch self {
+ case let .socketPairFailed(errno):
+ "Could not create the network device socket pair (errno \(errno))."
+ case .notRunning:
+ "The userspace network is not running."
+ }
+ }
+
+ public var errorDescription: String? { description }
+}
+
+// MARK: - The device
+
+/// A guest NIC backed entirely by this process.
+///
+/// `VZFileHandleNetworkDeviceAttachment` hands frames to us untouched — it
+/// performs no DHCP, no ARP, no translation — so everything the guest expects a
+/// network to do is implemented on this side, in `VPhoneUserspaceNetworkResponder`.
+///
+/// The point of the mode is egress: replies leave through ordinary host sockets,
+/// so they follow the host's routing table and therefore a VPN, with no root, no
+/// interface, and no change to the host's configuration. `nat` cannot do that
+/// because vmnet's masquerade is pinned to a physical interface.
+///
+/// Threading: every field is touched only on `queue`, a serial queue. Frame reads
+/// arrive as `DispatchSource` events on that queue, and `stop()` hops onto it
+/// before tearing down. That is the whole of the invariant behind
+/// `@unchecked Sendable`.
+public final class VPhoneUserspaceNetwork: @unchecked Sendable {
+ public let configuration: VPhoneUserspaceNetworkConfiguration
+
+ /// Our end of the socket pair. The other end belongs to the attachment.
+ private let socket: Int32
+ /// Held so the attachment (and therefore the VZ device tree) outlives us.
+ private let attachment: VZFileHandleNetworkDeviceAttachment
+ private let queue: DispatchQueue
+ private static let log = Logger(subsystem: "com.vphone.tunnel", category: "frames")
+ /// Reused across frames; see the note on the UDP forwarder's buffer.
+ private var frameBuffer = [UInt8](repeating: 0, count: VPhoneUserspaceNetwork.frameCapacity)
+ private var source: DispatchSourceRead?
+ /// Set by `stop()`. Cancelling the read source closes our descriptor once no
+ /// handler is running, so the pair cannot be reopened after that.
+ private var isStopped = false
+ private var responder: VPhoneUserspaceNetworkResponder
+ /// Carries the guest's UDP out to the host and the answers back. Owns one
+ /// socket per flow, so it is the thing `stop()` has to tear down.
+ ///
+ /// `lazy` because building it needs a closure over `self`, and a stored
+ /// property cannot be captured until every property is initialised. First
+ /// touch is always on `queue`.
+ private lazy var forwarder = VPhoneUDPForwarder(configuration: configuration, queue: queue) { [weak self] flow, payload in
+ self?.sendUDPReply(flow: flow, payload: payload)
+ }
+
+ /// Terminates the guest's TCP against host sockets. Owns one connection per
+ /// flow, and emits segments of its own rather than echoing ours.
+ private lazy var tcpForwarder = VPhoneTCPForwarder(queue: queue) { [weak self] flow, segment in
+ self?.sendTCPReply(flow: flow, segment: segment)
+ }
+
+ /// Largest frame we will accept from the guest. Ethernet header plus a
+ /// jumbo-sized IP packet; the guest is expected to stay within `mtu`.
+ private static let frameCapacity = 9216
+
+ public init(configuration: VPhoneUserspaceNetworkConfiguration = .default) throws {
+ var descriptors: [Int32] = [-1, -1]
+ guard socketpair(AF_UNIX, SOCK_DGRAM, 0, &descriptors) == 0 else {
+ throw VPhoneUserspaceNetworkError.socketPairFailed(errno: errno)
+ }
+ try self.init(
+ configuration: configuration,
+ guestDescriptor: descriptors[0],
+ hostDescriptor: descriptors[1],
+ )
+ }
+
+ /// Adopt a socket pair that already exists rather than making one.
+ ///
+ /// The frame loop only fails in ways a direct call cannot reproduce: a
+ /// blocking read that parks the shared queue, a `start()` that deadlocks
+ /// against the forwarders it owns. Catching those needs a real event loop,
+ /// and a test driving one needs the guest's end of the pair. That is what
+ /// this seam is for; production always goes through the initialiser above.
+ init(
+ configuration: VPhoneUserspaceNetworkConfiguration,
+ guestDescriptor: Int32,
+ hostDescriptor: Int32,
+ ) throws {
+ for descriptor in [guestDescriptor, hostDescriptor] {
+ // A SOCK_DGRAM pair has a small default buffer, and the guest can
+ // burst (a DHCP retry plus an ARP plus a DNS query) faster than we
+ // drain it. Dropping frames here would look like packet loss.
+ var size: Int32 = 4 << 20
+ _ = setsockopt(descriptor, SOL_SOCKET, SO_SNDBUF, &size, socklen_t(MemoryLayout<Int32>.size))
+ _ = setsockopt(descriptor, SOL_SOCKET, SO_RCVBUF, &size, socklen_t(MemoryLayout<Int32>.size))
+ // Non-blocking is load-bearing. `drain` loops until recv reports
+ // EAGAIN, and everything -- the UDP and TCP forwarders included --
+ // shares this one serial queue. On a blocking socket the loop parks
+ // in recv the moment the guest goes quiet, which is exactly when it
+ // is waiting for a reply, so the reply is never read. The symptom is
+ // a guest whose DNS queries leave but whose answers never arrive.
+ _ = fcntl(descriptor, F_SETFL, fcntl(descriptor, F_GETFL, 0) | O_NONBLOCK)
+ }
+
+ socket = hostDescriptor
+ attachment = VZFileHandleNetworkDeviceAttachment(
+ fileHandle: FileHandle(fileDescriptor: guestDescriptor, closeOnDealloc: true),
+ )
+ queue = DispatchQueue(label: "com.vphone.userspace-network")
+ responder = VPhoneUserspaceNetworkResponder(configuration: configuration)
+ self.configuration = configuration
+ }
+
+ /// The object to hand to `VZVirtioNetworkDeviceConfiguration.attachment`.
+ public var networkAttachment: VZNetworkDeviceAttachment { attachment }
+
+ /// Begin draining the guest's frames. Idempotent, and a no-op after `stop()`.
+ public func start() {
+ queue.sync {
+ guard !isStopped, source == nil else { return }
+ let descriptor = socket
+ let source = DispatchSource.makeReadSource(fileDescriptor: descriptor, queue: queue)
+ source.setEventHandler { [weak self] in self?.drain() }
+ // Closing the source closes the descriptor, but only once no handler
+ // is running; VZ holds its own end of the pair until the device goes.
+ source.setCancelHandler { close(descriptor) }
+ source.resume()
+ self.source = source
+ forwarder.start()
+ tcpForwarder.start()
+ Self.log.info(
+ "tunnel up: gateway \(String(describing: self.configuration.hostAddress), privacy: .public) guest \(String(describing: self.configuration.guestAddress), privacy: .public) mtu \(self.configuration.mtu, privacy: .public) resolver \(VPhoneHostResolver.preferred()?.description ?? "NONE", privacy: .public)",
+ )
+ }
+ }
+
+ /// Stop draining and close our end. Idempotent. There is no way back: the
+ /// descriptors are gone, so a later `start()` does nothing.
+ public func stop() {
+ queue.sync {
+ guard !isStopped else { return }
+ isStopped = true
+ source?.cancel()
+ source = nil
+ forwarder.stop()
+ tcpForwarder.stop()
+ }
+ }
+
+ deinit {
+ // Nothing may hop onto `queue` from deinit, so only cancel if we are
+ // already on it — which is why `stop()` exists and should be preferred.
+ source?.cancel()
+ }
+
+ // MARK: - Frame loop
+
+ private func drain() {
+ while true {
+ let received = frameBuffer.withUnsafeMutableBytes { raw in
+ recv(socket, raw.baseAddress, raw.count, 0)
+ }
+ if received <= 0 { return } // EAGAIN once the queue is empty
+ let frame = Array(frameBuffer[0 ..< received])
+ switch responder.handle(frame) {
+ case .drop:
+ continue
+ case let .reply(reply):
+ write(reply)
+ case let .forward(flow, payload):
+ // The answer arrives later, on this same queue.
+ forwarder.send(payload, for: flow)
+ case let .forwardTCP(flow, segment):
+ tcpForwarder.receive(segment, for: flow)
+ }
+ }
+ }
+
+ /// Hand a finished frame to the guest's side of the pair.
+ ///
+ /// The result matters. This is a datagram socket, so a frame the kernel
+ /// refuses is gone -- and since TCP is an ordered stream, one lost frame
+ /// leaves the guest waiting forever for a segment we never resend. Reporting
+ /// a failure here is the difference between "slow" and "silently stalled".
+ private func write(_ frame: [UInt8]) {
+ let sent = frame.withUnsafeBytes { raw in
+ send(socket, raw.baseAddress, raw.count, 0)
+ }
+ if sent != frame.count {
+ Self.log.error("frame send failed: \(sent, privacy: .public)/\(frame.count, privacy: .public) errno \(errno, privacy: .public)")
+ }
+ }
+
+ /// Wrap one forwarded datagram as if it came from where the guest sent it.
+ ///
+ /// The source address is the guest's *destination*, not our gateway address:
+ /// a DNS lookup was addressed to `192.168.127.1`, so the answer has to
+ /// appear to come from there or the guest's stack will discard it.
+ /// Wrap one TCP segment the forwarder produced.
+ ///
+ /// Same addressing rule as UDP: the source is what the guest believes it is
+ /// talking to, not our gateway address, or the guest's stack drops the
+ /// segment before its TCP ever sees it.
+ private func sendTCPReply(flow: VPhoneTCPFlow, segment: VPhoneTCPSegment) {
+ let packet = VPhoneIPv4Packet(
+ source: flow.destinationAddress,
+ destination: flow.sourceAddress,
+ proto: .tcp,
+ payload: segment.bytes(source: flow.destinationAddress, destination: flow.sourceAddress),
+ )
+ // Segments are already cut to the guest's MSS, so these normally fit in
+ // one. The call stays because a guest is free to advertise an MSS larger
+ // than the MTU we sent it, and silently emitting an oversized datagram
+ // would be the same bug as above.
+ for fragment in packet.fragmented(toFit: configuration.mtu) {
+ let frame = VPhoneEthernetFrame(
+ destination: flow.guestHardware,
+ source: .gateway,
+ etherType: .ipv4,
+ payload: fragment,
+ ).bytes
+ write(frame)
+ }
+ }
+
+ private func sendUDPReply(flow: VPhoneUDPFlow, payload: [UInt8]) {
+ let datagram = VPhoneUDPDatagram(
+ sourcePort: flow.destinationPort,
+ destinationPort: flow.sourcePort,
+ payload: payload,
+ )
+ let packet = VPhoneIPv4Packet(
+ source: flow.destinationAddress,
+ destination: flow.sourceAddress,
+ proto: .udp,
+ payload: datagram.bytes(source: flow.destinationAddress, destination: flow.sourceAddress),
+ )
+ // UDP has no layer above it to chop anything up, and QUIC rides right at
+ // the MTU boundary, so a reply that does not fit has to be fragmented
+ // here or it goes out as a datagram the guest cannot take.
+ for fragment in packet.fragmented(toFit: configuration.mtu) {
+ let frame = VPhoneEthernetFrame(
+ destination: flow.guestHardware,
+ source: .gateway,
+ etherType: .ipv4,
+ payload: fragment,
+ ).bytes
+ write(frame)
+ }
+ }
+
+}
diff --git a/VPhoneKit/VPhoneCoreKit/Network/VPhoneUserspaceNetworkResponder.swift b/VPhoneKit/VPhoneCoreKit/Network/VPhoneUserspaceNetworkResponder.swift
new file mode 100644
index 00000000..a8750274
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKit/Network/VPhoneUserspaceNetworkResponder.swift
@@ -0,0 +1,396 @@
+import Foundation
+
+// MARK: - ARP
+
+struct VPhoneARPMessage {
+ var operation: UInt16
+ var senderHardware: VPhoneMACAddress
+ var senderProtocol: VPhoneIPv4Address
+ var targetHardware: VPhoneMACAddress
+ var targetProtocol: VPhoneIPv4Address
+
+ static let ethernetIPv4 = (hardwareType: UInt16(1), protocolType: UInt16(0x0800), hardwareLength: UInt8(6), protocolLength: UInt8(4))
+ static let request: UInt16 = 1
+ static let reply: UInt16 = 2
+
+ var bytes: [UInt8] {
+ var out: [UInt8] = [
+ UInt8(Self.ethernetIPv4.hardwareType >> 8), UInt8(truncatingIfNeeded: Self.ethernetIPv4.hardwareType),
+ UInt8(Self.ethernetIPv4.protocolType >> 8), UInt8(truncatingIfNeeded: Self.ethernetIPv4.protocolType),
+ Self.ethernetIPv4.hardwareLength, Self.ethernetIPv4.protocolLength,
+ UInt8(operation >> 8), UInt8(truncatingIfNeeded: operation),
+ ]
+ out += senderHardware.bytes + senderProtocol.bytes
+ out += targetHardware.bytes + targetProtocol.bytes
+ return out
+ }
+
+ init(operation: UInt16, senderHardware: VPhoneMACAddress, senderProtocol: VPhoneIPv4Address,
+ targetHardware: VPhoneMACAddress, targetProtocol: VPhoneIPv4Address) {
+ self.operation = operation
+ self.senderHardware = senderHardware
+ self.senderProtocol = senderProtocol
+ self.targetHardware = targetHardware
+ self.targetProtocol = targetProtocol
+ }
+
+ init?(bytes: [UInt8]) {
+ guard bytes.count >= 28, bytes[0] == 0, bytes[1] == 1, bytes[2] == 0x08, bytes[3] == 0x00,
+ bytes[4] == 6, bytes[5] == 4
+ else { return nil }
+ operation = UInt16(bytes[6]) << 8 | UInt16(bytes[7])
+ senderHardware = VPhoneMACAddress(Array(bytes[8 ..< 14]))
+ senderProtocol = VPhoneIPv4Address(
+ UInt32(bytes[14]) << 24 | UInt32(bytes[15]) << 16 | UInt32(bytes[16]) << 8 | UInt32(bytes[17]),
+ )
+ targetHardware = VPhoneMACAddress(Array(bytes[18 ..< 24]))
+ targetProtocol = VPhoneIPv4Address(
+ UInt32(bytes[24]) << 24 | UInt32(bytes[25]) << 16 | UInt32(bytes[26]) << 8 | UInt32(bytes[27]),
+ )
+ }
+}
+
+// MARK: - DHCP
+
+/// The BOOTP/DHCP subset needed to hand one guest one address.
+///
+/// Only `DISCOVER`/`REQUEST` are understood and only `OFFER`/`ACK` are emitted.
+/// No lease is held: the same address is offered every time, which is all a
+/// single-guest VM needs and keeps allocation out of the picture.
+struct VPhoneDHCPMessage {
+ enum MessageType: UInt8 {
+ case discover = 1
+ case offer = 2
+ case request = 3
+ case decline = 4
+ case ack = 5
+ case nak = 6
+ case release = 7
+ }
+
+ static let serverPort: UInt16 = 67
+ static let clientPort: UInt16 = 68
+ private static let magicCookie: [UInt8] = [0x63, 0x82, 0x53, 0x63]
+
+ var operation: UInt8
+ var transactionID: UInt32
+ var clientHardware: VPhoneMACAddress
+ var broadcastFlag: Bool
+ var options: [UInt8]
+
+ /// The first option 53 we can find, which is the message type.
+ var messageType: MessageType? {
+ var index = 0
+ while index < options.count {
+ let code = options[index]
+ if code == 255 { return nil }
+ guard index + 1 < options.count else { return nil }
+ let length = Int(options[index + 1])
+ guard index + 2 + length <= options.count else { return nil }
+ if code == 53, length == 1 { return MessageType(rawValue: options[index + 2]) }
+ index += 2 + length
+ }
+ return nil
+ }
+
+ init(operation: UInt8, transactionID: UInt32, clientHardware: VPhoneMACAddress,
+ broadcastFlag: Bool, options: [UInt8]) {
+ self.operation = operation
+ self.transactionID = transactionID
+ self.clientHardware = clientHardware
+ self.broadcastFlag = broadcastFlag
+ self.options = options
+ }
+
+ init?(bytes: [UInt8]) {
+ guard bytes.count >= 240, bytes[236 ..< 240].elementsEqual(Self.magicCookie) else { return nil }
+ operation = bytes[0]
+ transactionID = UInt32(bytes[4]) << 24 | UInt32(bytes[5]) << 16 | UInt32(bytes[6]) << 8 | UInt32(bytes[7])
+ broadcastFlag = UInt16(bytes[10]) << 8 | UInt16(bytes[11]) != 0
+ clientHardware = VPhoneMACAddress(Array(bytes[28 ..< 34]))
+ options = Array(bytes[240...])
+ }
+
+ /// Build a reply. `assigned` is the address the guest should use.
+ static func reply(
+ type: MessageType,
+ to request: VPhoneDHCPMessage,
+ assigned: VPhoneIPv4Address,
+ server: VPhoneIPv4Address,
+ netmask: VPhoneIPv4Address,
+ mtu: Int,
+ leaseSeconds: UInt32 = 86_400,
+ ) -> [UInt8] {
+ var out = [UInt8](repeating: 0, count: 236)
+ out[0] = 2 // BOOTREPLY
+ out[1] = 1 // Ethernet
+ out[2] = 6 // hardware address length
+ out[3] = 0
+ out[4] = UInt8(truncatingIfNeeded: request.transactionID >> 24)
+ out[5] = UInt8(truncatingIfNeeded: request.transactionID >> 16)
+ out[6] = UInt8(truncatingIfNeeded: request.transactionID >> 8)
+ out[7] = UInt8(truncatingIfNeeded: request.transactionID)
+ // Echo the broadcast flag so a guest that cannot receive unicast before
+ // it owns an address still hears us.
+ out[10] = request.broadcastFlag ? 0x80 : 0x00
+ out[16 ..< 20] = assigned.bytes[...] // yiaddr: the lease
+ out[28 ..< 34] = request.clientHardware.bytes[...]
+ out += Self.magicCookie
+
+ var options: [UInt8] = []
+ func append(_ code: UInt8, _ values: [UInt8]) {
+ options += [code, UInt8(values.count)] + values
+ }
+ append(53, [type.rawValue])
+ append(54, server.bytes) // server identifier
+ append(51, withUnsafeBytes(of: leaseSeconds.bigEndian, Array.init)) // lease time
+ append(1, netmask.bytes) // subnet mask
+ append(3, server.bytes) // router
+ append(6, server.bytes) // DNS
+ append(26, [UInt8(mtu >> 8), UInt8(mtu & 0xFF)]) // interface MTU
+ options.append(255)
+ // Pad to the minimum BOOTP payload so short replies stay well-formed.
+ while (out.count + options.count) < 300 { options.append(0) }
+ return out + options
+ }
+}
+
+// MARK: - Responder
+
+/// One guest UDP flow, identified by both ends so a reply can be addressed back
+/// without keeping a mapping the other way round.
+struct VPhoneUDPFlow: Hashable {
+ let sourceAddress: VPhoneIPv4Address
+ let sourcePort: UInt16
+ let destinationAddress: VPhoneIPv4Address
+ let destinationPort: UInt16
+ /// The guest's MAC, learned from the frame. Carried here so the forwarder can
+ /// build a reply without reaching back into the responder.
+ let guestHardware: VPhoneMACAddress
+
+ /// Identity as the forwarder keys sessions: one host socket per flow, reused
+ /// while both ends stay the same.
+ var key: VPhoneUDPFlowKey {
+ VPhoneUDPFlowKey(sourceAddress: sourceAddress, sourcePort: sourcePort, destinationAddress: destinationAddress, destinationPort: destinationPort)
+ }
+}
+
+struct VPhoneUDPFlowKey: Hashable {
+ let sourceAddress: VPhoneIPv4Address
+ let sourcePort: UInt16
+ let destinationAddress: VPhoneIPv4Address
+ let destinationPort: UInt16
+}
+
+/// What a frame from the guest asks for.
+enum VPhoneUserspaceNetworkOutcome {
+ /// Send this frame straight back.
+ case reply([UInt8])
+ /// The frame is a UDP payload for somewhere beyond the guest; the forwarder
+ /// owns the answer, which arrives later.
+ case forward(flow: VPhoneUDPFlow, payload: [UInt8])
+ /// The frame is a TCP segment. TCP is terminated rather than relayed, so the
+ /// forwarder keeps the connection and emits segments of its own.
+ case forwardTCP(flow: VPhoneTCPFlow, segment: VPhoneTCPSegment)
+ /// Nothing to say.
+ case drop
+}
+
+/// Turns a frame from the guest into at most one frame back.
+///
+/// Everything here is deliberately pure apart from `guestMAC`, which is learned
+/// from the traffic: Virtualization.framework assigns the MAC and does not
+/// expose it, so the first frame the guest sends is the only place to find out
+/// what it is. That makes the type stateful, which is why the caller owns it
+/// behind a serial queue rather than treating it as a free function.
+final class VPhoneUserspaceNetworkResponder {
+ private let configuration: VPhoneUserspaceNetworkConfiguration
+ private var guestMAC: VPhoneMACAddress?
+
+ init(configuration: VPhoneUserspaceNetworkConfiguration) {
+ self.configuration = configuration
+ }
+
+ var netmask: VPhoneIPv4Address { VPhoneIPv4Address(255, 255, 255, 0) }
+
+ func handle(_ frame: [UInt8]) -> VPhoneUserspaceNetworkOutcome {
+ guard let ethernet = VPhoneEthernetFrame(bytes: frame) else { return .drop }
+ // Learn (or refresh) the guest's address from anything it sends.
+ if ethernet.source != VPhoneMACAddress.gateway {
+ guestMAC = ethernet.source
+ }
+ guard let etherType = VPhoneEtherType(rawValue: ethernet.etherType) else { return .drop }
+
+ switch etherType {
+ case .arp:
+ guard let message = VPhoneARPMessage(bytes: ethernet.payload) else { return .drop }
+ return respondToARP(message).map { .reply($0) } ?? .drop
+ case .ipv4:
+ guard let packet = VPhoneIPv4Packet(bytes: ethernet.payload) else { return .drop }
+ return respondToIPv4(packet)
+ }
+ }
+
+ // MARK: - ARP
+
+ private func respondToARP(_ message: VPhoneARPMessage) -> [UInt8]? {
+ // Only answer for ourselves, and only for requests. A gratuitous
+ // announcement needs no reply.
+ guard message.operation == VPhoneARPMessage.request,
+ message.targetProtocol == configuration.hostAddress
+ else { return nil }
+
+ let reply = VPhoneARPMessage(
+ operation: VPhoneARPMessage.reply,
+ senderHardware: .gateway,
+ senderProtocol: configuration.hostAddress,
+ targetHardware: message.senderHardware,
+ targetProtocol: message.senderProtocol,
+ )
+ return VPhoneEthernetFrame(
+ destination: message.senderHardware,
+ source: .gateway,
+ etherType: .arp,
+ payload: reply.bytes,
+ ).bytes
+ }
+
+ // MARK: - IPv4
+
+ private func respondToIPv4(_ packet: VPhoneIPv4Packet) -> VPhoneUserspaceNetworkOutcome {
+ // A fragment is only part of a datagram, and nothing here reassembles, so
+ // acting on it would mean reading an incomplete transport header.
+ guard !packet.isFragment else { return .drop }
+ guard let proto = VPhoneIPProtocol(rawValue: packet.proto) else { return .drop }
+ switch proto {
+ case .icmp:
+ return respondToICMP(packet).map { .reply($0) } ?? .drop
+ case .udp:
+ return respondToUDP(packet)
+ case .tcp:
+ return respondToTCP(packet)
+ }
+ }
+
+ private func respondToICMP(_ packet: VPhoneIPv4Packet) -> [UInt8]? {
+ // Answer pings for the gateway address only. Anything beyond it needs
+ // egress, which is a later stage.
+ guard packet.destination == configuration.hostAddress,
+ packet.payload.count >= 8, packet.payload[0] == 8, packet.payload[1] == 0
+ else { return nil }
+
+ var payload = packet.payload
+ payload[0] = 0 // echo reply
+ payload[1] = 0
+ payload[2] = 0
+ payload[3] = 0
+ let sum = VPhoneInternetChecksum.compute(payload)
+ payload[2] = UInt8(sum >> 8)
+ payload[3] = UInt8(sum & 0xFF)
+
+ let reply = VPhoneIPv4Packet(
+ source: configuration.hostAddress,
+ destination: packet.source == .any ? configuration.guestAddress : packet.source,
+ proto: .icmp,
+ payload: payload,
+ )
+ return encapsulate(reply.bytes, destinationMAC: guestMAC ?? broadcastMAC)
+ }
+
+ private func respondToUDP(_ packet: VPhoneIPv4Packet) -> VPhoneUserspaceNetworkOutcome {
+ guard let datagram = VPhoneUDPDatagram(bytes: packet.payload) else { return .drop }
+
+ // DHCP is the one UDP exchange this side finishes itself: the guest is
+ // asking us, by definition.
+ if let reply = respondToDHCP(packet, datagram) { return .reply(reply) }
+
+ // Everything else is egress. The answer has to reach the guest, so we
+ // need its MAC — and until it has sent something we do not have it.
+ guard let guestMAC, packet.source != .any else { return .drop }
+ return .forward(
+ flow: VPhoneUDPFlow(
+ sourceAddress: packet.source,
+ sourcePort: datagram.sourcePort,
+ destinationAddress: packet.destination,
+ destinationPort: datagram.destinationPort,
+ guestHardware: guestMAC,
+ ),
+ payload: datagram.payload,
+ )
+ }
+
+ /// Our own DHCP server, or nil when this is not a request we answer.
+ private func respondToDHCP(_ packet: VPhoneIPv4Packet, _ datagram: VPhoneUDPDatagram) -> [UInt8]? {
+ guard datagram.destinationPort == VPhoneDHCPMessage.serverPort,
+ let request = VPhoneDHCPMessage(bytes: datagram.payload)
+ else { return nil }
+
+ let type: VPhoneDHCPMessage.MessageType
+ switch request.messageType {
+ case .discover: type = .offer
+ case .request: type = .ack
+ // DECLINE/RELEASE/INFORM say nothing a single-lease server needs to act
+ // on, and unknown types are not ours to answer.
+ default: return nil
+ }
+
+ let reply = VPhoneDHCPMessage.reply(
+ type: type,
+ to: request,
+ assigned: configuration.guestAddress,
+ server: configuration.hostAddress,
+ netmask: netmask,
+ mtu: configuration.mtu,
+ )
+ let replyDatagram = VPhoneUDPDatagram(
+ sourcePort: VPhoneDHCPMessage.serverPort,
+ destinationPort: VPhoneDHCPMessage.clientPort,
+ payload: reply,
+ )
+ // The guest has no address yet, so a DHCP reply is always broadcast at
+ // the IP layer. That is what the BOOTP broadcast flag is for, and every
+ // client accepts it.
+ let wrapped = VPhoneIPv4Packet(
+ source: configuration.hostAddress,
+ destination: .broadcast,
+ proto: .udp,
+ ttl: 16,
+ payload: replyDatagram.bytes(source: configuration.hostAddress, destination: .broadcast),
+ )
+ return encapsulate(wrapped.bytes, destinationMAC: broadcastMAC)
+ }
+
+ // MARK: - TCP
+
+ /// Hand the segment to the TCP forwarder, which terminates it.
+ ///
+ /// Unlike UDP there is no local case to answer here: every guest segment
+ /// belongs to a connection the forwarder owns, and it emits whatever comes
+ /// back. A segment we cannot attribute to a guest MAC is dropped, since a
+ /// reply could not be addressed.
+ private func respondToTCP(_ packet: VPhoneIPv4Packet) -> VPhoneUserspaceNetworkOutcome {
+ guard let segment = VPhoneTCPSegment(bytes: packet.payload),
+ let guestMAC, packet.source != .any
+ else { return .drop }
+ return .forwardTCP(
+ flow: VPhoneTCPFlow(
+ sourceAddress: packet.source,
+ sourcePort: segment.sourcePort,
+ destinationAddress: packet.destination,
+ destinationPort: segment.destinationPort,
+ guestHardware: guestMAC,
+ ),
+ segment: segment,
+ )
+ }
+
+ // MARK: - Framing
+
+ private var broadcastMAC: VPhoneMACAddress {
+ VPhoneMACAddress([0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF])
+ }
+
+ private func encapsulate(_ payload: [UInt8], destinationMAC: VPhoneMACAddress) -> [UInt8] {
+ VPhoneEthernetFrame(destination: destinationMAC, source: .gateway, etherType: .ipv4, payload: payload).bytes
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKit/Support/VPhoneNetworking.swift b/VPhoneKit/VPhoneCoreKit/Support/VPhoneNetworking.swift
index 12f7bd82..cb605a31 100644
--- a/VPhoneKit/VPhoneCoreKit/Support/VPhoneNetworking.swift
+++ b/VPhoneKit/VPhoneCoreKit/Support/VPhoneNetworking.swift
@@ -21,7 +21,7 @@ extension VPhoneNetworkingError: CustomStringConvertible, LocalizedError {
public var description: String {
switch self {
case .hostOnlyUnsupported:
- "Network mode 'hostOnly' is not supported. Use nat, bridged, or none."
+ "Network mode 'hostOnly' is not supported. Use nat, bridged, tunnel, or none."
case let .bridgeInterfaceNotFound(requested, available):
"Bridge interface '\(requested)' not found. Available: \(available.isEmpty ? "none" : available.joined(separator: ", "))."
case .noBridgeInterfaces:
@@ -116,16 +116,28 @@ public enum VPhoneNetworking {
/// Build the VZ network device for a config, or nil for `.off` (no NIC).
/// The MAC is left framework-assigned; a forced MAC breaks guest networking.
/// Throws if the config cannot be realized (missing bridge interface, hostOnly).
- public static func makeNetworkDevice(_ cfg: NetworkConfig) throws -> VZVirtioNetworkDeviceConfiguration? {
+ ///
+ /// The returned `backend` is non-nil only for `.tunnel`, where the network is
+ /// implemented in this process. It is a reference type whose sockets live as
+ /// long as the last holder, so the caller must keep it for the whole time the
+ /// VM runs, and should `start()` it once the VM does.
+ public static func makeNetworkDevice(_ cfg: NetworkConfig) throws
+ -> (device: VZVirtioNetworkDeviceConfiguration?, backend: VPhoneUserspaceNetwork?)
+ {
switch cfg.mode {
case .off:
- return nil
+ return (nil, nil)
case .hostOnly:
throw VPhoneNetworkingError.hostOnlyUnsupported
case .nat:
let net = VZVirtioNetworkDeviceConfiguration()
net.attachment = VZNATNetworkDeviceAttachment()
- return net
+ return (net, nil)
+ case .tunnel:
+ let network = try VPhoneUserspaceNetwork()
+ let net = VZVirtioNetworkDeviceConfiguration()
+ net.attachment = network.networkAttachment
+ return (net, network)
case .bridged:
guard let id = cfg.bridgeInterface else {
throw VPhoneNetworkingError.noBridgeInterfaces
@@ -138,7 +150,7 @@ public enum VPhoneNetworking {
}
let net = VZVirtioNetworkDeviceConfiguration()
net.attachment = VZBridgedNetworkDeviceAttachment(interface: iface)
- return net
+ return (net, nil)
}
}
}
diff --git a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneVirtualMachineManifest.swift b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneVirtualMachineManifest.swift
index 37ab3e96..dd555ee4 100644
--- a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneVirtualMachineManifest.swift
+++ b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneVirtualMachineManifest.swift
@@ -162,6 +162,11 @@ public struct VPhoneVirtualMachineManifest: Codable, Sendable {
case nat
case bridged
case hostOnly
+ /// The guest's NIC is carried by this process. Egress leaves through
+ /// ordinary host sockets, so it follows the host's routing table —
+ /// and therefore a VPN — which vmnet's `nat` cannot do because its
+ /// masquerade is pinned to a physical interface.
+ case tunnel
/// No network device. Named `off` (not `none`) so a `NetworkMode?`
/// literal `.none` can't silently bind to `Optional.none`.
case off = "none"
diff --git a/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneInternetProtocolTests.swift b/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneInternetProtocolTests.swift
new file mode 100644
index 00000000..0bfe067c
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneInternetProtocolTests.swift
@@ -0,0 +1,123 @@
+import Foundation
+import Testing
+@testable import VPhoneCoreKit
+
+/// Tests for the parts of the IP and TCP encodings that the forwarders depend
+/// on, kept separate from the frame-level tests because they are about the
+/// encoding rather than about anything the loop does with it.
+struct VPhoneInternetProtocolTests {
+ // MARK: - IP fragmentation
+
+ /// A datagram that does not fit has to be split, not truncated.
+ ///
+ /// This is what made QUIC unusable at first: the guest advertised a 1280 MTU,
+ /// QUIC rode right at that boundary, and a reply with a 1280-byte payload
+ /// plus the headers came to 1308. Sending it whole got it dropped, silently,
+ /// once per datagram. UDP has no layer above it to chop anything up, so the
+ /// splitting has to happen here.
+ @Test func `an oversized packet is fragmented rather than dropped`() {
+ let payload = [UInt8](repeating: 0x5A, count: 3000)
+ let packet = VPhoneIPv4Packet(
+ source: VPhoneIPv4Address(192, 168, 127, 1),
+ destination: VPhoneIPv4Address(192, 168, 127, 3),
+ proto: .udp,
+ payload: payload,
+ )
+
+ let fragments = packet.fragmented(toFit: 1500)
+ #expect(fragments.count > 1, "a 3020-byte packet must not go out in one piece")
+
+ for fragment in fragments {
+ #expect(fragment.count <= 1500, "a fragment is \(fragment.count)B, over the MTU")
+ let parsed = try? #require(VPhoneIPv4Packet(bytes: fragment))
+ #expect(parsed?.isFragment == true)
+ }
+
+ // Every fragment but the last says more are coming, and the offsets walk
+ // forward in 8-byte units.
+ let parsed = fragments.compactMap { VPhoneIPv4Packet(bytes: $0) }
+ #expect(parsed.count == fragments.count, "a fragment did not parse back")
+ for fragment in parsed.dropLast() {
+ #expect(fragment.moreFragments, "a non-final fragment did not set MF")
+ }
+ #expect(parsed.last?.moreFragments == false, "the final fragment set MF")
+
+ let reassembled = parsed.flatMap(\.payload)
+ #expect(reassembled == payload, "the fragments do not reassemble to the original")
+ }
+
+ /// A packet that already fits must not be fragmented -- extra headers for
+ /// nothing, and offsets a peer would have to reassemble.
+ @Test func `a packet that fits is left alone`() {
+ let packet = VPhoneIPv4Packet(
+ source: VPhoneIPv4Address(192, 168, 127, 1),
+ destination: VPhoneIPv4Address(192, 168, 127, 3),
+ proto: .udp,
+ payload: [UInt8](repeating: 0x5A, count: 100),
+ )
+ let fragments = packet.fragmented(toFit: 1500)
+ #expect(fragments.count == 1)
+ #expect(fragments.first.map { VPhoneIPv4Packet(bytes: $0)?.isFragment } == false)
+ }
+
+ /// Each fragment carries its own header checksum, so a reassembling peer can
+ /// tell a corrupted piece from a lost one.
+ @Test func `each fragment carries a valid checksum`() {
+ let packet = VPhoneIPv4Packet(
+ source: VPhoneIPv4Address(192, 168, 127, 1),
+ destination: VPhoneIPv4Address(192, 168, 127, 3),
+ proto: .udp,
+ payload: [UInt8](repeating: 0x77, count: 4000),
+ )
+ for fragment in packet.fragmented(toFit: 1500) {
+ #expect(VPhoneIPv4Packet(bytes: fragment) != nil, "a fragment failed its checksum")
+ }
+ }
+
+ // MARK: - Encodings the forwarders rely on
+
+ /// The checksum has to cover the pseudo-header, or a peer rejects every
+ /// segment. TCP and UDP differ only in the protocol number.
+ @Test func `the TCP checksum covers the pseudo-header`() {
+ let source = VPhoneIPv4Address(192, 168, 127, 3)
+ let destination = VPhoneIPv4Address(142, 250, 1, 1)
+ let segment = VPhoneTCPSegment(
+ sourcePort: 51_000,
+ destinationPort: 443,
+ sequenceNumber: 1234,
+ acknowledgmentNumber: 5678,
+ flags: VPhoneTCPFlags.ack | VPhoneTCPFlags.psh,
+ windowSize: 65_535,
+ payload: Array("hello".utf8),
+ )
+ let bytes = segment.bytes(source: source, destination: destination)
+ let pseudo = VPhoneInternetChecksum.pseudoHeader(
+ source: source,
+ destination: destination,
+ proto: VPhoneIPProtocol.tcp.rawValue,
+ length: bytes.count,
+ )
+ #expect(VPhoneInternetChecksum.compute(bytes, seed: pseudo) == 0, "checksum does not verify")
+ }
+
+ /// Window scaling has to survive the option encoding, and the option list has
+ /// to pad to a 32-bit boundary or the data offset is wrong.
+ @Test func `TCP options round trip and pad to a word boundary`() {
+ let segment = VPhoneTCPSegment(
+ sourcePort: 1,
+ destinationPort: 2,
+ sequenceNumber: 0,
+ acknowledgmentNumber: 0,
+ flags: VPhoneTCPFlags.syn,
+ windowSize: 65_535,
+ maximumSegmentSize: 1460,
+ advertisedWindowScale: 7,
+ )
+ let bytes = segment.bytes(source: .any, destination: .any)
+ #expect(bytes[12] >> 4 == 7, "the header should be 28 bytes, i.e. 7 words")
+
+ let parsed = try? #require(VPhoneTCPSegment(bytes: bytes))
+ #expect(parsed?.maximumSegmentSize == 1460)
+ #expect(parsed?.windowScale == 7)
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneTCPForwarderTests.swift b/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneTCPForwarderTests.swift
new file mode 100644
index 00000000..7a458f5a
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneTCPForwarderTests.swift
@@ -0,0 +1,526 @@
+import Foundation
+import Testing
+@testable import VPhoneCoreKit
+
+/// Behaviour tests for the TCP forwarder.
+///
+/// These drive the forwarder the way the frame loop does and play the guest's
+/// part, so what is under test is the forwarder's own decisions -- how much it
+/// sends, when it sends it again, what it advertises -- against a real host
+/// socket on the loopback interface.
+///
+/// Every bug found against a real guest lived here: a window it did not honour,
+/// a retransmission that did not exist, a scale it never negotiated, an upload
+/// path that spun instead of waiting. They all passed the frame-level tests in
+/// `VPhoneUserspaceNetworkTests`, which is the point of having both.
+struct VPhoneTCPForwarderTests {
+ // MARK: - Shared plumbing
+
+ /// A mutex box, because the forwarder's callback fires on its own queue and
+ /// Swift 6 will not let that touch a captured `var`.
+ private final class Box<Value>: @unchecked Sendable {
+ private let lock = NSLock()
+ private var value: Value
+
+ init(_ value: Value) { self.value = value }
+
+ func withLock<Result>(_ body: (inout Value) -> Result) -> Result {
+ lock.lock()
+ defer { lock.unlock() }
+ return body(&value)
+ }
+ }
+
+ /// Plays the guest: hands segments to the forwarder and records what comes
+ /// back, exactly as the frame loop's `deliver` would.
+ private final class Harness: @unchecked Sendable {
+ let forwarder: VPhoneTCPForwarder
+ let flow: VPhoneTCPFlow
+ let guestPort: UInt16
+
+ private let queue: DispatchQueue
+ private let recorded = Box<[VPhoneTCPSegment]>([])
+ /// When set, the harness answers every segment the way a guest stack
+ /// would: acknowledge at once, window wide open. Used by the tests that
+ /// are about the send path rather than about windowing.
+ private let acknowledgesImmediately = Box(false)
+
+ init(guestPort: UInt16, destinationPort: UInt16, mss: Int = 1460) {
+ self.guestPort = guestPort
+ let queue = DispatchQueue(label: "forwarder-tests.\(guestPort)")
+ let recorded = self.recorded
+ let acknowledgesImmediately = self.acknowledgesImmediately
+ let flow = VPhoneTCPFlow(
+ sourceAddress: VPhoneUserspaceNetworkConfiguration.default.guestAddress,
+ sourcePort: guestPort,
+ destinationAddress: VPhoneIPv4Address(127, 0, 0, 1),
+ destinationPort: destinationPort,
+ guestHardware: VPhoneMACAddress([0x02, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE]),
+ )
+ self.queue = queue
+ self.flow = flow
+
+ // The callback needs the forwarder, and the forwarder needs the
+ // callback, so the reference goes through a box filled in below.
+ let box = Box<VPhoneTCPForwarder?>(nil)
+ forwarder = VPhoneTCPForwarder(queue: queue) { _, segment in
+ recorded.withLock { $0.append(segment) }
+ guard !segment.payload.isEmpty, acknowledgesImmediately.withLock({ $0 }) else { return }
+ let acknowledgment = VPhoneTCPSegment(
+ sourcePort: guestPort,
+ destinationPort: 0,
+ sequenceNumber: segment.sequenceNumber,
+ acknowledgmentNumber: segment.sequenceNumber &+ UInt32(segment.payload.count),
+ flags: VPhoneTCPFlags.ack,
+ windowSize: 65_535,
+ )
+ // Async rather than direct: `receive` re-enters the same object,
+ // and this way the recursion depth stays bounded.
+ queue.async { box.withLock { $0 }?.receive(acknowledgment, for: flow) }
+ }
+ box.withLock { $0 = forwarder }
+ _ = mss
+ }
+
+ func acknowledgeImmediately() { acknowledgesImmediately.withLock { $0 = true } }
+
+ /// What the forwarder has put on the wire, oldest first.
+ var sent: [VPhoneTCPSegment] { recorded.withLock { $0 } }
+
+ /// Our ISN, read off the SYN-ACK the only way any peer could.
+ var ourISN: UInt32? { sent.first { $0.hasSYN && $0.hasACK }?.sequenceNumber }
+
+ /// Bytes of *distinct* sequence numbers. A retransmission repeats a range
+ /// rather than extending it, so counting transmissions would overcount.
+ var sentDataBytes: Int {
+ var unique: [UInt32: Int] = [:]
+ for segment in sent where !segment.payload.isEmpty {
+ unique[segment.sequenceNumber] = segment.payload.count
+ }
+ return unique.values.reduce(0, +)
+ }
+
+ /// Distinct sequence numbers and their sizes, ascending.
+ var dataBySequence: [(sequence: UInt32, count: Int)] {
+ var unique: [UInt32: Int] = [:]
+ for segment in sent where !segment.payload.isEmpty {
+ unique[segment.sequenceNumber] = segment.payload.count
+ }
+ return unique.sorted { $0.key < $1.key }.map { (sequence: $0.key, count: $0.value) }
+ }
+
+ func feed(_ segment: VPhoneTCPSegment) { queue.sync { forwarder.receive(segment, for: flow) } }
+ func start() { queue.sync { forwarder.start() } }
+ func stop() { queue.sync { forwarder.stop() } }
+
+ /// Wait for something a background socket is responsible for.
+ ///
+ /// Polls rather than sleeping a fixed time: the far end of these tests is
+ /// a real socket, so there is no moment at which it is known to be done.
+ @discardableResult
+ func waitUntil(_ what: String, timeout: TimeInterval = 8, _ predicate: () -> Bool) -> Bool {
+ let deadline = Date().addingTimeInterval(timeout)
+ while Date() < deadline {
+ if predicate() { return true }
+ usleep(10_000)
+ }
+ Issue.record("timed out waiting for \(what)")
+ return false
+ }
+ }
+
+ /// A one-connection TCP server on the loopback interface, so the forwarder
+ /// has something real to terminate against.
+ private final class LoopbackServer: @unchecked Sendable {
+ let port: UInt16
+ private let listener: Int32
+ private let received = Box(0)
+ private let finished = Box(false)
+
+ /// - Parameter session: runs with the accepted socket on a background
+ /// queue and owns closing it.
+ init(session: @escaping @Sendable (Int32, LoopbackServer) -> Void) throws {
+ listener = socket(AF_INET, SOCK_STREAM, 0)
+ guard listener >= 0 else { throw Error.socketFailed }
+
+ var reuse: Int32 = 1
+ setsockopt(listener, SOL_SOCKET, SO_REUSEADDR, &reuse, socklen_t(MemoryLayout<Int32>.size))
+
+ var address = sockaddr_in()
+ address.sin_len = UInt8(MemoryLayout<sockaddr_in>.size)
+ address.sin_family = sa_family_t(AF_INET)
+ address.sin_port = 0 // let the kernel choose
+ address.sin_addr = in_addr(s_addr: UInt32(0x7F00_0001).bigEndian)
+ let bound = withUnsafePointer(to: &address) { pointer in
+ pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+ bind(listener, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+ }
+ }
+ guard bound == 0 else { throw Error.bindFailed }
+ guard listen(listener, 4) == 0 else { throw Error.listenFailed }
+
+ var assigned = sockaddr_in()
+ var length = socklen_t(MemoryLayout<sockaddr_in>.size)
+ _ = withUnsafeMutablePointer(to: &assigned) { pointer in
+ pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+ getsockname(listener, $0, &length)
+ }
+ }
+ port = UInt16(bigEndian: assigned.sin_port)
+
+ let descriptor = listener
+ let server = self
+ DispatchQueue.global().async {
+ let client = accept(descriptor, nil, nil)
+ defer { server.finished.withLock { $0 = true } }
+ guard client >= 0 else { return }
+ defer { close(client) }
+ session(client, server)
+ }
+ }
+
+ /// Bytes pulled out of the socket by the session.
+ var bytesReceived: Int { received.withLock { $0 } }
+ /// Whether the session has returned.
+ var isFinished: Bool { finished.withLock { $0 } }
+
+ /// Read and count everything the guest sends.
+ func drain(_ client: Int32) {
+ var buffer = [UInt8](repeating: 0, count: 65_536)
+ while true {
+ let read = recv(client, &buffer, buffer.count, 0)
+ if read <= 0 { return }
+ received.withLock { $0 += read }
+ }
+ }
+
+ /// Read and count, stopping early once `target` bytes have arrived.
+ func drain(_ client: Int32, until target: Int) {
+ var buffer = [UInt8](repeating: 0, count: 65_536)
+ while bytesReceived < target {
+ let read = recv(client, &buffer, buffer.count, 0)
+ if read <= 0 { return }
+ received.withLock { $0 += read }
+ }
+ }
+
+ func stop() { close(listener) }
+
+ enum Error: Swift.Error {
+ case socketFailed
+ case bindFailed
+ case listenFailed
+ }
+ }
+
+ /// Complete the three-way handshake, returning our ISN.
+ @discardableResult
+ private func handshake(
+ _ harness: Harness,
+ guestSequence: UInt32 = 1000,
+ window: UInt16 = 65_535,
+ mss: Int = 1460,
+ windowScale: Int? = nil,
+ ) throws -> UInt32 {
+ harness.feed(VPhoneTCPSegment(
+ sourcePort: harness.guestPort,
+ destinationPort: harness.flow.destinationPort,
+ sequenceNumber: guestSequence,
+ acknowledgmentNumber: 0,
+ flags: VPhoneTCPFlags.syn,
+ windowSize: window,
+ maximumSegmentSize: mss,
+ windowScale: windowScale,
+ ))
+ try #require(harness.waitUntil("the SYN-ACK") { harness.ourISN != nil })
+ let isn = try #require(harness.ourISN)
+ harness.feed(VPhoneTCPSegment(
+ sourcePort: harness.guestPort,
+ destinationPort: harness.flow.destinationPort,
+ sequenceNumber: guestSequence &+ 1,
+ acknowledgmentNumber: isn &+ 1,
+ flags: VPhoneTCPFlags.ack,
+ windowSize: window,
+ ))
+ return isn
+ }
+
+ /// Ask the host for data: a push with the peek byte.
+ private func request(_ harness: Harness, acknowledged: UInt32, window: UInt16 = 65_535) {
+ harness.feed(VPhoneTCPSegment(
+ sourcePort: harness.guestPort,
+ destinationPort: harness.flow.destinationPort,
+ sequenceNumber: 1001,
+ acknowledgmentNumber: acknowledged,
+ flags: VPhoneTCPFlags.ack | VPhoneTCPFlags.psh,
+ windowSize: window,
+ payload: [0x41],
+ ))
+ }
+
+ // MARK: - The guest's window
+
+ /// The window is a promise about how much the guest can take. Sending past
+ /// it is how a download stalls halfway: the extra segments are discarded,
+ /// nothing is sent again, and both ends sit waiting.
+ @Test func `a transfer does not outrun the window the guest advertises`() async throws {
+ let total = 5000
+ let payload = [UInt8](repeating: 0x5A, count: total)
+ let server = try LoopbackServer { client, server in
+ var buffer = [UInt8](repeating: 0, count: 4096)
+ _ = recv(client, &buffer, buffer.count, 0)
+ var sent = 0
+ while sent < payload.count {
+ let written = payload.withUnsafeBytes { send(client, $0.baseAddress, $0.count, 0) }
+ if written <= 0 { break }
+ sent += written
+ }
+ _ = server.drain(client)
+ }
+ defer { server.stop() }
+
+ let harness = Harness(guestPort: 51_001, destinationPort: server.port)
+ harness.start()
+ defer { harness.stop() }
+
+ let window: UInt16 = 2048
+ let isn = try handshake(harness, window: window, mss: 1024)
+ request(harness, acknowledged: isn &+ 1, window: window)
+
+ try #require(harness.waitUntil("the first burst") { harness.sentDataBytes > 0 })
+ try await Task.sleep(for: .seconds(1)) // let it overshoot if it is going to
+ let afterFirstWindow = harness.sentDataBytes
+ #expect(
+ afterFirstWindow <= Int(window),
+ "sent \(afterFirstWindow)B into a \(window)B window",
+ )
+ #expect(afterFirstWindow > 0, "nothing was sent even with the window open")
+
+ // Advance the window; the transfer must resume.
+ var acknowledged = isn &+ 1 &+ UInt32(afterFirstWindow)
+ for _ in 2 ... 8 {
+ harness.feed(VPhoneTCPSegment(
+ sourcePort: harness.guestPort,
+ destinationPort: server.port,
+ sequenceNumber: 1001 &+ UInt32(afterFirstWindow),
+ acknowledgmentNumber: acknowledged,
+ flags: VPhoneTCPFlags.ack,
+ windowSize: window,
+ ))
+ let before = harness.sentDataBytes
+ harness.waitUntil("more data", timeout: 3) { harness.sentDataBytes > before }
+ acknowledged = isn &+ 1 &+ UInt32(harness.sentDataBytes)
+ if harness.sentDataBytes >= total { break }
+ }
+
+ #expect(harness.sentDataBytes >= total, "stalled at \(harness.sentDataBytes)B of \(total)B")
+
+ let ordered = harness.dataBySequence
+ let contiguous = zip(ordered, ordered.dropFirst()).allSatisfy { previous, next in
+ next.sequence == previous.sequence &+ UInt32(previous.count)
+ }
+ #expect(contiguous, "sequence numbers are not contiguous: \(ordered.map(\.sequence))")
+ #expect(ordered.allSatisfy { $0.count <= 1024 }, "a segment exceeded the guest's MSS")
+ }
+
+ // MARK: - The upload direction
+
+ /// When the host stops reading, the bytes pile up on this side. The guest has
+ /// to be told to stop -- a zero window -- and answering that by spinning
+ /// would starve every other flow sharing the queue.
+ @Test func `the upload direction applies back pressure instead of spinning`() throws {
+ let total = 1 << 20
+ let server = try LoopbackServer { client, server in
+ sleep(1) // refuse to read, so the socket buffers fill
+ server.drain(client, until: total)
+ }
+ defer { server.stop() }
+
+ let harness = Harness(guestPort: 51_002, destinationPort: server.port)
+ harness.start()
+ defer { harness.stop() }
+
+ let isn = try handshake(harness, mss: 1024)
+
+ let chunk = [UInt8](repeating: 0x42, count: 1240)
+ var sequence = UInt32(1001)
+ var remaining = total
+ let started = Date()
+ while remaining > 0 {
+ let take = min(chunk.count, remaining)
+ harness.feed(VPhoneTCPSegment(
+ sourcePort: harness.guestPort,
+ destinationPort: server.port,
+ sequenceNumber: sequence,
+ acknowledgmentNumber: isn &+ 1,
+ flags: VPhoneTCPFlags.ack | VPhoneTCPFlags.psh,
+ windowSize: 65_535,
+ payload: Array(chunk.prefix(take)),
+ ))
+ sequence &+= UInt32(take)
+ remaining -= take
+ }
+ let pushTime = Date().timeIntervalSince(started)
+
+ #expect(
+ harness.sent.contains { $0.windowSize == 0 && $0.hasACK },
+ "the guest was never told the window shut",
+ )
+ #expect(
+ harness.sent.filter { $0.windowSize > 0 && $0.payload.isEmpty }.count > 1,
+ "no window update when the backlog cleared",
+ )
+ #expect(pushTime < 10, "handing the bytes over blocked for \(String(format: "%.1f", pushTime))s")
+
+ harness.waitUntil("the host to drain", timeout: 20) { server.bytesReceived >= total }
+ #expect(server.bytesReceived >= total, "the host only saw \(server.bytesReceived)B")
+ }
+
+ // MARK: - Window scaling
+
+ /// Scaling only applies when both ends offer it, so a guest finding no
+ /// option 3 in our SYN-ACK must keep its window under 64 KiB however much
+ /// buffer it has. That ceiling, divided by the round-trip time, is the most
+ /// the connection can ever carry.
+ @Test func `window scaling is negotiated and the guest's field read at its true size`() async throws {
+ // The option survives a round trip before anything else is meaningful.
+ let offered = VPhoneTCPSegment(
+ sourcePort: 1, destinationPort: 2,
+ sequenceNumber: 0, acknowledgmentNumber: 0,
+ flags: VPhoneTCPFlags.syn,
+ windowSize: 65_535,
+ maximumSegmentSize: 1460,
+ advertisedWindowScale: 7,
+ )
+ let encoded = offered.bytes(
+ source: VPhoneIPv4Address.any,
+ destination: VPhoneIPv4Address.any,
+ )
+ let decoded = try #require(VPhoneTCPSegment(bytes: encoded))
+ #expect(decoded.maximumSegmentSize == 1460, "MSS did not survive the round trip")
+ #expect(decoded.windowScale == 7, "window scale did not survive the round trip")
+ #expect(encoded[12] >> 4 == 7, "the option list must pad to a 32-bit boundary")
+
+ let total = 400_000
+ let blob = [UInt8](repeating: 0x21, count: 65_536)
+ let server = try LoopbackServer { client, server in
+ var buffer = [UInt8](repeating: 0, count: 4096)
+ _ = recv(client, &buffer, buffer.count, 0)
+ var sent = 0
+ while sent < total {
+ let written = blob.withUnsafeBytes { raw in
+ send(client, raw.baseAddress, min(raw.count, total - sent), 0)
+ }
+ if written <= 0 { break }
+ sent += written
+ }
+ _ = server.drain(client)
+ }
+ defer { server.stop() }
+
+ let harness = Harness(guestPort: 51_003, destinationPort: server.port)
+ harness.start()
+ defer { harness.stop() }
+
+ // A guest that offers scaling, then advertises a window field of 512 --
+ // which at scale 7 means 64 KiB, not 512 bytes.
+ let isn = try handshake(harness, windowScale: 7)
+ let synAck = try #require(harness.sent.first { $0.hasSYN && $0.hasACK })
+ #expect(synAck.advertisedWindowScale == 7, "we did not offer scaling back")
+
+ harness.feed(VPhoneTCPSegment(
+ sourcePort: harness.guestPort,
+ destinationPort: server.port,
+ sequenceNumber: 1001,
+ acknowledgmentNumber: isn &+ 1,
+ flags: VPhoneTCPFlags.ack | VPhoneTCPFlags.psh,
+ windowSize: 512,
+ windowScale: 7,
+ payload: [0x41],
+ ))
+
+ try #require(harness.waitUntil("a scaled window's worth") { harness.sentDataBytes > 512 * 8 })
+ #expect(
+ harness.sentDataBytes > 512,
+ "a scaled window was read as \(harness.sentDataBytes)B, i.e. unscaled",
+ )
+ }
+
+ // MARK: - Retransmission
+
+ /// A segment the guest never acknowledges stops the connection where it
+ /// stands. The link to the guest drops nothing by itself, but that is not the
+ /// only way a segment goes unacknowledged, and with no copy kept there is
+ /// nothing to send again -- the peer just waits for a timeout.
+ @Test func `data the guest does not acknowledge is sent again`() async throws {
+ let payload = [UInt8](repeating: 0x77, count: 4000)
+ let server = try LoopbackServer { client, server in
+ var buffer = [UInt8](repeating: 0, count: 4096)
+ _ = recv(client, &buffer, buffer.count, 0)
+ _ = payload.withUnsafeBytes { send(client, $0.baseAddress, $0.count, 0) }
+ _ = server.drain(client)
+ }
+ defer { server.stop() }
+
+ let harness = Harness(guestPort: 51_004, destinationPort: server.port)
+ harness.start()
+ defer { harness.stop() }
+
+ let isn = try handshake(harness)
+ request(harness, acknowledged: isn &+ 1) // and never acknowledge the reply
+
+ try #require(harness.waitUntil("the first data") { harness.sentDataBytes > 0 })
+ let nudged = harness.waitUntil("the data to be sent again", timeout: 6) {
+ var counts: [UInt32: Int] = [:]
+ for segment in harness.sent where !segment.payload.isEmpty {
+ counts[segment.sequenceNumber, default: 0] += 1
+ }
+ return counts.values.contains { $0 > 1 }
+ }
+ #expect(nudged, "nothing was ever sent twice, so a lost segment would stall forever")
+ }
+
+ // MARK: - Throughput
+
+ /// The send path should not be the limit. Not a benchmark -- a guard that a
+ /// change to windowing or retransmission has not made it one.
+ @Test func `a promptly acknowledging guest gets the payload fast`() throws {
+ let total = 4 << 20
+ let blob = [UInt8](repeating: 0x33, count: 65_536)
+ let server = try LoopbackServer { client, server in
+ var buffer = [UInt8](repeating: 0, count: 4096)
+ _ = recv(client, &buffer, buffer.count, 0)
+ var sent = 0
+ while sent < total {
+ let written = blob.withUnsafeBytes { raw in
+ send(client, raw.baseAddress, min(raw.count, total - sent), 0)
+ }
+ if written <= 0 { break }
+ sent += written
+ }
+ _ = server.drain(client, until: total)
+ }
+ defer { server.stop() }
+
+ let harness = Harness(guestPort: 51_005, destinationPort: server.port)
+ harness.acknowledgeImmediately()
+ harness.start()
+ defer { harness.stop() }
+
+ let isn = try handshake(harness)
+ request(harness, acknowledged: isn &+ 1)
+
+ let started = Date()
+ harness.waitUntil("the payload", timeout: 25) { harness.sentDataBytes >= total }
+ let elapsed = max(Date().timeIntervalSince(started), 0.001)
+ let kibibytesPerSecond = Double(harness.sentDataBytes) / 1024 / elapsed
+ #expect(
+ harness.sentDataBytes >= total,
+ "stalled at \(harness.sentDataBytes / 1024) KiB of \(total / 1024) KiB",
+ )
+ #expect(
+ kibibytesPerSecond > 2048,
+ "the send path only managed \(Int(kibibytesPerSecond)) KiB/s",
+ )
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneUserspaceNetworkIntegrationTests.swift b/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneUserspaceNetworkIntegrationTests.swift
new file mode 100644
index 00000000..26897c4e
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneUserspaceNetworkIntegrationTests.swift
@@ -0,0 +1,257 @@
+import Foundation
+import Testing
+@testable import VPhoneCoreKit
+
+/// End-to-end tests for the frame loop.
+///
+/// Where `VPhoneUserspaceNetworkTests` feeds the responder directly, these drive
+/// the real thing: a socket pair, a `DispatchSourceRead`, the shared serial
+/// queue, and both forwarders behind it.
+///
+/// That distinction is the point. The frame-loop bugs found against a real guest
+/// -- a blocking read that parked the queue so replies were never drained, a
+/// `start()` that deadlocked the queue against the forwarders it owns -- passed
+/// every direct test and appeared only once a real event loop was involved.
+struct VPhoneUserspaceNetworkIntegrationTests {
+ private let configuration = VPhoneUserspaceNetworkConfiguration.default
+ private let guestMAC = VPhoneMACAddress([0x02, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE])
+ private let broadcastMAC = VPhoneMACAddress([0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF])
+
+ // MARK: - Standing in for the attachment
+
+ /// The guest's end of the socket pair, plus the network under test. Playing
+ /// the attachment is all this has to do: write frames in, read frames out.
+ private final class GuestLink: @unchecked Sendable {
+ let descriptor: Int32
+ private let network: VPhoneUserspaceNetwork
+
+ init(configuration: VPhoneUserspaceNetworkConfiguration) throws {
+ var pair: [Int32] = [-1, -1]
+ guard socketpair(AF_UNIX, SOCK_DGRAM, 0, &pair) == 0 else {
+ throw GuestLinkError.socketPairFailed(errno: errno)
+ }
+ descriptor = pair[0]
+ // The network takes ownership of the guest's end through the
+ // attachment; we keep using the same descriptor.
+ network = try VPhoneUserspaceNetwork(
+ configuration: configuration,
+ guestDescriptor: pair[0],
+ hostDescriptor: pair[1],
+ )
+ }
+
+ func start() { network.start() }
+ func stop() { network.stop() }
+
+ /// Put a frame on the wire the way the attachment would.
+ func write(_ frame: [UInt8]) {
+ _ = frame.withUnsafeBytes { Darwin.send(descriptor, $0.baseAddress, $0.count, 0) }
+ }
+
+ /// The next frame, or nil if one does not arrive in time.
+ ///
+ /// The descriptor is non-blocking, so this polls rather than parking.
+ func read(timeout: TimeInterval = 3) -> [UInt8]? {
+ var buffer = [UInt8](repeating: 0, count: 9216)
+ let deadline = Date().addingTimeInterval(timeout)
+ while Date() < deadline {
+ let count = recv(descriptor, &buffer, buffer.count, 0)
+ if count > 0 { return Array(buffer[0 ..< count]) }
+ usleep(5_000)
+ }
+ return nil
+ }
+
+ enum GuestLinkError: Swift.Error { case socketPairFailed(errno: Int32) }
+ }
+
+ /// A mutex box, for state a background queue has to touch.
+ private final class Box<Value>: @unchecked Sendable {
+ private let lock = NSLock()
+ private var value: Value
+
+ init(_ value: Value) { self.value = value }
+
+ func withLock<Result>(_ body: (inout Value) -> Result) -> Result {
+ lock.lock()
+ defer { lock.unlock() }
+ return body(&value)
+ }
+ }
+
+ // MARK: - Frames, from the guest's point of view
+
+ private func dhcpFrame(type: VPhoneDHCPMessage.MessageType, transactionID: UInt32 = 0x1234_5678) -> [UInt8] {
+ var message = [UInt8](repeating: 0, count: 236)
+ message[0] = 1 // BOOTREQUEST
+ message[1] = 1 // Ethernet
+ message[2] = 6 // hardware address length
+ message[4] = UInt8(truncatingIfNeeded: transactionID >> 24)
+ message[5] = UInt8(truncatingIfNeeded: transactionID >> 16)
+ message[6] = UInt8(truncatingIfNeeded: transactionID >> 8)
+ message[7] = UInt8(truncatingIfNeeded: transactionID)
+ message[10] = 0x80 // broadcast
+ message[28 ..< 34] = guestMAC.bytes[...]
+ message += [0x63, 0x82, 0x53, 0x63]
+ message += [53, 1, type.rawValue, 255]
+ let datagram = VPhoneUDPDatagram(
+ sourcePort: VPhoneDHCPMessage.clientPort,
+ destinationPort: VPhoneDHCPMessage.serverPort,
+ payload: message,
+ )
+ return VPhoneEthernetFrame(
+ destination: broadcastMAC,
+ source: guestMAC,
+ etherType: .ipv4,
+ payload: VPhoneIPv4Packet(
+ source: .any,
+ destination: .broadcast,
+ proto: .udp,
+ payload: datagram.bytes(source: .any, destination: .broadcast),
+ ).bytes,
+ ).bytes
+ }
+
+ private func arpFrame() -> [UInt8] {
+ let message = VPhoneARPMessage(
+ operation: VPhoneARPMessage.request,
+ senderHardware: guestMAC,
+ senderProtocol: configuration.guestAddress,
+ targetHardware: VPhoneMACAddress([0, 0, 0, 0, 0, 0]),
+ targetProtocol: configuration.hostAddress,
+ )
+ return VPhoneEthernetFrame(
+ destination: broadcastMAC,
+ source: guestMAC,
+ etherType: .arp,
+ payload: message.bytes,
+ ).bytes
+ }
+
+ private func icmpEchoFrame(identifier: UInt16 = 0xBEEF, sequence: UInt16 = 1) -> [UInt8] {
+ var message: [UInt8] = [8, 0, 0, 0] // echo request, checksum placeholder
+ message += [UInt8(identifier >> 8), UInt8(truncatingIfNeeded: identifier)]
+ message += [UInt8(sequence >> 8), UInt8(truncatingIfNeeded: sequence)]
+ message += Array("vphone".utf8)
+ let sum = VPhoneInternetChecksum.compute(message)
+ message[2] = UInt8(sum >> 8)
+ message[3] = UInt8(sum & 0xFF)
+ return VPhoneEthernetFrame(
+ destination: .gateway,
+ source: guestMAC,
+ etherType: .ipv4,
+ payload: VPhoneIPv4Packet(
+ source: configuration.guestAddress,
+ destination: configuration.hostAddress,
+ proto: .icmp,
+ payload: message,
+ ).bytes,
+ ).bytes
+ }
+
+ // MARK: - Tests
+
+ /// The whole DHCP exchange has to work through the loop, not just through
+ /// the responder: the guest cannot reach anything until it has a lease.
+ @Test func `a DHCP exchange completes through the real frame loop`() throws {
+ let link = try GuestLink(configuration: configuration)
+ link.start()
+ defer { link.stop() }
+
+ link.write(dhcpFrame(type: .discover))
+ let offer = try #require(link.read(), "no offer came back through the loop")
+ let offerEthernet = try #require(VPhoneEthernetFrame(bytes: offer))
+ let offerPacket = try #require(VPhoneIPv4Packet(bytes: offerEthernet.payload))
+ let offerDatagram = try #require(VPhoneUDPDatagram(bytes: offerPacket.payload))
+ let offerMessage = try #require(VPhoneDHCPMessage(bytes: offerDatagram.payload))
+ #expect(offerMessage.messageType == .offer)
+
+ link.write(dhcpFrame(type: .request))
+ let ack = try #require(link.read(), "no ack came back through the loop")
+ let ackEthernet = try #require(VPhoneEthernetFrame(bytes: ack))
+ let ackPacket = try #require(VPhoneIPv4Packet(bytes: ackEthernet.payload))
+ let ackDatagram = try #require(VPhoneUDPDatagram(bytes: ackPacket.payload))
+ let ackMessage = try #require(VPhoneDHCPMessage(bytes: ackDatagram.payload))
+ #expect(ackMessage.messageType == .ack)
+ }
+
+ /// ARP and ICMP come back too -- they are the guest's other two ways of
+ /// finding out whether the link is alive at all.
+ @Test func `ARP and ping are answered through the real frame loop`() throws {
+ let link = try GuestLink(configuration: configuration)
+ link.start()
+ defer { link.stop() }
+
+ link.write(arpFrame())
+ let arp = try #require(link.read(), "ARP went unanswered")
+ let arpEthernet = try #require(VPhoneEthernetFrame(bytes: arp))
+ #expect(arpEthernet.etherType == VPhoneEtherType.arp.rawValue)
+
+ link.write(icmpEchoFrame())
+ let ping = try #require(link.read(), "ping went unanswered")
+ let pingEthernet = try #require(VPhoneEthernetFrame(bytes: ping))
+ let pingPacket = try #require(VPhoneIPv4Packet(bytes: pingEthernet.payload))
+ #expect(pingPacket.proto == VPhoneIPProtocol.icmp.rawValue)
+ }
+
+ /// The regression test for the blocking read.
+ ///
+ /// `drain` loops until `recv` reports EAGAIN and everything shares one serial
+ /// queue. On a blocking socket the loop parks in `recv` the moment the guest
+ /// goes quiet -- which is exactly when the guest is waiting for a reply, so
+ /// the reply is never read. The guest saw DNS queries leave and no answers
+ /// come back. Going quiet between exchanges is what makes this test read.
+ @Test func `the loop keeps draining after the guest goes quiet`() async throws {
+ let link = try GuestLink(configuration: configuration)
+ link.start()
+ defer { link.stop() }
+
+ for round in 1 ... 3 {
+ link.write(dhcpFrame(type: .discover))
+ let reply = link.read()
+ #expect(reply != nil, "round \(round) went unanswered after a period of silence")
+ // Silence is the condition under test.
+ try await Task.sleep(for: .milliseconds(700))
+ }
+ }
+
+ /// The regression test for the start-up deadlock.
+ ///
+ /// `start()` runs on the network's serial queue and calls into the forwarders
+ /// it owns. If any of those hops back onto the same queue with `sync`, the
+ /// queue waits on itself and traps. Production hit this immediately; nothing
+ /// that called the forwarders directly ever would.
+ @Test func `start returns instead of deadlocking against its own forwarders`() throws {
+ let link = try GuestLink(configuration: configuration)
+ let returned = Box(false)
+ DispatchQueue.global().async {
+ link.start()
+ returned.withLock { $0 = true }
+ }
+
+ let deadline = Date().addingTimeInterval(5)
+ while Date() < deadline, !returned.withLock({ $0 }) {
+ usleep(10_000)
+ }
+ #expect(
+ returned.withLock { $0 },
+ "start() never returned -- it deadlocked on the queue it shares with its forwarders",
+ )
+ link.stop()
+ }
+
+ /// A stopped network must not answer. Otherwise teardown leaves a source
+ /// firing on a closed descriptor.
+ @Test func `a stopped network stops answering`() throws {
+ let link = try GuestLink(configuration: configuration)
+ link.start()
+ link.write(dhcpFrame(type: .discover))
+ #expect(link.read() != nil, "not answering before stop()")
+
+ link.stop()
+ // Drain anything already in flight, then confirm nothing new arrives.
+ _ = link.read(timeout: 0.2)
+ link.write(dhcpFrame(type: .discover, transactionID: 0x9999))
+ #expect(link.read(timeout: 0.5) == nil, "still answering after stop()")
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneUserspaceNetworkTests.swift b/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneUserspaceNetworkTests.swift
new file mode 100644
index 00000000..33b02dc0
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKitTests/Network/VPhoneUserspaceNetworkTests.swift
@@ -0,0 +1,438 @@
+import Foundation
+import Testing
+@testable import VPhoneCoreKit
+
+/// Frame-level tests for the userspace network.
+///
+/// The responder takes a raw Ethernet frame and returns at most one, so the
+/// whole DHCP/ARP/ICMP path can be exercised without a VM, without a socket,
+/// and without any privilege. That is how the v1.x work was validated too.
+struct VPhoneUserspaceNetworkTests {
+ private let configuration = VPhoneUserspaceNetworkConfiguration.default
+ private let guestMAC = VPhoneMACAddress([0x02, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE])
+ private let broadcastMAC = VPhoneMACAddress([0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF])
+
+ private func responder() -> VPhoneUserspaceNetworkResponder {
+ VPhoneUserspaceNetworkResponder(configuration: configuration)
+ }
+
+ // MARK: - Frame builders (guest's point of view)
+
+ private func ipv4Frame(
+ source: VPhoneIPv4Address,
+ destination: VPhoneIPv4Address,
+ proto: VPhoneIPProtocol,
+ payload: [UInt8],
+ destinationMAC: VPhoneMACAddress? = nil,
+ ) -> [UInt8] {
+ let packet = VPhoneIPv4Packet(source: source, destination: destination, proto: proto, payload: payload)
+ return VPhoneEthernetFrame(
+ destination: destinationMAC ?? broadcastMAC,
+ source: guestMAC,
+ etherType: .ipv4,
+ payload: packet.bytes,
+ ).bytes
+ }
+
+ private func dhcpFrame(type: VPhoneDHCPMessage.MessageType, transactionID: UInt32 = 0x1234_5678) -> [UInt8] {
+ var message = [UInt8](repeating: 0, count: 236)
+ message[0] = 1 // BOOTREQUEST
+ message[1] = 1 // Ethernet
+ message[2] = 6 // hardware address length
+ message[4] = UInt8(truncatingIfNeeded: transactionID >> 24)
+ message[5] = UInt8(truncatingIfNeeded: transactionID >> 16)
+ message[6] = UInt8(truncatingIfNeeded: transactionID >> 8)
+ message[7] = UInt8(truncatingIfNeeded: transactionID)
+ message[10] = 0x80 // broadcast
+ message[28 ..< 34] = guestMAC.bytes[...]
+ message += [0x63, 0x82, 0x53, 0x63]
+ message += [53, 1, type.rawValue, 255]
+ let datagram = VPhoneUDPDatagram(
+ sourcePort: VPhoneDHCPMessage.clientPort,
+ destinationPort: VPhoneDHCPMessage.serverPort,
+ payload: message,
+ )
+ return ipv4Frame(
+ source: .any,
+ destination: .broadcast,
+ proto: .udp,
+ payload: datagram.bytes(source: .any, destination: .broadcast),
+ )
+ }
+
+ private func arpFrame(targeting target: VPhoneIPv4Address, operation: UInt16 = VPhoneARPMessage.request) -> [UInt8] {
+ let message = VPhoneARPMessage(
+ operation: operation,
+ senderHardware: guestMAC,
+ senderProtocol: configuration.guestAddress,
+ targetHardware: VPhoneMACAddress([0, 0, 0, 0, 0, 0]),
+ targetProtocol: target,
+ )
+ return VPhoneEthernetFrame(
+ destination: broadcastMAC,
+ source: guestMAC,
+ etherType: .arp,
+ payload: message.bytes,
+ ).bytes
+ }
+
+ private func icmpEchoFrame(identifier: UInt16 = 0xBEEF, sequence: UInt16 = 1, payload: [UInt8] = Array("vphone".utf8)) -> [UInt8] {
+ var message: [UInt8] = [8, 0, 0, 0] // echo request, checksum placeholder
+ message += [UInt8(identifier >> 8), UInt8(truncatingIfNeeded: identifier)]
+ message += [UInt8(sequence >> 8), UInt8(truncatingIfNeeded: sequence)]
+ message += payload
+ let sum = VPhoneInternetChecksum.compute(message)
+ message[2] = UInt8(sum >> 8)
+ message[3] = UInt8(sum & 0xFF)
+ return ipv4Frame(
+ source: configuration.guestAddress,
+ destination: configuration.hostAddress,
+ proto: .icmp,
+ payload: message,
+ destinationMAC: .gateway,
+ )
+ }
+
+ // MARK: - DHCP
+
+ @Test func `discover gets an offer for the configured address`() throws {
+ let reply = try #require(responder().respond(to: dhcpFrame(type: .discover)))
+ let ethernet = try #require(VPhoneEthernetFrame(bytes: reply))
+ #expect(ethernet.destination == broadcastMAC)
+
+ let packet = try #require(VPhoneIPv4Packet(bytes: ethernet.payload))
+ #expect(packet.source == configuration.hostAddress)
+ #expect(packet.destination == .broadcast)
+
+ let datagram = try #require(VPhoneUDPDatagram(bytes: packet.payload))
+ #expect(datagram.sourcePort == VPhoneDHCPMessage.serverPort)
+ #expect(datagram.destinationPort == VPhoneDHCPMessage.clientPort)
+
+ let replyMessage = try #require(VPhoneDHCPMessage(bytes: datagram.payload))
+ #expect(replyMessage.operation == 2) // BOOTREPLY
+ #expect(replyMessage.messageType == .offer)
+ #expect(replyMessage.clientHardware.bytes == guestMAC.bytes)
+ // yiaddr, the lease itself.
+ #expect(Array(datagram.payload[16 ..< 20]) == configuration.guestAddress.bytes)
+ }
+
+ @Test func `request gets an ack`() throws {
+ let reply = try #require(responder().respond(to: dhcpFrame(type: .request)))
+ let ethernet = try #require(VPhoneEthernetFrame(bytes: reply))
+ let packet = try #require(VPhoneIPv4Packet(bytes: ethernet.payload))
+ let datagram = try #require(VPhoneUDPDatagram(bytes: packet.payload))
+ let replyMessage = try #require(VPhoneDHCPMessage(bytes: datagram.payload))
+ #expect(replyMessage.messageType == .ack)
+ }
+
+ /// The guest's own address must survive into option 51/1/3/6, or iOS will
+ /// apply the lease and then have no route or resolver.
+ @Test func `offer carries the addressing options`() throws {
+ let reply = try #require(responder().respond(to: dhcpFrame(type: .discover)))
+ let ethernet = try #require(VPhoneEthernetFrame(bytes: reply))
+ let packet = try #require(VPhoneIPv4Packet(bytes: ethernet.payload))
+ let datagram = try #require(VPhoneUDPDatagram(bytes: packet.payload))
+ let options = Array(datagram.payload[240...])
+
+ func option(_ code: UInt8) -> [UInt8]? {
+ var index = 0
+ while index + 1 < options.count, options[index] != 255 {
+ let length = Int(options[index + 1])
+ guard index + 2 + length <= options.count else { return nil }
+ if options[index] == code { return Array(options[(index + 2) ..< (index + 2 + length)]) }
+ index += 2 + length
+ }
+ return nil
+ }
+
+ #expect(option(1) == [255, 255, 255, 0]) // subnet mask
+ #expect(option(3) == configuration.hostAddress.bytes) // router
+ #expect(option(6) == configuration.hostAddress.bytes) // DNS
+ #expect(option(26) == [UInt8(configuration.mtu >> 8), UInt8(configuration.mtu & 0xFF)])
+ #expect(option(54) == configuration.hostAddress.bytes) // server identifier
+ #expect(option(51)?.count == 4)
+ }
+
+ // MARK: - ARP
+
+ @Test func `arp for the gateway is answered with our address`() throws {
+ let reply = try #require(responder().respond(to: arpFrame(targeting: configuration.hostAddress)))
+ let ethernet = try #require(VPhoneEthernetFrame(bytes: reply))
+ #expect(ethernet.destination == guestMAC)
+ #expect(ethernet.source == .gateway)
+
+ let message = try #require(VPhoneARPMessage(bytes: ethernet.payload))
+ #expect(message.operation == VPhoneARPMessage.reply)
+ #expect(message.senderProtocol == configuration.hostAddress)
+ #expect(message.senderHardware.bytes == VPhoneMACAddress.gateway.bytes)
+ #expect(message.targetHardware.bytes == guestMAC.bytes)
+ #expect(message.targetProtocol == configuration.guestAddress)
+ }
+
+ /// Anything that is not us must stay silent, so the guest's own address
+ /// resolution still works when it asks about a peer.
+ @Test func `arp for another address is ignored`() {
+ #expect(responder().respond(to: arpFrame(targeting: VPhoneIPv4Address(192, 168, 127, 99))) == nil)
+ }
+
+ @Test func `arp reply is not answered`() {
+ let frame = arpFrame(targeting: configuration.hostAddress, operation: VPhoneARPMessage.reply)
+ #expect(responder().respond(to: frame) == nil)
+ }
+
+ // MARK: - ICMP
+
+ @Test func `echo request gets an echo reply`() throws {
+ let reply = try #require(responder().respond(to: icmpEchoFrame()))
+ let ethernet = try #require(VPhoneEthernetFrame(bytes: reply))
+ #expect(ethernet.destination == guestMAC)
+ let packet = try #require(VPhoneIPv4Packet(bytes: ethernet.payload))
+ #expect(packet.source == configuration.hostAddress)
+ #expect(packet.destination == configuration.guestAddress)
+
+ let message = packet.payload
+ #expect(message[0] == 0) // echo reply
+ #expect(message[1] == 0)
+ #expect(Array(message[4 ..< 8]) == [0xBE, 0xEF, 0x00, 0x01]) // id + sequence preserved
+ #expect(Array(message[8...]) == Array("vphone".utf8)) // payload preserved
+ #expect(VPhoneInternetChecksum.compute(message) == 0) // a valid checksum sums to zero
+ }
+
+ @Test func `a ping for someone else is left alone`() {
+ let packet = VPhoneIPv4Packet(
+ source: configuration.guestAddress,
+ destination: VPhoneIPv4Address(1, 1, 1, 1),
+ proto: .icmp,
+ payload: [8, 0, 0, 0, 0, 1, 0, 1],
+ )
+ let frame = VPhoneEthernetFrame(
+ destination: .gateway, source: guestMAC, etherType: .ipv4, payload: packet.bytes,
+ ).bytes
+ #expect(responder().respond(to: frame) == nil)
+ }
+
+ // MARK: - Framing and checksums
+
+ @Test func `ethernet round trips`() throws {
+ let frame = VPhoneEthernetFrame(
+ destination: broadcastMAC, source: guestMAC, etherType: .arp, payload: [1, 2, 3, 4],
+ )
+ let parsed = try #require(VPhoneEthernetFrame(bytes: frame.bytes))
+ #expect(parsed.destination.bytes == broadcastMAC.bytes)
+ #expect(parsed.source.bytes == guestMAC.bytes)
+ #expect(parsed.etherType == VPhoneEtherType.arp.rawValue)
+ #expect(parsed.payload == [1, 2, 3, 4])
+ }
+
+ @Test func `a truncated frame is rejected rather than crashing`() {
+ #expect(VPhoneEthernetFrame(bytes: [0, 1, 2]) == nil)
+ #expect(VPhoneIPv4Packet(bytes: [0x45, 0]) == nil)
+ #expect(VPhoneARPMessage(bytes: [0, 1, 8]) == nil)
+ #expect(VPhoneDHCPMessage(bytes: [UInt8](repeating: 0, count: 240)) == nil) // no magic cookie
+ #expect(responder().respond(to: []) == nil)
+ }
+
+ /// A built IPv4 header must verify, which is what catches a byte-order slip
+ /// in the checksum path before the guest silently drops everything.
+ @Test func `ipv4 header checksum verifies`() {
+ let packet = VPhoneIPv4Packet(
+ source: configuration.hostAddress,
+ destination: .broadcast,
+ proto: .udp,
+ payload: [0x00, 0x43],
+ )
+ var bytes = packet.bytes
+ let stored = UInt16(bytes[10]) << 8 | UInt16(bytes[11])
+ bytes[10] = 0
+ bytes[11] = 0
+ // The IPv4 checksum covers the header only, which is 20 bytes here.
+ #expect(VPhoneInternetChecksum.compute(Array(bytes[0 ..< 20])) == stored)
+ }
+
+ /// A fragmented packet cannot be answered without reassembly, so it must be
+ /// dropped instead of mis-parsed.
+ @Test func `a fragment is dropped`() {
+ let packet = VPhoneIPv4Packet(
+ source: configuration.guestAddress, destination: configuration.hostAddress,
+ proto: .icmp, payload: [8, 0, 0, 0, 0, 1, 0, 1],
+ )
+ var frame = VPhoneEthernetFrame(
+ destination: .gateway, source: guestMAC, etherType: .ipv4, payload: packet.bytes,
+ ).bytes
+ // Set a non-zero fragment offset in the copy the responder sees.
+ frame[14 + 6] = 0x00
+ frame[14 + 7] = 0x10
+ #expect(responder().respond(to: frame) == nil)
+ }
+
+ /// The guest MAC is only discoverable from its traffic, so the responder has
+ /// to keep it between frames for unicast replies to be addressed correctly.
+ @Test func `guest MAC is learned from traffic`() throws {
+ let responder = responder()
+ _ = responder.respond(to: arpFrame(targeting: configuration.hostAddress))
+ let reply = try #require(responder.respond(to: icmpEchoFrame()))
+ let ethernet = try #require(VPhoneEthernetFrame(bytes: reply))
+ #expect(ethernet.destination.bytes == guestMAC.bytes)
+ }
+
+ // MARK: - UDP forwarding
+
+ /// UDP that is not DHCP is egress rather than something this side answers.
+ /// The flow it names has to carry both ends and the guest's MAC, because the
+ /// answer is built later, by the forwarder, with no access to this type.
+ @Test func `UDP for somewhere else becomes a forward`() throws {
+ let responder = responder()
+ // Learn the MAC first, the way a real guest's traffic would.
+ _ = responder.handle(arpFrame(targeting: configuration.hostAddress))
+
+ let query = VPhoneUDPDatagram(sourcePort: 51000, destinationPort: 53, payload: [0xAB, 0xCD, 0x01, 0x00])
+ let frame = ipv4Frame(
+ source: configuration.guestAddress,
+ destination: configuration.hostAddress,
+ proto: .udp,
+ payload: query.bytes(source: configuration.guestAddress, destination: configuration.hostAddress),
+ destinationMAC: .gateway,
+ )
+
+ guard case let .forward(flow, payload) = responder.handle(frame) else {
+ Issue.record("expected a forward")
+ return
+ }
+ #expect(flow.sourceAddress == configuration.guestAddress)
+ #expect(flow.sourcePort == 51000)
+ #expect(flow.destinationAddress == configuration.hostAddress)
+ #expect(flow.destinationPort == 53)
+ #expect(flow.guestHardware.bytes == guestMAC.bytes)
+ #expect(payload == [0xAB, 0xCD, 0x01, 0x00])
+ }
+
+ /// Without a learned MAC there is nowhere to send the answer, so no forward
+ /// may be produced.
+ @Test func `UDP is dropped before the guest MAC is known`() {
+ let query = VPhoneUDPDatagram(sourcePort: 51000, destinationPort: 53, payload: [0x00])
+ let frame = ipv4Frame(
+ source: configuration.guestAddress,
+ destination: configuration.hostAddress,
+ proto: .udp,
+ payload: query.bytes(source: configuration.guestAddress, destination: configuration.hostAddress),
+ destinationMAC: .gateway,
+ )
+ if case .forward = responder().handle(frame) {
+ Issue.record("a forward was produced without a guest MAC")
+ }
+ }
+
+ /// DHCP stays local: it is the one UDP exchange this side finishes itself.
+ @Test func `DHCP is answered locally, not forwarded`() {
+ if case .forward = responder().handle(dhcpFrame(type: .discover)) {
+ Issue.record("DHCP should not be forwarded")
+ }
+ }
+
+ // MARK: - TCP
+
+ private func tcpFrame(_ segment: VPhoneTCPSegment, source: VPhoneIPv4Address, destination: VPhoneIPv4Address) -> [UInt8] {
+ let packet = VPhoneIPv4Packet(
+ source: source, destination: destination, proto: .tcp,
+ payload: segment.bytes(source: source, destination: destination),
+ )
+ return VPhoneEthernetFrame(destination: .gateway, source: guestMAC, etherType: .ipv4, payload: packet.bytes).bytes
+ }
+
+ /// TCP is terminated, not relayed, so the whole segment goes to the
+ /// forwarder along with the flow it belongs to.
+ @Test func `TCP segment becomes a forwardTCP`() throws {
+ let responder = responder()
+ let syn = VPhoneTCPSegment(
+ sourcePort: 51000, destinationPort: 80, sequenceNumber: 1000,
+ acknowledgmentNumber: 0, flags: VPhoneTCPFlags.syn, windowSize: 65535,
+ )
+ let frame = tcpFrame(syn, source: configuration.guestAddress, destination: VPhoneIPv4Address(1, 1, 1, 1))
+
+ guard case let .forwardTCP(flow, segment) = responder.handle(frame) else {
+ Issue.record("expected a TCP forward")
+ return
+ }
+ #expect(flow.sourcePort == 51000)
+ #expect(flow.destinationPort == 80)
+ #expect(flow.destinationAddress == VPhoneIPv4Address(1, 1, 1, 1))
+ #expect(flow.guestHardware.bytes == guestMAC.bytes)
+ #expect(segment.hasSYN)
+ #expect(segment.sequenceNumber == 1000)
+ }
+
+ // MARK: - TCP segment codec
+
+ @Test func `TCP segment round trips`() throws {
+ let segment = VPhoneTCPSegment(
+ sourcePort: 40000, destinationPort: 443, sequenceNumber: 0xDEAD_BEEF,
+ acknowledgmentNumber: 0x1234_5678, flags: VPhoneTCPFlags.ack | VPhoneTCPFlags.psh,
+ windowSize: 65535, payload: [1, 2, 3, 4],
+ )
+ let parsed = try #require(VPhoneTCPSegment(bytes: segment.bytes(source: configuration.guestAddress, destination: .broadcast)))
+ #expect(parsed.sourcePort == 40000)
+ #expect(parsed.destinationPort == 443)
+ #expect(parsed.sequenceNumber == 0xDEAD_BEEF)
+ #expect(parsed.acknowledgmentNumber == 0x1234_5678)
+ #expect(parsed.hasACK && parsed.hasFIN == false)
+ #expect(parsed.windowSize == 65535)
+ #expect(parsed.payload == [1, 2, 3, 4])
+ }
+
+ /// The checksum covers the IP pseudo-header, so it only verifies when summed
+ /// against the same addresses it was built with.
+ @Test func `TCP checksum verifies over the pseudo-header`() {
+ let segment = VPhoneTCPSegment(
+ sourcePort: 1, destinationPort: 2, sequenceNumber: 3, acknowledgmentNumber: 4,
+ flags: VPhoneTCPFlags.ack, windowSize: 100, payload: [9, 9, 9],
+ )
+ let bytes = segment.bytes(source: configuration.guestAddress, destination: .broadcast)
+ let seed = VPhoneInternetChecksum.pseudoHeader(
+ source: configuration.guestAddress, destination: .broadcast, proto: 6, length: bytes.count,
+ )
+ #expect(VPhoneInternetChecksum.compute(bytes, seed: seed) == 0)
+ }
+
+ /// A SYN and a FIN each occupy one sequence number, which is what makes the
+ /// guest's acknowledgment of our SYN-ACK line up.
+ @Test func `SYN and FIN each cost one sequence number`() {
+ let syn = VPhoneTCPSegment(sourcePort: 1, destinationPort: 2, sequenceNumber: 0, acknowledgmentNumber: 0, flags: VPhoneTCPFlags.syn, windowSize: 0)
+ #expect(syn.sequenceLength == 1)
+ let synWithData = VPhoneTCPSegment(sourcePort: 1, destinationPort: 2, sequenceNumber: 0, acknowledgmentNumber: 0, flags: VPhoneTCPFlags.syn, windowSize: 0, payload: [1, 2])
+ #expect(synWithData.sequenceLength == 3)
+ let plain = VPhoneTCPSegment(sourcePort: 1, destinationPort: 2, sequenceNumber: 0, acknowledgmentNumber: 0, flags: VPhoneTCPFlags.ack, windowSize: 0)
+ #expect(plain.sequenceLength == 0)
+ }
+
+ /// A header with options still parses; the options are skipped rather than
+ /// misread as payload.
+ @Test func `TCP header with options is parsed past`() throws {
+ var bytes: [UInt8] = [
+ 0x00, 0x50, 0x01, 0xBB, // 80 -> 443
+ 0, 0, 0, 1, 0, 0, 0, 1,
+ 8 << 4, // data offset 8 words = 32 bytes, so 12 bytes of options
+ VPhoneTCPFlags.ack, 0xFF, 0xFF, 0, 0, 0, 0,
+ ]
+ bytes += [UInt8](repeating: 0, count: 12) // the options themselves
+ bytes += [0xAA, 0xBB] // payload
+ let segment = try #require(VPhoneTCPSegment(bytes: bytes))
+ #expect(segment.sourcePort == 80 && segment.destinationPort == 443)
+ #expect(segment.payload == [0xAA, 0xBB])
+ }
+
+ @Test func `a truncated TCP segment is rejected`() {
+ #expect(VPhoneTCPSegment(bytes: [UInt8](repeating: 0, count: 19)) == nil)
+ }
+}
+
+// MARK: - Test shims
+
+private extension VPhoneUserspaceNetworkResponder {
+ /// The frame this responder would send back, or nil when it would send none.
+ /// Added when `respond(to:)` became `handle(_:)` returning an outcome, so
+ /// the frame-level tests above kept reading the same way.
+ func respond(to frame: [UInt8]) -> [UInt8]? {
+ if case let .reply(reply) = handle(frame) { return reply }
+ return nil
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Support/NetworkingTests.swift b/VPhoneKit/VPhoneCoreKitTests/Support/NetworkingTests.swift
index 29415d90..f74333b4 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Support/NetworkingTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Support/NetworkingTests.swift
@@ -43,13 +43,30 @@ struct NetworkingTests {
}
@Test func `make network device off is nil`() throws {
- let dev = try VPhoneNetworking.makeNetworkDevice(NetworkConfig(mode: .off, macAddress: ""))
+ let (dev, backend) = try VPhoneNetworking.makeNetworkDevice(NetworkConfig(mode: .off, macAddress: ""))
#expect(dev == nil)
+ #expect(backend == nil)
}
@Test func `make network device NAT has attachment`() throws {
- let dev = try VPhoneNetworking.makeNetworkDevice(NetworkConfig(mode: .nat, macAddress: ""))
+ let (dev, backend) = try VPhoneNetworking.makeNetworkDevice(NetworkConfig(mode: .nat, macAddress: ""))
#expect(dev != nil)
#expect(dev?.attachment is VZNATNetworkDeviceAttachment)
+ #expect(backend == nil)
+ }
+
+ /// `tunnel` is the only mode with a backend: the network lives in this
+ /// process, so the caller has to hold (and start) it.
+ @Test func `make network device tunnel carries an in-process backend`() throws {
+ let (dev, backend) = try VPhoneNetworking.makeNetworkDevice(NetworkConfig(mode: .tunnel, macAddress: ""))
+ #expect(dev?.attachment is VZFileHandleNetworkDeviceAttachment)
+ let backend = try #require(backend)
+ #expect(backend.configuration == .default)
+ // Starting and stopping must not trap; the rest of the behaviour is
+ // covered by the frame-level tests.
+ backend.start()
+ backend.start()
+ backend.stop()
+ backend.stop()
}
}