63
edits
Changes
add todos
== Rollout ==
* The DoH frontend is and its sub-features are gated behind the prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk. * The pref `doh-rollout.enabled`, which by default does not have serves as a valueblanket gate.* Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.
* Prefs are set TODO: links to true via Normandy Rolloutstickets, which allows us to target specific regions and control population size and growth so we can manage riskbugs, dashboards etc.
== Heuristics ==
* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.* TODO: more details, individual docs for each heuristic, flow diagram
== Respecting User-choice ==
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs
== Provider Steering ==
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs
== Opt-out Doorhanger ==
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.
* TODO: links to CFR code/docs, screenshot
== Telemetry ==
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.
* TODO: links to Events.yaml, data review bugs, etc.
== Migrations ==
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.
