@hyper-graph/ws-adapter

NestJS Websocket Adapter

Motivation:

Websocket adapters, which provided by NestJS, are very simple and cannot be used in large applications. They can only receive messages, send replies, without correlation id, and send events. Using them you can't reply with correlation id in common, can't verify connect and etc. This adapter try to resolve more of common cases.

Features

Correlation ID

Then you return data from a gateway it will return with correlationId which was received from client. This behavior can be configured by adapter options.

Events

It's not a feature, but events has different api than nestjs adapters. You can emit an event on connect and all data that you pass will be sent to client with wrapping into protocol.

Formatter

You can specify a formatter for your application. It means you can use JSON, yml, xml, binary or another format of data.

Protocol

Protocol control all data that receive or send application and wrap it into control object. Protocol can receive correlationId and send it in response with data what return message handler. You can also pass your own implementation of protocol.

Connect verification

You can set connect verification handler. This handler will be called for each connect request. If handler throws an error, connect will be rejected. You can set headers that will be sent to client with accept message.

Multiple handlers

You can set as many handlers for one patter as you need to. All responses will be merged into one object and pass into protocol as one result.

Regex patterns

In nestjs adapters you can pass only string as pattern into SubscribeMessage decorator. All messages checks using strict equal. This adapter supports string and regex for searching handlers which will be called.

Gateway namespaces

You can specify namespaces for your gateway. How do they work depends on protocol. See more information in API Reference.

API Reference:

Adapter

Base usage:

const app = await NestFactory.create(AppModule);

app.useWebsocketAdapter(new WebsocketAdapter(app));

await app.listenAsync(3000);

Formatter

You can pass formatter in options in first argument.

const app = await NestFactory.create(AppModule);

app.useWebsocketAdapter(new WebsocketAdapter(app, {
    formatter: new JsonFormat(),
}));

await app.listenAsync(3000);

JsonFormat is builtin formatter.

You can write your own formatter for example for yml.

For do this you will extend BaseFormat class and implement to methods: parse and format.

Protocol

You can use protocol like formatter. It can be passed in options in second argument.

const app = await NestFactory.create(AppModule);

app.useWebsocketAdapter(new WebsocketAdapter(app, {
    protocol: new JsonRpcProtocol(),
}));

await app.listenAsync(3000);

JsonRpcProtocol is builtin protocol.

You can write your own protocol handler.

For do this you will extend BaseProtocol class and implement to methods: handle and formatEvent.

These methods are not so simple as parse and format in a formatter, but BaseProtocol class provides some helpful methods. You also can use JsonRpcProtocol class as example for your own implementation.

Namespace delimiter

If you want to use namespaces, you can specify a delimiter between namespaces and method.

const app = await NestFactory.create(AppModule);

app.useWebsocketAdapter(new WebsocketAdapter(app, {
    namespaceDelimiter: '/',
}));

await app.listenAsync(3000);

Gateways

WebSocketGateway Decorator

This adapter support WebSocketGateway arguments. NestJS use first argument as port if it's a number else it will be used as options. If you pass a port, you can pass options in second argument.

TODO: Work In Progress