A string representing a set of channels id and backtrack desired messages separated by slash, example _/channel1.b3/channel2.b5/channel3.b2_.
The backtrack means the amount of old messages from each of the channels that will be delivered to the subscriber. On the example will be 3 messages from channel1, 5 from channel2 and 2 from channel3.
Backtrack isn't needed, you can only sign channels without get old messages, or you can mix things.
More accepted examples: _/channel1_, _/channel1/channel2_, _/channel1.b5/channel2_, _/channel1/channel2.b6_, ...
|push_stream_max_channel_id_length|unset|number|http, location|(push_stream_subscriber and push_stream_publisher) or main nginx configuration|
|push_stream_broadcast_channel_prefix|unset|any string|http, location|(push_stream_subscriber and push_stream_publisher) or main nginx configuration|
|push_stream_message_template|==~text~==|any string|http, location|(push_stream_subscriber and push_stream_publisher) or main nginx configuration|
|push_stream_max_number_of_channels|unset|number|http, location|(push_stream_subscriber and push_stream_publisher) or main nginx configuration|
|push_stream_max_number_of_broadcast_channels|unset|number|http, location|(push_stream_subscriber and push_stream_publisher) or main nginx configuration|
|push_stream_keepalive|off|on, off|http, location|(push_stream_publisher and push_stream_channels_statistics) or main nginx configuration|
Defines a location as a source of statistics. You can use this location to get statistics about a specific channel, or about all channels, in a resumed ou summarized way.
Defines a location as a source of statistics. You can use this location to get statistics about a specific, group or all channels, in a resumed ou summarized way.
To get statistics about all channels in a summarized way you have to make a GET in this location without specify a name in the push_stream_channel_id variable.
To get statistics about all channels in a detailed way you have to specify "ALL" in the push_stream_channel_id.
To get statistics about prefixed channels in a detailed way you have to specify "_prefix_*" in the push_stream_channel_id.
...
...
@@ -226,22 +244,36 @@ You can get statistics in the formats plain, xml, yaml and json. The default is
h4(#push_stream_publisher). push_stream_publisher
default: normal
context: location
values: normal, admin
Defines a location as a message publisher. Requests to a publisher location are treated as messages to be sent to subscribers.
This location supports two http methods:
This location supports three http methods:
GET, make possible to get statistics about the channel
POST, publish a message to the channel
DELETE, remove any existent stored messages, disconnect any subscriber, and delete the channel. Available only if _admin_ value is used in this directive.
<pre>
<code>
# normal publisher location
location /pub {
push_stream_publisher;
set $push_stream_channel_id $arg_id;
}
# GET /pub?id=channel_id -> get statistics about a channel
# POST /pub?id=channel_id -> publish a message to the channel
# GET /pub?id=channel_id -> get statistics about a channel
# POST /pub?id=channel_id -> publish a message to the channel
# admin publisher location
location /pub_admin {
push_stream_publisher admin;
set $push_stream_channel_id $arg_id;
}
# GET /pub_admin?id=channel_id -> get statistics about a channel
# POST /pub_admin?id=channel_id -> publish a message to the channel
# DELETE /pub_admin?id=channel_id -> delete the channel
h4(#push_stream_shared_memory_cleanup_objects_ttl). push_stream_shared_memory_cleanup_objects_ttl [ time ]
New in version 0.2.6
default: -
context: location
location: push_stream_subscriber
default: 30 seconds
context: http
location: main nginx configuration
The text that will be sended to subscribers before connection is closed (channel deleted ou subscriber timeout).
The length of time a message or a channel will stay on garbage collection area before it is completly discarded, freeing the shared memory. The minimum length is 30 seconds to ensure that no one is using these elements.
This operation is very important to help Nginx recycle memory consumed to create messages and channels, so do not use a large time.
location: (push_stream_subscriber and push_stream_publisher) or main nginx configuration
New in version 0.2.5
default: "Channel deleted"
context: http
location: main nginx configuration
The text template that will be used to format the message before be sended to subscribers. The template can contain any number of the reserved words: ==~id~, ~text~ and ~channel~, example: "<script>p(~id~,'~channel~','~text~');</script>"==
The string used on channel deleted message sent to subscribers when the channel is deleted by a publisher.
The content type used on responses to subscribers. Must be complient with push_stream_header_template, push_stream_message_template and push_stream_footer_template.
The string used on ping message sent to subscribers.
h4(#push_stream_ping_message_interval). push_stream_ping_message_interval [ time ]
h4(#push_stream_message_ttl). push_stream_message_ttl [ time ]
default: -
context: location
location: push_stream_subscriber
The time interval in which a keepalive message is sent to subscribers.
h4(#push_stream_max_messages_stored_per_channel). push_stream_max_messages_stored_per_channel [ number ]
default: 32M
default: -
context: http
location: main nginx configuration
The size of the memory chunk this module will use to store published messages, channels and other shared structures.
When this memory is full any new request for publish a message or subscribe a channel will receive an 500 Internal Server Error response.
The maximum number of messages to store per channel. A channel's message buffer will retain at most this many most recent messages. If you do not want messages to be discarded by length, just not set this directive.
h4(#push_stream_memory_cleanup_timeout). push_stream_memory_cleanup_timeout [ time ]
h4(#push_stream_max_channel_id_length). push_stream_max_channel_id_length [ number ]
default: 30 seconds
default: -
context: http
location: main nginx configuration
The length of time a message or a channel will stay on garbage collection area before it is completly discarded, freeing the shared memory. The minimum length is 30 seconds to ensure that no one is using these elements.
This operation is very important to help Nginx recycle memory consumed to create messages and channels, so do not use a large time.
Maximum permissible channel id length (number of characters). Longer ids will receive an 400 Bad Request response. If you do not want to limit channel id length, just not set this directive.
h4(#push_stream_subscriber_connection_ttl). push_stream_subscriber_connection_ttl [ time ]
New in version 0.2.5
default: ""
default: -
context: http
location: main nginx configuration
The string used on ping message sent to subscribers.
The length of time a subscriber will stay connected before it is considered expired and disconnected. If you do not want subscribers to be automatically disconnected, just not set this directive.
But, this operation is very important to help Nginx recycle memory consumed to send messages to susbscriber, allocated at pool request.
h4(#push_stream_store_messages). push_stream_store_messages [ on | off ]
h4(#push_stream_max_number_of_channels). push_stream_max_number_of_channels [ number ]
default: off
context: location
location: push_stream_publisher
default: -
context: http
location: main nginx configuration
Whether or not message queuing is enabled.
If store messages is "On" is needed to set at least one of these two directives push_stream_min_message_buffer_timeout or push_stream_max_message_buffer_length.
The maximum number of concurrent channels on the server. If you do not want to limit the number of channels, just not set this directive.
h4(#push_stream_min_message_buffer_timeout). push_stream_min_message_buffer_timeout [ time ]
h4(#push_stream_max_number_of_broadcast_channels). push_stream_max_number_of_broadcast_channels [ number ]
default: -
context: location
location: push_stream_publisher
context: http
location: main nginx configuration
The length of time a message may be queued before it is considered expired. If you do not want messages to expire, just not set this directive.
The maximum number of concurrent broadcats channels on the server. If you do not want to limit the number of broadcast channels, just not set this directive.
h4(#push_stream_max_message_buffer_length). push_stream_max_message_buffer_length [ number ]
The string prefix used to identify when a channel is a normal or broadcast channel, example: when you set this directive as "bd_", "bd_ch1" will be a broadcast channel
h4(#push_stream_store_messages). push_stream_store_messages [ on | off ]
default: off
context: location
location: push_stream_publisher
The maximum number of messages to store per channel. A channel's message buffer will retain at most this many most recent messages. If you do not want messages to be discarded by length, just not set this directive.
h3(#security). Security
Whether or not message queuing is enabled.
If store messages is "on" is needed to set at least one of these two directives push_stream_message_ttl or push_stream_max_messages_stored_per_channel.
h4(#push_stream_authorized_channels_only). push_stream_authorized_channels_only [ on | off ]
Whether or not a subscriber may create a channel by making a request to a push_stream_subscriber location. If set to on, a publisher must send a POST request before a subscriber can request messages on the channel. Otherwise, all subscriber requests to nonexistent channels will get a 403 Forbidden response.
This restriction is not applied to broadcast channels, but to subscribe to a broadcast channel is necessary to subscribe at least to one normal channel, and if this directive is set to on this channel has to be created before.
h4(#push_stream_subscriber_connection_timeout). push_stream_subscriber_connection_timeout [ time ]
The length of time a subscriber will stay connected before it is considered expired and disconnected. If you do not want subscribers to be automatically disconnected, just not set this directive.
But, this operation is very important to help Nginx recycle memory consumed to send messages to susbscriber, allocated at pool request.
h4(#push_stream_max_channel_id_length). push_stream_max_channel_id_length [ number ]
default: -
context: location
location: (push_stream_subscriber and push_stream_publisher) or main nginx configuration
Maximum permissible channel id length (number of characters). Longer ids will receive an 400 Bad Request response.
The text that will be sended to subscribers when they arrive.
location: (push_stream_subscriber and push_stream_publisher) or main nginx configuration
location: push_stream_subscriber
The string prefix used to identify when a channel is as normal or broadcast channel, example: when you set this directive as "bd_", "bd_ch1" will be a broadcast channel
The text template that will be used to format the message before be sended to subscribers. The template can contain any number of the reserved words: ==~id~, ~text~, ~channel~ and ~event-id~, example: "<script>p(~id~,'~channel~','~text~');</script>"==
h4(#push_stream_broadcast_channel_max_qtd). push_stream_broadcast_channel_max_qtd [ number ]
location: (push_stream_subscriber and push_stream_publisher) or main nginx configuration
location: push_stream_subscriber
The maximum number of broadcast channels that a subscriber may sign on the request.
This directive works in conjunction with push_stream_authorized_channels_only to preserve the server from a kind of attack where a subscriber sign one normal channel and many nonexistent broadcast channels.
The text that will be sended to subscribers before connection is closed (channel deleted ou subscriber timeout).
h4(#push_stream_max_number_of_channels). push_stream_max_number_of_channels [ number ]
location: (push_stream_subscriber and push_stream_publisher) or main nginx configuration
location: push_stream_subscriber
The maximum number of concurrent channels on the server. If you do not want to limit the number of channels, just not set this directive.
The content type used on responses to subscribers. Must be complient with push_stream_header_template, push_stream_message_template and push_stream_footer_template.
h4(#push_stream_max_number_of_broadcast_channels). push_stream_max_number_of_broadcast_channels [ number ]
h4(#push_stream_broadcast_channel_max_qtd). push_stream_broadcast_channel_max_qtd [ number ]
default: -
context: location
location: (push_stream_subscriber and push_stream_publisher) or main nginx configuration
location: push_stream_subscriber
The maximum number of concurrent broadcats channels on the server. If you do not want to limit the number of broadcast channels, just not set this directive.
The maximum number of broadcast channels that a subscriber may sign on the request.
This directive works in conjunction with push_stream_authorized_channels_only to preserve the server from a kind of attack where a subscriber sign one normal channel and many nonexistent broadcast channels.
h4(#push_stream_keepalive). push_stream_keepalive [ on | off ]
New in version 0.2.4
default: off
context: http, location
location: (push_stream_publisher and push_stream_channels_statistics) or main nginx configuration
Enable "Event Source":eventsource support for subscribers.
h2(#attention). Attention
...
...
@@ -509,6 +519,7 @@ To run them is needed to have an environment with:
** em-http-request >= 0.2.14
** json >= 1.4.3
** ruby-debug >= 0.10.4
** jasmine >= 1.0.2.1
You can install these gems with bundler (bundler is required to be installed before, _gem install bundler_)
...
...
@@ -527,23 +538,24 @@ gem install POpen4 -v 0.1.4
gem install em-http-request -v 0.2.14
gem install json -v 1.4.3
gem install ruby-debug -v 0.10.4
gem install jasmine -v 1.0.2.1
</code>
</pre>
Then issue <code>rake tests</code>.
Then issue @rake tests@.
This command run the tests using nginx *executable* located at _/usr/local/nginx/sbin/nginx_ with _1_ *worker* responding at *host* _localhost_ and *port* _9990_.
To change this behavior use the commands bellow
<pre>
<code>
rake tests executable="../build/nginx-1.0.0/objs/nginx" # to change default path for nginx executable
rake tests host=localhost # to change default hostname
rake tests executable="../build/nginx-1.0.5/objs/nginx" # to change default path for nginx executable
rake tests host=my_machine # to change default hostname
rake tests port=9889 # to change default port
rake tests workers=2 # to change dafault number of workers used
ngx_conf_log_error(NGX_LOG_ERR,cf,0,"memory cleanup objects ttl cannot't be less than %d.",NGX_HTTP_PUSH_STREAM_DEFAULT_SHM_MEMORY_CLEANUP_OBJECTS_TTL);
