@hapi/nes Documentation

Nes supports a pub/sub model where clients can subscribe to specific paths on the server.

1. On the Server: Use server.subscription(path) to enable subscriptions for a specific path pattern, and server.publish(path, payload) to send data to all clients subscribed to that path.
2. On the Client: Use client.subscribe(path, handler) to listen for updates. The handler receives the update (the payload) and flags.

Subscribers only receive messages that match the path they subscribed to.

// Server
await server.register(Nes);
server.subscription('/item/{id}');
await server.start();
server.publish('/item/5', { id: 5, status: 'complete' });

// Client
const client = new Nes.Client('ws://localhost');
await client.connect();
const handler = (update, flags) => {
    // update -> { id: 5, status: 'complete' }
};
client.subscribe('/item/5', handler);

To ensure the connection is still active when TCP cannot detect it, the server uses a heartbeat mechanism.

1. Server sends: A message with type: 'ping'.
2. Client responds: A message with type: 'ping' and a unique id.

Client Timeout Logic: The client should assume the connection is closed if it has not heard from the server within the period of heartbeat.interval + heartbeat.timeout (provided during the hello handshake).

// Server heartbeat request
{
    type: 'ping'
}

// Client heartbeat response
{
    type: 'ping',
    id: 6
}

To add native WebSocket support to your Hapi application, register the @hapi/nes plugin with your Hapi server instance. This allows you to use nes features like route invocation, subscriptions, and broadcasting within your existing Hapi architecture.

Note that the nes protocol version is 2.4.x, which is distinct from the module version.

const Hapi = require('@hapi/hapi');
const Nes = require('@hapi/nes');

const server = new Hapi.Server();

const start = async () => {
    await server.register(Nes);
    // ... configure routes and start server
    await server.start();
};

start();

When using @hapi/nes in a browser environment, you should avoid importing the full module to prevent loading unnecessary server-side code.

If you are using CommonJS, import only the client module: require('@hapi/nes/lib/client')

// Use this for browser-side clients to keep bundle size small
const Nes = require('@hapi/nes/lib/client');

Nes integrates with Hapi's authentication system. You can protect routes or subscriptions by applying standard Hapi authentication strategies to them.

When connecting via the client, pass the authentication credentials in the connect() method's options object under the auth.headers key.

// Server: Configure route with authentication
server.route({
    method: 'GET',
    path: '/h',
    config: {
        id: 'hello',
        handler: (request, h) => {
            return `Hello ${request.auth.credentials.name}`;
        }
    }
});

// Client: Connect with Basic Auth headers
const client = new Nes.Client('ws://localhost');
await client.connect({
    auth: {
        headers: { authorization: 'Basic am9objpzZWNyZXQ=' }
    }
});
const payload = await client.request('hello');

The nes plugin is registered using the standard hapi server.register() method. You can provide several optional configuration options to control connection lifecycles, message handling, and security.

await server.register({
    plugin: require('@hapi/nes'),
    options: {
        onConnection: (socket) => {
            console.log('New connection:', socket.id);
        },
        onDisconnection: (socket) => {
            console.log('Disconnected:', socket.id);
        },
        onMessage: async (socket, message) => {
            // Handle custom client messages
            return { status: 'received' };
        }
    }
});

Errors thrown by the Nes client include a type property to help distinguish the source of the error. Common error types include:

• timeout: The request or connection timed out.
• disconnect: The server disconnected.
• server: An error returned by the server (includes statusCode, data, headers, and path).
• protocol: A violation of the Nes protocol.
• ws: A WebSocket-level error.
• user: A client-side error (e.g., invalid path or calling connect() while already connected).

To use Nes, register it as a plugin in your Hapi server. Nes provides real-time, bidirectional communication via WebSockets. Upon registration, it decorates the server object with methods for broadcasting and publishing, and the request object with access to the current socket.

const Hapi = require('@hapi/hapi');
const Nes = require('@hapi/nes');

const init = async () => {
    const server = Hapi.server({
        port: 3000,
        host: 'localhost'
    });

    await server.register({
        plugin: Nes,
        options: {
            // Configuration options go here
        }
    });

    await server.start();
};

init();