Components
==========

This page summarizes the main components and how to extend the system safely.

The implementation is split into two directories:

* ``toolkit/components/ipprotection`` — platform-independent core (state machine,
  proxy/network stack, core helpers).
* ``browser/components/ipprotection`` — desktop-specific UI layer (panel, toolbar
  button, alert/infobar managers, and onboarding helpers).

Component Diagram
-----------------

A diagram of all the main components is the following:

.. mermaid::
   :align: center
   :caption: IP Protection architecture

   flowchart LR

     %% browser/components/ipprotection
     subgraph Browser["browser/components/ipprotection (UI layer)"]
       IPProtection
       IPProtectionPanel

       subgraph BrowserHelpers["Browser Helpers"]
         UIHelper["UI Helper"]
         IPPOnboardingMessage["Onboarding Message"]
         IPPOptOutHelper["Opt-Out Helper"]
         IPPUsageHelper["Usage Helper"]
         IPProtectionAlertManager["Alert Manager"]
         IPProtectionInfobarManager["Infobar Manager"]
       end
     end

     %% toolkit/components/ipprotection
     subgraph Toolkit["toolkit/components/ipprotection (core)"]
       IPProtectionService
       IPProtectionActivator

       subgraph CoreHelpers["Core Helpers"]
         IPPStartupCache["Startup Cache Helper"]
         IPProtectionServerlist
         IPPProxyManager
         IPPAutoStart["Auto-Start Helper"]
         IPPAutoRestoreHelper["Auto-Restore Helper"]
         IPPNimbusHelper["Nimbus Eligibility Helper"]
         IPPExceptionsManager
       end

       subgraph FxaAuth["FxA Authentication (fxa/)"]
         IPPAuthProvider
         IPPFxaAuthProvider
         IPPSignInWatcher["Sign-in Observer"]
         IPPEnrollAndEntitleManager["Enroll & Entitle Manager"]
       end

       subgraph Proxy["Proxy stack"]
         IPPChannelFilter
         IPPNetworkErrorObserver
         GuardianClient
       end
     end

     %% Activator wiring
     BrowserHelpers -- "addHelpers()" --> IPProtectionActivator
     IPProtectionActivator --> IPProtectionService
     IPProtectionActivator --> CoreHelpers
     IPProtectionActivator -- "setAuthProvider()" --> IPPFxaAuthProvider

     %% Service wiring
     IPProtectionService --> GuardianClient
     IPProtectionService --> CoreHelpers
     IPProtectionService -- "authProvider" --> IPPAuthProvider

     %% FxA auth wiring
     IPPFxaAuthProvider -->|extends| IPPAuthProvider
     IPPFxaAuthProvider --> IPPSignInWatcher
     IPPFxaAuthProvider --> IPPEnrollAndEntitleManager

     %% UI wiring
     IPProtection --> IPProtectionPanel
     IPProtection --> IPProtectionService

     %% Proxy wiring
     IPPProxyManager --> IPPChannelFilter
     IPPProxyManager --> IPPNetworkErrorObserver
     IPPNetworkErrorObserver -- "error events (401)" --> IPPProxyManager


Toolkit components (``toolkit/components/ipprotection``)
---------------------------------------------------------

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.

IPProtectionService
  The main service. It is initialized during browser startup, initializes helpers
  and other components, and implements the state machine that drives the feature.

IPProtectionActivator
  Entry point that assembles the full helper list and initialises
  ``IPProtectionService``.  It owns the ordered list of core helpers and exposes
  ``addHelpers()`` so that the browser layer can register additional,
  browser-specific helpers before ``init()`` is called.  It also exposes
  ``setAuthProvider()`` to set the active authentication provider.

IPPExceptionsManager
  Manages the exceptions logic (for example, domain exclusions) in coordination
  with the panel and preferences.

Additional proxy/telemetry components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

IPProtectionServerlist
  Provides the available proxy endpoints (server list) to the proxy manager.

IPPNetworkErrorObserver
  Observes network errors related to the proxy and notifies the proxy manager
  (for example, authentication or connectivity failures).

Core helpers
~~~~~~~~~~~~

The core helper list is defined in ``IPProtectionActivator.sys.mjs`` (toolkit).

IPPAutoStart
  Activates the proxy at startup time when auto-start is enabled.

IPPAutoRestoreHelper
  Restores the proxy state after a crash or restart when auto-restore is enabled.

IPPStartupCache
  Exposes cached information to keep the state machine responsive during startup
  (last known state and entitlement JSON object).

IPPNimbusHelper
  Monitors the Nimbus feature (``NimbusFeatures.ipProtection``) and triggers a
  state recomputation on updates.

FxA authentication (``toolkit/components/ipprotection/fxa``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Authentication is abstracted behind ``IPPAuthProvider``, which lives in the
toolkit root.  ``IPProtectionService`` always interacts with the provider through
this interface, so all FxA dependencies are fully contained in the ``fxa/``
sub-directory.  The concrete provider and its helpers are registered from
``IPProtectionHelpers.sys.mjs`` in the browser layer.

IPPAuthProvider
  Base class that defines the authentication interface used by
  ``IPProtectionService``: ``isReady``, ``getToken()``, ``aboutToStart()``,
  and ``excludedUrlPrefs``.  The default implementation is a no-op that keeps
  the service in an unauthenticated/inactive state.

IPPFxaAuthProvider
  Concrete FxA implementation of ``IPPAuthProvider``.  It obtains OAuth tokens
  from ``fxAccounts``, runs the enrollment flow before the proxy starts, and
  lists the FxA endpoint prefs whose URL values should bypass the proxy.
  Its ``helpers`` getter exposes ``IPPSignInWatcher`` and
  ``IPPEnrollAndEntitleManager`` so they can be registered as service helpers.
  The provider and its helpers are wired up from ``IPProtectionHelpers.sys.mjs``
  in the browser layer via ``IPProtectionActivator.setAuthProvider()`` and
  ``IPProtectionActivator.addHelpers()``.

IPPSignInWatcher
  Observes user authentication state.  It informs the state machine when the
  user signs in or out.

IPPEnrollAndEntitleManager
  Orchestrates the FxA-based enrollment flow with Guardian and updates the
  service when enrollment or entitlement status changes.

Browser components (``browser/components/ipprotection``)
---------------------------------------------------------

IPProtection
  Manages the UI integration and interactions with the panel.

IPProtectionPanel
  Controls the feature's panel UI.

IPProtectionHelpers
  Registers browser-specific helpers with ``IPProtectionActivator`` via
  ``addHelpers()``: ``UIHelper``, ``IPPOnboardingMessage``, ``IPPOptOutHelper``,
  ``IPPUsageHelper``, ``IPProtectionAlertManager``, and ``IPProtectionInfobarManager``.
  It also registers ``IPPFxaAuthProvider`` (and its FxA helpers) via
  ``setAuthProvider()`` and ``addHelpers()``.

UIHelper
  Shows and hides the UI based on the current state machine state.

IPPOptOutHelper
  Handles the user opt-out flow and clears stored state accordingly.

IPPOnboardingMessage
  Handles the onboarding message flow for new users.

IPPUsageHelper
  Tracks bandwidth usage warning state and fires state-change events when
  usage crosses the 75% or 90% thresholds.

IPProtectionAlertManager
  Manages alert notifications related to IP Protection.

IPProtectionInfobarManager
  Manages infobar notifications displayed to the user.

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. Decide whether the helper belongs in the **toolkit** layer (no UI, no chrome
   dependency) or the **browser** layer (UI or chrome integration required).
2. Create a helper class with the methods ``init()``, ``initOnStartupCompleted()``
   and ``uninit()`` as appropriate for lifecycle needs.
3. If your helper reacts to state changes, listen to the
   ``IPProtectionService:StateChanged`` event.
4. Register your helper:

   * **Toolkit helpers**: add it to the ``coreHelpers`` array in
     ``toolkit/components/ipprotection/IPProtectionActivator.sys.mjs``.
   * **Browser helpers**: call ``IPProtectionActivator.addHelpers([...])`` in
     ``browser/components/ipprotection/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.
5. If your component needs to recompute the service state, call
   ``IPProtectionService.updateState()`` after updating the helper data it
   relies on; the recomputation is synchronous.