From bbff9281522c565846ca0785c5a583843fae4a61 Mon Sep 17 00:00:00 2001 From: Andrew Godwin Date: Mon, 27 Mar 2017 19:04:58 -0700 Subject: [PATCH] Update ASGI spec with new process-local channels definition --- docs/asgi.rst | 25 +++++++++++-------------- docs/asgi/www.rst | 8 ++++---- 2 files changed, 15 insertions(+), 18 deletions(-) diff --git a/docs/asgi.rst b/docs/asgi.rst index 9e302e8..893ef76 100644 --- a/docs/asgi.rst +++ b/docs/asgi.rst @@ -127,7 +127,7 @@ is made between channels that have multiple readers (such as the ``http.request`` channel that web applications would listen on from every application worker process), *single-reader channels* that are read from a single unknown location (such as ``http.request.body?ABCDEF``), and -*process-specific channels* (such as a ``http.response!ABCDEF`` channel +*process-specific channels* (such as a ``http.response.A1B2C3!D4E5F6`` channel tied to a client socket). *Normal channel* names contain no type characters, and can be routed however @@ -146,19 +146,16 @@ channel to a server, but reads from this channel by a single process must always be in-order and return messages if the channel is non-empty. These names must be generated by the ``new_channel`` call. -*Process-specific channel* names contain an exclamation mark -(``!``) character in order to indicate to the channel layer that it may -have to route the data for these channels differently to ensure it reaches the -single process that needs it; these channels are nearly always tied to -incoming connections from the outside world. The ``!`` is always preceded by -the main channel name (e.g. ``http.response``) and followed by the -per-client/random portion - channel layers can split on the ``!`` and use just -the right hand part to route if they desire, or can ignore it if they don't -need to use different routing rules. Even if the right hand side contains -client routing information, it must still contain random parts too so that -each call to ``new_channel`` returns a new, unused name. These names -must be generated by the ``new_channel`` call; they are guaranteed to only -be read from the same process that calls ``new_channel``. +*Process-specific channel* names contain an exclamation mark (``!``) that +separates a remote and local part. These channels are received differently; +only the name up to and including the ``!`` character is passed to the +``receive()`` call, and it will receive any message on any channel with that +prefix. This allows a process, such as a HTTP terminator, to listen on a single +process-specific channel, and then distribute incoming requests to the +appropriate client sockets using the local part (the part after the ``!``). +The local parts must be generated and managed by the process that consumes them. +These channels, like single-reader channels, are guaranteed to give any extant +messages in order if received from a single process. Messages should expire after a set time sitting unread in a channel; the recommendation is one minute, though the best value depends on the diff --git a/docs/asgi/www.rst b/docs/asgi/www.rst index 0289f54..d81fcde 100644 --- a/docs/asgi/www.rst +++ b/docs/asgi/www.rst @@ -128,7 +128,7 @@ Send after any server pushes, and before any response chunks. If ``ChannelFull`` is encountered, wait and try again later, optionally giving up after a predetermined timeout. -Channel: ``http.response!`` +Channel: Defined by server, suggested ``http.response.RANDOMPART!CLIENTID`` Keys: @@ -154,7 +154,7 @@ Response Chunk Must be sent after an initial Response. If ``ChannelFull`` is encountered, wait and try again later. -Channel: ``http.response!`` +Channel: Defined by server, suggested ``http.response.RANDOMPART!CLIENTID`` Keys: @@ -194,7 +194,7 @@ If the remote peer does not support server push, either because it's not a HTTP/2 peer or because SETTINGS_ENABLE_PUSH is set to 0, the server must do nothing in response to this message. -Channel: ``http.response!`` +Channel: Defined by server, suggested ``http.response.RANDOMPART!CLIENTID`` Keys: @@ -372,7 +372,7 @@ If received while the connection is established: any send. * ``accept`` is ignored. -Channel: ``websocket.send!`` +Channel: Defined by server, suggested ``websocket.send.RANDOMPART!CLIENTID`` Keys: