Node.js integration
===================

Nodejs connects Drupal to the included Socket.IO gateway. It is an optional
low-latency delivery provider for Chatroom and can also publish events to
private channels for other modules. Chatroom works without it through polling,
and sites that want a Drupal-first generic live-update layer can also use the
Live Update module.

Quick start (local development)
-------------------------------

From the module directory, the complete local setup is one command:

    make setup

It creates a private `.env` file with a random service key, installs Node
dependencies, enables Nodejs, writes the matching Drupal settings, and clears
the cache. Edit `.env` only when the Drupal URL, port, or public hostname is
different from the local defaults.

Start the gateway in one terminal:

    make up

In another terminal, verify that it is ready:

    make health

To use it with Chatroom, enable `nodejs` and select `Node.js / Socket.IO` at
`/admin/config/user-interface/chatroom` under Message delivery. Keep JavaScript
polling enabled there as a fallback. See `chatroom/README.txt` for the room
setup and smoke test.

`.env` settings
---------------

The generated `.env` has safe local defaults:

    NODEJS_HOST=127.0.0.1
    NODEJS_PORT=8080
    NODEJS_INTERNAL_HOST=127.0.0.1
    NODEJS_SCHEME=http
    NODEJS_PUBLIC_HOST=localhost
    NODEJS_PUBLIC_PORT=8080
    NODEJS_PAGES=*
    DRUPAL_BASE_URL=http://localhost
    NODEJS_ALLOWED_ORIGINS=http://localhost
    NODEJS_SERVICE_KEY=<generated secret>

`NODEJS_HOST` and `NODEJS_PORT` are the private gateway listener used by the
gateway. `NODEJS_INTERNAL_HOST` is the address Drupal PHP uses for the gateway.
`NODEJS_SCHEME` is the scheme Drupal PHP uses for that connection.
`NODEJS_PUBLIC_*` are the address sent to browsers; change them when a proxy
exposes a different host or port. For Docker, VM, or WSL, use
`NODEJS_HOST=0.0.0.0`, `NODEJS_INTERNAL_HOST=127.0.0.1`, and the site's public
hostname in `NODEJS_PUBLIC_HOST`. `DRUPAL_BASE_URL` derives the callback URL
automatically. Keep `.env` private: it is ignored by Git.

Commands
--------

    make setup    # First run: create .env, install npm, configure Drupal.
    make up       # Start the gateway in the foreground.
    make health   # Authenticated readiness check.
    make test     # Run Node.js tests.
    make check    # Lint, tests and production dependency audit.
    make php      # Drupal coding standards and PHPStan.

Configuration
-------------

The browser-facing configuration page is
`/admin/config/nodejs/settings`. It has only the values needed for a normal
deployment: internal gateway scheme/host/port, public browser scheme/host/port,
pages that load the client, and the shared service key. For most local setups,
`.env` and `make setup` are simpler and set the equivalent Drupal config.

Use `nodejs.*` for Drupal-to-gateway traffic and `client.*` for browser-to-
gateway traffic. They differ when a reverse proxy exposes a public hostname.
Set `NODEJS_ALLOWED_ORIGINS` to a comma-separated allow-list in production.
Use HTTPS/WSS and keep `DRUPAL_CALLBACK_URL` private to the gateway.

Drush and operations
--------------------

The historical `nodejs.drush.inc` commands provide broadcasts and user/channel
operations only; they are not a configuration interface and are not a Drush 13
command provider. Use `make configure` (or `drush config:set nodejs.config …`)
for configuration.

Run the gateway under systemd, a container orchestrator, or another supervisor.
It provides heartbeat, bounded browser reconnects, payload/channel limits,
health checks, and graceful SIGTERM/SIGINT shutdown.

Chatroom delivery modes
-----------------------

Chatroom can use JavaScript polling, Node.js and Live Update at the same time.
Its delivery priority is configured by drag-and-drop on the Chatroom settings
page. Node.js provides immediate Socket.IO delivery and presence. Polling
retrieves missed messages if the gateway is unavailable. Live Update provides a
generic Drupal channel that can be reused by blocks and other page fragments.

Security
--------

The shared service key is server-to-server only. Never expose it to browsers or
commit it. Browser credentials are random, short-lived (five minutes), and
validated by Drupal; the gateway must enforce the channels returned by Drupal.
See PROTOCOL.md for the versioned realtime envelope and backend requirements.

Validation
----------

From the Drupal project root:

    cd web/modules/contrib/nodejs && make check && make php
