Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

slatcs readme

  • Loading branch information...
commit 12c040cade29f20282399c4f056a3e4a01971bce 1 parent c476b2e
@rsms authored
Showing with 174 additions and 227 deletions.
  1. +174 −227 README
View
401 README
@@ -1,234 +1,181 @@
-# Nginx HTTP push module
-
-Turn nginx into a _long-polling push_ server that relays messages.
-
-If you want a long-polling server but don't want to wait on idle connections
-via upstream proxies, 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.
-
-## Example config
-
- http {
- # Sending
- server {
- listen localhost:8089;
- location / {
- default_type text/plain;
- set $push_id $arg_channel; #/?channel=a or somesuch
- push_sender;
- push_message_timeout 2h; #buffered messages expire after 2 hours
- }
- }
-
- # Receiving
- server {
- listen 8088;
- location / {
- default_type text/plain;
- set $push_id $arg_channel; #/?channel=a or somesuch
- push_listener;
- }
- }
- }
-
-See section "Alternative example config" further down for a simpler example
-where no distinction or security is needed for posting messages.
-
-## Practical example
-
-_This assumes you have built nginx with this module._
-
-First time we need to create nginx log files or it will cry like a little baby:
-
- $ mkdir -p logs
- $ touch logs/access.log logs/error.log
-
-Now, lets start nginx with the example configuration (nginx.conf). `cd` to the
-directory of this module's source and:
-
- $ nginx -c nginx.conf -p `pwd`/
-
-_Note that nginx will stay in foreground (daemon set to off in nginx.conf)_
-
-In a new terminal, listen for a message:
-
- $ curl localhost:8088/?channel=a
-
-In another new terminal, send a message:
-
- $ curl -d 'hello' localhost:8089/?channel=a
-
-You can try to launch several listeners on the same channel and broadcast
-a message to them.
-
-
-## Configuration directives & variables
-
-### Directives
-
-#### `push_sender`
-
- push_sender
- default: none
- context: server, location
-
-Defines a server or location as the sender. Requests from a sender will be
-treated as messages to send to listeners.See protocol documentation
-for more info.
-
-#### `push_listener`
-
- push_listener
- default: none
- context: server, location
-
-Defines a server or location as a listener. Requests from a listener will
-not be responded to until a message for the listener (identified by
-$push_id) becomes available. See protocol documentation for more info.
-
-#### `push_listener_concurrency`
-
- push_listener_concurrency last | broadcast
- default: last
- context: http, server, location
+NGiNX HTTP push module - Turn NGiNX into an adept HTTP Push (Comet) server.
+
+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 ------------------------
+Variables:
+$push_channel_id
+ 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 query string parameter "id"
+ #(/foo/bar?id=channel_id_string)
+
+Directives:
+
+==Publisher/Subscriber==
+
+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), 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: broadcast
+ context: http, server, location
+ Controls how multiple subscriber requests to a channel (identified by
+ some common ID) are handled.
+ The values work as follows:
+ - 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 ==
+
+push_store_messages [ on | off ]
+ default: on
+ context: http, server, location
+ Whether or not message queuing is enabled. "Off" is equivalent to the setting
+ push_channel_buffer_length 0;
+
+push_max_reserved_memory [ size ]
+ default: 16M
+ context: http
+ The size of the memory chunk this module will use for all message queuing
+ and buffering.
+
+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 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 retain at most this many most recent messages.
+
+push_message_buffer_length [ number ]
+ default: none
+ context: http, server, location
+ The exact number of messages to store per channel. Sets both
+ push_max_message_buffer_length and push_min_message_buffer_length to this
+ value.
-Controls how listeners to the same channel id are handled. If `last` (default) is set, only the most recently connected listener to a channel will receive a message. If the value is set to `broadcast` all listeners to a channel will receive a message.
-
-#### `push_queue_messages`
-
- push_queue_messages on | off
- default: on
- context: http, server, location
-
-Whether or not message queuing is enabled. If set to off, messages will be
-delivered only if a push_listener connection is already present for the id.
-Applicable only if a push_sender is present in this or a child context.
-
-#### `push_message_timeout`
-
- 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_sender
-is present in this or a child context.
-
-#### `push_buffer_size`
-
- push_buffer_size <size>
- default: 3M
- context: http
-
-The size of the memory chunk this module will use for all message queuing
-and buffering.
-
-
-### Variables
-
-#### `$push_id`
-
-The channel id associated with a `push_listener` or `push_sender`. Must be present next
-to said directives.
-
-Identifies the channel of communication:
-
- sender
- ||
- ||
- [message]
- ||
- \/
- ----------------------
- channel {$push_id}
- ----------------------
- || || ||
- \/ || \/
- listener || listener
- \/
- listener
-
-Config example:
-
- set $push_id $arg_id #$push_id is now the url parameter "id"
-
-
-## Operation
-
-Assuming the example config given above:
-Clients will `GET http://example.com:8088/?id=...` and have the
-response delayed until a message is `POST`ed to `http://localhost:8089/?id=...`
+push_min_message_recipients [ number ]
+ default: 0
+ context: http, server, location
+ 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_message_timeout [ time ]
+ default: 1h
+ context: http, server, location
+ 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 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
+ 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.
+
+push_max_channel_id_length [ number ]
+ default: 512
+ context: main, server, location
+ Maximum permissible channel id length (number of characters).
+ Longer ids will be truncated.
+
+--------------------------- Example Config -----------------------------------
+http {
+ #maximum amount of memory the push module is allowed to use
+ #for buffering and stuff
+ push_max_reserved_memory 12M; #default is 3M
+
+ # internal publish endpoint (keep it private / protected)
+ location /publish {
+ set $push_channel_id $arg_channel; #/?channel=239aff3 or some-such
+ push_publisher;
+
+ push_message_timeout 2h; # expire buffered messages after 2 hours
+ push_max_message_buffer_length 10; # store absolutely at most 10 messages
+ push_min_message_recipients 0; # minimum recipients before purge
+ }
+
+ # public long-polling endpoint
+ location /activity {
+ push_subscriber;
+
+ # how multiple subscriber requests to the same channel id are handled
+ # - last: only the most recent subscriber request is kept, 409 for others.
+ # - first: only the oldest subscriber request is kept, 409 for others.
+ # - broadcast: any number of subscriber requests may be long-polling.
+ push_subscriber_concurrency broadcast;
+ set $push_channel_id $arg_channel; #/?channel=239aff3 or some-such
+ default_type text/plain;
+ }
+}
+
+---------------------------- Operation ---------------------------------------
+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_sender` 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_listener` with this id is 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 indend to have the `push_sender` be a server-side application,
-it's a damn good idea to make sure the `push_server` location is not visible
-publically, as it is intended for use only by your application.
-
-
-## Building & Installation
-
-Configure and build nginx with this module. Example:
-
- $ ./configure --add-module=path/to/nginx_http_push_module
- $ make
-
-
-## "Protocol" spec
-
-See [queuing-long-poll-relay-protocol](http://wiki.github.com/slact/nginx_http_push_module/queuing-long-poll-relay-protocol)
-
-
-## Todo
-
-- Add "first" (first in gets the message) functionality/switch to
- `push_listener_concurrency` (see prepared code in `ngx_http_push_listener_handler`)
-
-- Add other mechanisms of server pushing. The list should include
- "long-poll" (default), "interval-poll".
-
-- Add a `push_accomodate_strangers` setting (presently defaulting to on).
- When set to off, requests with a previously-unseen `$push_id`
- will be rejected.
-
-- When `POST`ing to `push_server`, if Content-Type is "message/http", the
- response sent to `$push_id` should be created from the body of the request.
-
-
-## License
-
-This software is licensed under MIT.
-
-See details in the file `LICENSE`.
-
-
-## Note on this branch of the source
-
-This branch was intially created by Rasmus Andersson who introduced concurrent
-listeners (broadcasting).
-
-
-## Alternative example config
+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.
-If there is no need for network-level security to protect sending/posting of
-messages, you can use the same server for sending and listening:
+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.)
- http {
- server {
- listen localhost:8088;
- default_type text/plain;
- location /send {
- set $push_id $arg_channel; #/?channel=a or somesuch
- push_sender;
- }
- location /listen {
- set $push_id $arg_channel; #/?channel=a or somesuch
- push_listener;
- }
- }
- }
+----------------------- Protocol Spec --------------------------------------
+This module is unconditionally (fully) compliant with the Basic HTTP Push
+Relay Protocol, Rev. 2.21, found in the file protocol.txt.
Please sign in to comment.
Something went wrong with that request. Please try again.