Update web-platform-tests to revision b9d4748d6a7f9b21bd420486955b44349aa005ea

tests/wpt/web-platform-tests/docs/writing-tests/python-handlers/index.md

@@ -0,0 +1,22 @@
+# Python Handlers
+
+Python file handlers are Python files which the server executes in response to
+requests made to the corresponding URL. This is hooked up to a route like
+`("*", "*.py", python_file_handler)`, meaning that any .py file will be
+treated as a handler file (note that this makes it easy to write unsafe
+handlers, particularly when running the server in a web-exposed setting).
+
+The Python files must define a single function `main` with the signature::
+
+    main(request, response)
+
+The wptserver implements a number of Python APIs for controlling traffic.
+
+```eval_rst
+.. toctree::
+   :maxdepth: 1
+
+   request
+   response
+   stash
+```

tests/wpt/web-platform-tests/docs/writing-tests/python-handlers/request.md

@@ -0,0 +1,3 @@
+```eval_rst
+.. include:: ../../../tools/wptserve/docs/request.rst
+```

tests/wpt/web-platform-tests/docs/writing-tests/python-handlers/response.md

@@ -0,0 +1,3 @@
+```eval_rst
+.. include:: ../../../tools/wptserve/docs/response.rst
+```

tests/wpt/web-platform-tests/docs/writing-tests/python-handlers/stash.md

@@ -0,0 +1,3 @@
+```eval_rst
+.. include:: ../../../tools/wptserve/docs/stash.rst
+```

tests/wpt/web-platform-tests/docs/writing-tests/server-features.md

@@ -82,12 +82,20 @@ the file e.g. `test.html.sub.headers`.
 
 ### Tests Requiring Full Control Over The HTTP Response
 
+```eval_rst
+.. toctree::
+   :maxdepth: 1
+
+   python-handlers/index
+   server-pipes
+```
+
 For full control over the request and response the server provides the
 ability to write `.asis` files; these are served as literal HTTP
-responses. It also provides the ability to write Python scripts that
-have access to request data and can manipulate the content and timing
-of the response. For details see the
-[wptserve documentation](https://wptserve.readthedocs.org).
+responses. It also provides the ability to write [Python
+"handlers"](python-handlers/index)--Python scripts that have access to request
+data and can manipulate the content and timing of the response. Responses are
+also influenced by [the `pipe` query string parameter](server-pipes).
 
 
 ### Writing tests for HTTP/2.0

tests/wpt/web-platform-tests/docs/writing-tests/server-pipes.md

@@ -0,0 +1,136 @@
+# wptserve Pipes
+
+## Enabling
+
+Pipes are functions that may be used when serving files to alter parts
+of the response. These are invoked by adding a pipe= query parameter
+taking a | separated list of pipe functions and parameters. The pipe
+functions are applied to the response from left to right. For example:
+
+    GET /sample.txt?pipe=slice(1,200)|status(404).
+
+This would serve bytes 1 to 199, inclusive, of foo.txt with the HTTP status
+code 404.
+
+Note: If you write directly to the response socket using ResponseWriter, or
+when using the asis handler, only the trickle pipe will affect the response.
+
+There are several built-in pipe functions, and it is possible to add
+more using the `@pipe` decorator on a function, if required.
+
+Note: Because of the way pipes compose, using some pipe functions prevents the
+content-length of the response from being known in advance. In these cases the
+server will close the connection to indicate the end of the response,
+preventing the use of HTTP 1.1 keepalive.
+
+## Built-In Pipes
+
+### `sub`
+
+Used to substitute variables from the server environment, or from the
+request into the response.
+
+Substitutions are marked in a file using a block delimited by `{{`
+and `}}`. Inside the block the following variables are available:
+
+- `{{host}}` - The host name of the server excluding any subdomain part.
+- `{{domains[]}}` - The domain name of a particular subdomain e.g.
+  `{{domains[www]}}` for the `www` subdomain.
+- `{{ports[][]}}` - The port number of servers, by protocol e.g.
+  `{{ports[http][0]}}` for the first (and, depending on setup, possibly only)
+  http server
+- `{{headers[]}}` The HTTP headers in the request e.g. `{{headers[X-Test]}}`
+  for a hypothetical `X-Test` header.
+- `{{header_or_default(header, default)}}` The value of an HTTP header, or a
+  default value if it is absent. e.g. `{{header_or_default(X-Test,
+  test-header-absent)}}`
+- `{{GET[]}}` The query parameters for the request e.g. `{{GET[id]}}` for an id
+  parameter sent with the request.
+
+So, for example, to write a JavaScript file called `xhr.js` that
+depends on the host name of the server, without hardcoding, one might
+write:
+
+    var server_url = http://{{host}}:{{ports[http][0]}}/path/to/resource;
+    //Create the actual XHR and so on
+
+The file would then be included as:
+
+    <script src="xhr.js?pipe=sub"></script>
+
+This pipe can also be enabled by using a filename `*.sub.ext`, e.g. the file above could be called `xhr.sub.js`.
+
+### `status`
+
+Used to set the HTTP status of the response, for example:
+
+    example.js?pipe=status(410)
+
+### `headers`
+
+Used to add or replace http headers in the response. Takes two or
+three arguments; the header name, the header value and whether to
+append the header rather than replace an existing header (default:
+False). So, for example, a request for:
+
+    example.html?pipe=header(Content-Type,text/plain)
+
+causes example.html to be returned with a text/plain content type
+whereas:
+
+    example.html?pipe=header(Content-Type,text/plain,True)
+
+Will cause example.html to be returned with both text/html and
+text/plain content-type headers.
+
+### `slice`
+
+Used to send only part of a response body. Takes the start and,
+optionally, end bytes as arguments, although either can be null to
+indicate the start or end of the file, respectively. So for example:
+
+    example.txt?pipe=slice(10,20)
+
+Would result in a response with a body containing 10 bytes of
+example.txt including byte 10 but excluding byte 20.
+
+    example.txt?pipe=slice(10)
+
+Would cause all bytes from byte 10 of example.txt to be sent, but:
+
+    example.txt?pipe=slice(null,20)
+
+Would send the first 20 bytes of example.txt.
+
+### `trickle`
+
+Note: Using this function will force a connection close.
+
+Used to send the body of a response in chunks with delays. Takes a
+single argument that is a microsyntax consisting of colon-separated
+commands. There are three types of commands:
+
+* Bare numbers represent a number of bytes to send
+
+* Numbers prefixed `d` indicate a delay in seconds
+
+* Numbers prefixed `r` must only appear at the end of the command, and
+  indicate that the preceding N items must be repeated until there is
+  no more content to send. The number of items to repeat must be even.
+
+In the absence of a repetition command, the entire remainder of the content is
+sent at once when the command list is exhausted. So for example:
+
+    example.txt?pipe=trickle(d1)
+
+causes a 1s delay before sending the entirety of example.txt.
+
+    example.txt?pipe=trickle(100:d1)
+
+causes 100 bytes of example.txt to be sent, followed by a 1s delay,
+and then the remainder of the file to be sent. On the other hand:
+
+    example.txt?pipe=trickle(100:d1:r2)
+
+Will cause the file to be sent in 100 byte chunks separated by a 1s
+delay until the whole content has been sent.