[adr] Network async/event API proposal

[titusfortner]

📄 The decision, its rationale, considered options, and consequences are in the record file this PR
adds (docs/decisions/17685-network-handler-behavior.md);
read it there. This body is context for the decision, not a restatement of it.

🔗 Related

• [🚀 Feature]: Implement high level BiDi network commands #13993 — the handler surface (add / remove / clear for requests, responses, and authentication,
  under driver.network) agreed at the Dev Summit; this record consolidates it, and the per-binding
  implementation history is tracked there.
• [docs] Selenium 5 release charter #17717 — the Selenium 5 release charter.
• [adr] BiDi implementation boundaries #17670 — BiDi is an internal implementation mechanism; driver.network is the protocol-neutral
  surface consistent with that boundary.
• @p0deje's BiDi Protocol Design Document,
  where @nvborisenko and I raised behavior concerns that were never resolved before meetings stopped —
  this record settles them.

📝 Proposal notes

• Satisfies a charter requirement. This is the ADR the charter ([docs] Selenium 5 release charter #17717) names for the Network
  async/event API bucket; on acceptance the charter links back to it.
• Already agreed — this record consolidates. From the summit ([🚀 Feature]: Implement high level BiDi network commands #13993): the driver.network
  accessor, and add / remove / clear handlers for requests, responses, and authentication. The rest
  of the record settles how those handlers behave.
• Non-blocking handlers are out of scope. Handlers block by default, and that is all this record
  settles. Whether to add non-blocking observation — and, if so, whether as a mode on these methods
  or its own surface — is a separate ADR; the last TLC discussion leaned toward blocking everything
  for now, and @nvborisenko and @diemol have argued observation is distinct enough to stand on its
  own. Nothing here forecloses that: it arrives later as an opt-in, leaving the blocking default
  intact.
• Implementation is unspecified, but the behaviors must compose into one dispatch. For
  illustration, this Ruby sketch — each handler run in turn, later-registered first, the event settled
  by the first to act — satisfies them:

def process_request(request)
  @handlers.reverse_each do |h|
    h.call(request)
    if request.failed?
      return fail_request(request)
    elsif request.response?
      return provide_response(request)
    elsif request.submit?
      return continue_request(request)
    end
  end
  continue_request(request)
end

🗣 Discussion

Pending — not yet discussed.

📌 Tracking

Tracking issue: (linked on acceptance)

[qodo-code-review]

PR Summary by Qodo

ADR: Define network handler disposition, ordering, and failure semantics
📝 Documentation 🕐 20-40 Minutes

Description

• Proposes user-facing behaviors for resolving conflicting network handlers.
• Defines handler disposition, default chaining, LIFO ordering, and exception handling.
• Specifies completion capture and body collection responsibilities for handlers.

Diagram

graph TD
U(["User/Test"]) --> API["Network API"] --> HS["Handler stack"] --> HC["Handler callable"] --> D{"Disposition?"}
D --> F["Fail request"] --> B["BiDi command"]
D --> R["Provide response"] --> B
D --> S["Continue/Submit"] --> B
HC --> E["Log & skip"]
HC --> C[("Completed event")]

subgraph Legend
  direction LR
  _actor(["Actor"]) ~~~ _proc["Process"] ~~~ _dec{"Decision"} ~~~ _store[("Stored state")]
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Require explicit disposition (Playwright-style fallback)

• ➕ Avoids ambiguity: every handler must declare whether it stops or continues processing
• ➕ Reduces surprises when handlers accidentally “chain” due to omitted disposition
• ➖ More verbose for common “mutate and continue” cases (headers, URL rewrites, etc.)
• ➖ Makes composition of multiple small handlers more cumbersome

2. Run all handlers then reconcile by fixed priority

• ➕ Deterministic resolution even if multiple handlers set conflicting dispositions
• ➕ Potentially simpler mental model for some users (priority table)
• ➖ Prevents a specific handler from intentionally short-circuiting others
• ➖ Can unintentionally apply mutations from handlers that “should not have run” under a user-chosen stop condition

3. FIFO ordering (first registered wins)

• ➕ Matches many event-listener models where registration order implies precedence
• ➕ Potentially easier to reason about for simple setups
• ➖ Makes local overrides difficult (tests can’t reliably override shared/global handlers)
• ➖ Encourages brittle global configuration and test coupling

Recommendation: The ADR’s proposed model (explicit disposition when needed, default chaining, LIFO precedence, and exception isolation) is the most composable for real test suites where local overrides must trump shared defaults. The main point to validate with stakeholders is whether the default “continue to next handler” is acceptable ergonomically and safety-wise; if not, consider the explicit-fallback alternative, but expect materially more boilerplate across bindings.

Files changed (1) +230 / -0

Documentation (1) +230 / -0

network-handler-behavior.mdAdd ADR defining network handler behavior and precedence rules +230/-0

Add ADR defining network handler behavior and precedence rules

• Introduces a proposed ADR that specifies how request/response handlers compose and resolve conflicts. Defines disposition verbs, default chaining behavior, LIFO ordering, exception handling, ignoring return values, access to original vs mutated event state, completion capture, and body-collection responsibilities.

docs/decisions/network-handler-behavior.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (4) 📘 Rule violations (1) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. UrlPattern naming mismatch ✓ Resolved 🐞 Bug ≡ Correctness ⭐ New

Description

Decision 2 defines URL-pattern components as host/path/query and uses UrlPattern.host(...),
but existing Selenium BiDi UrlPatternPattern implementations use hostname/pathname/search and
Java’s UrlPattern exposes hostname() (no host()). Without an explicit canonical
naming/mapping, bindings are likely to implement incompatible pattern objects or conflicting
examples.

Code

docs/decisions/17685-network-handler-behavior.md[R57-72]

+2. **A handler is scoped by an optional list of URL patterns given as structured objects.** Each
+   pattern is an object of URL components — protocol, host, port, path, query — each optional: a
+   component that is set matches exactly, one left unset matches any value. A handler matches a
+   request against any pattern in its list; with no list it matches every request. A pattern is an
+   object, not a URL or glob string.
+
+```ruby
+# One or more component objects; a request matches any of them
+network.add_request_handler(url_patterns: [{host: "api.example.com"}, {host: "cdn.example.com"}]) { |r| r.fail }
+```
+
+```java
+network.addRequestHandler(
+    List.of(UrlPattern.host("api.example.com"), UrlPattern.host("cdn.example.com")),
+    r -> r.fail());
+```

Evidence

The ADR defines and exemplifies URL pattern components using host and UrlPattern.host(...),
while the existing Selenium BiDi URL pattern types and helpers across bindings consistently use
hostname/pathname/search and Java has no host()/host(...) API. This mismatch demonstrates
the ADR’s current wording/examples are not aligned with the established BiDi shape in the repo and
must be clarified to avoid divergent implementations.

docs/decisions/17685-network-handler-behavior.md[57-72]
docs/decisions/17685-network-handler-behavior.md[84-87]
java/src/org/openqa/selenium/bidi/network/UrlPattern.java[25-56]
javascript/selenium-webdriver/bidi/urlPattern.js[18-89]
rb/lib/selenium/webdriver/bidi/protocol/network.rb[238-255]
py/private/_network_handlers.py[213-243]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Decision #2 introduces URL pattern component names (`host`, `path`, `query`) and Java example factories (`UrlPattern.host(...)`) that conflict with Selenium’s current BiDi UrlPatternPattern field naming (`hostname`, `pathname`, `search`). This creates an ambiguous cross-binding contract that can lead to incompatible implementations.

### Issue Context
Selenium already has BiDi URL pattern representations in multiple bindings (Java/JS/Ruby/Python) that follow the BiDi field names.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[57-72]
- docs/decisions/17685-network-handler-behavior.md[84-87]

### What to change
- Pick one of:
 - **Adopt the BiDi field names in the ADR** (`hostname`, `pathname`, `search`) and update the Ruby/Java snippets accordingly (e.g., `new UrlPattern().hostname("api.example.com")...`).
 - **Keep the ADR’s conceptual names** (`host`/`path`/`query`) but explicitly define the normative mapping to BiDi (`host→hostname`, `path→pathname`, `query→search`) and update the Java examples so they are valid (don’t call non-existent `UrlPattern.host(...)` unless the ADR also specifies adding such factories).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Auth handler API ambiguous ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

Decision #2 states authentication handlers "return credentials" and "do not ... respond", but the
adjacent example calls c.respond(...) (a side-effect API) instead of returning credentials. This
internal contradiction makes the proposed auth-handler contract unclear and risks different bindings
implementing incompatible semantics.

Code

docs/decisions/17685-network-handler-behavior.md[R55-64]

+2. **A handler is a callable, including authentication.** A request or response callable receives the
+   event object and acts on it. An authentication callable receives the challenge and returns
+   credentials for it; it does not fail, respond, or submit, and is not part of the disposition
+   chain. A callable lets credentials be computed per challenge; a static username and password for a
+   URL pattern is also accepted directly, without a callable.
+
+```ruby
+network.add_authentication_handler { |c| c.respond(vault.credentials_for(c.url)) }
+network.add_authentication_handler(username: "user", password: "pass", uri: "https://secure.example.com/*")
+```

Evidence

The ADR’s normative text says auth handlers return credentials and "do not ... respond", but the
included Ruby sketch demonstrates c.respond(...), creating an explicit contradiction within the
same decision section.

docs/decisions/17685-network-handler-behavior.md[55-64]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Decision #2 describes authentication handlers as returning credentials and explicitly says they do not `respond`, but the example immediately uses `c.respond(...)`. This is a normative ADR, so the prose and example must align to avoid inconsistent cross-binding implementations.

### Issue Context
You can resolve this either by:
- Making the contract **return-based** (handler returns credentials; no `respond` method), **or**
- Making the contract **command-based** (handler calls `respond(credentials)` / similar on the challenge object; it is not part of the request/response disposition chain).

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[55-64]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Undefined add_x_handler name ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

Decision #10 says body collection happens only through add_x_handler, but the ADR otherwise uses
concrete method names like add_request_handler and add_response_handler. Leaving an undefined
placeholder in the normative text can confuse implementers about the intended API surface and where
body collection is supported.

Code

docs/decisions/17685-network-handler-behavior.md[R165-177]

+10. **Body data is collected only when the handler opts in at registration.** A body is not available
+    by default; the handler declares that it needs the body when it is registered — not from inside
+    the callback, since the collector must be in place before the event — and Selenium then owns the
+    collector's lifecycle, size cap, and browser-support quirks. The body is readable on the event
+    inside that handler.
+   * The user never calls `addDataCollector` / `getData` or tears a collector down.
+   * There is no way to collect or read body data outside a handler; collection happens only through
+     `add_x_handler`.
+
+```ruby
+# Declare body collection at registration; the body is then available on the event
+network.add_response_handler(collect_body: true) { |r| log(r.body) }
+```

Evidence

The body-collection rule references add_x_handler, but the same ADR’s examples and API discussion
use add_request_handler and add_response_handler, indicating add_x_handler is not a defined
method name here.

docs/decisions/17685-network-handler-behavior.md[165-172]
docs/decisions/17685-network-handler-behavior.md[49-53]
docs/decisions/17685-network-handler-behavior.md[174-177]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Decision #10 uses `add_x_handler` without defining it as shorthand or naming the actual methods. Elsewhere the ADR uses `add_request_handler` / `add_response_handler`, so the placeholder is ambiguous.

### Issue Context
If body collection is supported for both request and response handlers, name both explicitly (or define `add_x_handler` as shorthand once and use it consistently). If it’s only supported for response handlers, say so directly.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[165-177]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Java order nondeterministic ✓ Resolved 🐞 Bug ≡ Correctness

Description

The ADR table says Java runs “only the first matching handler”, but the current Java implementation
selects a matching handler from a ConcurrentHashMap stream with no defined encounter order, so the
chosen handler is effectively arbitrary and can vary between runs. This can mislead
readers/implementers about Java’s current precedence semantics.

Code

docs/decisions/17685-network-handler-behavior.md[18]

+| Java       | Only the first matching handler runs; disposition is always continue; a throwing handler propagates and leaves the request blocked; return-value driven; no response handler or managed body collection. |

Evidence

The ADR claims a “first” handler semantics for Java, but Java stores handlers in a ConcurrentHashMap
and selects via values().stream()...findFirst(), which does not guarantee ordering; therefore the
selected handler is not consistently the first-registered or otherwise deterministic handler.

docs/decisions/17685-network-handler-behavior.md[16-22]
java/src/org/openqa/selenium/remote/RemoteNetwork.java[47-50]
java/src/org/openqa/selenium/remote/RemoteNetwork.java[143-148]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR’s “Current behavior” row for Java states “Only the first matching handler runs”, which implies a deterministic ordering. In the current Java implementation, handler selection is performed by streaming `ConcurrentHashMap.values()` and taking `findFirst()`, which has no guaranteed iteration/encounter order.

### Issue Context
This is in the ADR’s binding comparison table; the goal is to accurately describe current behavior so readers understand what is changing.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[16-22]

### Suggested change
Reword the Java row to avoid implying deterministic precedence (e.g., “Only one matching handler runs (selection order is unspecified) ...”), or explicitly state the current selection is not ordered by registration.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. No cross-binding source references 📘 Rule violation ≡ Correctness

Description

The ADR describes binding differences and proposes user-visible handler behavior changes but does
not provide any concrete cross-binding source references (e.g., rg results or links to the
Java/Python/Ruby/.NET/JS implementations) demonstrating the comparison was actually performed. This
risks inconsistent implementation across bindings because reviewers/implementers cannot verify the
stated current behaviors or the proposed alignment points.

Code

docs/decisions/17685-network-handler-behavior.md[R13-22]

+The bindings diverge today: each grew its handler API independently, so dispatch order,
+multi-handler resolution, error handling, and what an event exposes are all inconsistent.
+
+| Binding    | Current behavior |
+|------------|------------------|
+| Java       | Only the first matching handler runs; disposition is always continue; a throwing handler propagates and leaves the request blocked; return-value driven; no response handler or managed body collection. |
+| Python     | An explicit `continue` in a handler fires immediately and wins; otherwise staged outcomes reconcile by `fail` > `provide_response` > `continue`; response handlers have no `fail`; dispatch is FIFO; a throwing handler's staged mutations are still sent; only the mutated event is visible; body is not collected behind the handler. |
+| Ruby       | Handlers run in parallel threads, so multi-handler disposition races; exceptions are logged; dispatch is FIFO with no default-continue; only the mutated event is visible; body collection is user-managed. |
+| .NET       | No request or response handler API. |
+| JavaScript | No request or response handler API. |

Evidence

PR Compliance ID 389265 requires evidence of cross-binding comparison (e.g., project-wide search
output or references to compared files). The ADR includes a cross-binding behavior table but
provides no file references or search evidence to substantiate the claims, making the required
comparison non-auditable.

Rule 389265: Compare cross-language bindings when changing user-visible behavior
docs/decisions/17685-network-handler-behavior.md[13-22]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR asserts current cross-binding behaviors and proposes new user-visible behavior, but it lacks verifiable evidence of cross-binding comparison (project-wide search output and/or direct links to the analogous implementations in other bindings).

## Issue Context
Compliance requires that behavior-changing proposals include evidence of cross-language comparison so implementers can validate baseline behavior and keep bindings logically consistent.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[13-22]

## Suggested remediation
- Add a short section (e.g., "Cross-binding references") that lists at least one concrete file/link per compared binding (Java/Python/Ruby at minimum) that supports the "Current behavior" table entries.
- Optionally include a small snippet of the exact `rg ...` commands used (and the key hits) to demonstrate the repo-wide search comparison was performed.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (5)

6. Auth callable contradiction ✓ Resolved 🐞 Bug ≡ Correctness

Description

The ADR excludes authentication handlers because “authentication should not use a callable,” but
Selenium Ruby’s add_authentication_handler explicitly accepts a block and existing tests use
block-based auth handlers (&:skip, &:cancel). This makes the ADR’s rationale inaccurate for at
least one binding and risks confusing implementers about the scope/baseline.

Code

docs/decisions/17685-network-handler-behavior.md[R20-21]

+This applies to request and response handlers, but not authentication handlers, since
+authentication should not use a callable.

Evidence

Ruby’s Network API accepts an optional block for add_authentication_handler and uses it when
credentials aren’t provided, and Ruby integration tests exercise callable auth handlers via &:skip
and &:cancel, contradicting the ADR’s claim that authentication should not use a callable.

rb/lib/selenium/webdriver/common/network.rb[47-63]
rb/spec/integration/selenium/webdriver/network_spec.rb[86-101]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR states authentication handlers are out of scope because authentication should not use a callable. In current Selenium Ruby, authentication handlers can be provided as a callable/block, so the statement is not universally true across bindings.

## Issue Context
The ADR is meant to be cross-binding guidance; blanket statements that contradict an existing binding’s public API are likely to cause confusion.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[20-21]

## Suggested change
Reword to scope the statement as a proposal or explicitly note that auth handler behavior is out of scope and that existing bindings differ (e.g., “This ADR does not cover authentication handlers; bindings currently vary, and we may revisit whether auth should be callable-based separately.”).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. Wrong Python behavior claim 🐞 Bug ≡ Correctness

Description

The ADR claims current Python behavior lets continueRequest override failures and stubs, but
Python’s BiDi network handler registry resolves outcomes with fixed precedence where any fail()
wins and provide_response() wins over mutations. This misstates the existing semantics and can
mislead readers about what is actually changing.

Code

docs/decisions/17685-network-handler-behavior.md[R158-159]

+  - We could run every handler but have `continueRequest` override failures and stubs (current
+    Python behavior), but it is not obvious why that command should have precedence.

Evidence

Python’s handler registry documents and implements reconciliation where any handler calling fail()
causes the request to be failed during _resolve(), and the integration tests assert that fail
wins when handlers disagree—so continueRequest does not override failures/stubs in current Python
behavior.

py/private/_network_handlers.py[28-37]
py/private/_network_handlers.py[428-437]
py/test/selenium/webdriver/common/bidi_network_tests.py[251-266]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR’s “Considered options → Reconciliation” section states that in current Python behavior `continueRequest` overrides failures and stubs. The Python implementation instead reconciles handler actions with a strict priority (fail > provide_response > continue-with-mutations/default continue), so the ADR’s comparison baseline is inaccurate.

## Issue Context
This ADR is intended to guide cross-binding behavior decisions; incorrect statements about existing behavior can skew review/consensus and lead to incorrect implementations.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[154-160]

## Suggested change
Reword the parenthetical to reflect the actual Python semantics (e.g., “current Python behavior reconciles outcomes with fixed priority (fail > provide_response > continue) after running all matching handlers”).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. Overgeneralized exception behavior 🐞 Bug ⚙ Maintainability

Description

The ADR states (in a comparative bullet) that Selenium logs uncaught handler exceptions instead of
ending the session, but current behavior is binding-specific (e.g., Ruby handler blocks are executed
without rescue/logging, while Python does catch/log). This should be reworded as a proposed
cross-binding behavior or explicitly scoped to the bindings that implement it today.

Code

docs/decisions/network-handler-behavior.md[R77-80]

+   * In Playwright, uncaught exceptions propagate to end the session, which causes problems when
+     something unrelated to the test's intent goes wrong.
+   * Selenium is more lenient and only logs the error to the console.
+

Evidence

Ruby currently invokes handler blocks without rescue/logging, while Python explicitly catches and
logs exceptions, so the ADR’s statement is not uniformly true across Selenium bindings today.

docs/decisions/network-handler-behavior.md[77-80]
rb/lib/selenium/webdriver/common/network.rb[89-96]
py/private/_network_handlers.py[746-756]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR text implies a universal Selenium behavior (“only logs the error to the console”) for handler exceptions, but current bindings differ.

### Issue Context
Ruby’s handler dispatch yields directly to user code without rescue; Python catches/logs and continues.

### Fix Focus Areas
- docs/decisions/network-handler-behavior.md[72-80]

### What to change
- Rephrase the bullet to one of:
 - “In some Selenium bindings (e.g., Python), uncaught handler exceptions are logged and processing continues…”
 - or “Proposed: Selenium should log uncaught handler exceptions and continue processing…”
- If desired, add a short note indicating current binding differences to avoid readers assuming uniform behavior today.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

9. Wrong handler verb names 🐞 Bug ≡ Correctness

Description

The ADR states Selenium request/response handlers use respond/submit (and response fail), but
existing bindings expose different verbs (e.g., Python provide_response/continue_request, Ruby
provide_response/continue) and do not offer a response-level fail. This mismatch will mislead
implementers/readers about current APIs and what exactly is being proposed to change.

Code

docs/decisions/network-handler-behavior.md[R31-43]

+   * Selenium supports:
+     * Request: `fail` (Playwright's `abort`, BiDi's `FailRequest`), `respond` (Playwright's `fulfill`, BiDi's `ProvideResponse`), and `submit` (Playwright's `continue`, BiDi's `ContinueRequest`).
+     * Response: `fail` (BiDi's `FailRequest`), and `submit`: note that since we don't need to prevent a round trip from a request, whether this is a BiDi `ContinueResponse` or `ProvideResponse` can be an implementation detail based on whether a replacement body value is provided.
+
+```ruby
+# Specifics of parameters and names can match spec details
+network.add_request_handler { |r| r.fail if something }
+network.add_request_handler { |r| r.respond(content: mocked_response) if something }
+network.add_request_handler { |r| r.add_header("X-Test", true) && r.submit if something }
+
+network.add_response_handler { |r| r.fail if something }
+network.add_response_handler { |r| r.submit(content: mocked_response) if something }
+network.add_response_handler { |r| r.add_header("X-Test", true) && r.submit if something }

Evidence

The ADR’s listed verbs don’t exist in current binding implementations, which use different method
names and capabilities for request/response interception.

docs/decisions/network-handler-behavior.md[31-43]
py/private/_network_handlers.py[325-438]
py/private/_network_handlers.py[440-581]
rb/lib/selenium/webdriver/bidi/network/intercepted_request.rb[30-58]
rb/lib/selenium/webdriver/bidi/network/intercepted_response.rb[31-68]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR uses handler disposition verbs (`respond`, `submit`, and response `fail`) that don’t match the verbs exposed by current Selenium bindings, which makes the document confusing as a proposal baseline.

### Issue Context
Current Python and Ruby bindings use `provide_response`/`continue_request` (Python) and `provide_response`/`continue` (Ruby), and do not expose a response-level `fail`.

### Fix Focus Areas
- docs/decisions/network-handler-behavior.md[26-44]

### What to change
- Replace “Selenium supports:” wording with either:
 - a binding-neutral set of verbs (and explicitly state they are *proposed* names), or
 - the currently used names (and optionally add a mapping table: proposed ↔ existing per binding).
- Update the Ruby/Python code examples accordingly (e.g., `provide_response`/`continue_request`/`continue`) and remove or clearly label response `fail` as a proposed addition if that’s intended.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

10. Example violates stated behavior 🐞 Bug ≡ Correctness

Description

The Appendix claims the sample process_request implementation satisfies the ADR behaviors, but it
does not handle handler exceptions (behavior 4) and would propagate exceptions from
h.call(request) instead of logging and continuing. As written, it also cannot discard per-handler
staged mutations on exception because it mutates a shared request object.

Code

docs/decisions/network-handler-behavior.md[R208-226]

+The behaviors in this ADR explicitly do not specify an implementation. For illustrative
+purposes, this code — with state stored in the request wrapper object and evaluated after
+execution inside the loop — will satisfy the above behaviors:
+
+```ruby
+def process_request(request)
+  @handlers.reverse_each do |h|
+    h.call(request)
+    if request.complete?
+      h.request = request
+      remove_handler(h)
+    end
+    if request.failed?
+      return fail_request(request)
+    elsif request.response?
+      return provide_response(request)
+    elsif request.submit? || request.complete?
+      return continue_request(request)
+    end

Evidence

The ADR requires log-and-continue on handler exceptions, but the appendix code calls handlers
without any rescue/try-catch while still claiming it satisfies the behaviors.

docs/decisions/network-handler-behavior.md[72-79]
docs/decisions/network-handler-behavior.md[208-226]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The appendix implementation is presented as satisfying the ADR behaviors, but it lacks exception handling around handler invocation and does not show how staged mutations are discarded when a handler errors.

### Issue Context
Behavior 4 requires uncaught exceptions to be logged, staged changes discarded, and processing to continue as if the handler was not registered.

### Fix Focus Areas
- docs/decisions/network-handler-behavior.md[72-85]
- docs/decisions/network-handler-behavior.md[208-229]

### What to change
- Wrap `h.call(request)` in a begin/rescue (or language-appropriate equivalent) and explicitly note logging + continuing.
- Either:
 - update the pseudocode to show per-handler isolation/rollback of staged mutations (e.g., snapshot/clone before calling handler and restore on exception), or
 - amend the text to state the pseudocode is simplified and *does not* model rollback semantics (so it’s not claimed to fully satisfy behavior 4).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

11. Exception propagation unclear ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

Behavior 5 says intercept-handler exceptions “propagate” while also requiring the event to “keep
flowing as if that handler had not run,” but it doesn’t explicitly state how propagation should be
surfaced without interrupting dispatch/request resolution. This ambiguity can lead to inconsistent
cross-binding implementations of the same proposed behavior.

Code

docs/decisions/17685-network-handler-behavior.md[R104-106]

+5. **An uncaught exception discards the handler's staged changes; it propagates for an intercept
+   handler and is logged for an observe handler.** Either way the event keeps flowing as if that
+   handler had not run, so one broken handler cannot corrupt live traffic or stall the page. The

Evidence

The ADR simultaneously requires exception “propagation” for intercept handlers and continued event
flow, and the provided example implies remaining handlers still take effect; existing handler
dispatch code in-repo shows continued flow is typically implemented by catching exceptions and
continuing, which highlights why the ADR should be explicit about how “propagate” is achieved
without interrupting dispatch.

docs/decisions/17685-network-handler-behavior.md[104-106]
docs/decisions/17685-network-handler-behavior.md[114-120]
py/private/_network_handlers.py[746-766]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Behavior 5 mixes two distinct requirements (error visibility and continued network flow) without stating the intended mechanism for “propagate” in intercept mode. Readers may interpret “propagate” as letting the exception abort handler dispatch, which conflicts with the “event keeps flowing” requirement.

## Issue Context
The ADR’s example text also implies that other handlers’ effects still apply even when one handler errors.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[104-111]
- docs/decisions/17685-network-handler-behavior.md[114-120]

## Suggested direction
Adjust behavior 5 wording to explicitly separate:
1) **Network disposition guarantee:** Selenium must still resolve/unblock the event as if the failing handler did not run (discarding its staged mutations).
2) **Error visibility guarantee:** For intercept handlers, the error is surfaced to the user (e.g., recorded and raised at a defined observation point / next driver call), while dispatch continues; for observe handlers, it is logged.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

12. Markdown nesting broken ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

Under decision #7, the first bullet line is indented less than the preceding continuation lines of
the same list item, which can cause CommonMark/GitHub rendering to treat it as a separate top-level
list instead of nested under item 7. This makes the ADR harder to read and can change the visual
structure of the decision.

Code

docs/decisions/17685-network-handler-behavior.md[R129-134]

+7. **Body data is collected only when the handler opts in at registration.** A body is not
+   available by default; the handler declares that it needs the body when it is registered — not
+   from inside the callback, since the collector must be in place before the event — and Selenium
+   then owns the collector's lifecycle, size cap, and browser-support quirks. The body is readable
+   on the event inside that handler.
+  * The user never calls `addDataCollector` / `getData` or tears a collector down.

Evidence

Within list item 7, the continuation lines are indented deeper than the bullet that follows,
indicating inconsistent nesting that can alter Markdown rendering.

docs/decisions/17685-network-handler-behavior.md[129-134]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The nested bullet list under item 7 is not consistently indented, which can break Markdown nesting and render incorrectly.

### Issue Context
Under ordered list item `7.`, the paragraph continuation lines are indented more than the subsequent `*` bullet line, so the bullets may not be considered part of item 7.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[129-134]

### Suggested change
Indent the `*` bullet lines to the same level as the continuation lines for item 7 (typically 3–4 spaces after the margin for CommonMark nested content under an ordered list item).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

Code review by qodo was updated up to the latest commit 18895d1

[diemol]

I think this ADR will help us unify handler behavior across all language bindings, which is currently handled differently in each language.

If I understand this correctly, @titusfortner suggests this ADR is an alternative to #17671. But what I see is that this ADR covers network interception, which blocks because it waits for a handler disposition. Whereas #17671 is about observation, which should not block, and only subscribes to events (did I get that right, @AutomatedTester?).

That is why I believe the two ADRs complement each other.

In addition, this ADR, like #17671, seems to me to be a middle-layer API. One that users would use for specific use cases that the high-level API won't cover.

[titusfortner]

@diemol

Whereas #17671 is about observation, which should not block, and only subscribes to events

In the last TLC meeting people were pushing for the idea that for now everything that can block will block in our implementations and we won't handle it any differently.

I'm saying they are in opposition because if you adopt this ADR, you don't need the extra methods proposed by the other ADR.

Also, I think it is wrong to characterize these as "middle-layer API." Anything that affects the code the user needs to write is user-facing and needs to be part of the high-level API contract we are creating that we want to maintain.

[diemol]

@diemol

Whereas #17671 is about observation, which should not block, and only subscribes to events

In the last TLC meeting people were pushing for the idea that for now everything that can block will block in our implementations and we won't handle it any differently.

I'm saying they are in opposition because if you adopt this ADR, you don't need the extra methods proposed by the other ADR.

Also, I think it is wrong to characterize these as "middle-layer API." Anything that affects the code the user needs to write is user-facing and needs to be part of the high-level API contract we are creating that we want to maintain.

The way I see these two ADRs:

• This one is to actually manipulate the network call.
• The other one is for observation, because if you want to do observation and interception, then this could actually slow down tests, because you're intercepting and manipulating the call. I don't think that's what we want to do.

That's why I think there are two other options: either observe or intercept here.

I still think that this is a middle-layer API. I don't want the user to have to handle all these callbacks and other things to manipulate their code in BiDi. I want this API to land and be used in a higher-level API to do network routing, mocking, and method interception, covering all of this implementation.

In my head, we should have:

1. The CDDL parsing to generate the low-level stuff
2. The part where we map commands and do the instantiation of the driver
3. This current ADR, which is like the middle level
4. Some high-level features that make it very easy for users to actually interact with BiDi

If this current ADR is what we're doing at the high level, it is way too complex.

[qodo-code-review]

Code review by qodo was updated up to the latest commit 281e9bb

[qodo-code-review]

Code review by qodo was updated up to the latest commit 895d532

[titusfortner]

1. I removed the requirement for a "complete" resolution method because it was confusing things and also because I no longer think it is necessary right now
2. I added the requirement for toggling observation vs interception to minimize the confusion around this one vs [docs] decision: BiDi events are awaited with expect_* context managers #17671. Our normal handler method needs to support observation directly either now or in the future, we don't need (and shouldn't have) a separate method just because of that.
3. I want to push back on calling this middle layer. This is what we agreed to as the high layer at the TLC summit in SF 2 years ago. To clarify, what I think you are suggesting is methods that wrap the handler so users don't need to work with lambdas for common cases? If so, that represents a major expansion of the API across all the bindings for no functional gain when we don't even have the underlying behavior we want sorted out.

Can we get the functionality implemented across the bindings then figure out which wrappers and helpers and fixtures to add later?

I feel like we may need to step back from the ADRs and agree to the milestones and requirements for Selenium 5 again.

[diemol]

I removed the requirement for a "complete" resolution method because it was confusing things and also because I no longer think it is necessary right now

This is confusing because my interpretation is that the complete resolution is one of the core items of this ADR. Specially for network interception.

Our normal handler method needs to support observation directly either now or in the future, we don't need (and shouldn't have) a separate method just because of that.

I think this bit is what #17671 and this ADR need to agree on. That is the foundation for both.

I want to push back on calling this middle layer. This is what we agreed to as the high layer at the TLC summit in SF 2 years ago. To clarify, what I think you are suggesting is methods that wrap the handler so users don't need to work with lambdas for common cases? If so, that represents a major expansion of the API across all the bindings for no functional gain when we don't even have the underlying behavior we want sorted out.

I am calling it a middle layer, which is core to what we want to achieve, because when I check Playwright's API, I see a high-level API that lets users handle less. But I think you have a point: landing all this "first and later" about major abstractions.

[titusfortner]

my interpretation is that the complete resolution is one of the core items of this ADR.

Based on your questions it didn't seem like you understood my intention for including it or how it worked (it was never blocking anything, there was nothing in the lambda that needed resolving or a true state), so it seemed distracting from what I consider to be the primary things I want us to agree on.

Essentially 17671 and the "complete" method are 2 different ways to manage a wrapper around behavior the user can already easily do themselves for network calls.

desired_request = nil
handler = driver.network.add_request_handler { |req| desired_request = req if matching_condition(req) }
do_something
wait.until { !desired_request.nil? }
driver.network.remove_request_handler(handler)

Is it actually a priority to provide convenience methods to replaces those 4 lines?

When I started thinking in those terms I decided that we don't need wrapper behavior right now, so if I want to reject 17671 on that basis, I should also reject my "complete" method. If we decide we want wrapper behavior, then I would still prefer "complete" over "expect_*"

But also it feels like we're arguing over implementation details of a concept we haven't even agreed is behavior we need right now, so I also want to be able to step back one level on it.

For instance, I don't think "how to differentiate between observation and interception" is actually fundamental to any of our other conversations. The TLC meeting 2 weeks ago the general consensus from everyone else was to defer this decision until later because "intercept everything for now" works well enough for most things. I'd rather hammer it out now, but I'm fine with pushing it off. I only added it here to show that supporting it isn't a sufficient reason on its own to expand the API and accept 17671.

[qodo-code-review]

Code review by qodo was updated up to the latest commit 2d7b847

[Copilot]

Pull request overview

This pull request introduces a new Architecture Decision Record (ADR) defining the intended cross-binding behavior of Selenium’s protocol-neutral driver.network async/event handler API, specifically how request/response/authentication handlers are registered and how they compose when multiple handlers match.

Changes:

• Adds an ADR specifying handler registration (add/remove/clear), scoping via structured URL-pattern components, and handler execution ordering (LIFO).
• Defines observation vs interception mode semantics, disposition resolution (first to settle stops the chain), and default “fall through” behavior.
• Specifies exception handling semantics and opt-in body collection behavior.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (7) 📘 Rule violations (2) 📜 Skill insights (0)

1. Double-settle outcome unclear ✓ Resolved 🐞 Bug ≡ Correctness

Description

Decision 4 says a second disposition call “raises,” but the ADR does not specify whether the event
remains resolved according to the first disposition or whether the raised error changes
dispatch/continuation behavior via decision 7. This leaves bindings room to diverge for the common
user bug of calling fail/respond/submit more than once.

Code

docs/decisions/17685-network-handler-behavior.md[R143-144]

+   * Within one handler, settling more than once is an error — after it settles, a further
+     disposition call raises rather than overriding the first.

Evidence

The ADR defines that a second disposition call raises (decision 4) but also defines that uncaught
exceptions surface while the event continues (decision 7). Without a stated precedence between these
rules, bindings can implement different wire outcomes and handler-chain behavior when a handler
mistakenly settles twice.

docs/decisions/17685-network-handler-behavior.md[141-144]
docs/decisions/17685-network-handler-behavior.md[195-198]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Decision 4 states that settling more than once raises, but does not define what happens to the already-settled event when that error is raised (e.g., does the first disposition remain authoritative and stop the chain, or can the exception path re-enable continuation/next-handler processing).

## Issue Context
Decision 7 separately states that uncaught exceptions surface but the event still continues so the browser is not left waiting. Combined with the new “second disposition raises” rule, this needs an explicit tie-breaker.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[143-144]
- docs/decisions/17685-network-handler-behavior.md[195-198]

## Suggested change
Add a normative rule such as:
- Once a disposition is settled, the wire outcome is fixed and the handler chain is stopped.
- Any subsequent disposition attempts raise to the user but MUST NOT change the already-settled outcome or re-open the chain.
- Clarify whether the raised error is treated identically to other handler exceptions under decision 7 (surface to user, but do not alter the already-resolved event).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Post-settle mutations undefined 🐞 Bug ≡ Correctness

Description

Decision 4 defines that the first disposition-settling action resolves the event and stops the
chain, but it does not specify what happens if the same handler continues mutating the event object
after calling fail/respond/submit. Without an explicit rule, bindings can diverge on whether
those late mutations are applied, ignored, or rejected.

Code

docs/decisions/17685-network-handler-behavior.md[R130-136]

+4. **When a handler settles a disposition, the first to do so resolves the event and
+   stops the chain.** The user settles the event by acting on the object the callable receives. A
+   handler that only stages mutations does not settle; it passes the event to the next handler
+   (decision 5).
+   * A request has three: `fail` (BiDi's `FailRequest`) ends it with an error;
+     `respond` (`ProvideResponse`) replies with a mock, so nothing reaches the server; `submit`
+     (`ContinueRequest`) sends it on, with any staged mutations, and consults no further handler.

Evidence

The ADR specifies chain short-circuiting on disposition settlement but does not define whether
additional mutations after settlement are meaningful, leaving room for inconsistent implementations.

docs/decisions/17685-network-handler-behavior.md[130-136]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR does not define the event-object lifecycle after a handler settles disposition (e.g., calling `submit`). It is unclear whether subsequent mutator calls in the same callback have any effect.

### Issue Context
Because handlers act by mutating an event object, a concrete rule is needed to keep behavior portable across bindings.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[130-136]

### Suggested change
Add a normative statement like:
- Once disposition is settled, the event is finalized; any subsequent mutation attempts are (choose one) ignored or raise an error.
- Only mutations staged *before* settlement are included in the resulting request/response.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Body visibility ambiguous ✗ Dismissed 🐞 Bug ≡ Correctness

Description

Decision 10 says body collection is enabled when “the handler opts in” and that the body is readable
“inside that handler,” but it does not define whether body data should also be available to other
matching handlers in the same multi-handler dispatch. This omission can lead to inconsistent binding
behavior and inconsistent performance characteristics.

Code

docs/decisions/17685-network-handler-behavior.md[R241-248]

+10. **Body data is collected only when the handler opts in at registration.** A body is not available
+    by default; the handler declares that it needs the body when it is registered — not from inside
+    the callback, since the collector must be in place before the event — and Selenium then owns the
+    collector's lifecycle, size cap, and browser-support quirks. The body is readable on the event
+    inside that handler.
+    * The user never calls `addDataCollector` / `getData` or tears a collector down.
+    * There is no way to collect or read body data outside a handler; collection happens only through
+      the `addRequestHandler` / `addResponseHandler` registration.

Evidence

The ADR scopes body readability to “that handler” while also defining a multi-handler dispatch model
elsewhere, but does not state how those two concepts interact.

docs/decisions/17685-network-handler-behavior.md[241-248]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR does not specify whether body collection/visibility is per-event (shared across all handlers once enabled) or per-registration/per-handler (visible only to the handler that requested it).

### Issue Context
Decisions 4–6 explicitly allow multiple handlers per phase with ordered dispatch; body collection must compose with that model, otherwise bindings will diverge.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[241-248]

### Suggested change
Add a normative rule such as:
- If any matching handler is registered with body collection enabled, the body is collected for that event and is available to (choose one) (a) all subsequently invoked matching handlers, or (b) only handlers whose registrations requested collection.
Also clarify whether collection is deduplicated when multiple handlers opt in.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View high (3)

4. Observer timing unspecified ✗ Dismissed 🐞 Bug ≡ Correctness

Description

Decision 7 says observing handlers have no defined order, but the ADR never defines whether
observers run before or after the intercepting-handler chain or what event snapshot (original vs
mutated/resolved) they observe. This leaves room for bindings to expose different observer-visible
data for the same traffic, undermining portability of monitoring/logging code.

Code

docs/decisions/17685-network-handler-behavior.md[R200-201]

+   * Ordering is a property of the chain, so it covers intercepting handlers; observing handlers
+     have no defined order, including relative to one another.

Evidence

The ADR defines observers as read-only and outside the disposition chain, but later only states they
have no defined order without specifying their sequencing relative to the intercept chain or what
they observe.

docs/decisions/17685-network-handler-behavior.md[132-137]
docs/decisions/17685-network-handler-behavior.md[200-201]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR states that observing handlers have no defined order, but does not define *when* they run relative to the intercepting handler chain or *which representation* of the event they receive (original vs staged-mutation view vs final/resolved view). This underspecification will likely lead to cross-binding divergence in what observers can see.

### Issue Context
- Observers are defined as read-only and outside the disposition chain.
- Intercept handlers can stage mutations and/or settle the event.
- The ADR should explicitly define the observer-visible snapshot and sequencing relative to interception so that implementations converge.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[132-137]
- docs/decisions/17685-network-handler-behavior.md[200-201]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. UrlPattern naming mismatch ✓ Resolved 🐞 Bug ≡ Correctness

Description

Decision 2 defines URL-pattern components as host/path/query and uses UrlPattern.host(...),
but existing Selenium BiDi UrlPatternPattern implementations use hostname/pathname/search and
Java’s UrlPattern exposes hostname() (no host()). Without an explicit canonical
naming/mapping, bindings are likely to implement incompatible pattern objects or conflicting
examples.

Code

docs/decisions/17685-network-handler-behavior.md[R57-72]

+2. **A handler is scoped by an optional list of URL patterns given as structured objects.** Each
+   pattern is an object of URL components — protocol, host, port, path, query — each optional: a
+   component that is set matches exactly, one left unset matches any value. A handler matches a
+   request against any pattern in its list; with no list it matches every request. A pattern is an
+   object, not a URL or glob string.
+
+```ruby
+# One or more component objects; a request matches any of them
+network.add_request_handler(url_patterns: [{host: "api.example.com"}, {host: "cdn.example.com"}]) { |r| r.fail }
+```
+
+```java
+network.addRequestHandler(
+    List.of(UrlPattern.host("api.example.com"), UrlPattern.host("cdn.example.com")),
+    r -> r.fail());
+```

Evidence

The ADR defines and exemplifies URL pattern components using host and UrlPattern.host(...),
while the existing Selenium BiDi URL pattern types and helpers across bindings consistently use
hostname/pathname/search and Java has no host()/host(...) API. This mismatch demonstrates
the ADR’s current wording/examples are not aligned with the established BiDi shape in the repo and
must be clarified to avoid divergent implementations.

docs/decisions/17685-network-handler-behavior.md[57-72]
docs/decisions/17685-network-handler-behavior.md[84-87]
java/src/org/openqa/selenium/bidi/network/UrlPattern.java[25-56]
javascript/selenium-webdriver/bidi/urlPattern.js[18-89]
rb/lib/selenium/webdriver/bidi/protocol/network.rb[238-255]
py/private/_network_handlers.py[213-243]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Decision #2 introduces URL pattern component names (`host`, `path`, `query`) and Java example factories (`UrlPattern.host(...)`) that conflict with Selenium’s current BiDi UrlPatternPattern field naming (`hostname`, `pathname`, `search`). This creates an ambiguous cross-binding contract that can lead to incompatible implementations.

### Issue Context
Selenium already has BiDi URL pattern representations in multiple bindings (Java/JS/Ruby/Python) that follow the BiDi field names.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[57-72]
- docs/decisions/17685-network-handler-behavior.md[84-87]

### What to change
- Pick one of:
 - **Adopt the BiDi field names in the ADR** (`hostname`, `pathname`, `search`) and update the Ruby/Java snippets accordingly (e.g., `new UrlPattern().hostname("api.example.com")...`).
 - **Keep the ADR’s conceptual names** (`host`/`path`/`query`) but explicitly define the normative mapping to BiDi (`host→hostname`, `path→pathname`, `query→search`) and update the Java examples so they are valid (don’t call non-existent `UrlPattern.host(...)` unless the ADR also specifies adding such factories).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Auth handler API ambiguous ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

Decision #2 states authentication handlers "return credentials" and "do not ... respond", but the
adjacent example calls c.respond(...) (a side-effect API) instead of returning credentials. This
internal contradiction makes the proposed auth-handler contract unclear and risks different bindings
implementing incompatible semantics.

Code

docs/decisions/17685-network-handler-behavior.md[R55-64]

+2. **A handler is a callable, including authentication.** A request or response callable receives the
+   event object and acts on it. An authentication callable receives the challenge and returns
+   credentials for it; it does not fail, respond, or submit, and is not part of the disposition
+   chain. A callable lets credentials be computed per challenge; a static username and password for a
+   URL pattern is also accepted directly, without a callable.
+
+```ruby
+network.add_authentication_handler { |c| c.respond(vault.credentials_for(c.url)) }
+network.add_authentication_handler(username: "user", password: "pass", uri: "https://secure.example.com/*")
+```

Evidence

The ADR’s normative text says auth handlers return credentials and "do not ... respond", but the
included Ruby sketch demonstrates c.respond(...), creating an explicit contradiction within the
same decision section.

docs/decisions/17685-network-handler-behavior.md[55-64]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Decision #2 describes authentication handlers as returning credentials and explicitly says they do not `respond`, but the example immediately uses `c.respond(...)`. This is a normative ADR, so the prose and example must align to avoid inconsistent cross-binding implementations.

### Issue Context
You can resolve this either by:
- Making the contract **return-based** (handler returns credentials; no `respond` method), **or**
- Making the contract **command-based** (handler calls `respond(credentials)` / similar on the challenge object; it is not part of the request/response disposition chain).

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[55-64]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. glob warning left optional 📘 Rule violation ⚙ Maintainability ⭐ New

Description

The ADR makes glob-looking pattern warnings optional per binding, which enables user-visible
divergence across language bindings. This conflicts with the cross-binding consistency requirement
for shared behavior expectations.

Code

docs/decisions/17685-network-handler-behavior.md[R80-82]

+   valid pattern errors. A binding may log a warning when a value looks like a
+   glob, to flag that Selenium forwards it rather than expanding it; that
+   detection is optional and left to the binding rather than specified here.

Evidence

PR Compliance ID 4 requires cross-binding consistency for user-visible/shared behavior changes. The
added ADR text explicitly makes the glob-looking pattern warning optional and binding-specific,
permitting inconsistent behavior between bindings.

AGENTS.md: Cross-binding Consistency for User-visible or Shared Protocol Behavior Changes
docs/decisions/17685-network-handler-behavior.md[80-82]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR states that logging a warning for glob-looking URL patterns is optional per binding, which invites inconsistent user-visible behavior across bindings.

## Issue Context
This ADR is meant to align cross-binding behavior for the network handler API; optional warnings undermine that alignment unless a clear follow-up plan is recorded.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[80-82]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. Context scoping rules undefined 🐞 Bug ⚙ Maintainability

Description

Decision 11 allows scoping a handler by browsing context, user context, or both, but does not define
how providing both combines (AND vs precedence vs union) or what happens when the provided contexts
conflict, which will produce incompatible interception scopes across bindings.

Code

docs/decisions/17685-network-handler-behavior.md[R270-273]

+11. **Handlers are scoped to the current browsing context by default.** A handler applies to the
+    browsing context that is active when it is registered, resolved from the current window; the user
+    may pass a browsing context, a user context, or both to scope it elsewhere. This lets a handler
+    apply to a context that is not the active one, such as a background tab that does not currently

Evidence

The decision text explicitly allows providing both scope types but provides no combination or
mismatch rules, leaving a gap implementers must guess at.

docs/decisions/17685-network-handler-behavior.md[270-274]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Decision 11 explicitly permits passing a browsing context, a user context, or both, but does not define the required semantics when both are provided or when they disagree.

## Issue Context
Different bindings may interpret “both” differently (intersection vs precedence vs union), and may or may not validate that the browsing context belongs to the user context.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[270-274]
- docs/decisions/17685-network-handler-behavior.md[382-383]

## Suggested fix
Add explicit normative rules covering:
- whether supplying both means intersection (BC within UC), precedence (one overrides), or union
- required validation when the browsing context is not part of the user context (error vs ignore one)
- behavior when the default scope cannot be resolved from the “current window” (e.g., no active window)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

9. Body cap semantics missing ✗ Dismissed 🐞 Bug ⚙ Maintainability

Description

Decision 10 states Selenium owns the body collector “size cap” but does not define the cap policy or
the externally observable behavior when the cap is exceeded (e.g., truncate vs error vs
incomplete-body signaling), so bindings can implement incompatible outcomes for large request
bodies.

Code

docs/decisions/17685-network-handler-behavior.md[R251-253]

+    available by default; the handler declares that it needs the body when it is registered — not from
+    inside the callback, since the collector must be in place before the event — and Selenium then owns
+    the collector's lifecycle, size cap, and browser-support quirks. The body is readable on the event

Evidence

The ADR introduces a required “size cap” ownership but never defines the cap policy or overflow
semantics, leaving behavior underspecified.

docs/decisions/17685-network-handler-behavior.md[250-254]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Decision 10 claims Selenium owns the request-body collector’s “size cap”, but the ADR does not define what the cap is, whether it is configurable, or what must happen when the body exceeds the cap. This leaves observable behavior undefined and can cause cross-binding divergence.

## Issue Context
This ADR is meant to define portable semantics across language bindings.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[250-259]

## Suggested fix
Amend Decision 10 to specify, at minimum:
- whether the cap is fixed vs configurable (and where configured)
- what happens on overflow (error the handler registration vs error the specific event vs truncate)
- whether the handler still runs and how the event exposes “incomplete/truncated” body state
- whether overflow affects disposition calls (fail/respond/submit)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (11)

10. Normative API unclear 🐞 Bug ⚙ Maintainability

Description

The ADR says examples are “not a prescribed API” but then immediately lists concrete method names
(e.g., addRequestHandler/removeRequestHandler/clearRequestHandlers) as part of the decision,
leaving it unclear whether names/signatures are normative or only the semantics are. This can lead
to cross-binding API divergence even when behavior matches.

Code

docs/decisions/17685-network-handler-behavior.md[R34-40]

+By default, a handler blocks the event until it has run. The decisions below can be implemented in
+more than one way; the Ruby and Java examples show the user-facing shape, not a prescribed API.
+
+1. **Handlers can be added, removed, and cleared.** Each family — request,
+   response, and authentication — has an add, a remove, and a clear:
+   `addRequestHandler`, `removeRequestHandler`, and `clearRequestHandlers`, with
+   the equivalents for response and authentication. `add` returns a handle

Evidence

The decision section explicitly states the examples are not prescriptive, but then enumerates exact
method names as the decision, creating unclear normativity for implementers.

docs/decisions/17685-network-handler-behavior.md[34-40]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR simultaneously claims the examples are not a prescribed API while listing concrete method names in the decision text, which makes it ambiguous whether the exact names/signatures are required.

### Issue Context
This ADR is intended to align behavior across bindings; ambiguous normativity can produce inconsistent public APIs.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[34-40]

### Suggested change
Either (a) remove/soften “not a prescribed API” and explicitly state the listed operations + naming are required, or (b) keep the disclaimer but rephrase decision #1 to state only required *capabilities/semantics* (add/remove/clear + handle semantics) while allowing bindings to choose idiomatic names/signatures.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

11. Observe+patterns undefined ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

Decision 2 defines URL patterns for intercepting handler registration, while Decision 4 says
observing handlers “take no patterns,” but the ADR does not specify the required behavior when a
user supplies patterns while selecting observe mode. Without an explicit rule (e.g., raise on
invalid combination), bindings may diverge between ignoring the patterns vs rejecting the call.

Code

docs/decisions/17685-network-handler-behavior.md[R133-136]

+   The mode is decided at registration; intercepting is the default and observing is opt-in. An
+   observing handler receives a read-only event object, takes no part in the disposition chain
+   (decisions 5–7), and takes no patterns. An intercepting handler receives a mutable
+   event object: it can stage changes and settle the event, and traffic is paused until handling

Evidence

URL patterns are specified as part of intercepting registration, while observing explicitly says it
takes no patterns; additionally, the considered-options section argues against observer patterns
matched client-side, reinforcing that the ADR should define invalid-combination handling rather than
leaving it open.

docs/decisions/17685-network-handler-behavior.md[65-67]
docs/decisions/17685-network-handler-behavior.md[133-136]
docs/decisions/17685-network-handler-behavior.md[319-320]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR states that URL patterns are provided when registering an intercepting handler, and that observing handlers take no patterns, but it never defines what happens if a caller provides `url_patterns` (or equivalent) while registering an observing handler.

### Issue Context
This is an API contract/validation gap: if the binding exposes a single registration method with options/overloads, callers can plausibly pass both `observe: true` and `url_patterns`. The ADR should mandate consistent behavior across bindings (most naturally: reject with a clear argument error at registration).

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[65-67]
- docs/decisions/17685-network-handler-behavior.md[133-136]
- docs/decisions/17685-network-handler-behavior.md[319-320]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

12. Observe/body collection unclear ✓ Resolved 🐞 Bug ≡ Correctness

Description

Decision 11 requires opt-in body collection and says the body is readable inside the handler, but it
does not specify whether this applies to observe (non-blocking) handlers, intercept handlers, or
both. Without this, bindings may diverge on whether observe stays non-blocking when collect_body
is enabled and when body data becomes available.

Code

docs/decisions/17685-network-handler-behavior.md[R276-284]

+11. **Body data is collected only when the handler opts in at registration.** A body is not available
+    by default; the handler declares that it needs the body when it is registered — not from inside
+    the callback, since the collector must be in place before the event — and Selenium then owns the
+    collector's lifecycle, size cap, and browser-support quirks. The body is readable on the event
+    inside that handler.
+    * The user never calls `addDataCollector` / `getData` or tears a collector down.
+    * There is no way to collect or read body data outside a handler; collection happens only through
+      the `add_request_handler` / `add_response_handler` registration.
+

Evidence

The ADR explicitly distinguishes observe handlers as non-blocking/non-pausing, while separately
requiring body collection to be installed before the event and making the body readable inside the
handler, but it never defines whether these features can be combined or what semantics apply when
they are.

docs/decisions/17685-network-handler-behavior.md[131-137]
docs/decisions/17685-network-handler-behavior.md[276-284]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR defines observe vs intercept modes (including a non-blocking guarantee for observe) but later adds opt-in body collection without stating how that interacts with observe mode. This can produce inconsistent semantics across bindings (e.g., body collection forcing buffering/delay, or being rejected for observe).

### Issue Context
- Decision 4: observe is read-only and “does not pause network traffic”.
- Decision 11: body collection must be declared at registration and “body is readable on the event inside that handler”.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[131-137]
- docs/decisions/17685-network-handler-behavior.md[276-284]

### Suggested change
Add a normative rule clarifying one of:
- `collect_body` is supported only for intercept handlers (observe cannot request bodies), OR
- `collect_body` is supported for observe, but body is delivered only once fully available and must not pause traffic (define whether handler invocation is delayed vs body field is optional/empty until completion).
Also specify what happens when body collection is unsupported or exceeds the size cap (error vs omission) to keep behavior consistent across bindings.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

13. Undefined add_x_handler name ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

Decision #10 says body collection happens only through add_x_handler, but the ADR otherwise uses
concrete method names like add_request_handler and add_response_handler. Leaving an undefined
placeholder in the normative text can confuse implementers about the intended API surface and where
body collection is supported.

Code

docs/decisions/17685-network-handler-behavior.md[R165-177]

+10. **Body data is collected only when the handler opts in at registration.** A body is not available
+    by default; the handler declares that it needs the body when it is registered — not from inside
+    the callback, since the collector must be in place before the event — and Selenium then owns the
+    collector's lifecycle, size cap, and browser-support quirks. The body is readable on the event
+    inside that handler.
+   * The user never calls `addDataCollector` / `getData` or tears a collector down.
+   * There is no way to collect or read body data outside a handler; collection happens only through
+     `add_x_handler`.
+
+```ruby
+# Declare body collection at registration; the body is then available on the event
+network.add_response_handler(collect_body: true) { |r| log(r.body) }
+```

Evidence

The body-collection rule references add_x_handler, but the same ADR’s examples and API discussion
use add_request_handler and add_response_handler, indicating add_x_handler is not a defined
method name here.

docs/decisions/17685-network-handler-behavior.md[165-172]
docs/decisions/17685-network-handler-behavior.md[49-53]
docs/decisions/17685-network-handler-behavior.md[174-177]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Decision #10 uses `add_x_handler` without defining it as shorthand or naming the actual methods. Elsewhere the ADR uses `add_request_handler` / `add_response_handler`, so the placeholder is ambiguous.

### Issue Context
If body collection is supported for both request and response handlers, name both explicitly (or define `add_x_handler` as shorthand once and use it consistently). If it’s only supported for response handlers, say so directly.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[165-177]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

14. Java order nondeterministic ✓ Resolved 🐞 Bug ≡ Correctness

Description

The ADR table says Java runs “only the first matching handler”, but the current Java implementation
selects a matching handler from a ConcurrentHashMap stream with no defined encounter order, so the
chosen handler is effectively arbitrary and can vary between runs. This can mislead
readers/implementers about Java’s current precedence semantics.

Code

docs/decisions/17685-network-handler-behavior.md[18]

+| Java       | Only the first matching handler runs; disposition is always continue; a throwing handler propagates and leaves the request blocked; return-value driven; no response handler or managed body collection. |

Evidence

The ADR claims a “first” handler semantics for Java, but Java stores handlers in a ConcurrentHashMap
and selects via values().stream()...findFirst(), which does not guarantee ordering; therefore the
selected handler is not consistently the first-registered or otherwise deterministic handler.

docs/decisions/17685-network-handler-behavior.md[16-22]
java/src/org/openqa/selenium/remote/RemoteNetwork.java[47-50]
java/src/org/openqa/selenium/remote/RemoteNetwork.java[143-148]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR’s “Current behavior” row for Java states “Only the first matching handler runs”, which implies a deterministic ordering. In the current Java implementation, handler selection is performed by streaming `ConcurrentHashMap.values()` and taking `findFirst()`, which has no guaranteed iteration/encounter order.

### Issue Context
This is in the ADR’s binding comparison table; the goal is to accurately describe current behavior so readers understand what is changing.

### Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[16-22]

### Suggested change
Reword the Java row to avoid implying deterministic precedence (e.g., “Only one matching handler runs (selection order is unspecified) ...”), or explicitly state the current selection is not ordered by registration.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

15. No cross-binding source references 📘 Rule violation ≡ Correctness

Description

The ADR describes binding differences and proposes user-visible handler behavior changes but does
not provide any concrete cross-binding source references (e.g., rg results or links to the
Java/Python/Ruby/.NET/JS implementations) demonstrating the comparison was actually performed. This
risks inconsistent implementation across bindings because reviewers/implementers cannot verify the
stated current behaviors or the proposed alignment points.

Code

docs/decisions/17685-network-handler-behavior.md[R13-22]

+The bindings diverge today: each grew its handler API independently, so dispatch order,
+multi-handler resolution, error handling, and what an event exposes are all inconsistent.
+
+| Binding    | Current behavior |
+|------------|------------------|
+| Java       | Only the first matching handler runs; disposition is always continue; a throwing handler propagates and leaves the request blocked; return-value driven; no response handler or managed body collection. |
+| Python     | An explicit `continue` in a handler fires immediately and wins; otherwise staged outcomes reconcile by `fail` > `provide_response` > `continue`; response handlers have no `fail`; dispatch is FIFO; a throwing handler's staged mutations are still sent; only the mutated event is visible; body is not collected behind the handler. |
+| Ruby       | Handlers run in parallel threads, so multi-handler disposition races; exceptions are logged; dispatch is FIFO with no default-continue; only the mutated event is visible; body collection is user-managed. |
+| .NET       | No request or response handler API. |
+| JavaScript | No request or response handler API. |

Evidence

PR Compliance ID 389265 requires evidence of cross-binding comparison (e.g., project-wide search
output or references to compared files). The ADR includes a cross-binding behavior table but
provides no file references or search evidence to substantiate the claims, making the required
comparison non-auditable.

Rule 389265: Compare cross-language bindings when changing user-visible behavior
docs/decisions/17685-network-handler-behavior.md[13-22]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR asserts current cross-binding behaviors and proposes new user-visible behavior, but it lacks verifiable evidence of cross-binding comparison (project-wide search output and/or direct links to the analogous implementations in other bindings).

## Issue Context
Compliance requires that behavior-changing proposals include evidence of cross-language comparison so implementers can validate baseline behavior and keep bindings logically consistent.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[13-22]

## Suggested remediation
- Add a short section (e.g., "Cross-binding references") that lists at least one concrete file/link per compared binding (Java/Python/Ruby at minimum) that supports the "Current behavior" table entries.
- Optionally include a small snippet of the exact `rg ...` commands used (and the key hits) to demonstrate the repo-wide search comparison was performed.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

16. Auth callable contradiction ✓ Resolved 🐞 Bug ≡ Correctness

Description

The ADR excludes authentication handlers because “authentication should not use a callable,” but
Selenium Ruby’s add_authentication_handler explicitly accepts a block and existing tests use
block-based auth handlers (&:skip, &:cancel). This makes the ADR’s rationale inaccurate for at
least one binding and risks confusing implementers about the scope/baseline.

Code

docs/decisions/17685-network-handler-behavior.md[R20-21]

+This applies to request and response handlers, but not authentication handlers, since
+authentication should not use a callable.

Evidence

Ruby’s Network API accepts an optional block for add_authentication_handler and uses it when
credentials aren’t provided, and Ruby integration tests exercise callable auth handlers via &:skip
and &:cancel, contradicting the ADR’s claim that authentication should not use a callable.

rb/lib/selenium/webdriver/common/network.rb[47-63]
rb/spec/integration/selenium/webdriver/network_spec.rb[86-101]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR states authentication handlers are out of scope because authentication should not use a callable. In current Selenium Ruby, authentication handlers can be provided as a callable/block, so the statement is not universally true across bindings.

## Issue Context
The ADR is meant to be cross-binding guidance; blanket statements that contradict an existing binding’s public API are likely to cause confusion.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[20-21]

## Suggested change
Reword to scope the statement as a proposal or explicitly note that auth handler behavior is out of scope and that existing bindings differ (e.g., “This ADR does not cover authentication handlers; bindings currently vary, and we may revisit whether auth should be callable-based separately.”).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

17. Wrong Python behavior claim 🐞 Bug ≡ Correctness

Description

The ADR claims current Python behavior lets continueRequest override failures and stubs, but
Python’s BiDi network handler registry resolves outcomes with fixed precedence where any fail()
wins and provide_response() wins over mutations. This misstates the existing semantics and can
mislead readers about what is actually changing.

Code

docs/decisions/17685-network-handler-behavior.md[R158-159]

+  - We could run every handler but have `continueRequest` override failures and stubs (current
+    Python behavior), but it is not obvious why that command should have precedence.

Evidence

Python’s handler registry documents and implements reconciliation where any handler calling fail()
causes the request to be failed during _resolve(), and the integration tests assert that fail
wins when handlers disagree—so continueRequest does not override failures/stubs in current Python
behavior.

py/private/_network_handlers.py[28-37]
py/private/_network_handlers.py[428-437]
py/test/selenium/webdriver/common/bidi_network_tests.py[251-266]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR’s “Considered options → Reconciliation” section states that in current Python behavior `continueRequest` overrides failures and stubs. The Python implementation instead reconciles handler actions with a strict priority (fail > provide_response > continue-with-mutations/default continue), so the ADR’s comparison baseline is inaccurate.

## Issue Context
This ADR is intended to guide cross-binding behavior decisions; incorrect statements about existing behavior can skew review/consensus and lead to incorrect implementations.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[154-160]

## Suggested change
Reword the parenthetical to reflect the actual Python semantics (e.g., “current Python behavior reconciles outcomes with fixed priority (fail > provide_response > continue) after running all matching handlers”).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

18. Overgeneralized exception behavior 🐞 Bug ⚙ Maintainability

Description

The ADR states (in a comparative bullet) that Selenium logs uncaught handler exceptions instead of
ending the session, but current behavior is binding-specific (e.g., Ruby handler blocks are executed
without rescue/logging, while Python does catch/log). This should be reworded as a proposed
cross-binding behavior or explicitly scoped to the bindings that implement it today.

Code

docs/decisions/network-handler-behavior.md[R77-80]

+   * In Playwright, uncaught exceptions propagate to end the session, which causes problems when
+     something unrelated to the test's intent goes wrong.
+   * Selenium is more lenient and only logs the error to the console.
+

Evidence

Ruby currently invokes handler blocks without rescue/logging, while Python explicitly catches and
logs exceptions, so the ADR’s statement is not uniformly true across Selenium bindings today.

docs/decisions/network-handler-behavior.md[77-80]
rb/lib/selenium/webdriver/common/network.rb[89-96]
py/private/_network_handlers.py[746-756]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR text implies a universal Selenium behavior (“only logs the error to the console”) for handler exceptions, but current bindings differ.

### Issue Context
Ruby’s handler dispatch yields directly to user code without rescue; Python catches/logs and continues.

### Fix Focus Areas
- docs/decisions/network-handler-behavior.md[72-80]

### What to change
- Rephrase the bullet to one of:
 - “In some Selenium bindings (e.g., Python), uncaught handler exceptions are logged and processing continues…”
 - or “Proposed: Selenium should log uncaught handler exceptions and continue processing…”
- If desired, add a short note indicating current binding differences to avoid readers assuming uniform behavior today.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

19. Wrong handler verb names 🐞 Bug ≡ Correctness

Description

The ADR states Selenium request/response handlers use respond/submit (and response fail), but
existing bindings expose different verbs (e.g., Python provide_response/continue_request, Ruby
provide_response/continue) and do not offer a response-level fail. This mismatch will mislead
implementers/readers about current APIs and what exactly is being proposed to change.

Code

docs/decisions/network-handler-behavior.md[R31-43]

+   * Selenium supports:
+     * Request: `fail` (Playwright's `abort`, BiDi's `FailRequest`), `respond` (Playwright's `fulfill`, BiDi's `ProvideResponse`), and `submit` (Playwright's `continue`, BiDi's `ContinueRequest`).
+     * Response: `fail` (BiDi's `FailRequest`), and `submit`: note that since we don't need to prevent a round trip from a request, whether this is a BiDi `ContinueResponse` or `ProvideResponse` can be an implementation detail based on whether a replacement body value is provided.
+
+```ruby
+# Specifics of parameters and names can match spec details
+network.add_request_handler { |r| r.fail if something }
+network.add_request_handler { |r| r.respond(content: mocked_response) if something }
+network.add_request_handler { |r| r.add_header("X-Test", true) && r.submit if something }
+
+network.add_response_handler { |r| r.fail if something }
+network.add_response_handler { |r| r.submit(content: mocked_response) if something }
+network.add_response_handler { |r| r.add_header("X-Test", true) && r.submit if something }

Evidence

The ADR’s listed verbs don’t exist in current binding implementations, which use different method
names and capabilities for request/response interception.

docs/decisions/network-handler-behavior.md[31-43]
py/private/_network_handlers.py[325-438]
py/private/_network_handlers.py[440-581]
rb/lib/selenium/webdriver/bidi/network/intercepted_request.rb[30-58]
rb/lib/selenium/webdriver/bidi/network/intercepted_response.rb[31-68]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR uses handler disposition verbs (`respond`, `submit`, and response `fail`) that don’t match the verbs exposed by current Selenium bindings, which makes the document confusing as a proposal baseline.

### Issue Context
Current Python and Ruby bindings use `provide_response`/`continue_request` (Python) and `provide_response`/`continue` (Ruby), and do not expose a response-level `fail`.

### Fix Focus Areas
- docs/decisions/network-handler-behavior.md[26-44]

### What to change
- Replace “Selenium supports:” wording with either:
 - a binding-neutral set of verbs (and explicitly state they are *proposed* names), or
 - the currently used names (and optionally add a mapping table: proposed ↔ existing per binding).
- Update the Ruby/Python code examples accordingly (e.g., `provide_response`/`continue_request`/`continue`) and remove or clearly label response `fail` as a proposed addition if that’s intended.

[Comment truncated to fit github's 65,536-char limit.]

[qodo-code-review]

Code review by qodo was updated up to the latest commit 0f9f79c

[qodo-code-review]

Code review by qodo was updated up to the latest commit 887ad3c

[qodo-code-review]

Code review by qodo was updated up to the latest commit 7fd4917

[qodo-code-review]

Code review by qodo was updated up to the latest commit 1d78efe

[qodo-code-review]

Code review by qodo was updated up to the latest commit 0e068c9

[nvborisenko]

This is push based mechanism. I agree it should be blocked/ordered. Not yet clear if handler fails occasionally, then what (in .NET I fail fast, stop delivering, reveal at the end)?

Additionally I propose pull based events. Already in .NET:

await using var stream = await bidi.Network.BeforeRequestSent.StreamAsync();

// do something
// stop stream (via dispose)

// magic I am sure available in any binding
var allNotFoundImageUrls = await stream.Where(r => r.Status == 404 && r.Url.EndsWith("png")).Select(r => r.Url).ToListAsync();

This is amazing API for free - async enumeration.

[titusfortner]

On failure: Good question. What's in the ADR isn't exactly what I thought. User must handle exceptions themselves. Unhandled exceptions are propagated to the user, but do not automatically stop the session. It should be possible for a user to have code that can catch an exception from the main thread still. The ADR currently says other handlers will process the event, but I think we need to change it so that the event stops being processed if there is an error, and the event is submitted. I'll bring this up at the next TLC meeting.

I like it pull-based streaming but, but it fits observation approach, and doesn't really work for interception, and async-enumeration only works with an async/await solution which isn't available for several of the bindings, so it can't be part of the shared contract.

[qodo-code-review]

2. Context scoping rules undefined 🐞 Bug ⚙ Maintainability

Decision 11 allows scoping a handler by browsing context, user context, or both, but does not define
how providing both combines (AND vs precedence vs union) or what happens when the provided contexts
conflict, which will produce incompatible interception scopes across bindings.

Agent Prompt

## Issue description
Decision 11 explicitly permits passing a browsing context, a user context, or both, but does not define the required semantics when both are provided or when they disagree.

## Issue Context
Different bindings may interpret “both” differently (intersection vs precedence vs union), and may or may not validate that the browsing context belongs to the user context.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[270-274]
- docs/decisions/17685-network-handler-behavior.md[382-383]

## Suggested fix
Add explicit normative rules covering:
- whether supplying both means intersection (BC within UC), precedence (one overrides), or union
- required validation when the browsing context is not part of the user context (error vs ignore one)
- behavior when the default scope cannot be resolved from the “current window” (e.g., no active window)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

Code review by qodo was updated up to the latest commit d87ed06

[qodo-code-review]

1. glob warning left optional 📘 Rule violation ⚙ Maintainability

The ADR makes glob-looking pattern warnings optional per binding, which enables user-visible
divergence across language bindings. This conflicts with the cross-binding consistency requirement
for shared behavior expectations.

Agent Prompt

## Issue description
The ADR states that logging a warning for glob-looking URL patterns is optional per binding, which invites inconsistent user-visible behavior across bindings.

## Issue Context
This ADR is meant to align cross-binding behavior for the network handler API; optional warnings undermine that alignment unless a clear follow-up plan is recorded.

## Fix Focus Areas
- docs/decisions/17685-network-handler-behavior.md[80-82]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

Code review by qodo was updated up to the latest commit 7d08abd