@qogni/nes-uws
v8.0.1
Published
Nes server-side plugin using uWebsockets
Downloads
3
Readme
nes adds native WebSocket support to hapi-based application servers. Instead of treating the WebSocket connections as a separate platform with its own security and application context, nes builds on top of the existing hapi architecture to provide a flexible and organic extension.
Protocol version: 2.2.x (different from module version)
Lead Maintainer - Matt Harrison
API
The full client and server API is available in the API documentation.
Protocol
The nes protocol is described in the Protocol documentation.
Examples
Route invocation
Server
const Hapi = require('hapi');
const Nes = require('nes');
const server = new Hapi.Server();
const start = async () => {
await server.register(Nes);
server.route({
method: 'GET',
path: '/h',
config: {
id: 'hello',
handler: (request, h) => {
return 'world!';
}
}
});
await server.start();
};
start();
Client
const Nes = require('nes');
var client = new Nes.Client('ws://localhost');
const start = async () => {
await client.connect();
const payload = await client.request('hello'); // Can also request '/h'
// payload -> 'world!'
};
start();
Subscriptions
Server
const Hapi = require('hapi');
const Nes = require('nes');
const server = new Hapi.Server();
const start = async () => {
await server.register(Nes);
server.subscription('/item/{id}');
await server.start();
server.publish('/item/5', { id: 5, status: 'complete' });
server.publish('/item/6', { id: 6, status: 'initial' });
};
start();
Client
const Nes = require('nes');
const client = new Nes.Client('ws://localhost');
const start = async () => {
await client.connect();
const handler = (update, flags) => {
// update -> { id: 5, status: 'complete' }
// Second publish is not received (doesn't match)
};
client.subscribe('/item/5', handler);
};
start();
Broadcast
Server
const Hapi = require('hapi');
const Nes = require('nes');
const server = new Hapi.Server();
const start = async () => {
await server.register(Nes);
await server.start();
server.broadcast('welcome!');
};
start();
Client
const Nes = require('nes');
const client = new Nes.Client('ws://localhost');
const start = async () => {
await client.connect();
client.onUpdate = (update) => {
// update -> 'welcome!'
};
};
start();
Route authentication
Server
const Hapi = require('hapi');
const Basic = require('hapi-auth-basic');
const Bcrypt = require('bcrypt');
const Nes = require('nes');
const server = new Hapi.Server();
const start = async () => {
await server.register([Basic, Nes]);
// Set up HTTP Basic authentication
const users = {
john: {
username: 'john',
password: '$2a$10$iqJSHD.BGr0E2IxQwYgJmeP3NvhPrXAeLSaGCj6IR/XU5QtjVu5Tm', // 'secret'
name: 'John Doe',
id: '2133d32a'
}
};
const validate = async (request, username, password) => {
const user = users[username];
if (!user) {
return { isValid: false };
}
const isValid = await Bcrypt.compare(password, user.password);
const credentials = { id: user.id, name: user.name };
return { isValid, credentials };
};
server.auth.strategy('simple', 'basic', 'required', { validate });
// Configure route with authentication
server.route({
method: 'GET',
path: '/h',
config: {
id: 'hello',
handler: (request, h) => {
return `Hello ${request.auth.credentials.name}`;
}
}
});
await server.start();
};
start();
Client
const Nes = require('nes');
const client = new Nes.Client('ws://localhost');
const start = async () => {
await client.connect({ auth: { headers: { authorization: 'Basic am9objpzZWNyZXQ=' } } });
const payload = await client.request('hello') // Can also request '/h'
// payload -> 'Hello John Doe'
};
start();
Subscription filter
Server
const Hapi = require('hapi');
const Basic = require('hapi-auth-basic');
const Bcrypt = require('bcrypt');
const Nes = require('nes');
const server = new Hapi.Server();
const start = async () => {
await server.register([Basic, Nes]);
// Set up HTTP Basic authentication
const users = {
john: {
username: 'john',
password: '$2a$10$iqJSHD.BGr0E2IxQwYgJmeP3NvhPrXAeLSaGCj6IR/XU5QtjVu5Tm', // 'secret'
name: 'John Doe',
id: '2133d32a'
}
};
const validate = async (request, username, password) => {
const user = users[username];
if (!user) {
return { isValid: false };
}
const isValid = await Bcrypt.compare(password, user.password);
const credentials = { id: user.id, name: user.name };
return { isValid, credentials };
};
server.auth.strategy('simple', 'basic', 'required', { validate });
// Set up subscription
server.subscription('/items', {
filter: (path, message, options) => {
return (message.updater !== options.credentials.username);
}
});
await server.start();
server.publish('/items', { id: 5, status: 'complete', updater: 'john' });
server.publish('/items', { id: 6, status: 'initial', updater: 'steve' });
};
start();
Client
const Nes = require('nes');
const client = new Nes.Client('ws://localhost');
// Authenticate as 'john'
const start = async () => {
await client.connect({ auth: { headers: { authorization: 'Basic am9objpzZWNyZXQ=' } } });
const handler = (err, update) => {
// First publish is not received (filtered due to updater key)
// update -> { id: 6, status: 'initial', updater: 'steve' }
};
client.subscribe('/items', handler);
};
start();
Browser Client
When you require('nes')
it loads the full module and adds a lot of extra code that is not needed
for the browser. The browser will only need the nes client. If you are using CommonJS you can
load the client with require('nes/client')
.