ethermeris 0.0.7 | Documentation

ethermeris

0.0.7

EthermerisManager ▸
- Instance members
- #createServer
- #attach
EthermerisServer ▸
- Instance members
- #getState
- #getWebSocketServer
- #getClients
- #addCompressor
- #emitToAll
- #on
- #off
- #once
- #respond
- #setState
EthermerisServer~clientModifierCallback
EthermerisClient ▸
- Instance members
- #id
- #ready
- #socket
- #init
- #destroy
- #on
- #off
- #once
- #respond
- #emit
- #request
EthermerisClient#disconnection
EthermerisClient#connection
EthermerisServer#connection
EthermerisServer#disconnection
ClientConnection ▸
- Instance members
- #destroy
- #emit
- #request
ServerSettings
ManagerSettings
ClientSettings

EthermerisManager

The Ethermeris Manager. This class holds multiple servers and automatically routes clients to specific servers. Handles WebSocket upgrades, WebRTC Signalling, and ICE Candidate exchanges. Also hosts the client library file.

new EthermerisManager(settings: ManagerSettings)

Parameters

settings (ManagerSettings) Ethermeris Manager Settings

Instance Members

▸ createServer(settings)

Creates a server and attaches it to this manager.

createServer(settings: ServerSettings): EthermerisServer

Parameters

settings (ServerSettings) The Ethermeris Server Configuration

Returns

EthermerisServer:

▸ attach(server)

Attaches an existing server to this manager.

attach(server: EthermerisServer): (String | Number)

Parameters

server (EthermerisServer) The Ethermeris server to attach

Returns

(String | Number): Returns the server's ID

EthermerisServer

The Ethermeris Server. This class contains the state, networker and event emitter. It is not meant to be used bare. Use the Manager to create servers instead.

new EthermerisServer(settings: ServerSettings)

Parameters

settings (ServerSettings) Ethermeris Server Settings

Instance Members

▸ getState()

Obtains a cloned state.

getState(): Object

Returns

Object: The server's current state.

▸ getWebSocketServer()

Obtains the server's WebSocket server

getWebSocketServer(): WebSocketServer

Returns

WebSocketServer:

▸ getClients()

Returns all clients connected to the server

getClients(): Object<ClientID, ClientConnection>

Returns

Object<ClientID, ClientConnection>:

▸ addCompressor(settings)

Work-In-Progress Method

addCompressor(settings: any)

Parameters

settings (any)

▸ emitToAll(name, data)

Emits an event to all connected clients.

emitToAll(name: (String | Number), data: ...(Object | EthermerisServer~clientModifierCallback)): Boolean

Parameters

name ((String | Number)) The event name

data (...(Object | EthermerisServer~clientModifierCallback)) The event data. Can also be a callback that returns event data.

Returns

Boolean: Returns true on success, false on failure.

▸ on(eventName, listener)

Adds an event handler to the emitter

on(eventName: (String | Number), listener: Function): EventEmitter

Parameters

eventName ((String | Number)) Name of the event to handle.

listener (Function) Event listener to add.

Returns

EventEmitter:

▸ off(eventName, listener)

Removes an event handler to the emitter

off(eventName: (String | Number), listener: Function): EventEmitter

Parameters

eventName ((String | Number)) Name of the event to remove.

listener (Function) Event listener to remove.

Returns

EventEmitter:

▸ once(eventName, listener)

Adds an ephemeral event handler to the emitter that is removed once it's called.

once(eventName: (String | Number), listener: Function): EventEmitter

Parameters

eventName ((String | Number)) Name of the event to handle.

listener (Function) Event listener to add ephemerally.

Returns

EventEmitter:

▸ respond(eventName, listener)

Adds an event responder. It's like an event handler, except only one handler per event and that handler can return a value.

respond(eventName: (String | Number), listener: Function): EventEmitter

Parameters

eventName ((String | Number)) Name of the event to respond to.

listener (Function) Event responder listener to add.

Returns

EventEmitter:

▸ setState(newPartialState, clientModifier?, shallowMerge?)

Sets the state of the server using a partial state, finds the differences between the new state and the old state, then emits those differences to all clients.

setState(newPartialState: Object, clientModifier: EthermerisServer~clientModifierCallback?, shallowMerge: Boolean?)

Parameters

newPartialState (Object) A partial object that gets merged into the main state to update it.

clientModifier (EthermerisServer~clientModifierCallback?) An optional callback Function that is called to modify all diffs for specific clients.

shallowMerge (Boolean?) If set to true, the newPartialState will be merged into the main state by just the parent object keys. Useful for optimization if you already have an entire state to set.

EthermerisServer~clientModifierCallback

Pre-flight per client state difference modifier callback. Its return value will be the new diff to send to the client.

EthermerisServer~clientModifierCallback(client: ClientConnection, differences: Object)

Type: Function

Parameters

client (ClientConnection) The specific client.

differences (Object) The object differences to be modified.

EthermerisClient

The Ethermeris Client. This class contains WebSocket/WebRTC connections, an event emitter, the local state, and responders. This class is only meant to be used on the browser to connect with Ethermeris servers.

new EthermerisClient(settings: ClientSettings)

Parameters

settings (ClientSettings) Ethermeris Client Settings

Instance Members

▸ id

Client ID

Type: Number

▸ ready

Turns true when the client has successfully connected with the server

ready

Type: Boolean

▸ socket

WebSocket Instance - Only used when in WebSocket mode.

socket

Type: [type]

▸ init()

Initiates the client by choosing the best connection method.

init(): EthermerisClient

Returns

EthermerisClient:

▸ destroy()

Destroys this instance and terminates all connections.

destroy(): [type]

Returns

[type]: [description]

▸ on(eventName, listener)

Adds an event handler to the emitter

on(eventName: (String | Number), listener: Function): EventEmitter

Parameters

eventName ((String | Number)) Name of the event to handle.

listener (Function) Event listener to add.

Returns

EventEmitter:

▸ off(eventName, listener)

Removes an event handler to the emitter

off(eventName: (String | Number), listener: Function): EventEmitter

Parameters

eventName ((String | Number)) Name of the event to remove.

listener (Function) Event listener to remove.

Returns

EventEmitter:

▸ once(eventName, listener)

Adds an ephemeral event handler to the emitter that is removed once it's called.

once(eventName: (String | Number), listener: Function): EventEmitter

Parameters

eventName ((String | Number)) Name of the event to handle.

listener (Function) Event listener to add ephemerally.

Returns

EventEmitter:

▸ respond(eventName, callback, listener)

Adds an event responder. It's like an event handler, except only one handler per event and that handler can return a value.

respond(eventName: (String | Number), callback: any, listener: Function): EventEmitter

Parameters

eventName ((String | Number)) Name of the event to respond to.

callback (any)

listener (Function) Event responder listener to add.

Returns

EventEmitter:

▸ emit(name, data)

Sends an event to the server.

emit(name: (String | Number), data: ...Object): Boolean

Parameters

name ((String | Number)) The event name

data (...Object) The event data

Returns

Boolean: Returns true on success, false on fail.

▸ request(eventName, data)

Sends a request to the server and waits for a response.

request(eventName: (String | Number), data: ...Object): Promise

Parameters

eventName ((String | Number)) The name of the event.

data (...Object) The event data

Returns

Promise: Returns a promise that holds the response from the server.

EthermerisClient#disconnection

Disconnection Event.

EthermerisClient#disconnection

Parameters

disconnectionReason (String) The reason for disconnection.

disconnectionCode (Number) The disconnection code.

EthermerisClient#connection

Connection Event.

EthermerisClient#connection

Parameters

initialState (Object) The entire state object of the server.

initialData (Object) An object containing custom initial data

EthermerisServer#connection

Connection Event.

EthermerisServer#connection

Parameters

client (ClientConnection) The connection of the client that just connected.

clientRequestData (Object) Object containing the data that the client sent over in the connection request.

EthermerisServer#disconnection

Disconnection Event.

EthermerisServer#disconnection

Parameters

client (ClientConnection) The dead connection of the client that just disconnected.

ClientConnection

A Server's Client Connection. This class represents a connection to a client on the server. The server can use this class to send events and requests to the client. Not meant to be used bare.

new ClientConnection()

Instance Members

▸ destroy(reason)

Destroys this instance by closing all connections and signalling the parent server to delete it.

destroy(reason: String): Boolean

Parameters

reason

(String
            = "No reason specified.")

The reason for disconnection.

Returns

Boolean: Returns true on success false on fail.

▸ emit(name, data)

Emits an event to the client.

emit(name: (String | Number), data: ...Object): Boolean

Parameters

name ((String | Number)) The event name

data (...Object) The event data

Returns

Boolean: Returns true on success, false on failure.

▸ request(eventName, data)

Sends a request to the client and waits for a response.

request(eventName: (String | Number), data: ...Object): Promise

Parameters

eventName ((String | Number)) The name of the event.

data (...Object) The event data

Returns

Promise: Returns a promise that holds the response from the client.

ServerSettings

Type: Object

Properties

serverID ((String | Number)?) : The ID of the server. Used by the client to select a specific server. An ID is automatically generated if omitted.

stateSchema (Object) : The initial state of the server. No new keys should be added to the state after it is set.

getInitialData (Function) : A callback function that returns the initial data that gets sent to the user on connection.

maxMessagesPerSecond (Number) : The maximum amount of messages per second allowed. The client is automatically disconnected if this threshold is broken.

clientTimeout (Number) : The client will disconnect when this amount of time passes with no messages sent from it.

peerSettings (Object) : The RTCPeerConnection settings object.

RTCPeerConnection for further information on RTCPeerConnection's.

ManagerSettings

Type: Object

Properties

httpServer (NodeHTTPServer) : The Node.js HTTP Server to attach the manager to.

serverRoute (String?) : The root route that the manager uses for all server communications.

ClientSettings

Type: Object

Properties

serverID ((String | Number)?) : The ID of the server that the client is attempting to connect to.

verbose (Boolean?) : If set to true, the client's operations are logged to the console.

forceWebSockets (Boolean?) : Forces the client to use WebSockets.

serverRoute (String?) : Root server route to use when signalling and exchanging candidates.

getInitialData (Function?) : This function gets called if initial data is required to connect to the server.

peerSettings (Object) : The RTCPeerConnection settings object.

RTCPeerConnection for further information on RTCPeerConnection's.