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