Permalink
Browse files

deprecated deprecation, rename message buffer size setting

  • Loading branch information...
1 parent 733ec77 commit 7828a9ea621c05abe4973a3bc8ddf46fbbd2a3aa @slact committed Oct 8, 2009
Showing with 68 additions and 58 deletions.
  1. +57 −47 README
  2. +11 −11 src/ngx_http_push_module_setup.c
View
104 README
@@ -1,65 +1,27 @@
-Nginx HTTP push module - Turn nginx into a long-polling push server that
-relays messages.
+Nginx HTTP push module - Turn nginx into a long-polling message queuing
+HTTP push server.
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 {
- #maximum amount of memory the push module is allowed to use
- #for buffering and stuff
- push_buffer_size 12M; #default is 3M
-
- #sender
- server {
- listen localhost:8089;
- location / {
- default_type text/plain;
- set $push_id $arg_id; #/?id=239aff3 or somesuch
- push_sender;
- push_message_timeout 2h; #buffered messages expire after 2 hours
- }
- }
-
- #receiver
- server {
- listen 8088;
- location / {
- default_type text/plain;
- set $push_id $arg_id; #/?id=239aff3 or somesuch
- push_listener;
- }
- }
-}
+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.
---------------- Configuration directives & variables ------------------------
directives:
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
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_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_id) becomes available. See protocol documentation for more info.
push_message_timeout [ time ]
default: 1h
@@ -68,19 +30,64 @@ push_message_timeout [ time ]
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 [ size ]
+push_max_reserved_memory [ size ]
default: 3M
context: http
- The size of the memory chunk this module will use for all message queuing
+ The size of the memory chunk this module will use for all message queuing
and buffering.
+push_message_buffer_length [ number ]
+ default: 5
+ context: http, server, location
+ The maximum number of messages to store per channel. Old messages are removed
+ when a channel's message buffer length exceeds this setting. Set to 0 to
+ disable buffering.
+
+The following directives are DEPRECATED. They will be respected,
+but may not be around for very long.
+
+push_queue_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;
+
Variables:
$push_id
The id associated with a push_listener or push_sender. Must be present next
to said directives.
Example:
set $push_id $arg_id #$push_id is now the url parameter "id"
+--------------------------- Example Config -----------------------------------
+http {
+ #maximum amount of memory the push module is allowed to use
+ #for buffering and stuff
+ push_buffer_size 12M; #default is 3M
+
+ #sender
+ server {
+ listen localhost:8089;
+ location / {
+ default_type text/plain;
+ set $push_id $arg_id; #/?id=239aff3 or somesuch
+ push_sender;
+ push_message_timeout 2h; #buffered messages expire after 2 hours
+ push_message_buffer_length 10; #store 10 messages.
+ }
+ }
+
+ #receiver
+ server {
+ listen 8088;
+ location / {
+ default_type text/plain;
+ set $push_id $arg_id; #/?id=239aff3 or somesuch
+ push_listener;
+ }
+ }
+}
+
---------------------------- Operation ---------------------------------------
Assuming the example config given above:
Clients will connect to http://example.com:8088/?id=... and have the
@@ -96,6 +103,9 @@ 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.
+Traversal through the message buffer by a listener requires proper caching
+support. Make sure your client correctly send Last-Modified and ETag headers.
+
----------------------- "Protocol" spec --------------------------------------
see http://wiki.github.com/slact/nginx_http_push_module/queuing-long-poll-relay-protocol
@@ -14,15 +14,7 @@ static ngx_command_t ngx_http_push_commands[] = {
offsetof(ngx_http_push_main_conf_t, shm_size),
NULL },
- //deprecated and misleading. remove no earlier than november 2009.
- { ngx_string("push_max_buffer_size"),
- NGX_HTTP_MAIN_CONF|NGX_CONF_TAKE1,
- ngx_conf_set_size_slot,
- NGX_HTTP_MAIN_CONF_OFFSET,
- offsetof(ngx_http_push_main_conf_t, shm_size),
- NULL },
-
- { ngx_string("push_channel_buffer_length"),
+ { ngx_string("push_message_buffer_length"),
NGX_HTTP_MAIN_CONF|NGX_CONF_TAKE1,
ngx_conf_set_num_slot,
NGX_HTTP_LOC_CONF_OFFSET,
@@ -42,7 +34,15 @@ static ngx_command_t ngx_http_push_commands[] = {
NGX_HTTP_LOC_CONF_OFFSET,
0,
NULL },
-
+
+ //deprecated and misleading. remove no earlier than november 2009.
+ { ngx_string("push_buffer_size"),
+ NGX_HTTP_MAIN_CONF|NGX_CONF_TAKE1,
+ ngx_conf_set_size_slot,
+ NGX_HTTP_MAIN_CONF_OFFSET,
+ offsetof(ngx_http_push_main_conf_t, shm_size),
+ NULL },
+
ngx_null_command
};
@@ -168,7 +168,7 @@ static char *ngx_http_push_setup_handler(ngx_conf_t *cf, void * conf, ngx_int_t
plcf->index = ngx_http_get_variable_index(cf, &ngx_http_push_id);
if (plcf->index == NGX_ERROR) {
return NGX_CONF_ERROR;
- }
+ }
return NGX_CONF_OK;
}

0 comments on commit 7828a9e

Please sign in to comment.