Pestras Micro Socket.IO

Pestras microservice plugin for socket.io server support.

install

npm i @pestras/micro @pestras/micro-socket

Template

$ git clone https://github.com/pestras/pestras-micro-template

Plug In

import { SERVICE, Micro } from '@pestras/micro';
import { MicroSocket } from '@pestras/micro-socket;

Micro.plugin(new MicroSocket());

@SERVICE()
class test {}

Micro.start(Test);

MicroSocket plugin accepts a two optional arguments:

SocketIOOptions

Name | Type | default | Description --- | --- | --- | --- serverOptions | SocketIO.ServerOptions | null | see socket.io docs maxListeners | number | 10 | adapter | any | null | SocketIO Adapter port | number | 3001 | Htto server port host | string | "0.0.0.0" | Http server host

Http Server

MicroSocket can accept an http server as input to use instead of creating a new server;

The argumant could be a server instance or function that returns the server instance, the plugin will call the function after it initialized, that is useful when we want to pass the server that is not available at the instantiating time.

import *  as http from 'http';
import { SERVICE, Micro } from '@pestras/micro';
import { MicroRouter } from '@pestras/micro-router;
import { MicroSocket } from '@pestras/micro-socket;

Micro.plugin(new MicroRouter();
console.log(MicroRouter.server) // output: null
Micro.plugin(new MicroSocket(null, () => MicroRouter.server)); // at initialize time the server does exist

@SERVICE()
class test {}

Micro.start(Test);

CONNECT DECORATOR

This decorator will call the method attached to whenever a new socket has connected, it accepts an optional array of namespaces names, defaults to ['default'] which is the main io server instance.

import { SERVICE } from '@pestras/micro';
import { CONNECT } from '@pestras/micro-socket';

@SERVICE()
class Publisher {

  @CONNECT()
  onSocketConnect(io: SocketIO.Servier, socket: SocketIO.Socket) {}

  @CONNECT(['blog'])
  onSocketConnectToBlog(ns: SocketIO.Namespace, socket: SocketIO.Socket) {}
}

RECONNECT DECORATOR

Called whenever a socket reconnect to the namespace or the server.

import { SERVICE } from '@pestras/micro';
import { RECONNECT } from '@pestras/micro-socket';

@SERVICE()
class Publisher {

  @RECONNECT()
  onSocketReconnect(io: SocketIO.Servier, socket: SocketIO.Socket) {}

  @RECONNECT(['blog'])
  onSocketReconnectToBlog(ns: SocketIO.Namespace, socket: SocketIO.Socket) {}
}

HANDSHAKE DECORATOE

Called when a socket establish a coonection for the first time, mostly used for authorization.

It accepts an optional array of namespaces names and defaults to ['defualt'].

import { SERVICE } from '@pestras/micro';
import { HANDSHAKE } from '@pestras/micro-socket';

@SERVICE()
class Publisher {

  @HANDSHAKE()
  handshake(io: SocketIO.Servier, socket: SocketIO.Socket, next: (err?: any) => void) {}

  @HANDSHAKE(['blog'])
  blogHandshake(ns: SocketIO.Namespace, socket: SocketIO.Socket, next: (err?: any) => void) {
    
  }
}

USE DECORATOE

Same as HANDSHAKE decorator.

import { SERVICE } from '@pestras/micro';
import { USE } from '@pestras/micro-socket';

@SERVICE()
class Publisher {

  @USE()
  use(io: SocketIO.Servier, socket: SocketIO.Socket, next: (err?: any) => void) {}

  @USE(['blog'])
  blogUse(ns: SocketIO.Namespace, socket: SocketIO.Socket, next: (err?: any) => void) {}
}

USESOCKET DECORATOE

Used to listen to all socket incoming events.

import { SERVICE } from '@pestras/micro';
import { USESOCKET } from '@pestras/micro-socket';

@SERVICE()
class Publisher {

  @USESOCKET()
  useSocket(io: SocketIO.Servier, packet: SocketIO.Packet, next: (err?: any) => void) {}

  @USESOCKET(['blog'])
  blogUseSocket(ns: SocketIO.Namespace, packet: SocketIO.Packet, next: (err?: any) => void) {}
}

EVENT DECORATOE

Used to listen to a specific event, accepts an event name as a first parameter and an optional array of namespaces for the second defaults to ['default'].

import { SERVICE } from '@pestras/micro';
import { EVENT } from '@pestras/micro-socket';

@SERVICE()
class Publisher {

  @EVENT('userLoggedIn')
  userLoggedIn(io: SocketIO.Servier, socket: SocketIO.Socket, ...args: any[]) {}

  @EVENT('newArticle', ['blog'])
  newArticle(ns: SocketIO.Namespace, socket: SocketIO.Socket, ...args: any[]) {}
}

DISCONNECT DECORATOE

Triggered when a socket disconnect form the namespace or the server.

import { SERVICE } from '@pestras/micro';
import { DISCONNECT } from '@pestras/micro-socket';

@SERVICE()
class Publisher {

  @DISCONNECT()
  socketDisconnected(io: SocketIO.Servier, packet: SocketIO.Packet) {}

  @DISCONNECT(['blog'])
  blogSocketDisconnected(ns: SocketIO.Namespace, socket: SocketIO.Socket) {}
}

Subserveces

Each subservice can have multiple namespaces, however namespaces may not be shared among several subservice.

// subserviceA.ts
import { EVENT } from '@pestras/micro-socket';

export class SubServiceA {

  @EVENT('someevent', ['ns01'])
  eventHandler(ns: SocketIO.Namespace, socket: SocketIO.Socket, ...args: any[]) {}

  @EVENT('someevent', ['ns02'])
  eventHandler(ns: SocketIO.Namespace, socket: SocketIO.Socket, ...args: any[]) {}
}

// subserviceB.ts
import { EVENT } from '@pestras/micro-socket';

export class SubServiceB {

  @EVENT('someevent', ['ns03'])
  eventHandler(ns: SocketIO.Namespace, socket: SocketIO.Socket, ...args: any[]) {}

  // using same namespace 'ns02' in both SubServiceA and SubServiceB will cause unexpected behavior.
  @EVENT('someevent', ['ns02'])
  eventHandler(ns: SocketIO.Namespace, socket: SocketIO.Socket, ...args: any[]) {}
}

Publish

In case of not using a socket io adapter, PMS provide another helper method to manage communications between workers for handling socket io broadcasting using Micro.publish method which accepts SocketIOPublishMessage object.

Name | Type | Required | Default | Description --- | --- | ---- | --- | --- event | string | true | - | Event name that needs to be published data | any[] | true | - | event payload array distributed on multipe arguments namespace | string | false | 'default' | If we need to publish through a specific namespace room | string | false | null | If we need to publish to a specific room socketId | string | false | null | In case we need to send to specific socket or exclude it from the receivers broadcast | boolean | false | false | When socketId is provided and broadcast set to true socket will be excluded it from receivers

import { SERVICE } from '@pestras/micro';
import { MicroSocket, EVENT } from '@pestras/micro-socket';

@SERVICE({ workers: 4 })
class Publisher {

  @EVENT('ArticleUpdated', ['blog'])
  onArticleUpdate(ns: SocketIO.Namespace, socket: SocketIO.Socket, id: string) {
    socket.to('members').emit('ArticleUpdated', id);
    // publish to other worker socket io
    MicroSocket.publish({
      event: 'ArticleUpdated',
      data: [id],
      namespace: 'blog',
      room: 'members'
    });
  }
}

Thank you