nchan

Pub/sub messaging over WebSocket and EventSource

dynamic moduleMITsource docs

Overview

Nchan turns nginx into a pub/sub message server. Clients subscribe to named channels over WebSocket, EventSource (server-sent events), or long-polling, and messages published to a channel are delivered to every subscriber. The protocol is negotiated per client, so one subscriber endpoint serves browsers and plain HTTP clients alike.

Publishing is a plain HTTP POST, so any backend language can push messages without a client library. This lets an application hand off live updates, chat, or notification fan-out to nginx instead of holding thousands of open connections itself.

Messages are buffered in shared memory by default. A Redis backend adds persistence and lets several nginx servers share the same channels.

Key directives

nchan_publisherMarks a location as a publisher endpoint that accepts messages via HTTP POST or WebSocket.
nchan_subscriberMarks a location as a subscriber endpoint serving WebSocket, EventSource, and long-poll clients.
nchan_channel_idSets the channel a location publishes to or subscribes from, usually from a variable such as $arg_id.
nchan_pubsubCombines publisher and subscriber behavior in a single location.
nchan_message_buffer_lengthSets how many recent messages each channel keeps for delivery to late or reconnecting subscribers.
nchan_redis_passStores channel messages in a Redis upstream so multiple nginx servers can share channels.

Example

nginx.conf
load_module modules/ngx_nchan_module.so; http { server { listen 80; location = /pub { nchan_publisher; nchan_channel_id $arg_id; } location = /sub { nchan_subscriber; nchan_channel_id $arg_id; } } }

Availability

Ships as a dynamic module in libnginx-mod-nchan, installed automatically with nginx-extras. The package drops a load_module config into /etc/nginx/modules-enabled/, so it loads on start.