https://nchan.io

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 hundreds, 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 servers with Redis.

Messages are published to channels with HTTP POST requests or Websocket, and subscribed also through Websocket, long-polling, EventSource (SSE), old-fashioned interval polling, and more.

In a web browser, you can use Websocket or EventSource natively, or the NchanSubscriber.js wrapper library. It supports Long-Polling, EventSource, and resumable Websockets, and has a few other added convenience options. It's also available on NPM.

Features

RESTful, HTTP-native API.
Supports Websocket, EventSource (Server-Sent Events), Long-Polling and other HTTP-based subscribers.
Per-channel configurable message buffers with no-repeat, no-loss message delivery guarantees.
Subscribe to hundreds of channels over a single subscriber connection.
HTTP request callbacks and hooks for easy integration.
Introspection with channel events and url for monitoring performance statistics.
Channel group usage accounting and limits.
Fast, nonblocking shared-memory local message storage and optional, slower, persistent storage with Redis.
Horizontally scalable (using Redis).
Auto-failover and high availability with no single point of failure using Redis Cluster.

Status and History

The latest Nchan release is 1.3.8 (February 14, 2026) (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.

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?

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.

Install

Download Packages

Arch Linux: nginx-mod-nchan and nginx-mainline-mod-nchan are available in the Arch User Repository.
Mac OS X: a homebrew package is available. brew tap denji/nginx; brew install nginx-full --with-nchan-module
Debian: A dynamic module build is available in the Debian package repository: libnginx-mod-nchan.
Additionally, you can use the pre-built static module packages nginx-common.deb and nginx-extras.deb. Download both and install them with dpkg -i, followed by sudo apt-get -f install.
Ubuntu: nginx-common.ubuntu.deb and nginx-extras.ubuntu.deb. Download both and install them with dpkg -i, followed by sudo apt-get -f install. Who knows when Ubuntu will add Nchan to their repository?...
Fedora: Dynamic module builds for Nginx > 1.10.0 are available: nginx-mod-nchan.x86_64.rpm, nginx-mod-nchan.src.rpm.
Heroku: A buildpack for compiling Nchan into Nginx is available: nchan-buildpack. A one-click, readily-deployable app is also available: nchan-heroku.
A statically compiled binary and associated linux nginx installation files are also available as a tarball.

Build 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, then make install.

Getting Started

Once you've built and installed Nchan, it's very easy to start using. Add two locations to your nginx config:

#...
http {  
  server {
    #...
    
    location = /sub {
      nchan_subscriber;
      nchan_channel_id $arg_id;
    }
    
    location = /pub {
      nchan_publisher;
      nchan_channel_id $arg_id;
    }
  }
}

You can now publish messages to channels by POSTing data to /pub?id=channel_id , and subscribe by pointing Websocket, EventSource, or NchanSubscriber.js to sub/?id=channel_id. It's that simple.

But Nchan is very flexible and highly configurable. So, of course, it can get a lot more complicated...

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.

  location /pub {
    #example publisher location
    nchan_publisher;
    nchan_channel_id foo;
    nchan_channel_group test;
    nchan_message_buffer_length 50;
    nchan_message_timeout 5m;
  }

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": 5, "requested": 18, "subscribers": 0, "last_message_id": "1450755280: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

Nchan

Install / Use

README