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;
}
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)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
syntax: push_stream_allow_connections_to_events_channel on | off
default: off
context: location
release version: 0.6.0
Enable subscriptions to events channel.
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.
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.
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.
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.
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 (:) .
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.