[dotnet] Implement third-party Permissions module

[RenderMichael]

User description

🔗 Related Issues

Fixes #15329

• New feature (non-breaking change which adds functionality and tests!)

New API surface:

var permissions = bidi.AsPermissions();
await permissions.SetPermissionAsync("geolocation", PermissionState.Denied, newPage, userContext.UserContext);

---

PR Type

Enhancement

---

Description

• Enable external BiDi module creation and extension

• Refactor module architecture with InternalModule base class

• Expose Broker and JsonOptions for external access

• Simplify module creation with public static method

---

Diagram Walkthrough

flowchart LR
  BiDi["BiDi Class"] -- "exposes" --> Broker["Internal Broker"]
  BiDi -- "exposes" --> JsonOptions["JSON Options"]
  Module["Base Module"] -- "extends" --> InternalModule["InternalModule"]
  InternalModule -- "used by" --> AllModules["All Built-in Modules"]
  Module -- "public creation" --> ExternalModules["External Modules"]

Loading

File Walkthrough

Relevant files

Enhancement

13 files BiDi.cs Expose internal properties and refactor module creation    +26/-21  InternalModule.cs Add new base class for internal modules                                    +34/-0    Module.cs Refactor to support external module creation                          +6/-7      BrowserModule.cs Change inheritance to InternalModule                                          +1/-1      BrowsingContextModule.cs Change inheritance to InternalModule                                          +1/-1      EmulationModule.cs Change inheritance to InternalModule                                          +1/-1      InputModule.cs Change inheritance to InternalModule                                          +1/-1      LogModule.cs Change inheritance to InternalModule                                          +1/-1      NetworkModule.cs Change inheritance to InternalModule                                          +1/-1      ScriptModule.cs Change inheritance to InternalModule                                          +1/-1      SessionModule.cs Change inheritance to InternalModule                                          +1/-1      StorageModule.cs Change inheritance to InternalModule                                          +1/-1      WebExtensionModule.cs Change inheritance to InternalModule                                          +1/-1

---

[qodo-merge-pro]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟡	🎫 #15329 🟢 Enable a minimal, public mechanism in .NET to implement extendable third-party BiDi modules without relying on internal members. Expose necessary BiDi primitives (e.g., broker/transport and JSON serialization options/context) for external modules to function. Provide a straightforward way for consumers to create/use external BiDi modules (e.g., a factory/extension pattern). Maintain compatibility with existing built-in modules while refactoring to allow extensibility. ⚪ Include example usage feasibility similar to creating a Permissions module as an external extension.
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
⚪	No custom compliance provided Follow the guide to enable custom compliance check.
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Validate serializer context against options In the Create method, validate that the provided cachedContext is compatible with the jsonOptions by comparing their Options properties, and throw an ArgumentException if they do not match. dotnet/src/webdriver/BiDi/Module.cs [34-45] public static TModule Create<TModule>(BiDi bidi, JsonSerializerOptions jsonOptions, JsonSerializerContext? cachedContext = null) where TModule : Module, new() { + if (cachedContext is not null && cachedContext.Options != jsonOptions) + { + throw new ArgumentException("The provided JsonSerializerContext is not compatible with the provided JsonSerializerOptions.", nameof(cachedContext)); + } + TModule module = new() { Broker = bidi.Broker, }; module.JsonContext = cachedContext ?? module.Initialize(jsonOptions); return module; } Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies a potential configuration issue in the public Create method and proposes a validation check to prevent runtime errors, which enhances the robustness of the API.	Low
Learned best practice	Validate constructor input URL Add argument validation to ensure url is not null/empty and is an absolute URI, throwing ArgumentException/ArgumentNullException with clear messages. dotnet/src/webdriver/BiDi/BiDi.cs [64-83] private BiDi(string url) { - var uri = new Uri(url); + if (url is null) throw new ArgumentNullException(nameof(url)); + if (string.IsNullOrWhiteSpace(url)) throw new ArgumentException("URL must not be empty.", nameof(url)); + if (!Uri.TryCreate(url, UriKind.Absolute, out var uri)) + throw new ArgumentException("URL must be a valid absolute URI.", nameof(url)); JsonOptions = DefaultBiDiOptions(); _jsonContext = new BiDiJsonSerializerContext(JsonOptions); Broker = new Broker(this, uri, JsonOptions); SessionModule = Module.Create<Session.SessionModule>(this, JsonOptions, _jsonContext); BrowsingContext = Module.Create<BrowsingContext.BrowsingContextModule>(this, JsonOptions, _jsonContext); Browser = Module.Create<Browser.BrowserModule>(this, JsonOptions, _jsonContext); Network = Module.Create<Network.NetworkModule>(this, JsonOptions, _jsonContext); InputModule = Module.Create<Input.InputModule>(this, JsonOptions, _jsonContext); Script = Module.Create<Script.ScriptModule>(this, JsonOptions, _jsonContext); Log = Module.Create<Log.LogModule>(this, JsonOptions, _jsonContext); Storage = Module.Create<Storage.StorageModule>(this, JsonOptions, _jsonContext); WebExtension = Module.Create<WebExtension.WebExtensionModule>(this, JsonOptions, _jsonContext); Emulation = Module.Create<Emulation.EmulationModule>(this, JsonOptions, _jsonContext); } Apply / Chat Suggestion importance[1-10]: 6 __ Why: Relevant best practice - Validate inputs early with precise checks to prevent null/invalid argument issues.	Low
Update

[nvborisenko]

No value,. In any case thank you.

[nvborisenko]

This is definitely should be in another class. The reason is we are CLS compatible (I don't still understand why, but anyway), meaning some languages cannot deal with extension methods. They will use static method: WebDriverExtensions.AsPermissions(bidi). But it is not extension of WebDriver.

We should introduce good name for static class, and its namespace.

BiDiExtensions.AsPermissions(bidi)?

[nvborisenko]

When Bluetooth module comes to under umbrella, then what? Should we have single static class for all them, or they define own static class in theirs namespace?

I vote for "everything in their namespace". It would be good pattern to demonstrate good practices how to develop module. Separate namespace is not a problem, IDE is still able to suggest extension method.

[RenderMichael]

extension methods do not affect CLS compliance. Users can call WebDriverExtensions.AsPermissions(bidi) even on extension methods.

But I agree that extensions should be in separate files. I will make those changes.

[nvborisenko]

My concern is about naming: WebDriverExtensions.AsPermissions(bidi) - it is not extension for WebDriver, it is for BiDi.

[RenderMichael]

I followed the two suggestions: WebDriverExtensions -> BiDiExtensions, and permissions in its own area

[RenderMichael]

There are some libraries that wrap/extend Selenium that use the OpenQA.Selenium namespace segment, so it’s not a marginal concern.

[nvborisenko]

My final confidence: # 1 - 65%, # 2 - 35%;

Please think and share your confidence (don't cheat).

[RenderMichael]

For me: # 1 - 75%, # 2 - 25%

[nvborisenko]

@YevgeniyShunevych please just vote blindly.

[YevgeniyShunevych]

From my point of view, extra namespaces within the same assembly, which do not have strong practical need, often provide only complexity without benefits. I'm for more clear type names, rather then giving short type names, which increases name conflict chance, and putting such types in different namespaces.

For example, Visual Studio 2022 IntelliSense, will not suggest you AsPermissions() extension method for bidi object unless you explicitly add using OpenQA.Selenium.BiDi.Permissions; to a .cs file before that. But I would like to see all the available "As..." methods in IDE without knowing and adding exact namespace before that.

I generally do support project folder structuring, similar as currently Selenium.WebDriver project is structured. It is also fine that we have all functionality under OpenQA.Selenium.BiDi namespace. But I would stop with sub-namespaces at this point. I don't see a strong need having 10+ sub-namespaces, one for each submodule. I am talking not only about extension classes, but all classes inside /dotnet/src/webdriver/BiDi folder.

Despite of namespace topic, the current BiDi folder is good. I'm ok with keeping methods like AsPermissions in separate extension classes inside corresponding folder ("Permissions"). If I had to choose a name for such extension class having method public static PermissionsModule AsPermissions(this BiDi bidi), I would name it PermissionsBiDiExtensions, not PermissionsExtensions, because the class's extension methods extend BiDi type. So just {Module}BiDiExtensions.

If you are not ready to apply single common OpenQA.Selenium.BiDi namespace for all types of /dotnet/src/webdriver/BiDi, it's understandable. But at least, it would be great to have {Module}BiDiExtensions in OpenQA.Selenium.BiDi namespace.