Skip to content
This repository
Newer
Older
100644 82 lines (63 sloc) 3.364 kb
6404eb24 »
2009-08-10 info
1 Nginx push module - redirect a request body to other waiting requests
2
3 If you want a long-polling server but don't want to wait on idle connections
4 via upstream proxies, use this module to have nginx accept client connections.
5 Communication with clients is done via a different location, one only accessible
6 to your application.
7
8 Example conf:
9
10 #message source server
11 server {
12 listen localhost:8089;
13 location / {
14 default_type text/plain;
15 set $push_id $arg_id; #/?id=239aff3 or somesuch
16 push_source;
17 }
18 }
19
20 #long-polling client server
21 server {
22 listen 8088;
23 location / {
24 default_type text/plain;
25 set $push_id $arg_id; #/?id=239aff3 or somesuch
26 push_destination;
27 }
28 }
29
30 Clients will connect to http://example.com:8088/?id=... and have the
31 response delayed until a message is POSTed to http://localhost:8089/?id=...
32 Messages can be sent to clients that have not yet connected, i.e. they are queued.
33
97c3e493 »
2009-08-10 elaborate.
34 Upon sending a request to a push_source location, the server will respond with
35 a 201 Created if the message has been sent. If it must be queued up (i.e. the
36 destination id is presently connected), a 202 Accepted will be sent.
37
38 ---- ---
39
6404eb24 »
2009-08-10 info
40 It's a damn good idea to make sure the push_source location is not visible
97c3e493 »
2009-08-10 elaborate.
41 publically, as it is intended for use only by your application.
885051f4 »
2009-08-12 clarified the protocol, added a todo
42
43 --- "Protocol" spec ---
44
45 Let push_source refer to a location (or server) configured with the push_source; option.
46 Let push_destination refer to a location (or server) configured with the push_destination; option.
47
48 push_destination:
49 Only POST requests are allowed to this location. The response will be delayed until a message
50 for the $push_id of said requests becomes available, at which point its contents will be sent
51 in the body of the response with a 200 OK status code.
52
53 When two requests to this location have the same $push_id, messages will be delivered to the
54 newer of the two. The older request receives an immediate response with a 409 Conflict status
55 code.
56
57 push_source:
58 POST, PUT, and DELETE requests are allowed at this location.
59 A POST request will have its body ("the message"), treated as plaintext (text/plain) sent to
60 the request identified by $push_id. If no such request exists, the message will be queued
61 until it can be sent. Multiple messages can be queued, and will be received in a FILO order.
62 When the request results in an immediate sending of the message (i.e. there was a waiting
63 request identified by $push_id), the response will have a 201 Created status. If the message
64 is queued, a 202 Accepted status is sent back.
65
66 (NOT IMPLEMENTED YET) Requesting a PUT notifies the server to expect connections from
67 $push_id.
68
69 (NOT IMPLEMENTED YET) a DELETE deletes all messages intended for $push_id. If there is a waiting
70 request on push_destination identified by $push_id, it will be immediately responded to with a
71 204 No Content status code.
72
73 -----------------------------
74
75 TODO:
76 - Implelent DELETE for push_source.
77 - Add a push_accomodate_strangers setting (presently defaulting to on). When set to off, requests
78 with a previously-unseen $push_id will be rejected.
79 - When POSTing to push_source, if Content-Type is "message/http", the response sent to $push_id
80 should be created from the body of the request.
81
Something went wrong with that request. Please try again.