Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-10-22 09:45:41 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bug 1554816 [wpt PR 17039] - [docs] Integrate wptserve documentation, a=testonly

Browse Source 
Automatic update from web-platform-tests
[docs] Generalize desc of Python file handlers

Remove references to PHP since readers may not be familiar with that
language.

--
[docs] Integrate wptserve documentation

Relocate instructions that are specifically geared towards test authors
to the "docs" directory. Persist API documentation in its current
location and configure Sphinx to include relevant aspects in the
generated website.

--

wp5At-commits: fe3019b4c6526136171192a0f7e993b06f59f62b, eeb34a17faace5d8b05abee1f4c56536a44a9cee
wpt-pr: 17039
This commit is contained in:
Mike Pennisi 2019-06-13 14:43:04 +00:00 committed by James Graham
parent 55ec3e6db5
commit accbe89a71
9 changed files with 187 additions and 171 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
testing/web-platform/tests/docs/conf.py
View File

@ -42,7 +42,8 @@ release = u''
# ones.
extensions = [
'recommonmark',
'sphinxarg.ext'
'sphinxarg.ext',
'sphinx.ext.autodoc'
]
# Add any paths that contain templates here, relative to this directory.

22
testing/web-platform/tests/docs/writing-tests/python-handlers/index.md Normal file
View File

@ -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
```

3
testing/web-platform/tests/docs/writing-tests/python-handlers/request.md Normal file
View File

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

3
testing/web-platform/tests/docs/writing-tests/python-handlers/response.md Normal file
View File

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

3
testing/web-platform/tests/docs/writing-tests/python-handlers/stash.md Normal file
View File

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

16
testing/web-platform/tests/docs/writing-tests/server-features.md
View File

@ -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

136
testing/web-platform/tests/docs/writing-tests/server-pipes.md Normal file
View File

@ -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.

15
testing/web-platform/tests/tools/wptserve/docs/handlers.rst
View File

@ -71,16 +71,13 @@ decorator::
Python File Handlers
--------------------
Python file handlers are designed to provide a vaguely PHP-like interface
where each resource corresponds to a particular python file on the
filesystem. Typically 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 python files unsafe in
much the same way that .php files are when using PHP).
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).
Unlike PHP, the python files don't work by outputting text to stdout
from the global scope. Instead they must define a single function
`main` with the signature::
The Python files must define a single function `main` with the signature::
main(request, response)

157
testing/web-platform/tests/tools/wptserve/docs/pipes.rst
View File

@ -1,163 +1,6 @@
Pipes
======
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.
:mod:`Interface <pipes>`
------------------------