[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]

But why CoreModule?

[nvborisenko]

Let me remind: we made Module class ctor parameterless, especially for external modules.

[RenderMichael]

We have 2 requirements:

1. Each module should maintain its own serialization
2. We want the first-party modules to share the same serialization

For that reason, they need to have some shared logic.

[nvborisenko]

I am not ready to generalize it in this PR. Still not clear how to move on.

[RenderMichael]

I have an example in this PR’s description, of how to move forward with these changes.

[nvborisenko]

I though making Module.Create(...) to public would be enough, please give me time to review.

[nvborisenko]

Observed it is theoretical changes. Let be practicable.

[RenderMichael]

It is, except for the shared JSON context introduced in #16402

It is not theoretical changes.

[nvborisenko]

I came to the following:

1. BiDi has new method AsModule<T>()
2. PermissionsModule creates its own context based on options (and keep it as private field)

Then changes looks simple.

[nvborisenko]

I feel introducing new AsModule<T>() method will be good for us:

• we may introduce cached modules
• it negotiates use of internal properties

[nvborisenko]

All right, AsModule<T> is required. Built-in modules are cached, third-party modules also want to be cached per bidi instance. Let's do it (here or in separate PR).

[nvborisenko]

No value,. In any case thank you.