Nchan Expert

Overview

This skill provides procedural knowledge for configuring, optimizing, and securing Nchan, the high-performance pub/sub module for Nginx. It is based on the core Nchan documentation.

Core Capabilities

1. Endpoint Configuration

Map Nginx locations to pub/sub endpoints.

• Publishers: Use

  nchan_publisher

  to create endpoints that accept messages via HTTP POST or Websockets.
• Subscribers: Use

  nchan_subscriber

  to support Websocket, EventSource (SSE), Long-Polling, and more.
• PubSub: Use

  nchan_pubsub

  for locations that act as both.

2. Scalability & Storage

Configure local memory storage and Redis for horizontal scaling.

• Redis Modes: Implement Distributed (shared), Backup (persistence), or Nostore (broadcast) modes.
• Redis Cluster: Set up high availability and sharding.
• See references/storage.md for implementation details.

3. Security & Access Control

Secure channels using standardized patterns:

• Authorization: Use

  nchan_authorize_request

  to delegate auth to an upstream application.
• Internal Redirects: Implement

  X-Accel-Redirect

  to hide internal channel IDs.
• ACLs: Apply standard Nginx

  allow

  /

  deny

  directives for publisher endpoints.
• See references/security.md for patterns.

4. Advanced Messaging Features

• Multiplexing: Subscribe to up to 255 channels over a single connection.
• Channel Groups: Use

  nchan_channel_group

  for accounting and namespace isolation.
• Upstream Hooks: Use

  nchan_publisher_upstream_request

  to mutate messages before publication.

5. Monitoring & Introspection

• Stub Status: Monitor real-time metrics via

  nchan_stub_status

  .
• Channel Events: Track channel lifecycle events for debugging.
• Variables: Utilize Nchan-specific variables like

  $nchan_channel_id

  and

  $nchan_subscriber_count

  .
• See references/variables.md for the full reference.

6. Testing & Validation

• Verify Handshakes: Use

  curl

  with

  --http1.1

  and a valid 16-byte

  Sec-WebSocket-Key

  .
• Troubleshoot: Resolve issues with HTTP/2 negotiation and strict proxy key enforcement (e.g., Cloudflare/Render).
• See references/testing.md for commands and troubleshooting steps.

7. Containerization

• Compile Module: Use multi-stage builds to compile Nchan for Nginx Alpine.
• Harden Security: Run as a non-root user and implement container healthchecks.
• See references/docker.md for the Dockerfile pattern and configuration.

Resources

• references/directives.md: Comprehensive list of configuration directives.
• references/variables.md: Nchan-specific Nginx variables.
• references/security.md: Security and authorization patterns.
• references/storage.md: Memory and Redis storage configuration.
• references/testing.md: Minimal testing patterns with curl (stats, pub/sub, wss) and handshake troubleshooting.
• references/docker.md: Docker containerization and multi-stage build patterns.