StateMachine.rst (3710B)
1 State Machine 2 ============= 3 4 Service state machine 5 --------------------- 6 7 The finite state machine is implemented in the ``IPProtectionService`` class 8 and the states are defined in the ``IPProtectionStates`` object. 9 10 Service states 11 ~~~~~~~~~~~~~~ 12 13 The service transitions across the following states: 14 15 - ``UNINITIALIZED``: Service not initialized or feature disabled. 16 - ``UNAVAILABLE``: User not eligible (Nimbus) or signed out with no eligibility; UI hidden. 17 - ``UNAUTHENTICATED``: User signed out but eligible; UI shows login. 18 - ``READY``: Ready to activate the proxy. 19 20 High‑level transitions 21 ~~~~~~~~~~~~~~~~~~~~~~ 22 23 - Feature disabled → ``UNINITIALIZED``. 24 - During startup, if initialization isn’t complete, use cached state from ``IPPStartupCache``. 25 - Not signed in → ``UNAVAILABLE`` if not eligible, otherwise ``UNAUTHENTICATED``. 26 - If an entitlement is cached/valid → ``READY``. 27 - Otherwise, check enrollment with Guardian (via ``IPPEnrollAndEntitleManager``): 28 - Not enrolled → ``UNAVAILABLE`` (not eligible). 29 - Enrolled → fetch entitlement; if successful → ``READY``, else ``UNAVAILABLE`` when not eligible. 30 31 Events and integration points 32 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 33 34 - ``IPProtectionService:StateChanged`` is dispatched on state changes with 35 ``detail.state`` and ``detail.prevState``. 36 - Helpers can call ``IPProtectionService.updateState()`` to recompute the state immediately; update any helper-owned data first because the call is synchronous. 37 - Public actions: ``start(userAction)``, ``stop(userAction)``, and ``startLoginFlow(browser)``. 38 39 Proxy manager state machine 40 --------------------------- 41 42 The ``IPPProxyManager`` layers a proxy‑specific finite state machine on top of 43 ``IPProtectionService``. It mirrors eligibility changes from the service and 44 drives the lifecycle of the proxy connection. 45 46 Proxy states 47 ~~~~~~~~~~~~ 48 49 - ``NOT_READY``: Service is not ``READY``. Channel filters are torn down and UI should not offer activation. 50 - ``READY``: Service is ``READY`` and the proxy can be activated. 51 - ``ACTIVATING``: ``start()`` is creating a channel filter, fetching a proxy pass, and selecting an endpoint. 52 - ``ACTIVE``: Proxy connected. Usage and network observers are reporting metrics. 53 - ``ERROR``: A recoverable error occurred while activating or rotating credentials. Errors are kept in a bounded history. 54 55 Proxy transitions 56 ~~~~~~~~~~~~~~~~~ 57 58 - ``IPProtectionService:StateChanged`` → ``IPPProxyManager.updateState()``: 59 - Service ``READY`` → proxy ``READY`` (resets connection/error history). 60 - Any other service state → proxy ``NOT_READY`` (stops active connections). 61 - ``start(userAction)`` from ``READY`` moves to ``ACTIVATING``. 62 - Successful activation → ``ACTIVE`` and telemetry ``ipprotection.toggled``. 63 - Failures (missing entitlement, server list, proxy pass…) → ``ERROR`` via ``#setErrorState``. 64 - ``stop(userAction)`` from ``ACTIVE`` → ``READY`` after closing the channel filter and observers. 65 - ``reset()`` or helper‑driven recomputations call ``updateState()`` which demotes the proxy back to ``READY``/``NOT_READY`` and clears the credential cache. 66 - Network errors (``proxy-http-error`` with 401) trigger Proxy Pass rotation while staying ``ACTIVE``; repeated failures bubble up through ``#setErrorState``. 67 68 Proxy events and hooks 69 ~~~~~~~~~~~~~~~~~~~~~~ 70 71 - ``IPPProxyManager:StateChanged`` is dispatched with ``detail.state`` whenever the proxy state machine moves. 72 - ``IPPProxyManager`` listens to ``IPProtectionService:StateChanged`` and to ``proxy-http-error`` from ``IPPNetworkErrorObserver``. 73 - Consumers can observe ``IPPProxyManager.state`` (or listen for events) to synchronize UI/telemetry with the proxy lifecycle.