Prototype channel mechanism (script.MessageEvent)

[thiagowfx]

Provide a way to communicate from scripts evaluated on the page side to
the BiDi client.

This is a safe (non-observable by the page script) analog of the Runtime.addBinding CDP command.

Prototype the mechanism using long-poll. Implementation details: http://go/webdriver-binding-implementation.

Reference: https://chromedevtools.github.io/devtools-protocol/tot/Runtime/#method-callFunctionOn

Bug: #294

Aligning with spec:

• BindingValue -> Channel
• ScriptBindingCalledParams -> MessageParams

Status

• Introduce Script.Message: forked to Align binding (script message and channel) protocol with the spec #541
• Finish passing argument to the event in the deserialization method.
• Rename PROTO.binding to channel to match spec.

[sadym-chromium]

This PR is the beginning of the #294

[thiagowfx]

Planning to resume this PR this week.

[thiagowfx]

Q: What is the difference between protocol-parser.ts and protocol.ts?

Q: Some definitions have both schema + event type with zod.infer. Others don't have schema. What's the difference?

[sadym-chromium]

Q: What is the difference between protocol-parser.ts and protocol.ts?

As Puppeteer doesn't need zod, but needs BiDi types, we had to duplicate them. Details: #350

Q: Some definitions have both schema + event type with zod.infer. Others don't have schema. What's the difference?

Can you give a specific example?

[thiagowfx]

Side note: discussed off-line.

[thiagowfx]

Reference: https://chromedevtools.github.io/devtools-protocol/tot/Runtime/#method-callFunctionOn

[thiagowfx]

@sadym-chromium I continued the design doc but now I am stuck. More specifically:

1. What should getMessage do?
2. What should sendMessage do?
3. What should the deserialization (the case) do?
4. Do we have a definition of "Binding" anywhere? https://w3c.github.io/webdriver-bidi/ contains nothing. I'd like to document it in the newly added class.
5. When/where should I emit the script.bindingCalled event?
6. What should the E2E test look like? Should it be a call to script.evaluate? If yes, that should it contain?

[sadym-chromium]

@sadym-chromium I continued the design doc but now I am stuck. More specifically:

2. What should sendMessage do?

sendMessage should add message to the Binding's message queue.

1. What should getMessage do?

getMessage is used for long-poll messages to Mapper from the page. It returns either a value from the message queue, if it's non-empty, or a promise, which will be resolved after a message appears in the queue.

3. What should the deserialization (the case) do?

During deserialization, you should create a binding object on the page side, store it's objectId (will be required to poll messages), and provide its sendMessage to the user script as an argument.

4. Do we have a definition of "Binding" anywhere? https://w3c.github.io/webdriver-bidi/ contains nothing. I'd like to document it in the newly added class.

It's a CDP term: https://chromedevtools.github.io/devtools-protocol/tot/Runtime/#method-addBinding. In BiDi it will probably called in another way:

• Communication channel from page scripts to the automation client w3c/webdriver-bidi#157
• Add support for custom browser to client messages w3c/webdriver-bidi#361

5. When/where should I emit the script.bindingCalled event?

Script Evaluator should start long-polling getMessage(), and send script.bindingCalled event for each message.

6. What should the E2E test look like? Should it be a call to script.evaluate? If yes, that should it contain?

There is no way to pass argument to script.evaluate. The simplest e2e test should call script.callFunction with binding argument and with some script invoking that binding. Then you should verify the events are received by the Mapper. Additionally I can think of events order verification, and serialization.

[sadym-chromium]

comments after 1:1

[thiagowfx]

@sadym-chromium PTAL. I wrote 3 TODO(BLOCKER) comments.