Merge changes from topic 'cors'

* changes:
  Support faster cross-domain XHR calls
  Allow CORS to use modifying REST API

Documentation/config-gerrit.txt

@@ -3920,9 +3920,12 @@ Defaults to an empty list, meaning no additional TLDs are allowed.
 [[site.allowOriginRegex]]site.allowOriginRegex::
 +
 List of regular expressions matching origins that should be permitted
-to use the Gerrit REST API to read content. These should be trusted
-applications as the sites may be able to use the user's credentials.
-Only applies to GET and HEAD requests.
+to use the full Gerrit REST API.  These should be trusted applications,
+as the sites may be able to use the user's credentials. Applies to
+all requests, including state changing methods (PUT, DELETE, POST).
++
+Expressions should not require trailing slash. For example a valid
+pattern might be `https://build-status[.]example[.]com`.
 +
 By default, unset, denying all cross-origin requests.
 

Documentation/rest-api.txt

@@ -32,12 +32,41 @@ By default all REST endpoints assume anonymous access and filter
 results to correspond to what anonymous users can read (which may
 be nothing at all).
 
-Users (and programs) may authenticate by prefixing the endpoint URL with
-`/a/`. For example to authenticate to `/projects/`, request the URL
-`/a/projects/`.
+Users (and programs) can authenticate with HTTP passwords by prefixing
+the endpoint URL with `/a/`. For example to authenticate to
+`/projects/`, request the URL `/a/projects/`. Gerrit will use HTTP basic
+authentication with the HTTP password from the user's account settings
+page. This form of authentication bypasses the need for XSRF tokens.
 
-Gerrit uses HTTP basic authentication with the HTTP password from the
-user's account settings page.
+An authorization cookie may be presented in the request URL inside the
+`access_token` query parameter.  XSRF tokens are not required when a
+valid `access_token` is used in the URL.
+
+[[cors]]
+=== CORS
+
+Cross-site scripting may be supported if the administrator has configured
+link:config-gerrit.html#site.allowOriginRegex[site.allowOriginRegex].
+
+Approved web applications running from an allowed origin can rely on
+CORS preflight to authorize requests requiring cookie based
+authentication, or mutations (POST, PUT, DELETE). Mutations require a
+valid XSRF token in the `X-Gerrit-Auth` request header.
+
+Alternatively applications can use `access_token` in the URL (see
+above) to authorize requests. Mutations sent as POST with a request
+content type of `text/plain` can skip CORS preflight. Gerrit accepts
+additional query parameters `$m` to override the correct method (PUT,
+POST, DELETE) and `$ct` to specify the actual content type, such as
+`application/json; charset=UTF-8`. Example:
+
+----
+    POST /changes/42/topic?$m=PUT&$ct=application/json%3B%20charset%3DUTF-8&access_token=secret HTTP/1.1
+	Content-Type: text/plain
+	Content-Length: 23
+
+	{"topic": "new-topic"}
+----
 
 [[preconditions]]
 === Preconditions