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

Jump to bottom

Clarify Optional meaning #190

Merged
merged 1 commit into from Aug 17, 2020
Merged

Clarify Optional meaning #190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
6 changes: 3 additions & 3 deletions specs/lifespan.rst
View file
Open in desktop
Expand Up @@ -41,7 +41,7 @@ The scope information passed in ``scope`` contains basic metadata:
* ``type`` (*Unicode string*) -- ``"lifespan"``.
* ``asgi["version"]`` (*Unicode string*) -- The version of the ASGI spec.
* ``asgi["spec_version"]`` (*Unicode string*) -- The version of this spec being
used. Optional; defaults to ``"1.0"``.
used. Optional; if missing defaults to ``"1.0"``.

If an exception is raised when calling the application callable with a
``lifespan.startup`` message or a ``scope`` with type ``lifespan``,
Expand Down Expand Up @@ -84,7 +84,7 @@ sees this it should log/print the message provided and then exit.
Keys:

* ``type`` (*Unicode string*) -- ``"lifespan.startup.failed"``.
* ``message`` (*Unicode string*) -- Optional; defaults to ``""``.
* ``message`` (*Unicode string*) -- Optional; if missing defaults to ``""``.


Shutdown - ``receive`` event
Expand Down Expand Up @@ -118,7 +118,7 @@ sees this it should log/print the message provided and then terminate.
Keys:

* ``type`` (*Unicode string*) -- ``"lifespan.shutdown.failed"``.
* ``message`` (*Unicode string*) -- Optional; defaults to ``""``.
* ``message`` (*Unicode string*) -- Optional; if missing defaults to ``""``.


Version History
Expand Down
144 changes: 78 additions & 66 deletions specs/www.rst
View file
Open in desktop
Expand Up @@ -70,9 +70,9 @@ The *connection scope* information passed in ``scope`` contains:

* ``asgi["version"]`` (*Unicode string*) -- Version of the ASGI spec.

* ``asgi["spec_version"]`` (*Unicode string*) -- Version of the ASGI HTTP spec
this server understands; one of ``"2.0"`` or ``"2.1"``. Optional; if missing
assume ``2.0``.
* ``asgi["spec_version"]`` (*Unicode string*) -- Version of the ASGI
HTTP spec this server understands; one of ``"2.0"`` or
``"2.1"``. Optional; if missing assume ``2.0``.

* ``http_version`` (*Unicode string*) -- One of ``"1.0"``, ``"1.1"`` or ``"2"``.

Expand All @@ -85,16 +85,17 @@ The *connection scope* information passed in ``scope`` contains:
string, with percent-encoded sequences and UTF-8 byte sequences
decoded into characters.

* ``raw_path`` (*byte string*) -- The original HTTP path component unmodified
from the bytes that were received by the web server. Some web server
implementations may be unable to provide this. Optional; defaults to ``None``.
* ``raw_path`` (*byte string*) -- The original HTTP path component
unmodified from the bytes that were received by the web server. Some
web server implementations may be unable to provide this. Optional;
if missing defaults to ``None``.

* ``query_string`` (*byte string*) -- URL portion after the ``?``,
percent-encoded.

* ``root_path`` (*Unicode string*) -- The root path this application
is mounted at; same as ``SCRIPT_NAME`` in WSGI. Optional; defaults
to ``""``.
is mounted at; same as ``SCRIPT_NAME`` in WSGI. Optional; if missing
defaults to ``""``.

* ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable of
``[name, value]`` two-item iterables, where ``name`` is the header name, and
Expand All @@ -106,13 +107,15 @@ The *connection scope* information passed in ``scope`` contains:
the iterable with ``host`` as the header name or replace any existing host
header already present.

* ``client`` (*Iterable[Unicode string, int]*) -- A two-item iterable of
``[host, port]``, where ``host`` is the remote host's IPv4 or IPv6 address, and
``port`` is the remote port as an integer. Optional; defaults to ``None``.
* ``client`` (*Iterable[Unicode string, int]*) -- A two-item iterable
of ``[host, port]``, where ``host`` is the remote host's IPv4 or
IPv6 address, and ``port`` is the remote port as an
integer. Optional; if missing defaults to ``None``.

* ``server`` (*Iterable[Unicode string, int]*) -- A two-item iterable of
``[host, port]``, where ``host`` is the listening address for this server,
and ``port`` is the integer listening port. Optional; defaults to ``None``.
* ``server`` (*Iterable[Unicode string, int]*) -- A two-item iterable
of ``[host, port]``, where ``host`` is the listening address for
this server, and ``port`` is the integer listening port. Optional;
if missing defaults to ``None``.

Servers are responsible for handling inbound and outbound chunked transfer
encodings. A request with a ``chunked`` encoded body should be automatically
Expand All @@ -137,15 +140,15 @@ Keys:

* ``type`` (*Unicode string*) -- ``"http.request"``.

* ``body`` (*byte string*) -- Body of the request. Optional; defaults to
``b""``. If ``more_body`` is set, treat as start of body and concatenate
on further chunks.
* ``body`` (*byte string*) -- Body of the request. Optional; if
missing defaults to ``b""``. If ``more_body`` is set, treat as start
of body and concatenate on further chunks.

* ``more_body`` (*bool*) -- Signifies if there is additional content
to come (as part of a Request message). If ``True``, the consuming
application should wait until it gets a chunk with this set to ``False``. If
``False``, the request is complete and should be processed. Optional;
defaults to ``False``.
application should wait until it gets a chunk with this set to
``False``. If ``False``, the request is complete and should be
processed. Optional; if missing defaults to ``False``.


Response Start - ``send`` event
Expand All @@ -171,10 +174,11 @@ Keys:

* ``status`` (*int*) -- HTTP status code.

* ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable of
``[name, value]`` two-item iterables, where ``name`` is the header name, and
``value`` is the header value. Order must be preserved in the HTTP response.
Header names must be lowercased. Optional; defaults to an empty list. Pseudo
* ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable
of ``[name, value]`` two-item iterables, where ``name`` is the
header name, and ``value`` is the header value. Order must be
preserved in the HTTP response. Header names must be
lowercased. Optional; if missing defaults to an empty list. Pseudo
headers (present in HTTP/2 and HTTP/3) must not be present.


Expand All @@ -190,14 +194,15 @@ Keys:

* ``type`` (*Unicode string*) -- ``"http.response.body"``.

* ``body`` (*byte string*) -- HTTP body content. Concatenated onto any previous
``body`` values sent in this connection scope. Optional; defaults to
``b""``.
* ``body`` (*byte string*) -- HTTP body content. Concatenated onto any
previous ``body`` values sent in this connection scope. Optional; if
missing defaults to ``b""``.

* ``more_body`` (*bool*) -- Signifies if there is additional content
to come (as part of a Response Body message). If ``False``, response will
be taken as complete and closed, and any further messages on the channel
will be ignored. Optional; defaults to ``False``.
to come (as part of a Response Body message). If ``False``, response
will be taken as complete and closed, and any further messages on
the channel will be ignored. Optional; if missing defaults to
``False``.


Disconnect - ``receive`` event
Expand Down Expand Up @@ -243,12 +248,12 @@ metadata (mostly from the HTTP request line and headers):

* ``asgi["version"]`` (*Unicode string*) -- The version of the ASGI spec.

* ``asgi["spec_version"]`` (*Unicode string*) -- Version of the ASGI HTTP spec
this server understands; one of ``"2.0"`` or ``"2.1"``. Optional; if missing
assume ``"2.0"``.
* ``asgi["spec_version"]`` (*Unicode string*) -- Version of the ASGI
HTTP spec this server understands; one of ``"2.0"`` or
``"2.1"``. Optional; if missing assume ``"2.0"``.

* ``http_version`` (*Unicode string*) -- One of ``"1.1"`` or ``"2"``. Optional;
default is ``"1.1"``.
* ``http_version`` (*Unicode string*) -- One of ``"1.1"`` or
``"2"``. Optional; if missing default is ``"1.1"``.

* ``scheme`` (*Unicode string*) -- URL scheme portion (likely ``"ws"`` or
``"wss"``). Optional (but must not be empty); default is ``"ws"``.
Expand All @@ -257,16 +262,17 @@ metadata (mostly from the HTTP request line and headers):
string, with percent-encoded sequences and UTF-8 byte sequences
decoded into characters.

* ``raw_path`` (*byte string*) -- The original HTTP path component unmodified
from the bytes that were received by the web server. Some web server
implementations may be unable to provide this. Optional; defaults to ``None``.
* ``raw_path`` (*byte string*) -- The original HTTP path component
unmodified from the bytes that were received by the web server. Some
web server implementations may be unable to provide this. Optional;
if missing defaults to ``None``.

* ``query_string`` (*byte string*) -- URL portion after the ``?``. Optional;
default is empty string.
* ``query_string`` (*byte string*) -- URL portion after the
``?``. Optional; if missing default is empty string.

* ``root_path`` (*byte string*) -- The root path this application
is mounted at; same as ``SCRIPT_NAME`` in WSGI. Optional; defaults
to empty string.
* ``root_path`` (*byte string*) -- The root path this application is
mounted at; same as ``SCRIPT_NAME`` in WSGI. Optional; if missing
defaults to empty string.

* ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable of
``[name, value]`` two-item iterables, where ``name`` is the header name and
Expand All @@ -277,16 +283,18 @@ metadata (mostly from the HTTP request line and headers):
must be added to the start of the iterable with ``host`` as the header name
or replace any existing host header already present.

* ``client`` (*Iterable[Unicode string, int]*) -- A two-item iterable of
``[host, port]``, where ``host`` is the remote host's IPv4 or IPv6 address,
and ``port`` is the remote port. Optional; defaults to ``None``.
* ``client`` (*Iterable[Unicode string, int]*) -- A two-item iterable
of ``[host, port]``, where ``host`` is the remote host's IPv4 or
IPv6 address, and ``port`` is the remote port. Optional; if missing
defaults to ``None``.

* ``server`` (*Iterable[Unicode string, int]*) -- A two-item iterable of
``[host, port]``, where ``host`` is the listening address for this server,
and ``port`` is the integer listening port. Optional; defaults to ``None``.
* ``server`` (*Iterable[Unicode string, int]*) -- A two-item iterable
of ``[host, port]``, where ``host`` is the listening address for
this server, and ``port`` is the integer listening port. Optional;
if missing defaults to ``None``.

* ``subprotocols`` (*Iterable[Unicode string]*) -- Subprotocols the client
advertised. Optional; defaults to empty list.
* ``subprotocols`` (*Iterable[Unicode string]*) -- Subprotocols the
client advertised. Optional; if missing defaults to empty list.


Connect - ``receive`` event
Expand Down Expand Up @@ -314,16 +322,18 @@ Sent by the application when it wishes to accept an incoming connection.

* ``type`` (*Unicode string*) -- ``"websocket.accept"``.

* ``subprotocol`` (*Unicode string*) -- The subprotocol the server wishes to
accept. Optional; defaults to ``None``.
* ``subprotocol`` (*Unicode string*) -- The subprotocol the server
wishes to accept. Optional; if missing defaults to ``None``.

* ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable of
``[name, value]`` two-item iterables, where ``name`` is the header name, and
``value`` is the header value. Order must be preserved in the HTTP response.
Header names must be lowercased. Must not include a header named
``sec-websocket-protocol``; use the ``subprotocol`` key instead. Optional;
defaults to an empty list. *Added in spec version 2.1*. Pseudo headers
(present in HTTP/2 and HTTP/3) must not be present.
* ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable
of ``[name, value]`` two-item iterables, where ``name`` is the
header name, and ``value`` is the header value. Order must be
preserved in the HTTP response. Header names must be
lowercased. Must not include a header named
``sec-websocket-protocol``; use the ``subprotocol`` key
instead. Optional; if missing defaults to an empty list. *Added in
spec version 2.1*. Pseudo headers (present in HTTP/2 and HTTP/3)
must not be present.


Receive - ``receive`` event
Expand All @@ -335,11 +345,13 @@ Keys:

* ``type`` (*Unicode string*) -- ``"websocket.receive"``.

* ``bytes`` (*byte string*) -- The message content, if it was binary mode, or
``None``. Optional; if missing, it is equivalent to ``None``.
* ``bytes`` (*byte string*) -- The message content, if it was binary
mode, or ``None``. Optional; if missing, it is equivalent to
``None``.

* ``text`` (*Unicode string*) -- The message content, if it was text mode, or
``None``. Optional; if missing, it is equivalent to ``None``.
* ``text`` (*Unicode string*) -- The message content, if it was text
mode, or ``None``. Optional; if missing, it is equivalent to
``None``.

Exactly one of ``bytes`` or ``text`` must be non-``None``. One or both
keys may be present, however.
Expand Down Expand Up @@ -395,8 +407,8 @@ with the close code passed in the message (or 1000 if none is specified).

* ``type`` (*Unicode string*) -- ``"websocket.close"``.

* ``code`` (*int*) -- The WebSocket close code, as per the WebSocket spec.
Optional; defaults to ``1000``.
* ``code`` (*int*) -- The WebSocket close code, as per the WebSocket
spec. Optional; if missing defaults to ``1000``.


WSGI Compatibility
Expand Down