[rb] hold BiDi numbers to their declared ranges - #18198

• Reject out-of-range Ruby BiDi numbers before commands are sent and when responses are received.
• Generate field bounds from schema declarations and alias chains, including numeric map values.
• Cover inclusive and exclusive limits, alias bounds, and map values with tests.

graph TD
  S["BiDi schema"] --> G["Ruby generator"] --> F["Record fields"] --> V["Range validation"] -->|"valid commands"| B["Browser BiDi"]
  B -->|"responses"| V
  V -->|"invalid values"| E["Typed errors"]

Loading

The following are alternative approaches to this PR:

1. Validate directly against the schema at runtime

• ➕ Avoids embedding numeric bounds throughout generated protocol files.
• ➖ Adds a runtime schema dependency and resolution work to record validation.
• ➖ Moves range interpretation away from the existing generated field metadata.

Recommendation: Keep the PR's generated-metadata approach. It fits the existing record validator and lets inbound and outbound checks share the same bounds without loading the schema at runtime.

Enhancement (1) +8 / -0

serialization.rbsDeclare new serialization validation helpers +8/-0

Declare new serialization validation helpers

• Adds RBS signatures for the shared primitive and bound mismatch methods used by record validation.

rb/sig/lib/selenium/webdriver/bidi/serialization.rbs

Bug fix (14) +500 / -161

browser.rbBound client-window coordinates and dimensions +20/-8

Bound client-window coordinates and dimensions

• Adds safe-integer ranges to client-window information and set-window-state fields, distinguishing signed positions from nonnegative dimensions.

rb/lib/selenium/webdriver/bidi/protocol/browser.rb

browsing_context.rbBound browsing-context parameters and event numbers +86/-29

Bound browsing-context parameters and event numbers

• Adds ranges for depths, node counts, image and print settings, viewport values, history deltas, and event timestamps. Device pixel ratio uses an exclusive zero minimum.

rb/lib/selenium/webdriver/bidi/protocol/browsing_context.rb

emulation.rbBound geolocation and emulation values +59/-14

Bound geolocation and emulation values

• Adds geographic ranges, a heading maximum exclusive of 360, and nonnegative or positive limits for media, screen, and touch fields.

rb/lib/selenium/webdriver/bidi/protocol/emulation.rb

input.rbBound pointer and wheel action numbers +94/-30

Bound pointer and wheel action numbers

• Adds ranges for action durations, buttons, pointer dimensions and properties, and signed wheel coordinates and deltas.

rb/lib/selenium/webdriver/bidi/protocol/input.rb

log.rbBound log-entry timestamps +4/-4

Bound log-entry timestamps

• Applies the nonnegative JavaScript safe-integer range to timestamps across generated log-entry variants.

rb/lib/selenium/webdriver/bidi/protocol/log.rb

moz_debugging.rbBound Firefox debugging locations +7/-7

Bound Firefox debugging locations

• Applies nonnegative safe-integer ranges to breakpoint, pause, and call-frame line and column fields.

rb/lib/selenium/webdriver/bidi/protocol/moz_debugging.rb

moz_profiler.rbBound Firefox profiler options +2/-2

Bound Firefox profiler options

• Adds nonnegative safe-integer limits to profiler entry counts and intervals.

rb/lib/selenium/webdriver/bidi/protocol/moz_profiler.rb

network.rbBound network counts, sizes, and status fields +70/-27

Bound network counts, sizes, and status fields

• Adds generated ranges for timestamps, redirects, byte counts, response statuses, cookie values, and other network numbers. Cookie max age retains a signed range.

rb/lib/selenium/webdriver/bidi/protocol/network.rb

script.rbBound script locations and serialization depths +22/-8

Bound script locations and serialization depths

• Adds nonnegative safe-integer limits to exception and stack-frame locations, node properties, and serialization depth options.

rb/lib/selenium/webdriver/bidi/protocol/script.rb

session.rbBound SOCKS versions and Firefox preference integers +9/-3

Bound SOCKS versions and Firefox preference integers

• Limits SOCKS versions to 0–255 and adds signed JavaScript safe-integer bounds for numeric Firefox preference map values.

rb/lib/selenium/webdriver/bidi/protocol/session.rb

storage.rbBound storage cookie sizes and expiry +3/-3

Bound storage cookie sizes and expiry

• Applies nonnegative safe-integer limits to cookie size and expiry fields in generated storage records.

rb/lib/selenium/webdriver/bidi/protocol/storage.rb

web_extension.rbBound extension manifest versions +1/-1

Bound extension manifest versions

• Applies the nonnegative JavaScript safe-integer range to the manifest version received in extension information.

rb/lib/selenium/webdriver/bidi/protocol/web_extension.rb

record.rbValidate numeric bounds in both serialization directions +49/-14

Validate numeric bounds in both serialization directions

• Stores inclusive and exclusive bounds on record fields and shares range checks between outbound construction and inbound decoding. Numeric map values use the same checks while retaining direction-specific error types.

rb/lib/selenium/webdriver/bidi/serialization/record.rb

bidi_generate.rbGenerate bounds from fields, aliases, and maps +74/-11

Generate bounds from fields, aliases, and maps

• Narrows numeric bounds through alias chains and emits them as record metadata, formatting large literals and wrapped entries. For maps, generation rejects numeric union arms with incompatible bounds.

rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb

Tests (2) +136 / -0

serialization_spec.rbTest inbound and outbound numeric limits +64/-0

Test inbound and outbound numeric limits

• Covers inclusive and exclusive boundaries, alias-derived safe-integer limits, invalid responses, and numeric Firefox preference map values.

rb/spec/unit/selenium/webdriver/bidi/serialization_spec.rb

bidi_generate_spec.rbTest bound generation and map conflicts +72/-0

Test bound generation and map conflicts

• Covers field and alias-chain bounds, exclusive-bound precedence, numeric map arms, incompatible map bounds, and line wrapping with a separating comma.

rb/spec/unit/selenium/webdriver/bidi/support/bidi_generate_spec.rb

Description

Ruby marks geolocation heading as strictly less than 360, while Java validates the same field with
an inclusive upper bound. A caller using the valid endpoint accepted by Java therefore receives an
ArgumentError in Ruby instead.

Code

rb/lib/selenium/webdriver/bidi/protocol/emulation.rb[R246-253]

+            heading: {
+              wire_key: 'heading',
+              required: false,
+              nullable: true,
+              primitive: 'number',
+              min: 0,
+              max: 360,
+              exclusive_max: true

Evidence

The Ruby declaration adds exclusive_max: true, and the Ruby test verifies that heading 360 raises.
Java uses inclusive validation through 360 for the same field, producing different user-visible
behavior across bindings.

AGENTS.md: Maintain Cross-Binding Consistency for User-Visible Behavior
rb/lib/selenium/webdriver/bidi/protocol/emulation.rb[246-253]
rb/spec/unit/selenium/webdriver/bidi/serialization_spec.rb[568-576]
java/src/org/openqa/selenium/bidi/emulation/GeolocationCoordinates.java[59-63]

Agent prompt

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

## Issue description
Ruby rejects a geolocation heading of exactly 360, while the Java binding accepts that endpoint through inclusive range validation.

## Fix Focus Areas
- rb/lib/selenium/webdriver/bidi/protocol/emulation.rb[246-253]
- rb/spec/unit/selenium/webdriver/bidi/serialization_spec.rb[568-576]
- java/src/org/openqa/selenium/bidi/emulation/GeolocationCoordinates.java[59-63]

## Recommended Fix
Align the Ruby and Java heading validation with the authoritative BiDi schema, or document and approve the intentional difference. Update the implementation and boundary tests so all bindings agree on whether 360 is accepted.

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

Description

LocateNodesParameters now enforces a minimum of 1 for max_node_count, rejecting zero that the
Ruby API previously accepted and the corresponding Java BiDi API still accepts. Ruby callers using
max_node_count: 0 receive ArgumentError before the command reaches the browser, while users
switching bindings or sharing generated test data get different results for the same request.

Code

rb/lib/selenium/webdriver/bidi/protocol/browsing_context.rb[R379-384]

+            max_node_count: {
+              wire_key: 'maxNodeCount',
+              required: false,
+              primitive: 'integer',
+              min: 1,
+              max: 9_007_199_254_740_991

Evidence

The changed Ruby protocol declaration adds min: 1, and its serialization test confirms that zero
raises before the command is sent. Java's corresponding range test explicitly accepts zero,
establishing both the change from Ruby's previously accepted input and the inconsistent behavior
across bindings.

AGENTS.md: Preserve Public API and ABI Compatibility
rb/lib/selenium/webdriver/bidi/protocol/browsing_context.rb[379-384]
rb/spec/unit/selenium/webdriver/bidi/serialization_spec.rb[554-561]
java/test/org/openqa/selenium/bidi/protocol/input/JsIntRangeTest.java[63-72]

Agent prompt

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

## Issue description
Ruby now rejects `max_node_count: 0` before sending the command, changing behavior for existing callers and differing from Java's acceptance of the corresponding BiDi value.

## Fix Focus Areas
- rb/lib/selenium/webdriver/bidi/protocol/browsing_context.rb[379-384]
- rb/spec/unit/selenium/webdriver/bidi/serialization_spec.rb[554-561]
- java/test/org/openqa/selenium/bidi/protocol/input/JsIntRangeTest.java[63-72]

## Recommended Fix
Confirm the authoritative range and whether rejecting zero is an intentional breaking change. If compatibility is required, preserve Ruby's prior acceptance and align the affected binding and tests so zero behaves consistently across bindings; otherwise, approve and document the difference and provide a migration path before enforcing the stricter bound.

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

Description

bound_mismatch now raises a SerializationError for any numeric field outside its declared
min/max, and this is invoked from read/check_primitive for every incoming field such as
headersSize, bodySize, cookie expiry, or initiator line/column numbers. Browsers have
historically sent out-of-range sentinel values (e.g. -1) for some of these optional fields; if
that happens, parsing the entire enclosing record now raises instead of just that field, causing the
whole event or response to be lost rather than degrading gracefully.

Code

rb/lib/selenium/webdriver/bidi/serialization/record.rb[R305-310]

+            def bound_mismatch(field, value)
+              return unless value.is_a?(::Numeric)

-              raise Error::SerializationError, "#{name}##{field.name} expected #{field.primitive}, got #{raw.inspect}"
+              bound = violated_min(field, value) || violated_max(field, value)
+              " expected #{bound}, got #{value.inspect}" if bound
+            end

Agent prompt

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

Issue description
Newly added numeric bound checks (`bound_mismatch`, `violated_min`, `violated_max`) now raise `SerializationError` on any inbound value outside its declared range, for fields like `headersSize`, `bodySize`, cookie `expiry`, and initiator line/column numbers that are populated directly from browser-sent BiDi messages. If a browser implementation sends an out-of-range sentinel (e.g. -1) for one of these fields, the entire containing record fails to parse instead of just that field being rejected.

Fix Focus Areas
- rb/lib/selenium/webdriver/bidi/serialization/record.rb[290-322]

Recommended Fix
Run the Ruby BiDi integration suite against current Chrome and Firefox builds focusing on network/storage/log events to confirm no in-the-wild sentinel values hit these new bounds; if any do, add a schema override that loosens that specific field's bounds rather than removing the general bound-checking mechanism.

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

Description

wrap_call now always adds trailing: 1 for every spec entry via FieldIR#spec_entry, assuming
each field is followed by a separating comma. The last field in a Record.define(...) call has no
trailing comma, so an entry whose one-line form is exactly at the limit gets needlessly wrapped onto
multiple lines, producing noisier generated diffs than necessary.

Code

rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[R331-334]

      return "#{ruby_name}: '#{wire_key}'" if meta.empty?

      meta.unshift("wire_key: '#{wire_key}'")
-      BiDiGenerate.wrap_call("#{ruby_name}: ", meta, indent, open: '{', close: '}')
+      BiDiGenerate.wrap_call("#{ruby_name}: ", meta, indent, open: '{', close: '}', trailing: 1)

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 generator always passes `trailing: 1` to `wrap_call` when rendering a field's spec entry, assuming a trailing comma always follows, even for the last field in a `Record.define` call where no comma is emitted.

Fix Focus Areas
- rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[331-334]

Recommended Fix
Thread whether the field is the last one in its containing record into `spec_entry`, and only pass `trailing: 1` when a trailing comma will actually be emitted afterward, so the one-line length check isn't overly conservative for the final field.

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

💡 Did you know, you can move or hide resolved findings to focus on what still needs action

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Review updated until commit 24fcf5f

Results up to commit 3785fd1 🧠 Deep

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

1. Ruby callers passing zero now fail ✗ Dismissed

Description

LocateNodesParameters now enforces a minimum of 1 for max_node_count, rejecting zero that the
Ruby API previously accepted and the corresponding Java BiDi API still accepts. Ruby callers using
max_node_count: 0 receive ArgumentError before the command reaches the browser, while users
switching bindings or sharing generated test data get different results for the same request.

Code

rb/lib/selenium/webdriver/bidi/protocol/browsing_context.rb[R379-384]

+            max_node_count: {
+              wire_key: 'maxNodeCount',
+              required: false,
+              primitive: 'integer',
+              min: 1,
+              max: 9_007_199_254_740_991

Evidence

The changed Ruby protocol declaration adds min: 1, and its serialization test confirms that zero
raises before the command is sent. Java's corresponding range test explicitly accepts zero,
establishing both the change from Ruby's previously accepted input and the inconsistent behavior
across bindings.

AGENTS.md: Preserve Public API and ABI Compatibility
rb/lib/selenium/webdriver/bidi/protocol/browsing_context.rb[379-384]
rb/spec/unit/selenium/webdriver/bidi/serialization_spec.rb[554-561]
java/test/org/openqa/selenium/bidi/protocol/input/JsIntRangeTest.java[63-72]

Agent prompt

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

## Issue description
Ruby now rejects `max_node_count: 0` before sending the command, changing behavior for existing callers and differing from Java's acceptance of the corresponding BiDi value.

## Fix Focus Areas
- rb/lib/selenium/webdriver/bidi/protocol/browsing_context.rb[379-384]
- rb/spec/unit/selenium/webdriver/bidi/serialization_spec.rb[554-561]
- java/test/org/openqa/selenium/bidi/protocol/input/JsIntRangeTest.java[63-72]

## Recommended Fix
Confirm the authoritative range and whether rejecting zero is an intentional breaking change. If compatibility is required, preserve Ruby's prior acceptance and align the affected binding and tests so zero behaves consistently across bindings; otherwise, approve and document the difference and provide a migration path before enforcing the stricter bound.

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

---

2. Ruby rejects 360-degree headings ✗ Dismissed

Description

Ruby marks geolocation heading as strictly less than 360, while Java validates the same field with
an inclusive upper bound. A caller using the valid endpoint accepted by Java therefore receives an
ArgumentError in Ruby instead.

Code

rb/lib/selenium/webdriver/bidi/protocol/emulation.rb[R246-253]

+            heading: {
+              wire_key: 'heading',
+              required: false,
+              nullable: true,
+              primitive: 'number',
+              min: 0,
+              max: 360,
+              exclusive_max: true

Evidence

The Ruby declaration adds exclusive_max: true, and the Ruby test verifies that heading 360 raises.
Java uses inclusive validation through 360 for the same field, producing different user-visible
behavior across bindings.

AGENTS.md: Maintain Cross-Binding Consistency for User-Visible Behavior
rb/lib/selenium/webdriver/bidi/protocol/emulation.rb[246-253]
rb/spec/unit/selenium/webdriver/bidi/serialization_spec.rb[568-576]
java/src/org/openqa/selenium/bidi/emulation/GeolocationCoordinates.java[59-63]

Agent prompt

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

## Issue description
Ruby rejects a geolocation heading of exactly 360, while the Java binding accepts that endpoint through inclusive range validation.

## Fix Focus Areas
- rb/lib/selenium/webdriver/bidi/protocol/emulation.rb[246-253]
- rb/spec/unit/selenium/webdriver/bidi/serialization_spec.rb[568-576]
- java/src/org/openqa/selenium/bidi/emulation/GeolocationCoordinates.java[59-63]

## Recommended Fix
Align the Ruby and Java heading validation with the authoritative BiDi schema, or document and approve the intentional difference. Update the implementation and boundary tests so all bindings agree on whether 360 is accepted.

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

---

3. Range checks can drop whole BiDi events on sentinel values ✗ Dismissed

Description

bound_mismatch now raises a SerializationError for any numeric field outside its declared
min/max, and this is invoked from read/check_primitive for every incoming field such as
headersSize, bodySize, cookie expiry, or initiator line/column numbers. Browsers have
historically sent out-of-range sentinel values (e.g. -1) for some of these optional fields; if
that happens, parsing the entire enclosing record now raises instead of just that field, causing the
whole event or response to be lost rather than degrading gracefully.

Code

rb/lib/selenium/webdriver/bidi/serialization/record.rb[R305-310]

+            def bound_mismatch(field, value)
+              return unless value.is_a?(::Numeric)

-              raise Error::SerializationError, "#{name}##{field.name} expected #{field.primitive}, got #{raw.inspect}"
+              bound = violated_min(field, value) || violated_max(field, value)
+              " expected #{bound}, got #{value.inspect}" if bound
+            end

Agent prompt

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

Issue description
Newly added numeric bound checks (`bound_mismatch`, `violated_min`, `violated_max`) now raise `SerializationError` on any inbound value outside its declared range, for fields like `headersSize`, `bodySize`, cookie `expiry`, and initiator line/column numbers that are populated directly from browser-sent BiDi messages. If a browser implementation sends an out-of-range sentinel (e.g. -1) for one of these fields, the entire containing record fails to parse instead of just that field being rejected.

Fix Focus Areas
- rb/lib/selenium/webdriver/bidi/serialization/record.rb[290-322]

Recommended Fix
Run the Ruby BiDi integration suite against current Chrome and Firefox builds focusing on network/storage/log events to confirm no in-the-wild sentinel values hit these new bounds; if any do, add a schema override that loosens that specific field's bounds rather than removing the general bound-checking mechanism.

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

---

4. Wrapping overestimates every field, not just the last ✓ Resolved

Description

wrap_call now always adds trailing: 1 for every spec entry via FieldIR#spec_entry, assuming
each field is followed by a separating comma. The last field in a Record.define(...) call has no
trailing comma, so an entry whose one-line form is exactly at the limit gets needlessly wrapped onto
multiple lines, producing noisier generated diffs than necessary.

Code

rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[R331-334]

      return "#{ruby_name}: '#{wire_key}'" if meta.empty?

      meta.unshift("wire_key: '#{wire_key}'")
-      BiDiGenerate.wrap_call("#{ruby_name}: ", meta, indent, open: '{', close: '}')
+      BiDiGenerate.wrap_call("#{ruby_name}: ", meta, indent, open: '{', close: '}', trailing: 1)

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 generator always passes `trailing: 1` to `wrap_call` when rendering a field's spec entry, assuming a trailing comma always follows, even for the last field in a `Record.define` call where no comma is emitted.

Fix Focus Areas
- rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[331-334]

Recommended Fix
Thread whether the field is the last one in its containing record into `spec_entry`, and only pass `trailing: 1` when a trailing comma will actually be emitted afterward, so the one-line length check isn't overly conservative for the final field.

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

---