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"]
       EligibilityHelper["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.

EligibilityHelper
  Monitors the Nimbus experiment flag and triggers state updates when it changes.

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 (e.g. Nimbus
   eligibility is registered last to avoid premature updates).
4. If your component needs to trigger a recomputation, call
   ``IPProtectionService.updateState``.