Components.rst (5053B)
1 Components 2 ========== 3 4 This page summarizes the main components and how to extend the system safely. 5 6 Component Diagram 7 ----------------- 8 9 A diagram of all the main components is the following: 10 11 .. mermaid:: 12 :align: center 13 :caption: IP Protection architecture 14 15 flowchart TD 16 17 IPProtectionService 18 19 Helpers["IPProtectionHelpers"] 20 21 %% UI 22 subgraph UI 23 IPProtection 24 IPProtectionPanel 25 IPPExceptionsManager 26 end 27 28 %% Helpers 29 subgraph Helpers 30 IPPStartupCache["Startup Cache Helper"] 31 IPPSignInWatcher["Sign-in Observer"] 32 IPProtectionServerlist 33 IPPEnrollAndEntitleManager["Enroll & Entitle Manager"] 34 IPPProxyManager 35 UIHelper["UI Helper"] 36 IPPVPNAddonHelper["VPN Add-on Helper"] 37 IPPAutoStart["Auto-Start Helper"] 38 IPPEarlyStartupFilter["Early Startup Filter Helper"] 39 IPPNimbusHelper["Nimbus Eligibility Helper"] 40 end 41 42 %% Proxy stack 43 subgraph Proxy 44 IPPChannelFilter 45 IPProtectionUsage 46 IPPNetworkErrorObserver 47 GuardianClient 48 end 49 50 %% Service wiring 51 IPProtectionService --> GuardianClient 52 IPProtectionService --> Helpers 53 54 %% UI wiring 55 IPProtection --> IPProtectionPanel 56 IPProtection --> IPProtectionService 57 58 %% Proxy wiring 59 IPPProxyManager --> IPPChannelFilter 60 IPPProxyManager --> IPProtectionUsage 61 IPPProxyManager --> IPPNetworkErrorObserver 62 IPPNetworkErrorObserver -- "error events (401)" --> IPPProxyManager 63 64 65 GuardianClient 66 Manages communication between Firefox and the Guardian backend. It retrieves 67 account information, obtains the token for the proxy, and exposes the server list. 68 69 IPPChannelFilter 70 Main network component. It processes network requests and decides which ones 71 should go through the proxy. 72 73 IPPProxyManager 74 Implements the proxy activation/deactivation and exposes the current status. 75 76 IPProtectionPanel 77 Controls the feature’s panel UI. 78 79 IPPExceptionsManager 80 Manages the exceptions UI and logic (for example, domain exclusions) 81 in coordination with the panel and preferences. 82 83 IPProtectionService 84 The main service. It is initialized during browser startup, initializes helpers 85 and other components, and implements the state machine that drives the feature. 86 87 IPProtection 88 Manages the UI integration and interactions with the panel. 89 90 Additional proxy/telemetry components 91 ------------------------------------- 92 93 IPProtectionServerlist 94 Provides the available proxy endpoints (server list) to the proxy manager. 95 96 IPProtectionUsage 97 Gathers usage information and telemetry related to proxy activity. 98 99 IPPNetworkErrorObserver 100 Observes network errors related to the proxy and notifies the proxy manager 101 (for example, authentication or connectivity failures). 102 103 Helper objects 104 -------------- 105 106 The list of helpers lives in ``IPProtectionHelpers.sys.mjs`` and is exported 107 as the ``IPPHelpers`` array. Helpers implement small, self‑contained behaviors 108 and listen to service events when needed. 109 110 IPPAutoStart 111 Activates the proxy at startup time when auto‑start is enabled. 112 113 IPPSignInWatcher 114 Observes user authentication state. It informs the state machine when the user 115 signs in or out. 116 117 IPPStartupCache 118 Exposes cached information to keep the state machine responsive during startup 119 (last known state and entitlement JSON object). 120 121 UIHelper 122 Shows and hides the UI based on the current state machine state. 123 124 AccountResetHelper 125 Resets stored account information and stops the proxy when the account becomes 126 unavailable. 127 128 IPPVPNAddonHelper 129 Monitors the installation of the Mozilla VPN add‑on and removes the UI when 130 appropriate. 131 132 IPPNimbusHelper 133 Monitors the Nimbus feature (``NimbusFeatures.ipProtection``) and triggers a 134 state recomputation on updates. 135 136 IPPEnrollAndEntitleManager 137 Orchestrates the user enrollment flow with Guardian and updates the service 138 when enrollment status changes. 139 140 IPPProxyManager 141 Manages the proxy lifecycle: requests proxy passes, selects the active server, 142 and exposes the connection status to the rest of the feature. 143 144 How to implement new components 145 ------------------------------- 146 147 Do not modify the state machine. New functionality should be added via helper 148 classes to keep the core simple and robust. 149 150 Recommended steps: 151 152 1. Create a helper class with the methods ``init()``, ``initOnStartupCompleted()`` 153 and ``uninit()`` as appropriate for lifecycle needs. 154 2. If your helper reacts to state changes, listen to the 155 ``IPProtectionService:StateChanged`` event. 156 3. Add your helper to the ``IPPHelpers`` array in ``IPProtectionHelpers.sys.mjs``. 157 Be mindful of ordering if your helper depends on others. For example, 158 ``IPPNimbusHelper`` is registered last to avoid premature state updates 159 triggered by Nimbus’ immediate callback. 160 4. If your component needs to recompute the service state, call 161 ``IPProtectionService.updateState()`` after updating the helper data it 162 relies on; the recomputation is synchronous.