[🚀 Feature]: [dotnet] Provide a possibility to implement BiDi Permissions module

[nvborisenko]

Feature and motivation

https://www.w3.org/TR/permissions/

The implementation should not rely on internal members. The goal is to expose minimal required to make it possible to implement new extendable by the third-partied modules.

Usage example

var bidi = await driver.AsBiDiAsync(); // selenium responsibility

// straightforward API (not yet approved)
var permissionsModule = new PermissionsModule(bidi);

// or as extension to emphasize this is extension
var permissionsModule = bidi.AsPermissions();

await permissionsModule.QueryAsync();

[github-actions]

@nvborisenko, thank you for creating this issue. We will troubleshoot it as soon as we can.

---

Info for maintainers

Triage this issue by using labels.

If information is missing, add a helpful comment and then I-issue-template label.

If the issue is a question, add the I-question label.

If the issue is valid but there is no time to troubleshoot it, consider adding the help wanted label.

If the issue requires changes or fixes from an external project (e.g., ChromeDriver, GeckoDriver, MSEdgeDriver, W3C), add the applicable G-* label, and it will provide the correct link and auto-close the issue.

After troubleshooting the issue, please add the R-awaiting answer label.

Thank you!

[nvborisenko]

I am thinking more about it and coming to a conclusion that "reusing" existing BiDi connection is "not possible". JsonSerializerContext is immutable, reading it as third-party module should initialize his own connection (Broker) providing described json context.

So, I think the following will be more appreciated:

var bidi = await driver.AsBiDiAsync(); // W3C WebDriver implementation

var permissions = await driver.AsBiDiPermissionsAsync(); // It initializes new Broker/WebSocketConnection/JsonContext

Then each bidi and permissions are isolated, and both have own "context" including everything needed to deal with remote end (still immutable). The trick is that remote end send data (responses/events) per WebSocketConnection.

I think this is a good solution. But semantic of this solution is not related to extensibility.

[nvborisenko]

But semantic of this solution is not related to extensibility.

And I am entirely OK with it! Permissions module can be easily implemented (defining his own DTO types), Bluetooth module too.

Appium is a separate topic, but seems yes, we consider Appium as yet another BiDi module (with his own isolated "context").

[nvborisenko]

var bidi = await driver.AsBiDiAsync(opts => opts.WithPermissions(out var permissions));

await permissions.QueryAsync();

This way we inject JsonTypeInfoResolver, reusing entire core bidi infrastructure, and expose permissions object with methods related to Permissions only. This way also guarantees there is no performance impact even if we will have 100 attached extensions.

Researching continued. @RenderMichael what do you think?

[RenderMichael]

I think the configuration builder would work well, the main drawback is that it requires all of BiDi for an extension. If we want to have Permissions separate from BiDi, then we would need a separate flow.

[nvborisenko]

Trying to evaluate the statement "JsonOptions is immutable" and understood it is actually mutable. It is safe to inject TypeInfoResolver when it is already constructed.

Pseudo flow:

var bidi = driver.GetBidi(); // existing functionality

var permissionsModule = bidi.AsPermissions(); // here it is safe to modify JsonOptions!

var bluetoothModule = bidi.AsBluetooth(); // even safe, just adds one more TypeInfoResolver

I hope it will be useful.

[RenderMichael]

We can improve it even more with the TypeInfoResolverChain, a new feature of STJ designed to make this process simpler.

[nvborisenko]

Yes, kind of "inject TypeInfoResolver". I am more curios it helps us in general. From end user point of view this is absolutely legal operation.

[RenderMichael]

What do we think about a builder pattern:

var bidi = await driver.AsBiDiBuilder()
    .AddExtension(connection => new PermissionsModule(connection), out var permissions)
    .BuildAsync();

Extension creator can provide nice extensions on BiDiBuilder so they can do whatever they need:

public static BiDiBuilder AddPermissions(this BiDiBuilder builder, out PermissionsModule permissions)
{
    return builder.AddExtension(connection =>
    {
        connection.AddSerializerContextAndConverters(PermissionsJsonSerializerContext.Default)
        return new PermissionsModule(connection);
    },
    out permissions);
}

var bidi = await driver.AsBiDiBuilder()
    .AddPermissions(out var permissions)
    .BuildAsync();

[RenderMichael]

With the above pattern, we can do things like make the PermissionsModule constructor internal, to enforce using the extension method and guide users to use the builder instead (avoiding any of the problems with adding extensions)

[nvborisenko]

Usually builder pattern lives on top of existing functionality. I am still thinking the following is our primary way:

var permissionsModule = bidi.AsPermissions();

But I understand selenium should expose "something" to be public. If my thoughts are true, then I just want to make this "something" hidden from regular users. When our users type bidi. then intellisense should not promote "hidden something" (ideally).

[nvborisenko]

One more point against pre-initialized pattern (builder): user should capture the reference to it even if he doesn't want it. Or if he wants it, he should keep this ref during application lifecycle. The following is still better:

var permissionsModule = bidi.AsPermissions(); // here permissions module starts to live, pretty intuitive

And now we also should remember about disposing permissions module, just removing JsonTypeResolver?

[nvborisenko]

Thinking more... "hidden something" could be bidi.AsModule<T>(...?). I think it is not criminal. This way also opens a door for having separated BiDiJsonContext per module. Lighter json context could be beneficial (need benchmarks). And even more could be more friendly with AOT trimming?

[RenderMichael]

If we want to create extension modules on the fly instead of at the same time as the bidi object lifecycle, then we cannot share a connection. We can do it that way too.