Initial draft

[zcorpan]

A start of milestone 0 in #15

This is modeled after the WebDriver BiDi spec: https://w3c.github.io/webdriver-bidi/

---

Preview | Diff

[jscholes]

@zcorpan Some questions that occured to me; these don't necessarily need answers right now but would be good to note down as TODOs:

1. Does, or should, the protocol imply anything about the ordering of data coming from the remote end? E.g. if I send a command, and am awaiting a response, can an event-related payload be sent back before that response?
2. Will the transport use SSL? Is this something the protocol itself should concern itself with?

[zcorpan]

@zcorpan Some questions that occured to me; these don't necessarily need answers right now but would be good to note down as TODOs:

1. Does, or should, the protocol imply anything about the ordering of data coming from the remote end? E.g. if I send a command, and am awaiting a response, can an event-related payload be sent back before that response?

I think this should be the same as in WebDriver BiDi:

Multiple commands can run at the same time, and commands can potentially be long-running. As a consequence, commands can finish out-of-order.

https://w3c.github.io/webdriver-bidi/#commands

There is no restriction in when a remote end can send events, and so they could be sent in between a command message and its result message.

2. Will the transport use SSL? Is this something the protocol itself should concern itself with?

WebSocket can be used with or without TLS. WebDriver BiDi also allows both to be used: https://w3c.github.io/webdriver-bidi/#listener-secure-flag

At least for connections that are over the wire, it seems good to at least strongly suggest TLS connections to be used, for both privacy and security. WebDriver BiDi doesn't currently say anything about this as far as I can tell.

[zcorpan]

Now the draft contains the first command session.new where you can request a session of a particular AT with a specific version on a specific platform, or a choice of several (firstMatch). The result will contain the chosen AT's name, version, and platform.

[jscholes]

@zcorpan Thanks for this. I think this illustrates the need for some working sessions, by voice, so we can all make sure we're on the same page and have an opportunity to ask questions. I'm highlighting what doesn't make sense to me below.

you can request a session of a particular AT with a specific version on a specific platform, or a choice of several (firstMatch).

Practically speaking, I don't understand how this will/should work. If each AT will host its own remote end, acting as the server, the client end will need to already decide which AT to connect to before establishing the transport. If I've already decided to connect to NVDA, asking for NVDA on Windows seems redundant because I'll already have it, and won't have access to anything else.

I'm probably simply not understanding how this works in WebDriver BiDi (and I feel that needing to understand two specs is adding a lot of cognitive overhead). But if I can use the session.new command to request a specific AT, does that not imply that the remote end will need to know how to invoke multiple ATs, plus determine which ones are applicable on a given platform (e.g. in order to throw an error if I try to request VoiceOver on Windows)?

Additional question: platformName is defined as text, but should it have any specific format/level of detail? E.g. "Windows", "Windows 10", "windows" in lower case, something including a build number/identifier, etc.?

[zcorpan]

If each AT will host its own remote end, acting as the server, the client end will need to already decide which AT to connect to before establishing the transport.

It's possible to implement a remote end that supports multiple ATs, or multiple versions of an AT.

WebDriver also supports proxies, which could be applicable for us as well but isn't included in the draft currently.

That's not to say that all implementations have to support more than one version of one AT on one platform. But the protocol can be designed to allow scaling.

That said, we can remove firstMatch for now, to keep it simple.

If I've already decided to connect to NVDA, asking for NVDA on Windows seems redundant because I'll already have it, and won't have access to anything else.

Yes, it is redundant in that case. Though I think it seems worthwhile to have it so that it's consistent with WebDriver and we can support remote ends controlling multiple versions or multiple ATs going forward.

Additional question: platformName is defined as text, but should it have any specific format/level of detail? E.g. "Windows", "Windows 10", "windows" in lower case, something including a build number/identifier, etc.?

In WebDriver, it's lowercase and some suggested values are "windows", "macos", "linux".

https://w3c.github.io/webdriver/#dfn-matching-capabilities

There used to be a platformVersion as well but it was removed from the WebDriver spec, see w3c/webdriver#741 .

[zcorpan]

I've committed some more progress here today. The session.new command is not fully specced out, but there's a lot more now than previously, so may be worth a review at this point.

[zcorpan]

In 57c161d I added some code to extract the CDDL into two files (at-driver-remote.cddl and at-driver-local.cddl), using npm run extract-schemas.

No JSON Schemas yet.

[zcorpan]

@SamuelHShaw @jscholes you said in our check-in meeting yesterday that PAC have reviewed this and had no comments. Can you mark it as reviewed with GitHub's UI? Then we can merge. Thanks!

[jscholes]

@zcorpan If you explicitly require a review, please request it from @jkva on GitHub so he is notified.

[jugglinmike]

Thanks to feedback from @jkva in gh-26, I've fixed a few typos and removed the assert implementation. (If the need arises, it might be better to rely on Node.js's built-in assert module for that functionality.)