--- name: necko-review description: Use this skill when reviewing or writing patches to networking code (Necko, netwerk/). --- # Guidelines for netwerk/ (Necko) patches These guidelines assume the general Firefox C++ rules, which they do not repeat. Follow the [Mozilla C++ coding style](https://firefox-source-docs.mozilla.org/code-quality/coding-style/coding_style_cpp.html) (naming prefixes, string argument types, error checking, include rules, `static` linkage, clang-format) and [Using C++ in Mozilla code](https://firefox-source-docs.mozilla.org/code-quality/coding-style/using_cxx_in_firefox_code.html) (permitted language features, and Mozilla data structures such as `nsTArray`, `nsTHashMap` and `Maybe` in place of their `std::` equivalents). The guidelines below cover what reviewers repeatedly asked for beyond those documents. ## 1. Explain the non-obvious in comments and interface docs Add a short comment saying *why*: why a dispatch goes through the event loop, why an early return is safe, why a fix is the right one. Document every new IDL attribute, interface, enum ordering and `StaticPrefList.yaml` entry. Link or quote the spec step being implemented. Delete or update comments that the change makes stale. Update prose docs, for example `captive_portals.md`, when behaviour changes, and mark retired bitflag values as unused. Be concise and use existing terminology. Limit inline comments to 2 lines if possible. ## 2. Reuse existing helpers, simplify control flow, and keep APIs minimal and well placed Use existing Gecko helpers whenever possible, for example: - `CloseTransaction` - `DataMutex` in place of hand-rolled locking - `Services.io.newURI` in place of regex URI parsing - an existing `"last-pb-context-exited"` observer Prefer early returns to extra indentation, not only on error paths, and factor duplicated branches into one. Keep members private, adding a `Take…()` accessor or a read-only IDL attribute instead of making fields public. Don't make functions public when they are only used inside their `.cpp` file. Put code in the layer that owns the concept. For example, `NeqoHttp3Conn` stays inside `Http3Session`, and generic UDP and QUIC fixes go upstream into neqo or `quinn-udp` (file happy-eyeballs state-machine issues on its GitHub repository). Forward-declare interfaces in IDL too, not only in C++ headers. Never include private netwerk headers by relative path. ## 3. Ship tests with the change, and make them robust Maintain test coverage: - Every fix comes with a regression test: xpcshell, gtest, mochitest, marionette or WPT. - Cover both pref states, including the old behaviour with the pref flipped. - Cover negative paths and redirects. - If the logic runs in a child process, add a `netwerk/test/unit_ipc` variant. - Extend `http3server` when HTTP/3 behaviour needs a server. - Prefer `NodeServer.sys.mjs` to `httpd.sys.mjs`. - See [Network Testing Guidelines](https://firefox-source-docs.mozilla.org/networking/network_test_guidelines.html) for examples. Good test hygiene: - Restore state with `registerCleanupFunction` and `Services.prefs.clearUserPref`, or with `SpecialPowers.pushPrefEnv`, and close servers in cleanup. - Wait with `TestUtils.waitForCondition` rather than racing events. - Prefer using events instead of timeouts. - Run new tests with `--verify`. - Avoid deprecated helpers such as `Preferences.jsm`. - Give each `skip-if` a minimal condition and a bug number. ## 4. Keep the diff minimal and lint-clean Remove the following before requesting review: - includes your change made unnecessary (but keep the ones you use directly, as the C++ style guide requires) - dead code and redundant checks or assertions - debug leftovers - unrelated files and unneeded IDL uuid bumps Don't reformat code you didn't touch. Do reformat code you did touch. Run all linters with `./mach lint --outgoing --warnings` and static analysis with `./mach static-analysis --warnings --outgoing`, not just clang-format. Use `//` comments in C++. ## 5. Send a well-described, correctly split, try-tested stack - **Commit message:** make it describe what the patch actually does, including removals. Keep security-sensitive details such as UAF descriptions out of the summary, because it lands as the commit message. - **Stack shape:** put each change in the revision it belongs to, and keep dependencies in the stack. - **Follow-up bugs:** file one for deferred work and reference it in a `TODO`/`XXX` comment. - **Sign-offs:** get the required ones: necko-reviewers, data review, l10n review for new strings, and `supply-chain/` audits for new crates (extend existing audits where possible). - **Dependencies:** pin crate versions, not `"*"`, and pin releases, not branches. - **Try runs:** link a try run with the relevant suites. - **Builds:** watch for includes that only non-unified builds catch, and for heavy headers such as `GleanMetrics.h` included from a header. ## 6. Handle every failure path, assert your invariants, and log usefully Handling failures: - Null-check anything that can be null, even where it rarely is, such as the URI from `NS_GetFinalChannelURI`. - Don't let an early return skip later work (e.g., logging, notifications in `Cancel`, `OnStart`/`OnStopRequest`, sanitization steps). - Pick the error code deliberately. `NS_ERROR_NET_RESET` restarts the transaction. - Make intentionally ignored results explicit with `(void)`. Assertions: - State invariants with `MOZ_ASSERT`, and use `MOZ_ASSERT_UNREACHABLE` for exhaustive cases. In Rust, add a debug-mode panic for "impossible" states, such as unexpected 0-RTT states. - Decide deliberately between `MOZ_DIAGNOSTIC_ASSERT`, a release assert, and a runtime check with a graceful fallback. Reviewers prefer a check to a crash when the case is reachable, or `MOZ_ASSERT` plus an early return. Logging: - Keep `LOG()` lines reachable across early returns, and don't drop them in a rebase. - Log cancel reasons where they are guaranteed to run, such as the channel destructor. - Log state transitions through a setter. - Log `nsresult` values with `PRIx32` and a cast. - Use `neqo_common::qerror` (and similar) in Rust, including in the HTTP/3 test server. - Emit a console message only once per load. ## 7. Use precise names and clear user-facing strings Names: - Bake units into names, for example `sleepInMs`. - Drop legacy `NS_`/`ns` prefixes inside `mozilla::net`. - Choose names that describe what the thing is, for example `mAttempts` and `is_doh`. - Keep Glean metric namespaces consistent, for example all TRR metrics under `dns::`. - Name enum values so that comparisons read correctly. - Positive pref names are covered in guideline 11. User-facing strings: - Avoid Necko jargon, for example "speculative connection". - Give a string a new ID when its meaning or placeholders change, as with `CORSDidNotSucceed2`. - Add a Fluent migration when moving `.properties` strings to `.ftl`. Migrations between two `.properties` files are not supported. - Keep phrasing consistent within a file, and describe placeholders accurately for translators. ## 8. Use Gecko idioms in C++ and Rust C++, beyond the style guide: - Use `nsDependentCSubstring` for string views and `LowerCaseEqualsASCII` for case-insensitive comparisons. - Use `Result`/`mozilla::pkix::Result` over ad-hoc result types, and enums over bare `bool` return values. - Use `size_t` for sizes, to avoid implicit narrowing. - Make data `const` when it is never mutated. - Use `inline constexpr` for header constants. - Move rvalues instead of copying. - Avoid unnecessary `reinterpret_cast`. - Don't add new NSPR (`PR_*`) uses. Rust: - Use `moz_task` rather than hand-rolled runnables. - Return a `Result` internally and convert it to an `nsresult` at the public boundary. Avoid `unwrap` where an error can propagate. - Drop unneeded `pub`. ## 9. Treat the content process as untrusted, and design IPC defensively Validating content-process data: - Validate or recompute in the parent anything a content process sends, such as hosts, flags like `LOAD_DOCUMENT_NEEDS_COOKIE` and domains written to prefs. Don't trust values arriving through `CookieServiceChild` or `DocumentLoadListener`. - Use type-checked enums in IPDL rather than bare integers. - Use `IPC_FAIL` with a reason string. Limiting what reaches the content process: - Send the content process only what it needs, for example no proxy response headers, and cleared headers for cancelled channels as a Spectre defence. - Consider whether a feature should be parent-process-only. Security checks: - Use principals rather than URIs. Calling `SchemeIs` on a principal is a smell. - Include `OriginAttributes` in keys, and key WebTransport connection hashes by `serverCertificateHashes`. - Keep anonymous (`SEC_COOKIES_OMIT`) requests off connections that carry cookies. - Filter private-browsing entries, for example in `about:networking`. - Fail closed on unauthenticated metadata. IPC design: - Don't send IPC messages from constructors. - Avoid new sync IPC. - Prefer IPDL return values or `MozPromise` to paired request/response messages. ## 10. Design telemetry so it can be analysed, and test it Before landing, decide how the change will be measured in the field. - **Metric type:** pick the Glean type that fits: - `memory_distribution` for byte values - labeled counters with labels taken from, for example, `neqo_transport::Error` - `exponential` rather than `linear` custom distributions for log-normal data - **Labels:** use generated label enums via `EnumGet`. - **Existing probes:** don't change the type of an existing probe, because that breaks queries. Rename it instead. - **Hot paths:** avoid recording at high frequency on hot paths, and aggregate instead. - **Coverage:** add tests that assert collection, and don't drop existing probes on some platforms. ## 11. Gate new behaviour behind a well-named pref, and plan rollout and migration Gating and rollout: - Gate new behaviour behind a pref, and check it before doing any other work. - Use positive `.enabled` names. - Document each value in `StaticPrefList.yaml`. - Enable in Nightly first and file a bug for the release flip. - Mark Nimbus features that record exposure accordingly in `FeatureManifest.yaml`. - Decide whether a pref is read once at `Init()` or live, and what a runtime change means for cached state. - Remove prefs that become dead. - Push to try with the relevant networking pref flipped, for example `fast-fallback-to-IPv4`, and run `./mach try perf` with a new pref enabled. Migration: - When renaming prefs or changing persisted data (cookie DB, Cache API `DBSchema`, permissions, profile flags), write a migration. - Preserve raw stored values, such as the cookie DB's `rawSameSite`. - Weigh a schema migration against alternatives. For example, reviewers compared a cookie schema migration with re-shipping CHIPS. - Check upgrade and downgrade paths, including extension and embedder APIs. ## 12. Make thread affinity and locking explicit Necko objects are often touched from several threads: the main thread, the socket thread, the WebSocket `IOThread` and others. Thread affinity: - Assert thread affinity with `MOZ_ASSERT(NS_IsMainThread())`, even when every current caller is on the right thread. This is especially important when reading prefs that are not `RelaxedAtomic`, and for main-thread-only state such as the maps in `nsIOService`. - Use `NS_DECL_THREADSAFE_ISUPPORTS` for objects used off the main thread. - Decide up front which thread owns an object, and assert it. `SocketProcessChild` singletons, for example, should assert their owning thread, and a `HappyEyeballs` instance should track the thread it was created on. - Don't re-dispatch when already on the target thread. - Proxy-release members on their owning thread, for example the WebSocket `IOThread`, instead of adding locks. Locking: - Annotate locked state with `MOZ_REQUIRES`/`MOZ_GUARDED_BY` rather than runtime asserts, as with `MOZ_REQUIRES(mLock)` on `nsHttpTransaction` accessors. - Place a mutex next to the fields it guards. - Keep pref accesses and sorting outside locked regions. ## 13. Follow the spec, compare with other browsers, and keep WPT metadata accurate - **Spec conformance:** link and/or quote the spec (WHATWG, W3C or IETF RFCs) at the implementing code, and check behaviour against its exact wording, for example "*from* secure contexts". When diverging from a spec, comment on the reason. - **Other browsers:** when diverging, check what Chrome does. - **WPT:** - Update `testing/web-platform/meta` expectations when results change. - Don't delete expectations wholesale. - Upstream new WPTs through the web-platform-tests repository. ## 14. Avoid unnecessary work on hot paths, and measure performance claims Avoiding waste: - Reuse buffers on hot paths (`Truncate()` and refill) instead of reallocating. - Avoid memory allocations or copies when possible. - Order conditions so the cheapest check runs first. - Hoist values that don't change per request, such as an SSD check. - Reuse an already-computed `now` rather than making another syscall. - Avoid extra refcount cycles. - Avoid a sync main-thread dispatch followed by sync IPC; do the work off the main thread. - Move blocking I/O off the thread that owns it. - Bound loops over untrusted input. - Use the best-suited data structures in terms of operational complexity, especially for the hot path. Measuring claims: - Back performance claims with profiles at realistic sizes. - Back them with a `./mach try perf` or Talos run. ## 15. Get ownership, lifetimes and shutdown order right Ownership: - Pass non-owning references as raw pointers. - Capture `RefPtr{this}` in async lambdas. - Don't return raw pointers into internal data. - Clear back-pointers so that nothing outlives its owner. - Prefer `MOZ_STACK_CLASS` to refcounting for scope guards. - Copy data that listeners could mutate by cancelling, because otherwise a UAF can result. Cycles and shutdown: - Check for reference cycles, for example between `Http3Stream` and `Http3Session`. Break them with `WeakPtr` as `Http2Session` does, and cycle-collect held promises. - Use an observer such as `"last-pb-context-exited"` for private-browsing cleanup. - Order shutdown relative to Glean and XPCOM.