forked from slact/nchan
-
Notifications
You must be signed in to change notification settings - Fork 1
/
protocol.txt
191 lines (148 loc) · 7.95 KB
/
protocol.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
Basic HTTP Push Relay Protocol
Rev. 2.23
1. Introduction
1.1. Purpose
The primary purpose of this protocol is to enable a method of
long-polling, transparent to the web client, where client connections
idle only on the HTTP server and need not be forwarded.
1.2. Requirements
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC2119. An
implementation is not compliant if it fails to satisfy one or more of
the MUST or REQUIRED level requirements for the protocols it
implements.
An implementation that satisfies all the MUST or REQUIRED level and all
the SHOULD level requirements for its protocols is said to be
"unconditionally compliant"; one that satisfies all the MUST level
requirements but not all the SHOULD level requirements for its
protocols is said to be "conditionally compliant."
1.3. Terminology
This specification uses a number of terms to refer to the roles played
by participants in, and objects of, this protocol:
server
The HTTP server implementing this protocol.
client
A program that initiates TCP/IP connections with the HTTP server
for the purpose of sending HTTP requests.
message
Application specific data, usually enclosed in a request or
response body.
channel
A resource representing an isolated pathway for message
transmission. Each channel has a single unique message queue.
subscriber
A client that sends HTTP requests to the server for the purposes
of receiving messages via some channel.
publisher
A client that sends HTTP requests to the server in order to
transmit messages to subscribers via a channel.
channel id
A unique identifier for a channel.
location
A url (or set of urls) on the server.
2. Requirements
2.1. Server Requirements
The HTTP server MUST have a mechanism of specifying a url, or a set of
urls as publisher and subscriber locations. All requests to the
publisher location MUST be treated as publisher requests, all to the
subscriber location as subscriber requests.
The server MUST implement a mechanism for identifying channels with
unique ids. This MAY, for example, be a url parameter (/foo/?id=123) or
a cookie. Methods of channel identification other than those using the
url MAY be used, but are strongly discouraged.
The server MUST accept requests on publisher locations and respond to
them immediately. It MUST also accept requests on subscriber locations,
but need not respond immediately.
2.2. Client Requirements
All clients must prodice valid HTTP requests. Subscriber clients must
have a caching mechanism that appropriately reacts to Last-Modified and
Etag response headers (web browsers, for example).
2.3. The Channel ID
It is not the responsibility of the server to generate IDs.
3. Server Operation
A publisher request functions as notification to the server of a
message to send to some subscribers over some channel. A subscriber
request notifies the server of the subscriber's intent to receive a
message.
3.1. The Subscriber
The server MUST accept all valid HTTP GET requests to the subscriber
location. All other request methods SHOULD be responded to with a 405
Method Not Allowed status code.
Subscriber requests are considered notifications of intent to receive
some message. Subscribers may request existing messages, messages that
are not yet available, and messages that are no longer available. The
requested message is identified using the If-Modified-Since and
If-None-Match request headers. A request with no If-Modified-Since
header MUST be assumed to be requesting the oldest available message in
a channel. Each 200 OK response containing a message MUST have its
Last-Modified and Etag headers set so that a request using those
headers will be interpreted as a request for the next available
message. Additionally, said 200 OK MUST contain the Content-Type header
of the message publisher request, unless no Content-Type header had
been provided or it is explicitly overridden by server configuration.
There are several common mechanisms for performing an HTTP server push.
The rest of the behavior of the server in response to a subscriber
request SHOULD be configurable and MUST be selected from the following
list of mechanisms:
Long-Polling
Requests for existing messages will be responded to immediately;
responses to requests for messages not yet available MUST be
delayed until the message becomes available. Delayed responses
MUST satisfy all of the following conditions:
+ A 200 OK response containing the message (and its
Content-Type) MUST be sent immediately after the message
becomes available. The entire response must be
indistinguishable from a response to a request for an existing
message.
+ If the channel the subscriber is waiting on is deleted or for
some reason becomes unavailable, the server MUST immediately
send a 410 Gone response.
+ If another subscriber has conflicted with this request, the
server MUST immediately send a 409 Conflict response.
Interval-Polling
All requests will be responded to immediately. Requests for
messages not yet available MUST produce a 304 Not Modified
response code.
In addition, when the server receives more than one concurrent
subscriber request on the same channel, it MUST do one of the
following:
Broadcast
No additional actions are performed
Last-in, first-out
All but the most recent long-held subscriber request on the
channel are sent a 409 Conflict response.
First-in, last-out
All but the oldest request will be sent a 409 Conflict
The server SHOULD make this selection configurable, and MUST default to
broadcast behavior.
3.2. The Publisher
The server MUST accept all valid HTTP requests to the publisher
location. The server, when sent a publisher request, MUST satisfy all
of the following conditions:
* GET requests receive a 200 OK response for existing channels and a
404 Not Found otherwise.
* PUT requests receive a 200 OK response. The request creates a
channel if no channel with the given channel id exists.
* DELETE requests receive a 200 OK if the channel identified by the
channel id exists and has been completely deleted. All subscribers
MUST have been sent a 410 Gone response. Requests for nonexistent
channels MUST be responded to with a 404 Not Found.
* POST requests are used to send messages. The request MAY contain a
body in any encoding representing a message to be sent over the
channel. The message MUST be immediately delivered to all currently
long-held subscriber requests. Additionally, the message MAY be
stored for future retrieval and the oldest message stored for the
channel MAY be deleted.
A POST request MUST be replied to with a 201 Created if there were
any long-held subscribers that have been sent this message, and
with a 202 Accepted otherwise.
The Content-Type header of the request MUST be forwarded with the
message.
Message storage limits SHOULD be configurable. publisher locations
SHOULD be configurable to allow foregoing message storage on POST
requests. All 200-level responses MUST, in the response body, contain
information about the applicable channel. This information MAY contain
the number of stored messages and the number of subscribers' requests
being long-held prior to this request. The server MAY implement a
content-negotiation scheme for this information.