Permalink
319 lines (176 sloc) 12.8 KB

Subscribers Configuration

push_stream_subscriber  

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

  # 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;
  }

push_stream_channels_path  

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?

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)

push_stream_authorized_channels_only  

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.

push_stream_header_template_file  

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.

push_stream_header_template  

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.

push_stream_message_template  

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: "<script>p(~id~,'~channel~','~text~', ~tag~, '~time~');</script>"

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.

push_stream_wildcard_channel_max_qtd  

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 to preserve the server from a kind of attack where a subscriber sign one normal channel and many nonexistent wildcard channels.

push_stream_ping_message_interval  

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.

push_stream_subscriber_connection_ttl  

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.

push_stream_longpolling_connection_ttl  

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.

push_stream_timeout_with_body  

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.

push_stream_websocket_allow_publish  

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.

push_stream_allow_connections_to_events_channel  

syntax: push_stream_allow_connections_to_events_channel on | off

default: off

context: location

release version: 0.6.0

Enable subscriptions to events channel.

push_stream_last_received_message_time  

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.

push_stream_last_received_message_tag  

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.

push_stream_last_event_id  

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.

push_stream_user_agent  

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.

push_stream_padding_by_user_agent  

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 (:) .

push_stream_allowed_origins  

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.