Add a User-Agent String section.

Fixes #146
whatwg · Feb 1, 2022 · 9556c69 · 9556c69
1 parent 222b392
commit 9556c69
Showing 1 changed file with 172 additions and 0 deletions.
diff --git a/compatibility.bs b/compatibility.bs
@@ -47,11 +47,22 @@ urlPrefix: https://drafts.csswg.org/css-values-3/
     text: dppx; url: #dppx
 </pre>
 
+<pre class="biblio">
+{
+  "HTTP-SEMANTICS": {
+    "href": "https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html",
+    "title": "HTTP Semantics",
+    "authors": [ "R. Fielding", "M. Nottingham", "J. Reschke" ]
+  }
+}
+</pre>
+
 <pre class=link-defaults>
 spec:css-display-3; type:value; for:display; text:flex
 spec:css-flexbox-1; type:value; text:inline-flex
 spec:filter-effects-1; type:property; text:filter
 spec:css-conditional-3; type:at-rule; text:@media
+spec:infra; type:dfn; text:user agent
 </pre>
 
 <!-- Commented out until we know what the heck to put here:
@@ -816,6 +827,167 @@ The following are the event handlers and their corresponding event handler event
 WebKit also has this on <a href="https://github.com/WebKit/webkit/blob/e455672f9e6861ced85d8be01cb7bc03a30a0555/LayoutTests/fast/dom/event-handler-attributes.html#L335">HTMLFrameSetElement</a>. It's unclear if this is needed for compatibility.
 </div>
 
+<h2 id="ua-string-section">The User-Agent String</h2>
+
+The <code>User-Agent</code> header field syntax is formally defined by [[!HTTP-SEMANTICS]] and
+provides SHOULD-level guidance on its value. This section serves as a descriptive record of the
+<code>User-Agent</code> patterns found in the so-called major web browsers, but much of it will
+apply to other browsers with a shared heritage (i.e., forks and embedders) as well as any
+<a>user agent</a> in the more general sense that send a <code>User-Agent</code> <a>header</a>.
+
+<h3 id="ua-string-patterns">User-Agent Tokens</h3>
+
+A User-Agent <dfn>token</dfn> is a string that represents an abstraction over a semantic unit in the
+<code>User-Agent</code> string. This document formalizes <a>tokens</a> as a <a>string</a> that
+begins with an opening bracket "<" and ends with a closing ">" bracket, e.g.,
+<code>&lt;version&gt;</code>.
+
+<h4 id="ua-string-token-reference">User-Agent Token Reference</h4>
+
+This is a non-exhaustive list of common User-Agent <a>tokens</a>.
+
+<table>
+  <thead>
+    <th>Tokens</th>
+    <th>Description</th>
+  </thead>
+  <tbody>
+    <!-- TODO(miketaylr): fit Android into existing model
+    <tr>
+      <td><code>&lt;<dfn>androidVersion</dfn>&gt;</code></td>
+      <td>Represents Android major version.</td>
+    </tr> -->
+    <tr>
+      <td><code>&lt;<dfn>deviceCompat</dfn>&gt;</code></td>
+      <td>Represents the form-factor of the device. Primarily this is <code>Mobile </code>, or just
+      the empty string, for Desktop or non-mobile devices. Some browsers have also sent token values
+      such as <code>Tablet</code>, <code>TV</code>, <code>Mobile VR</code>, etc., or included
+      build information as well.</td>
+    </tr>
+    <!-- TODO(miketaylr): fit Android into existing model
+    <tr>
+      <td><code>&lt;<dfn>deviceModel</dfn>&gt;</code></td>
+      <td>Represents Android device model.</td>
+    </tr>
+    -->
+    <tr>
+      <td><code>&lt;<dfn>frozenWebKitVersion</dfn>&gt;</code></td>
+      <td><code>AppleWebKit/</code> followed by a WebKit revision number, (<code>537.36</code> in
+      the case of Chrome, and <code>605.1.15</code> in the case of Safari), followed by
+      <code> (KHTML, like Gecko)</code>.</td>
+    </tr>
+    <tr>
+      <td><code>&lt;<dfn>frozenSafariVersion</dfn>&gt;</code></td>
+      <td><code>Safari/</code> followed by a WebKit revision number, (<code>537.36</code> in
+      the case of Chrome, and <code>605.1.15</code> in the case of Safari).</td>
+    </tr>
+    <tr>
+      <td><code>&lt;<dfn>legacyMozillaVersion</dfn>&gt;</code></td>
+      <td><code>Mozilla/5.0</code></td>
+    </tr>
+    <tr>
+      <td><code>&lt;<dfn>majorVersion</dfn>&gt;</code></td>
+      <td>Represents the browser's major version number.</td>
+    </tr>
+    <tr>
+      <td><code>&lt;<dfn>minorVersion</dfn>&gt;</code></td>
+      <td>Represents the browser's non-major version numbers.</td>
+    </tr>
+    <tr>
+      <td><code>&lt;<dfn>oscpu</dfn>&gt;</code></td>
+      <td>Represents the device operating system and (optionally) CPU architecture.</td>
+    </tr>
+    <tr>
+      <td><code>&lt;<dfn>platform</dfn>&gt;</code></td>
+      <td>Represents the underlying device platform.
+    </tr>
+  </tbody>
+</table>
+
+<h3 id="ua-string-meta-structure">Meta Structure</h3>
+
+The User-Agent strings that follow share the common meta structure:
+
+<code>&lt;<a>legacyMozillaVersion</a>&gt;</code> (<code>a</code>) <code>b</code>
+
+Where <code>a</code> is a set of tokens representing device information and <code>b</code> is a set
+of tokens representing browser information.
+
+<h3 id="ua-string-chrome">Chrome</h3>
+
+<h4 id="ua-string-pattern-chrome">Chrome User-Agent pattern</h4>
+
+<code>&lt;<a>legacyMozillaVersion</a>&gt; (&lt;<a>platform</a>&gt;; &lt;<a>oscpu</a>&gt;)
+&lt;<a>frozenWebKitVersion</a>&gt; Chrome/&lt;<a>chromeVersion</a>&gt; &lt;<a>deviceCompat</a>&gt;
+&lt;<a>frozenSafariVersion</a>&gt;</code>
+
+<div class="example" id="chrome-ua-examples">
+  <strong>Desktop</strong>: <code>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
+  (KHTML, like Gecko) Chrome/96.0.4664.93 Safari/537.36</code>
+
+  <strong>Mobile</strong>: <code>Mozilla/5.0 (Linux; Android 10) AppleWebKit/537.36 (KHTML,
+  like Gecko) Chrome/96.0.4664.93 Mobile Safari/537.36</code>
+</div>
+
+<h4 id="ua-string-tokens-chrome">Chrome-specific tokens</h4>
+
+<code>&lt;<dfn>chromeVersion</dfn>&gt;</code> decomposes to the following:
+<!-- TODO(miketaylr): add dfn for "decompose -->
+
+<code>&lt;<a>majorVersion</a>&gt;.&lt;<a>minorVersion</a>&gt;</code>, where
+<code>&lt;<a>minorVersion</a>&gt;</code> represents MINOR.BUILD.PATCH version numbers.
+
+<h3 id="ua-string-firefox">Firefox</h3>
+
+<h4 id="ua-string-pattern-firefox">Firefox User-Agent pattern</h4>
+
+<code>&lt;<a>legacyMozillaVersion</a>&gt; (&lt;<a>platform</a>&gt;; &lt;<a>oscpu</a>&gt; rv:&lt;
+<a>firefoxVersion</a>&gt;) Gecko/&lt;<a>geckoVersion</a>&gt; Firefox/&lt;<a>firefoxVersion</a>&gt;</code>
+
+<div class="example" id="firefox-ua-examples">
+  <strong>Desktop</strong>: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:100.0) Gecko/20100101
+  Firefox/100.0</code>
+
+  <strong>Mobile</strong>: <code>Mozilla/5.0 (Android 10; Mobile; rv:100.0) Gecko/100.0
+  Firefox/100.0</code>
+</div>
+
+<h4 id="ua-string-tokens-firefox">Firefox-specific tokens</h4>
+
+<code>&lt;<dfn>firefoxVersion</dfn>&gt;</code> decomposes to the following:
+
+<code>&lt;<a>majorVersion</a>&gt;.0</code>
+
+In Firefox on desktop platforms (Windows, macOS, Linux, etc.),
+<code>&lt;<dfn>geckoVersion</dfn>&gt;</code> is the frozen build
+date "<code>20100101</code>". In Firefox on Android, <code>&lt;<a>geckoVersion</a>&gt;</code> is the
+same value as <code>&lt;<a>firefoxVersion</a>&gt;</code>.
+
+
+<h3 id="ua-string-safari">Safari</h3>
+
+<h4 id="ua-string-pattern-safari">Safari User-Agent pattern</h4>
+
+<code>&lt;<a>legacyMozillaVersion</a>&gt; (Macintosh; Intel Mac OS X 10_15_7)
+&lt;<a>frozenWebKitVersion</a>&gt; Version/&lt;<a>safariVersion</a>&gt; &lt;<a>deviceCompat</a>&gt;
+&lt;<a>frozenSafariVersion</a>&gt;</code>
+
+<div class="example" id="safari-ua-examples">
+  <strong>Desktop</strong>: <code>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
+  (KHTML, like Gecko) Chrome/96.0.4664.93 Safari/537.36</code>
+
+  <strong>Mobile</strong>: <code>Mozilla/5.0 (iPhone; CPU iPhone OS 15_3 like Mac OS X)
+  AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.2 Mobile/15E148 Safari/604.1
+</code>
+</div>
+
+<h4 id="ua-string-tokens-safari">Safari-specific tokens</h4>
+
+<code>&lt;<dfn>safariVersion</dfn>&gt;</code> decomposes to the following:
+
+<code>&lt;<a>majorVersion</a>&gt;.&lt;<a>minorVersion</a>&gt;</code>, where
+<code>&lt;<a>minorVersion</a>&gt;</code> is a single digit.
+
 <h2 id="acknowledgements" class="no-num">Acknowledgements</h2>
 Thanks to Alan Cutter, Cameron McCormack, Chris Rebert, Chun-Min (Jeremy) Chen, Daniel Holbert,
 David Håsäther, Domenic Denicola, hexalys, Jean-Yves Perrier, Jacob Rossi, Karl Dubost,