This package has been deprecated

Author message:

replaced by yoctopus (without scope)

@clerksystems/yoctopus

Yoctopus

Description

Plugin based WebSocket server. Mostly everything in Yoctopus is done through the use of (small) plugins. A plugins can define event listeners and endpoints.

When a websocket connection is made, it is given a data store. In that store each plugin gets it own public namespace in which it can privately set predeclared variables called settings. As plugins can read (or listen to changes to) each others' settings, they are easy to combine. (A use case might be an authentication plugin upon which's settings certain endpoints are forbidden.)

Initializing Yoctopus

const server = new Yoctopus( {
	port,           // port to host the server on
	keyPath,        // path to ssl key
	certPath,       // path to ssl cert
	caPath,         // path to ssl ca
} );

await server.plugin( pluginConfig, endpointAlias );
await server.start();

Plugin Config

{
	name: 'test-plugin'
,   settings    :	{
						'some-setting'	: 'type'
					}
,   listeners   :	{
						server	: {
									onConnectionOpened  : ({ request, notify, socket, connectionSettings, ...staticEndpointArguments }) => {}
								,   onConnectionChanged : ({ request, notify, connectionSettings, ...staticEndpointArguments }) => {}
								,   onConnectionClosed  : ({ request, notify, connectionSettings, ...staticEndpointArguments }) => {}
								,   onRequestReceived   : ({ request, notify, connectionSettings, ...staticEndpointArguments }) => {}
								,   onResponsePrepared  : ({ request, notify, connectionSettings, ...staticEndpointArguments }) => {}
								,   onResponseSent      : ({ request, notify, connectionSettings, ...staticEndpointArguments }) => {}
								}
					,	plugins	: {
									pluginName	: {
													setting	: ({ value, setting, connectionId }) => {}
												}
								}
					}
,   endpoints   :	{
					'endpoint-name' : {
						'method': {
							requirements: {
								'plugin.key': expectedValue
							}
						,	requestFormat: {
								'key': 'type'
							}
						,	handler : ({ request, connectionSettings, ...staticEndpointArguments }) => {}
						}
					}
				}
}

Plugin Alias

Endpoint names are automatically prefixed with the plugin name. For example: an endpoint user, defined by a plugin called fb-auth will become accessible as fb-auth:user.

Calling endpoints in this required plugin-name:endpoint-format can be a bit tedious. It also makes it hard to switch plugins. Which is why aliasing can be a good idea.

You can make an endpoint alias, allowing the endpoint to be accessed in the global namespace without the prefixed plugin name, simply by supplying a JSON object defining the endpoint mapping.

{
	endpointAliases: {
		'endpoint name': 'global endpoint name'
	}
}

In the case of our fb-auth:user endpoint, let's assume we'd rather have the endpoint as account. We'd then have to define the following map:

{
	endpointAliases: {
		'user': 'account'
	}
}

                             *#(##((((###/                                 
                          (/*(***,*/(/,****##                              
                        ,(*((((,*,,,,,,,,,,/(#/                            
                       (/**((//*////..,,,//*/((%                           
                      *(//*,,,,,/////..,,,,**////                          
                      %#/////*,,.//*,,.,,//(*((/#                          
                      %(((///,,,...,/....///((((%                          
                      #(##/,,,,//.......,,//*((#%                          
                      %%%%(//,/,,....//..,,*(%%#%                          
                       &&@%(*,,,,./...,,,.,/#&&%                           
                        %#*%%%/,/*,//**,*%%#,(%                            
                //(/(   ///#@@@(#/,,**(/@@@(*/*   (/(//                    
                */(///* #@%.&@@@%*,*,,#@&(@@@@# ,(////*                    
         /*/*/ #%%%/%/, /@@@@@@(%/,,,,#/@@&&@@/ ,/#/#%%# *//*/             
        /*(% .. %##/#(%   (%#%%****,*,,*###%(   %(%*%%% ...##*/            
       .(/#*     (#**(%.    /(/,(/,,,./,/(*     #(/*/#     (#//.           
        ,*(#/     #(//(#/((*(,,,./...,*,,/*,#%#(###(#     #/(**            
        (#//*(//    ###%(,***(///....//....,,,*####    **(/**((            
          (////(/*((((/(**(.,///,,.....////*,**/(((/,*(*/***(              
             (//*//**/((**/*,,,,.,.....*////..*(((//(/***/                 
                ((,%#%((*,,,*.,////......,,,,.*/(%#%,/(                    
             (/#/#  &//**/,*,,,*///....*/,,,,,,,,/&  (*#/(                 
             (/(/  /##*(#((**(/,*,,.,,,/////(((/*(/,  *///                 
            #/%//&%(#((*   ((/***/**/*****(*   *(*/(#&*/%(#                
             (%/(//*///,   ,%/*/((* ,#(//(%.   ,((/////*%/                 
             #//(///*/     /#(((#     (/*(#*     (/***/*/#                 
                       ((#**/((##     #(**/**#(#                           
                       (##/&/(/#,     .(/#/@/(#(                           
                      #((%/&%###       #(#&&*%((#                          
                      /((*(%#(#%       ((%(*##(                          
                       *((%/%%&.       .&%&/%((*.                          
                        ,(#(/(           (//#(,