Source code
Revision control
Copy as Markdown
Other Tools
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"]
UIHelper["UI Helper"]
AccountResetHelper["Account Reset Helper"]
VPNAddonHelper["VPN Add-on Helper"]
IPPNimbusHelper["Nimbus Eligibility Helper"]
IPPAutoStart["Auto-Start Helper"]
IPPEarlyStartupFilter["Early Startup Filter Helper"]
end
%% Proxy stack
subgraph Proxy
IPPProxyManager
IPPChannelFilter
IPProtectionUsage
IPPNetworkErrorObserver
IPProtectionServerlist
GuardianClient
end
%% Service wiring
IPProtectionService --> IPPProxyManager
IPProtectionService --> GuardianClient
IPProtectionService --> Helpers
%% UI wiring
IPProtection --> IPProtectionPanel
IPProtection --> IPProtectionService
%% Proxy wiring
IPPProxyManager --> GuardianClient
IPPProxyManager --> IPPChannelFilter
IPPProxyManager --> IPProtectionUsage
IPPProxyManager --> IPPNetworkErrorObserver
IPPProxyManager --> IPProtectionServerlist
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.
VPNAddonHelper
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.
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 trigger a recomputation, call
``IPProtectionService.updateState``.