Design Decisions

​

Why SwiftNIO Instead of URLSession

URLSession is a high-level HTTP client. Rockxy needs a low-level TCP server that can accept connections, parse HTTP, perform MITM TLS interception via CONNECT tunnels, and forward traffic — all things that require direct socket control. SwiftNIO provides the event-driven, non-blocking I/O foundation that makes this possible in pure Swift.

​

Why NSTableView for the Request List

SwiftUI List cannot handle 100k+ rows with virtual scrolling. The request list uses NSTableView wrapped in NSViewRepresentable for O(1) scrolling performance regardless of traffic volume. Cell reuse keeps memory constant even at high row counts.

​

Why a Privileged Helper Daemon

macOS requires admin authentication for each networksetup call. The helper tool (SMAppService.daemon()) runs as root and validates callers via certificate-chain comparison, eliminating repeated password prompts while maintaining security through defense-in-depth.

​

Actor-Based Concurrency Model

The proxy server, session managers, and certificate manager are all Swift actors. This eliminates data races without manual locking. The coordinator bridges actor-isolated state to @MainActor for SwiftUI consumption via batched updates (every 100ms).

​

Three Isolation Domains

​

Plugin Sandbox

JavaScript plugins run in JavaScriptCore with a controlled bridge API ($rockxy). Each script execution has a 5-second timeout. Plugins can inspect and modify requests but cannot access the filesystem or network directly.

​

Performance Design

​

Storage Architecture

​

CI/CD Pipeline

GitHub Actions workflow (manual dispatch with optional channel parameter) — canonical file: .github/workflows/build.yml.

1. Lint — swiftlint lint --strict on macOS 14
2. Build — parallel arm64 and x86_64 release builds with Xcode 16
3. Artifacts — uploads signed build artifacts for distribution

​

Next Steps