Crate: kinetic-pac

Stage: 11

Reading Time: 60 mins

Depends On: kinetic-core, kinetic-daemon (running at port 16000)

What Is This?

kinetic-pac is the Proxy Auto-Configuration server for the Kinetic network. It serves a dynamically generated JavaScript PAC file at http://127.0.0.1:16001/proxy.pac, and injects this URL into the OS-level proxy settings so all browsers and network-aware applications automatically route .kin traffic through the local Kinetic HTTP proxy.

A PAC (Proxy Auto-Config) file is a JavaScript function that browsers and OSes call for every HTTP request: “given this URL and hostname, should I go direct or use a proxy?” Kinetic generates this function dynamically based on whatever TLD proxies are currently registered.

Key Pieces

1. SavedState + lockfile: Captures the original OS proxy settings before modification and writes them atomically to proxy_active.lock. If the daemon crashes, the next launch restores the old settings before applying new ones.
2. ProxyConfigurator trait + OS implementations: Platform-specific code (KdeConfigurator, GnomeConfigurator, MacosConfigurator, WindowsConfigurator) that shells out to gsettings, kwriteconfig5, networksetup, or PowerShell to inject the PAC URL into the OS network settings.
3. PacManager: The lifecycle controller. Calls save_previous_state → atomic lockfile write → install. Reverses on uninstall.
4. The PAC HTTP server: An Axum server at http://127.0.0.1:16001 with a single /proxy.pac route. On each request, it scans the proxies/ directory for registered JSON proxy descriptors and generates a fresh JavaScript PAC function.
5. Graceful shutdown: A tokio::spawn background task listens for SIGTERM (Unix) or Ctrl+C and calls pac_manager.uninstall() before std::process::exit(0).

How to Read This Stage

• Start with 02_pac_main_1.md to understand SavedState, ProxyConfigurator, PacManager, and crash recovery.
• Read 03_pac_main_2.md to see the PAC file generation loop and the shutdown signal handling.
• Finish with 04_pac_os.md to understand each platform’s concrete proxy injection commands.