h1(#subscribers_configuration). Subscribers Configuration

h2(#push_stream_subscriber). push_stream_subscriber <a name="push_stream_subscriber" href="#">&nbsp;</a>

*syntax:* _push_stream_subscriber [streaming | polling | long-polling | eventsource | websocket]_

*default:* _streaming_

*context:* _location_

Defines a location as a subscriber. This location represents a subscriber's interface to a channel's message queue.
This location only supports GET http method to receive published messages.
The polling and long-polling modes could be set by the request header *X-Nginx-PushStream-Mode* overriding push_stream_subscriber directive value, except for websocket.
The eventsource mode enable "Event Source":eventsource_ref support for subscribers, using the headers Event-ID and Event-Type on publish is possible to set values to _id:_ and _event:_ attributes on message sent to subscribers.
The websocket mode enable subscriber to use WebSocket protocol.


<pre>
  # streaming subscriber location
  location /sub/(.*) {
      push_stream_subscriber;
      # positional channel path
      push_stream_channels_path                   $1;
  }

  curl -s --no-buffer localhost/sub/ch1 -H 'X-Nginx-PushStream-Mode:polling'      #polling request on a streaming location
  curl -s --no-buffer localhost/sub/ch1 -H 'X-Nginx-PushStream-Mode:long-polling' #long-polling request on a streaming location

  # polling subscriber location
  location /sub/(.*) {
      push_stream_subscriber                      polling;
      # positional channel path
      push_stream_channels_path                   $1;
  }

  curl -s --no-buffer localhost/sub/ch1                                           #polling request
  curl -s --no-buffer localhost/sub/ch1 -H 'X-Nginx-PushStream-Mode:long-polling' #long-polling request on a polling location

  # long polling subscriber location
  location /sub/(.*) {
      push_stream_subscriber                      long-polling;
      # positional channel path
      push_stream_channels_path                   $1;
  }

  curl -s --no-buffer localhost/sub/ch1                                           #long-polling request
  curl -s --no-buffer localhost/sub/ch1 -H 'X-Nginx-PushStream-Mode:polling'      #polling request on a logn-polling location

  # eventsource subscriber location
  location /sub/(.*) {
      push_stream_subscriber                      eventsource;
      # positional channel path
      push_stream_channels_path                   $1;
  }

  curl -s --no-buffer localhost/sub/ch1                                           #eventsource request

  # eventsource subscriber location
  location /sub/(.*) {
      push_stream_subscriber                      websocket;
      # positional channel path
      push_stream_channels_path                   $1;
  }
</pre>


h2(#push_stream_channels_path). push_stream_channels_path <a name="push_stream_channels_path" href="#">&nbsp;</a>

*values:* _set of channels id and backtrack desired messages_

*location:* _push_stream_subscriber_

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_ , ...

"*How is it used on a publisher location?*":push_stream_channels_path

<pre>
location /sub/(.*) {
  push_stream_channels_path $1;
}
#channels path is now part of url
#(/sub/channel_id_string or /sub/channel_id_string.b2/other_channel)
</pre>


h2(#push_stream_authorized_channels_only). push_stream_authorized_channels_only <a name="push_stream_authorized_channels_only" href="#">&nbsp;</a>

*syntax:* _push_stream_authorized_channels_only on | off_

*default:* _off_

*context:* _location (push_stream_subscriber)_

When set to on, subscribers can connect only to a channel with at least one stored message.
All subscriber requests to nonexistent channels or channels without stored messages will get a 403 Forbidden response.
This restriction is not applied to wildcard channels, but to connect to a wildcard channel is necessary to connect to at least one normal channel on the same request.


h2(#push_stream_header_template_file). push_stream_header_template_file <a name="push_stream_header_template_file" href="#">&nbsp;</a>

*syntax:* _push_stream_header_template_file string_

*default:* _none_

*context:* _location (push_stream_subscriber)_

The path of a file with the text that will be sent to subscribers when they arrive, except when long polling connections timed out.
The file is read only once on server startup.
Must not be used on the same level (http/server/location block) of push_stream_header_template directive.


h2(#push_stream_header_template). push_stream_header_template <a name="push_stream_header_template" href="#">&nbsp;</a>

*syntax:* _push_stream_header_template string_

*default:* _none_

*context:* _location (push_stream_subscriber)_

The text that will be sent to subscribers when they arrive, except when long polling connections timed out.
Must not be used on the same level (http/server/location block) of push_stream_header_template_file directive.


h2(#push_stream_message_template). push_stream_message_template <a name="push_stream_message_template" href="#">&nbsp;</a>

*syntax:* _push_stream_message_template string_

*default:* _==~text~==_

*context:* _location (push_stream_subscriber)_

The text template that will be used to format the message before be sent to subscribers. The template can contain any number of the reserved words: ==~id~, ~text~, ~size~, ~channel~, ~time~, ~tag~, ~event-id~ and ~event-type~, example: "&lt;script&gt;p(~id~,'~channel~','~text~', ~tag~, '~time~');&lt;/script&gt;"==


h2(#push_stream_footer_template). push_stream_footer_template <a name="push_stream_footer_template" href="#">&nbsp;</a>

*syntax:* _push_stream_footer_template string_

*default:* _none_

*context:* _location (push_stream_subscriber)_

*release version:* _0.2.6_

The text that will be sent to subscribers before connection is closed (channel deleted or subscriber timeout), except when long polling connections timed out.


h2(#push_stream_wildcard_channel_max_qtd). push_stream_wildcard_channel_max_qtd <a name="push_stream_wildcard_channel_max_qtd" href="#">&nbsp;</a>

*syntax:* _push_stream_wildcard_channel_max_qtd number_

*default:* _none_

*context:* _location (push_stream_subscriber)_

The maximum number of wildcard channels that a subscriber may sign on the request.
This directive works in conjunction with "push_stream_authorized_channels_only":push_stream_authorized_channels_only to preserve the server from a kind of attack where a subscriber sign one normal channel and many nonexistent wildcard channels.


h2(#push_stream_ping_message_interval). push_stream_ping_message_interval <a name="push_stream_ping_message_interval" href="#">&nbsp;</a>

*syntax:* _push_stream_ping_message_interval time_

*default:* _none_

*context:* _location (push_stream_subscriber)_

The time interval in which a keepalive message is sent to subscribers. If you do not want to send ping messages, just not set this directive.


h2(#push_stream_subscriber_connection_ttl). push_stream_subscriber_connection_ttl <a name="push_stream_subscriber_connection_ttl" href="#">&nbsp;</a>

*syntax:* _push_stream_subscriber_connection_ttl time_

*default:* _none_

*context:* _location (push_stream_subscriber)_

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.


h2(#push_stream_longpolling_connection_ttl). push_stream_longpolling_connection_ttl <a name="push_stream_longpolling_connection_ttl" href="#">&nbsp;</a>

*syntax:* _push_stream_longpolling_connection_ttl time_

*default:* _value in push_stream_subscriber_connection_ttl_

*context:* _location (push_stream_subscriber)_

*release version:* _0.3.1_

The length of time a long polling subscriber will stay connected waiting for a message before it is disconnected. If you do not want subscribers to be automatically disconnected, just not set this directive and push_stream_longpolling_connection_ttl directive.


h2(#push_stream_timeout_with_body). push_stream_timeout_with_body <a name="push_stream_timeout_with_body" href="#">&nbsp;</a>

*syntax:* _push_stream_timeout_with_body on | off_

*default:* _off_

*context:* _location (push_stream_subscriber)_

*release version:* _0.4.0_

When set to on will send a http 200 message indicating that a timeout happens on long polling connections instead of send only a http 304 header.


h2(#push_stream_websocket_allow_publish). push_stream_websocket_allow_publish <a name="push_stream_websocket_allow_publish" href="#">&nbsp;</a>

*syntax:* _push_stream_websocket_allow_publish on | off_

*default:* _off_

*context:* _location_

*release version:* _0.3.2_

Enable a WebSocket subscriber send messages to the channel(s) it is connected through the same connection it is receiving the messages, using _send_ method from WebSocket interface.


h2(#push_stream_allow_connections_to_events_channel). push_stream_allow_connections_to_events_channel <a name="push_stream_allow_connections_to_events_channel" href="#">&nbsp;</a>

*syntax:* _push_stream_allow_connections_to_events_channel on | off_

*default:* _off_

*context:* _location_

*release version:* _0.6.0_

Enable subscriptions to events channel.


h2(#push_stream_last_received_message_time). push_stream_last_received_message_time <a name="push_stream_last_received_message_time" href="#">&nbsp;</a>

*syntax:* _push_stream_last_received_message_time string_

*default:* _none_

*context:* _location_

*release version:* _0.3.3_

Set the time when last message was received. With that the server knows which messages has to be sent to subscriber. Is a replacement for If-Modified-Since header. Example, $arg_time indicate that the value will be taken from time argument.


h2(#push_stream_last_received_message_tag). push_stream_last_received_message_tag <a name="push_stream_last_received_message_tag" href="#">&nbsp;</a>

*syntax:* _push_stream_last_received_message_tag string_

*default:* _none_

*context:* _location_

*release version:* _0.3.3_

Set the tag of the last received message. With that the server knows which messages has to be sent to subscriber. Is a replacement for If-None-Match header. Example, $arg_tag indicate that the value will be taken from tag argument.


h2(#push_stream_last_event_id). push_stream_last_event_id <a name="push_stream_last_event_id" href="#">&nbsp;</a>

*syntax:* _push_stream_last_event_id string_

*default:* _none_

*context:* _location_

*release version:* _0.4.0_

Set the last event id of a message. With that the server knows which messages has to be sent to subscriber. Is a replacement for Last-Event-Id header. Example, $arg_last_event indicate that the value will be taken from last_event argument.


h2(#push_stream_user_agent). push_stream_user_agent <a name="push_stream_user_agent" href="#">&nbsp;</a>

*syntax:* _push_stream_user_agent string_

*default:* _http user-agent header_

*context:* _location_

*release version:* _0.3.3_

Set from where the user agent will be get to be used on validation for the need of padding. Is a replacement for User-Agent header. Example, $arg_ua indicate that the value will be take from ua argument.


h2(#push_stream_padding_by_user_agent). push_stream_padding_by_user_agent <a name="push_stream_padding_by_user_agent" href="#">&nbsp;</a>

*syntax:* _push_stream_padding_by_user_agent string_

*default:* _none_

*context:* _location_

*release version:* _0.3.3_

Set the minimum header size and minimum message size to each user agent who match the given expression. The value may be compound for many groups on the format _user-agent-regexp,header_min_size,message_min_size_ separate by a colon (_:_) .


h2(#push_stream_allowed_origins). push_stream_allowed_origins <a name="push_stream_allowed_origins" href="#">&nbsp;</a>

*syntax:* _push_stream_allowed_origins string_

*default:* _none_

*context:* _location (push_stream_publisher, push_stream_channels_subscriber)_

*release version:* _0.3.4_

Set the value used on the Access-Control-Allow-Origin header to allow cross domain requests by javascript.
You can use a variable as value to this directive.
When this directive is set, the module will set Access-Control-Allow-Methods and Access-Control-Allow-Headers headers with proper values.

[eventsource_ref]http://dev.w3.org/html5/eventsource/
[push_stream_authorized_channels_only]subscribers.textile#push_stream_authorized_channels_only
[push_stream_channels_path]publishers.textile#push_stream_channels_path