http/2 ready
Powered by nginx

Nchan is a scalable, flexible pub/sub server for the modern web, built as a module for the Nginx web server. It can be configured as a standalone server, or as a shim between your application and tens, thousands, or millions of live subscribers. It can buffer messages in memory, on-disk, or via Redis. All connections are handled asynchronously and distributed among any number of worker processes. It can also scale to many nginx server instances with Redis.

Messages are published to channels with HTTP POST requests or websockets, and subscribed also through websockets, long-polling, EventSource (SSE), old-fashioned interval polling, and more. Each subscriber can listen to up to 255 channels per connection, and can be optionally authenticated via a custom application url. An events meta channel is also available for debugging.

For use in a web browser, you can try the NchanSubscriber.js wrapper library. It supports Long-Polling, EventSource, and resumable Websockets -- or you can build your own.

Status and History

The latest Nchan release is v1.0.1 (August 22, 2016) (changelog).

The first iteration of Nchan was written in 2009-2010 as the Nginx HTTP Push Module, and was vastly refactored into its present state in 2014-2016. The present release is in the testing phase. The core features and old functionality are thoroughly tested and stable. Some of the new functionality, especially Redis Cluster may be a bit buggy.

Please help make the entire codebase ready for production use! Report any quirks, bugs, leaks, crashes, or larvae you find.

Upgrade from Nginx HTTP Push Module

Although Nchan is backwards-compatible with all Push Module configuration directives, some of the more unusual and rarely used settings have been disabled and will be ignored (with a warning). See the upgrade page for a detailed list of changes and improvements, as well as a full list of incompatibilities.

Does it scale?

benchmarking internal subscriber response times

Yes it does. Like Nginx, Nchan can easily handle as much traffic as you can throw at it. I've tried to benchmark it, but my benchmarking tools are much slower than Nchan. The data I've gathered is on how long Nchan itself takes to respond to every subscriber after publishing a message -- this excludes TCP handshake times and internal HTTP request parsing. Basically, it measures how Nchan scales assuming all other components are already tuned for scalability. The graphed data are averages of 5 runs with 50-byte messages.

With a well-tuned OS and network stack on commodity server hardware, expect to handle upwards of 300K concurrent subscribers per second at minimal CPU load. Nchan can also be scaled out to multiple Nginx instances using the Redis storage engine, and that too can be scaled up beyond a single-point-of-failure by using Redis Cluster.

Currently, Nchan's performance is limited by available memory bandwidth. This can be improved significantly in future versions with fewer allocations and the use of contiguous memory pools. Please consider supporting Nchan to speed up the work of memory cache optimization.

Download

Packages

From Source

Grab the latest copy of Nginx from nginx.org. Grab the latest Nchan source from github. Follow the instructions for building Nginx, except during the configure stage, add

./configure --add-module=path/to/nchan ...

If you're using Nginx > 1.9.11, you can build Nchan as a dynamic module with --add-dynamic-module=path/to/nchan

Run make, make install, and enjoy. (Caution, contents may be hot.)

Conceptual Overview

The basic unit of most pub/sub solutions is the messaging channel. Nchan is no different. Publishers send messages to channels with a certain channel id, and subscribers subscribed to those channels receive them. Some number of messages may be buffered for a time in a channel's message buffer before they are deleted. Pretty simple, right?

Well... the trouble is that nginx configuration does not deal with channels, publishers, and subscribers. Rather, it has several sections for incoming requests to match against server and location sections. Nchan configuration directives map servers and locations onto channel publishing and subscribing endpoints:

#very basic nchan config
worker_processes 5;

http {  
  server {
    listen       80;

    location = /sub {
      nchan_subscriber;
      nchan_channel_id foobar;
    }

    location = /pub {
      nchan_publisher;
      nchan_channel_id foobar;
    }
  }
}

The above maps requests to the URI /sub onto the channel foobar's subscriber endpoint , and similarly /pub onto channel foobar's publisher endpoint.

Publisher Endpoints

Publisher endpoints are Nginx config locations with the nchan_publisher directive.

Messages can be published to a channel by sending HTTP POST requests with the message contents to the publisher endpoint locations. You can also publish messages through a Websocket connection to the same location.

Publishing Messages

Requests and websocket messages are responded to with information about the channel at time of message publication. Here's an example from publishing with curl:

>  curl --request POST --data "test message" http://127.0.0.1:80/pub

 queued messages: 5
 last requested: 18 sec. ago
 active subscribers: 0
 last message id: 1450755280:0

The response can be in plaintext (as above), JSON, or XML, based on the request's Accept header:

> curl --request POST --data "test message" -H "Accept: text/json" http://127.0.0.2:80/pub

 {"messages": 6, "requested": 55, "subscribers": 0, "last_message_id": "1450755317:0" }

Websocket publishers also receive the same responses when publishing, with the encoding determined by the Accept header present during the handshake.

The response code for an HTTP request is 202 Accepted if no subscribers are present at time of publication, or 201 Created if at least 1 subscriber was present.

Metadata can be added to a message when using an HTTP POST request for publishing. A Content-Type header will be associated as the message's content type (and output to Long-Poll, Interval-Poll, and multipart/mixed subscribers). A X-EventSource-Event header can also be used to associate an EventSource event: line value with a message.

Other Publisher Endpoint Actions

HTTP GET requests return channel information without publishing a message. The response code is 200 if the channel exists, and 404 otherwise:

> curl --request POST --data "test message" http://127.0.0.2:80/pub
  ...

> curl -v --request GET -H "Accept: text/json" http://127.0.0.2:80/pub

 {"messages": 1, "requested": 7, "subscribers": 0, "last_message_id": "1450755421:0" }

HTTP DELETE requests delete a channel and end all subscriber connections. Like the GET requests, this returns a 200 status response with channel info if the channel existed, and a 404 otherwise.

Subscriber Endpoint

Subscriber endpoints are Nginx config locations with the nchan_subscriber directive.

Nchan supports several different kinds of subscribers for receiving messages: Websocket, EventSource (Server Sent Events), Long-Poll, Interval-Poll. HTTP chunked transfer, and HTTP multipart/mixed.

PubSub Endpoint

PubSub endpoints are Nginx config locations with the nchan_pubsub directive.

A combination of publisher and subscriber endpoints, this location treats all HTTP GET requests as subscribers, and all HTTP POST as publishers. One simple use case is an echo server:

  location = /pubsub {
    nchan_pubsub;
    nchan_channel_id foobar;
  }

A more applicable setup may set different publisher and subscriber channel ids:

  location = /pubsub {
    nchan_pubsub;
    nchan_publisher_channel_id foo;
    nchan_subscriber_channel_id bar;
  }

Here, subscribers will listen for messages on channel foo, and publishers will publish messages to channel bar. This can be useful when setting up websocket proxying between web clients and your application.

The Channel ID

So far the examples have used static channel ids, which is not very useful in practice. It can be set to any nginx variable, such as a querystring argument, a header value, or a part of the location url:

  location = /sub_by_ip {
    #channel id is the subscriber's IP address
    nchan_subscriber;
    nchan_channel_id $remote_addr;
  }

  location /sub_by_querystring {
    #channel id is the query string parameter chanid
    # GET /sub/sub_by_querystring?foo=bar&chanid=baz will have the channel id set to 'baz'
    nchan_subscriber;
    nchan_channel_id $arg_chanid;
  }

  location ~ /sub/(\w+)$ {
    #channel id is the word after /sub/
    # GET /sub/foobar_baz will have the channel id set to 'foobar_baz'
    # I hope you know your regular expressions...
    nchan_subscriber;
    nchan_channel_id $1; #first capture of the location match
  }

Channel Multiplexing

Any subscriber location can be an endpoint for up to 255 channels. Messages published to all the specified channels will be delivered in-order to the subscriber. There are two ways to enable multiplexing:

Up to 7 channel ids can be specified for the nchan_channel_id or nchan_channel_subscriber_id config directive:

  location ~ /multisub/(\w+)/(\w+)$ {
    nchan_subscriber;
    nchan_channel_id "$1" "$2" "common_channel";
    #GET /multisub/foo/bar will be subscribed to:
    # channels 'foo', 'bar', and 'common_channel',
    #and will receive messages from all of the above.
  }

For more than 7 channels, nchan_channel_id_split_delimiter can be used to split the nchan_channel_id or nchan_channel_subscriber_id into up to 255 individual channel ids:

  location ~ /multisub-split/(.*)$ {
    nchan_subscriber;
    nchan_channel_id "$1";
    nchan_channel_id_split_delimiter ",";
    #GET /multisub-split/foo,bar,baz,a will be subscribed to:
    # channels 'foo', 'bar', 'baz', and 'a'
    #and will receive messages from all of the above.
  }

DELETE requests on any channel are forwarded to relevant multi-channel subscribers, and their connections are terminated.

Publishing to multiple channels with a single request is also possible, with similar configuration:

  location ~ /multipub/(\w+)/(\w+)$ {
    nchan_publisher;
    nchan_channel_id "$1" "$2" "another_channel";
  }

Storage

Nchan can stores messages in memory, on disk, or via Redis. Memory storage is much faster, whereas Redis has additional overhead as is considerably slower for publishing messages, but offers near unlimited scalability for broadcast use cases with far more subscribers than publishers.

Memory Storage

This storage method uses a segment of shared memory to store messages and channel data. Large messages as determined by Nginx's caching layer are stored on-disk. The size of the memory segment is configured with nchan_max_reserved_memory. Data stored here is not persistent, and is lost if Nginx is restarted or reloaded.

Redis

Nchan can also store messages and channels on a Redis server, or in a Redis cluster. To use a Redis server, set nchan_use_redis on; and set the server url with nchan_redis_url. These two settings are inheritable by nested locations, so it is enough to set them within an http { } block to enable Redis for all Nchan locations in that block. Different locations can also use different Redis servers.

To use a Redis Cluster, the Redis servers acting as cluster nodes need to be configured in an upstream { } block:

  upstream redis_cluster {
    nchan_redis_server redis://127.0.0.1:7000;
    nchan_redis_server redis://127.0.0.1:7001;
    nchan_redis_server redis://127.0.0.1:7002;
  }

It is best to specify all master cluster nodes, but this is not required -- as long as Nchan can connect to at least 1 node, it will discover and connect to the whole cluster.

To use Redis Cluster in an Nchan location, use the nchan_redis_pass setting:

  location ~ /pubsub/(\w+)$ {
    nchan_channel_id $1;
    nchan_pubsub;
    nchan_redis_pass redis_cluster;
  }

Note that nchan_redis_pass implies nchan_use_redis on;, and that this setting is not inherited by nested locations.

When connecting several Nchan servers to the same Redis server (or cluster), the servers must have their times synced up. Failure to do so will result in missing and duplicated messages.

Variables

Nchan makes several variables usabled in the config file:

Additionally, nchan_stub_status data is also exposed as variables. These are available only when nchan_stub_status is enabled on at least one location:

Configuration Directives

copy, but don't plagiarise