2.7 KiB
Make system-proxy application declarative and network-aware
Status: superseded for system-proxy lifecycle policy by ADR-0020 and ADR-0022. ADR-0020 replaced endpoint-signature cleanup; ADR-0022 replaces passive-network reapplication, launch application, external-change handling, and health-gate behavior. The text below records the historical decision, not current policy.
The system proxy switch manages the values 2.0 applies, not another application's prior configuration: enabling writes 2.0's SOCKS, HTTP, and HTTPS endpoints, PAC/auto-discovery suppression, and exception settings to every service in the active network location when the local runtime passes its existing health and exit gate; disabling scans every network location and clears the complete Proxies dictionary for each service whose enabled SOCKS and HTTP/HTTPS endpoints exactly match the most recent endpoint signature 2.0 tried to apply. If the health or exit gate closes while enabled, matching 2.0 endpoint settings are cleared until the gate recovers. Persist only that endpoint signature for cleanup, before attempting the write so partial failures remain identifiable—never the prior per-service dictionaries—and do not detect or report external edits. The signature is a cleanup selector, not proof of exclusive ownership.
While enabled and the GUI is running, a network-location, service, or app-visible network-path update triggers reapplication to the active location; a proxy-configuration-only change is ignored to avoid competing software entering a write loop. Network path updates are observed with Apple's NWPathMonitor. Startup reconciles once before observation begins. During a disable cleanup, location, service, and proxy-configuration changes trigger another scan; observation stops when the cleanup attempt completes, including on failure. Launching with the switch off performs one cleanup scan and stops. An unsuccessful cleanup may leave settings for the user to handle manually or overwrite with another proxy app.
This deliberately chooses last-writer behavior: enabling can replace another app's values in the active location, and disabling can clear a dictionary written by another app if it has the same endpoint signature. Applying to the active location covers all its network services, not only the interface currently carrying traffic. Changes that occur while the GUI is closed are reconciled on its next launch. This supersedes the system-proxy ownership, conflict, snapshot, restore, and rollback clauses of ADR-0002, ADR-0009, ADR-0010, and ADR-0012; their unrelated decisions remain in force.