Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generalize protocol extension mechanism #1177

Merged
merged 2 commits into from
Jan 6, 2018
Merged

Generalize protocol extension mechanism #1177

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
daa2d9e
Generalize protocol extension mechanism
jugglinmike Dec 22, 2017
a6ff1fb
fixup! Generalize protocol extension mechanism
jugglinmike Jan 6, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 27 additions & 29 deletions webdriver-spec.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -671,11 +671,11 @@ <h3>Simplicity</h3>
<section>
<h3>Extensions</h3>

<p>WebDriver aims to allow other standards
to <a data-lt="extension commands">provide extensions</a> to support new functionality,
and to allow conformance tests that cannot be implemented
entirely in <a href=https://tc39.github.io/ecma262/>ECMAScript</a>
to be written in a vendor-neutral way.
<p>WebDriver provides a mechanism for others to define extensions to the protocol
for the purposes of automating functionality that cannot be implemented entirely
in <a href=https://tc39.github.io/ecma262/>ECMAScript</a>. This allows other
web standards to support the automation of new platform features. It also
allows vendors to expose functionality that is specific to their browser.
</section>
</section> <!-- /Design Notes -->

Expand Down Expand Up @@ -1790,29 +1790,36 @@ <h3>Handling Errors</h3>
<section>
<h2>Protocol Extensions</h2>

<p>The protocol is designed to allow extension to meet vendor-specific needs.
Commands that are specific to a user agent
<p>Using the terminology defined in this section, others may define additional
commands that seamlessly integrate with the standard protocol. This allows
vendors to expose functionality that is specific to their user agent, and it
also allows other web standards to define commands for automating new platform
features.

<p>Commands defined in this way
are called <dfn data-lt="extension command">extension commands</dfn>
and behave no differently than other <a>commands</a>;
each has a dedicated HTTP endpoint and a set of <a>remote end steps</a>.

<p>Each <a>extension command</a> has an associated
<dfn>extension command name</dfn>
<dfn>extension command URI Template</dfn>
that is a <a>URI Template</a> string,
and which should bear some resemblance to what the command performs.
The name is used to form an <a>extension command</a>’s
<a data-lt="extension command URI Template">URI Template</a>.

<p>The <a>extension command</a>’s <dfn>extension command URI Template</dfn>
is a <a>URI Template</a> composed of the <a>extension command prefix</a>,
followed by "<code>/</code>",
and the <a>extension command</a>’s <a data-lt="extension command name">name</a>.
The <a>extension command URI Template</a>,
This value,
along with the HTTP method and <a>extension command</a>,
is added to the <a>table of endpoints</a>
and thus follows the same rules for <a>request routing</a>
as that of other built-in <a>commands</a>.

<p>In order to avoid potential resource conflicts with other implementations,
vendor-specific <a>extension command URI Template</a>s SHOULD begin with one
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can add <dfn data-lt="extension command URI Templates">…</dfn> for the plural form on :1805.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like the convention is to prefer the singular for term definitions, so I've done the inverse:

<a data-lt="extension command URI Template">extension command URI Templates</a>

Does that seem okay to you?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe the vendor namespace was a requirement before and we shouldn’t loosen this by saying vendors should be using a vendor prefix.

I suggest s/SHOULD/must/ here or just rephrasing it to have a normative sound to it:

… vendor-specific extension command URI templates beginw tih on or more path segments …

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure thing!

or more path segments which uniquely identifies the vendor and UA.
It is suggested that vendors use their vendor prefixes
without additional characters as outlined in [[CSS21]],
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I filed #1179 about defining what ‘additional characters’ mean.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, very good

notably in <a href=https://www.w3.org/TR/CSS21/syndata.html#vendor-keywords>section 4.1.2.2 on <i>vendor keywords</i></a>,
as the name for this path element,
and include a vendor-chosen UA identifier.

<aside class=note>
If the <a>extension command URI Template</a> includes a variable named
<var>session id</var>, the value of this variable will be used to define the
Expand All @@ -1822,25 +1829,16 @@ <h2>Protocol Extensions</h2>
<aside class=example>
<p>This might lead to a URL of the form
<code>/session/5d376174-36f0-11e5-9b9a-6bdf200a3f7f/<var>ms</var>/<var>edge</var>/<var>context</var></code>,
where <var>/session/{<var>session id</var>}/ms/edge</var> is an <a>extension command prefix</a>
based on the vendor prefix associated with Microsoft,
and <var>context</var> the <a>extension command name</a>
where <code>session/{<var>session id</var>}</code> associates the request
with the specified session, <code>ms/edge</code> identifies the command as
specific to the Edge browser distributed by Microsoft,
and <code>context</code> describes the functionality
that, in the context of Edge, allows a <a>local end</a>
to switch between browser-specific contexts.
Requesting this URL will call the <a>extension command</a>’s
<a>remote end steps</a>.
</aside>

<p>An <dfn>extension command prefix</dfn>
is a <a>URI Template</a> string that forms a <a>URL</a> path part,
separating <a>extension commands</a> from other <a>commands</a>
in order to avoid potential resource conflicts with other implementations.
It is suggested that vendors use their vendor prefixes
without additional characters as outlined in [[CSS21]],
notably in <a href=https://www.w3.org/TR/CSS21/syndata.html#vendor-keywords>section 4.1.2.2 on <i>vendor keywords</i></a>,
as the name for this path element,
and include a vendor-chosen UA identifier.

<p><a>Remote ends</a> may also introduce
<dfn data-lt="extension capability">extension capabilities</dfn>
that are extra <a>capabilities</a>
Expand Down