Nchan's LICENCE file defeats the licence metadata

The licence file is spelled with a C and the metadata gave up

The repository has nine top level entries and one of them is a file called LICENCE rather than LICENSE. That single letter is the whole explanation for why this repository's licence field reports nothing identifiable to automated tooling. The convention that licence checkers look for is the American spelling, and a file with the British spelling is a file those tools skip, so the project appears to have no terms at all to anything reading metadata rather than browsing the tree. Nothing else about the file is unusual and the licence text is plainly there. It is worth knowing before you conclude from a package listing that the project is unlicensed, because it is not; it is invisible to the tooling. The same kind of small naming decision explains another thing in the tree: a line counting tool exclusion file sits at the root, which is bookkeeping for generated code and only matters to whoever regenerates it.

The subscriber figure comes from five runs of fifty byte messages

The scaling section opens by admitting something most benchmark sections would not: the author has tried to benchmark it, but their benchmarking tools are much slower than the thing being measured. Then it defines exactly what is being timed, which is how long the engine takes to respond to every subscriber after a message is published, explicitly excluding TCP handshake times and internal request parsing, on the reasoning that this measures how the engine scales assuming everything around it is already tuned. The data are averages of five runs with fifty byte messages. The conclusion is that on a well tuned operating system and network stack on commodity server hardware you can expect upwards of three hundred thousand concurrent subscribers per second at minimal processor load. So the number is not unsupported; it is scoped, small sample, and disclosed as such. Three hundred thousand subscribers against fifty byte messages is a fan-out measurement, not a throughput measurement, and the file is honest enough to let you tell the difference.

The whole engine is one Nginx module and two config locations

The thing to understand before reading any configuration is that this is not a server with a port. It is a module compiled into Nginx, and the delivery model comes from that. Messages are buffered per channel in shared memory between worker processes, which is why the module can fan one published message out to many subscribers across processes without a broker in between, and why all connections are handled asynchronously and distributed among any number of workers. The persistence option is slower and lives in Redis. Enabling the whole feature takes two locations in an ordinary Nginx config:

location = /sub {
  nchan_subscriber;
  nchan_channel_id $arg_id;
}

location = /pub {
  nchan_publisher;
  nchan_channel_id $arg_id;
}

Two directives each, one for subscribers and one for publishers. Everything else in the feature list, the multiplexed channels, the introspection events, the hooks, the groups and the accounting, hangs off that arrangement.

The channel identifier comes from a query argument

Look at the two directives above and one fact dominates the security model. Both the publish and the subscribe location take the channel identifier from a query argument, so the channel a client talks to is whatever it puts in the address. Publishing is an HTTP POST to that address with a body, and subscribing is a connection to the other address. The feature list does contain the mitigations: channels can be grouped, and those groups have accounting and limits. But nothing in the configuration shown enables either, and the readme calls the result that simple. So the default posture of this system is that any client that knows or guesses a channel identifier can publish to it, and a second guarantee worth naming is scoped rather than absolute: per-channel configurable buffers with no-repeat and no-loss delivery. No loss and no repeat is a property of the buffer window, and the buffer is configurable, so the guarantee is about what fits.

Two of the seven install routes belong to someone else

The install section lists seven ways in, and two of them are maintained by a different person whose name appears in both of their links. Those two are a buildpack for compiling the module into Nginx on a platform as a service, and a one click deployable application built on that buildpack. The rest are first party: two packages in the Arch community repository, one for the stable Nginx line and one for the mainline; a dynamic module in the Debian repository; prebuilt static module packages for Debian and separate ones for Ubuntu, each installed with a package tool call followed by a dependency fix; a Fedora package for one architecture plus a source package; a Homebrew tap owned by a third party with a formula flag that asks for the module to be included; and a tarball containing a statically compiled binary with the Linux server files. The Ubuntu entry ends with a rhetorical complaint about how long it has taken that distribution to package the module, which tells you the story.

The static and dynamic module flags are two eras of Nginx

Building from source means taking Nginx from its own site, taking this module's source from the releases page, and following the server's own build instructions with one addition at the configure stage:

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

And then, in the next line, the alternative. On a server newer than a specific 2016 version, the module can be built as a dynamic module instead, using the dynamic flag, which means you do not recompile the server and can load and unload the module with the rest of the dynamic ones. Two flags for the same module, one for each generation of how Nginx modules are compiled, both supported. That compatibility is a maintenance commitment with a real cost, and it is the reason the module still installs on the servers people actually run. The rest of the build is unchanged: make, then make install.

Backwards compatible except for the settings that were disabled

The history section is unusually open about a project that has been through a rename. The first version was written in 2009 and 2010 as a push module for the same server, under its own name and its own host, and was refactored into its present form across 2014 to 2016. The upgrade note says the module is backwards compatible with all of the old configuration directives, and then in the same sentence says that some of the more unusual and rarely used settings have been disabled and will be ignored, with a warning. That is the honest way to say this: no configuration you wrote in 2010 will break, but some of it will now be quietly doing nothing except printing a warning. The details, including a full list of what changed and what no longer applies, are on an upgrade page rather than in the file, so anyone with an old deployment has one more place to read before upgrading.

Editorial conclusion

Use this if you already run Nginx and want to add live updates without standing up a separate service, because the fan-out happens inside the workers you already have and the configuration is two locations in a config file you already edit. Three things to check before you rely on it. The channel identifier comes from a query argument on both the publish and the subscribe endpoint, so treat every channel as public unless you configure the accounting and limits the feature list mentions; that is a design choice, not a bug, but it means the default posture is open. Scaling beyond one machine requires Redis, and the file says so plainly, so budget for a second datastore and decide whether you need the cluster form for availability. And pick your install route carefully, because two of the seven are third party and one of them is a tap on a package manager whose flags have moved on. The benchmark's own caveats are worth reading before you quote the number.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. slact/nchan on GitHub