Permalink
Browse files

readme improvements

  • Loading branch information...
1 parent 8f994cd commit e171fe730e9d66689ee954bcb594586008002fba @slact committed Nov 6, 2009
Showing with 61 additions and 54 deletions.
  1. +60 −53 README
  2. +1 −1 protocol.txt
View
113 README
@@ -1,51 +1,53 @@
-Nginx HTTP push module - Turn nginx into a long-polling message queuing
-HTTP push server.
+NGiNX HTTP push module - Turn NGiNX into an adept HTTP Push (Comet) server.
-If you want a long-polling server but don't want to wait on idle connections
-via upstream proxies or make your applications totally asynchronous, use
-this module to have nginx accept and hold long-polling client connections.
-Send responses to those clients by sending an HTTP request to a different
-location.
+This module takes care of all the connection juggling, and exposes a simple
+interface to broadcast messages to clients via plain old HTTP requests.
+This makes it possible to write live-updating applications without having to
+wait on idle connections via upstream proxies or making your code all
+asynchronous and concurrent.
----------------- Configuration directives & variables ------------------------
+---------------- Configuration Directives & Variables ------------------------
Variables:
$push_channel_id
- A token uniquely identifying a channel. Must be present in the context of
- the push_subscriber and push_publisher directives.
+ A token uniquely identifying a communication channel. Must be present in the
+ context of the push_subscriber and push_publisher directives.
Example:
- set $push_channel_id $arg_id; #channel id is now the url parameter "id"
- (/foo/bar?id=channel_id_string)
+ set $push_channel_id $arg_id;
+ #channel id is now the url query string parameter "id"
+ #(/foo/bar?id=channel_id_string)
Directives:
==Publisher/Subscriber==
-push_publisher
- default: none
- context: server, location
- Defines a server or location as the publisher. Requests from a publisher will be
- treated as messages to send to subscribers. See protocol documentation
- for more info.
-
push_subscriber [ long-poll | interval-poll ]
default: long-poll
context: server, location
Defines a server or location as a subscriber. This location represents a
subscriber's interface to a channel's message queue. The queue is traversed
automatically via caching information request headers (If-Modified-Since and
- If-None-Match). Requests for future messages are handles in accordance with
- the setting provided. See protocol documentation for more info.
+ If-None-Match), beginning with the oldest available message. Requests for
+ upcoming messages are handled in accordance with the setting provided.
+ See the protocol documentation for a detailed description.
push_subscriber_concurrency [ last | first | broadcast ]
default: last
context: http, server, location
- Controls how multiple subscriber requests to the same channel id are handled.
+ Controls how multiple subscriber requests to a channel (identified by
+ some common ID) are handled.
The values work as follows:
- broadcast: any number of subscriber requests may be long-polling.
- last: only the most recent subscriber request is kept, all others get a 409
- Conflict response.
- first: only the oldest subscriber request is kept, all others get a 409
- Conflict response.
+ - broadcast: any number of concurrent subscriber requests may be held.
+ - last: only the most recent subscriber request is kept, all others get
+ a 409 Conflict response.
+ - first: only the oldest subscriber request is kept, all others get a
+ 409 Conflict response.
+
+push_publisher
+ default: none
+ context: server, location
+ Defines a server or location as a message publisher. Requests to a publisher
+ location are treated as messages to be sent to subscribers. See the protocol
+ documentation for a detailed description.
== Message storage ==
@@ -65,42 +67,43 @@ push_min_message_buffer_length [ number ]
default: 1
context: http, server, location
The minimum number of messages to store per channel. A channel's message
- buffer, will contain at least this many most recent messages.
+ buffer will retain at least this many most recent messages.
push_max_message_buffer_length [ number ]
default: 10
context: http, server, location
The maximum number of messages to store per channel. A channel's message
- buffer, will contain at most this many most recent messages.
+ buffer will retain at most this many most recent messages.
push_min_message_recipients [ number ]
default: 0
context: http, server, location
- How many times a message must be received before it is considered for
+ The number of times a message must be received before it is considered for
deletion. Useful to guarantee message delivery. (This does NOT override the
- push_max_message_buffer_length setting.
+ push_max_message_buffer_length setting).
push_message_timeout [ time ]
default: 1h
context: http, server, location
- How long a message may be queued before it is considered expired. If you do
- not want messages to expire, set this to 0. Applicable only if a push_publisher
- is present in this or a child context.
+ The length of time a message may be queued before it is considered expired.
+ If you do not want messages to expire, set this to 0. Applicable only if a
+ push_publisher is present in this or a child context.
== Security ==
push_authorized_channels_only [ on | off ]
default: off
context: http, server, location
Whether or not a subscriber may create a channel by making a request to a
- push_subscriber location. If set to on, a publisher must send a request
- to some channel (POST or PUT) before a subscriber. Otherwise, all subscriber
- requests to nonexistent channels will get a 403 Forbidden response.
+ push_subscriber location. If set to on, a publisher must send a POST or PUT
+ request before a subscriber can request messages on the channel. Otherwise,
+ all subscriber requests to nonexistent channels will get a 403 Forbidden
+ response.
push_channel_group [ string ]
default: (none)
context: server, location
- As settings are bound to locations and urls instead of individual channels,
+ Because settings are bound to locations and not individual channels,
it is useful to be able to have channels that can be reached only from some
locations and never others. That's where this setting comes in. Think of it
as a prefix string for the channel id.
@@ -142,26 +145,30 @@ http {
}
---------------------------- Operation ---------------------------------------
-Assuming the example config given above:
+The following describes what is likely to be the most commonly desired setup:
+
+Assuming the example config given above,
Clients will connect to http://example.com/activity?id=... and have the
response delayed until a message is POSTed to http://example.com/publish?id=...
Messages can be sent to clients that have not yet connected, i.e. they are
queued.
-Upon sending a request to a push_publisher location, the server will respond with
-a 201 Created if the message has been sent. If it must be queued up (i.e. the
-push_subscriber with this id is not presently connected), a 202 Accepted will be sent.
+Upon sending a request to a push_publisher location, the message, contained in
+the publisher request body, will be sent to the channel identified by
+$push_channel_id and to all presently connected channel subscribers. If there
+are no subscribers waiting for a message at the time, the publisher will be
+sent to with a with a 202 Accepted response. Otherwise, a 201 Created response
+is sent. Additionally, the body of the publisher response will contain
+information about the channel (number of current subscribers, message queue
+length, etc).
-If you intend to have the publisher be a server-side application,
-it's a damn good idea to make sure the push_publisher location is not visible
-publicly, as it is intended for use only by your application.
-
-Traversal through the message buffer by a subscriber requires proper caching
-support. Make sure your client correctly sends Last-Modified and Etag headers.
-(All modern web browsers do this.)
+If you intend to have the publisher be a server-side application, it's a damn
+good idea to make sure the push_publisher location is not publicly accessible.
------------------------ Protocol spec --------------------------------------
-see the file protocol.txt
+Traversal through a channel's message buffer by a subscriber requires proper
+HTTP caching support from the subscriber client. Make sure it correctly sends
+Last-Modified and Etag headers. (All modern web browsers do this.)
----------------------------- todo --------------------------------------------
-- Memcached message storage
+----------------------- Protocol Spec --------------------------------------
+This module is unconditionally (fully) compliant with the Basic HTTP Push
+Relay Protocol, Rev. 2.21, found in the file protocol.txt.
View
2 protocol.txt
@@ -1,4 +1,4 @@
-Simplish HTTP Push Relay Protocol, Rev. 2.2
+Basic HTTP Push Relay Protocol, Rev. 2.21
1. Introduction
1.1 Purpose

0 comments on commit e171fe7

Please sign in to comment.