API.md

Classes

ObjectBuffer ⇐ EventEmitter

Object Buffer

de/serialize objects to/from a Buffer

Automatically reassembles fragmented buffers (useful when the buffer passes through a socket, for example, and is received in pieces) and gives you your object back

SockhopClient ⇐ EventEmitter

Wrapped TCP client

SockhopError ⇐ Error

Custom sockhop errors

Error types, should only change with major versions

• ERR_MULTICONNECT : attempting to call connect while a socket is already connecting
• ERR_SOCKET_DESTROYED : attempting to interact with a destroyed socket
• ERR_REMOTE_CALLBACK_TYPE : attempting to use remote callbacks with wrong message types, or not a callback function
• ERR_REQUEST_TYPE : attempting to use requests with wrong message types
• ERR_NO_SOCKET : attempting to send a message with no socket
• ERR_BAD_DATA : attempting to send a message with no data payload
• ERR_OBJECTBUFFER_BAD_BUFFER : attempting to do a buffer operation with a non-buffer
• ERR_OBJECTBUFFER_BAD_BUFFER_DATA : attempting to do a buffer operation with bad data in the buffer
• ERR_OBJECTBUFFER_BAD_OBJECT : attempting to do an object operation with a non-serializable object
• ERR_RESPONSE_TIMEOUT : the response timed out
• ERR_RESPONSE_SEND : the response could not be sent

SockhopPing

TCP Ping

Used internally when .ping() is called

SockhopPong

TCP Ping reply

Used internally when .ping() is replied

SockhopRequest

A SockhopRequest object

This is used (primarially internally) to wrap requests to the peer connection, and for them to generate and return SockhopResponses.

On the "requester-side" this object is never actually touched by the user, it is auto-generated by the .request(...) method. On the "responder-side", a copy of this object is emitted by the request event, which the responder can use to de-payload the request via the .type and .data attributes.

SockhopResponsePacket

A SockhopResponsePacket object

These are used internally to pass back responses to requests

SockhopResponseReadableStream ⇐ EventEmitter

A SockhopResponseReadableStream object

This is used by the requester to catch all the response packets that the responder is sending back, it functions vaguely like an ReadableStream from the core library, but is not yet fully featured for that.

SockhopResponseWriteableStream

A SockhopResponseWriteableStream object

This is used by the responder to stream out all the response packets to the requester, it functions vaguely like an WriteableStream from the core library, but is not yet fully featured for that.

SockhopServer ⇐ EventEmitter

Wrapped TCP server

When data is received by the server, the received Buffer is concatenated with previously received Buffers until a delimiter (usually "\n") is received. The composite Buffer is then treated like a JSON string and converted to an object, which is triggers a "receive" event. If the client is a SockhopClient, it will further wrap sent data in metadata that describes the type - this allows you to pass custom objects (prototypes) across the wire, and the other end will know it has received your Widget, or Foo, or whatever. Plain objects, strings, etc. are also similarly labelled. The resulting receive event has a "meta" parameter; meta.type will list the object type.

Of course, if your client is not a SockhopClient, you don't want this wrapping/unwrapping behavior and you might want a different delimiter for JSON. Both these parameters are configurable in the constructor options.

SockhopSession ⇐ EventEmitter

Base class wrapper for server-side sockets

When a new connection is received by the server, the server will wrap that socket with an instance of this (or child of this) class -- configurable with the session_type option in the server's constructor. This class allows for arbitrary user-data to be assigned to the clients (for example, authentication state information) without having to abuse the underlying net.Socket object.

This class does almost nothing, apart from holding internal references to the net.Socket and SockhopServer instances, and is really intended to be extended. As such, there are several 'virtual' methods included here, which users are encouraged to implement for their specific application.

Sessions are the preferred way for users to interact with client connections, in that users should write child classes which inhert from this base class to interact with the net.Socket instance, and then have their applications call the session methods, rather than calling socket methods directly. For instance, users are discouraged from directly calling socket.end() to terminate clients connection from the server. Rather, users should call session.kill().

TimedMap

A timed map object

This is a wrapper around a map, which keeps a timer going to automatically remove values that have been present for too long.

Typedefs

ResponsePacketPayload : object

ObjectBuffer ⇐ EventEmitter

Object Buffer

de/serialize objects to/from a Buffer

Automatically reassembles fragmented buffers (useful when the buffer passes through a socket, for example, and is received in pieces) and gives you your object back

Kind: global class
Extends: EventEmitter

• ObjectBuffer ⇐ EventEmitter
  • new ObjectBuffer(opts)
  • .buf2obj(buffer) ⇒ Array
  • .obj2buf(object, buffer)

new ObjectBuffer(opts)

Constructs a new ObjectBuffer

Param	Type	Default	Description
opts	object		the options
[opts.terminator]	string | array	""\n""	the terminator to signal the end of a JSON object. If an array is given, the first element is a receive (buf2obj) terminator and the second is the transmit (obj2buf) element
[opts.allow_non_objects]	boolean	false	allow non objects in buf2obj (will be passed through as Strings)

objectBuffer.buf2obj(buffer) ⇒ Array

buf2obj

Convert a Buffer into one or more objects

Kind: instance method of ObjectBuffer
Returns: Array - found the objects we found

Param	Type	Description
buffer	Buffer	the buffer to read (we may modify or store it!)

objectBuffer.obj2buf(object, buffer)

obj2buf

Convert an Object to a Buffer

Kind: instance method of ObjectBuffer

Param	Type	Description
object	Object	the object to convert
buffer	Buffer	the buffer representing that object

SockhopClient ⇐ EventEmitter

Wrapped TCP client

Kind: global class
Extends: EventEmitter
Emits: connect, disconnect, receive, request, event:SockhopError

• SockhopClient ⇐ EventEmitter
  • new SockhopClient([opts])
  • .connected ⇒ boolean
  • .auto_reconnect ⇒ boolean
  • .auto_reconnect
  • .socket : net.socket
  • ._perform_auto_reconnect()
  • .connect() ⇒ Promise
  • .get_bound_address() ⇒ string
  • .send(object, [rcallback]) ⇒ Promise
  • .request(object, config) ⇒ Promise.<SockhopResponseReadableStream>
  • .ping(delay)
  • .disconnect() ⇒ Promise
  • "connect" (sock)
  • "receive" (object, meta)
  • "request" (req, res)
  • "disconnect" (sock)

new SockhopClient([opts])

Constructs a new SockhopClient

Param	Type	Default	Description
[opts]	object		an object containing configuration options
[opts.path]	string		the path for a Unix domain socket. If used, this will override the address and port values.
[opts.address]	string	""127.0.0.1""	the IP address to bind to
[opts.port]	number	50000	the TCP port to use
[opts.ssl]	boolean	false	use tls
[opts.ssl_options]	object	{}	options to pass to the tls socket constructor, see tls.connect for details, note, if any options are provided, the opts.ssl flag is overriden as true
[opts.auto_reconnect_interval]	number	2000	the auto reconnection interval, in ms.
opts.peer_type	string		the type of client to expect. Defaults to "Sockhop" and expects wrapped JSON objects. Set to "json" to expect and deliver raw JSON objects
[opts.terminator]	string | array	""\n""	the JSON object delimiter. Passed directly to the ObjectBuffer constructor.
[opts.allow_non_objects]	boolean	false	allow non objects to be received and transmitted. Passed directly to the ObjectBuffer constructor.
[opts.response_timeout]	number		the length of time in ms that this map should hold values by default

sockhopClient.connected ⇒ boolean

connected

Kind: instance property of SockhopClient
Returns: boolean - connected whether or not we are currently connected

sockhopClient.auto_reconnect ⇒ boolean

auto_reconnect getter

Kind: instance property of SockhopClient
Returns: boolean - auto_reconnect the current auto_reconnect setting

sockhopClient.auto_reconnect

auto_reconnect setter

Kind: instance property of SockhopClient

Param	Type	Description
auto_reconnect	boolean	the desired auto_reconnect setting

sockhopClient.socket : net.socket

Underlying net.socket

Kind: instance property of SockhopClient

sockhopClient._perform_auto_reconnect()

Perform an auto reconnet (internal)

We have determined that an auto reconnect is necessary. We will initiate it, and manage the fallout.

Kind: instance method of SockhopClient

sockhopClient.connect() ⇒ Promise

Connect

Connect to the server If you want to quietly start an auto_reconnect sequence to an unavailable server, just set .auto_reconnect=true. Calling this directly will get you a Promise rejection if you are not able to connect the first time. N.B.: The internals of net.socket add their own "connect" listener, so we can't rely on things like sock.removeAllListeners("connect") or sock.listenerCount("connect") here

Kind: instance method of SockhopClient

sockhopClient.get_bound_address() ⇒ string

Get bound address

Kind: instance method of SockhopClient
Returns: string - the IP address we are bound to

sockhopClient.send(object, [rcallback]) ⇒ Promise

Send

Send an object to the server

Kind: instance method of SockhopClient
Throws:

• SockhopError

Param	Type	Description
object	object	to be sent over the wire
[rcallback]	function	Callback when remote side calls meta.callback (see receive event) - this is basically a remote Promise

sockhopClient.request(object, config) ⇒ Promise.<SockhopResponseReadableStream>

Make a request

Send a request to the server

Kind: instance method of SockhopClient
Throws:

• SockhopError

Param	Type	Description
object	object	to be sent over the wire
config	object
[config.timeout]	number

sockhopClient.ping(delay)

Ping

Send ping, detect timeouts. If we have 4 timeouts in a row, we kill the connection and emit a 'disconnect' event. You can then call .connect() again to reconnect.

Kind: instance method of SockhopClient

Param	Type	Default	Description
delay	number	0	in ms (0 disables ping)

sockhopClient.disconnect() ⇒ Promise

disconnect

Disconnect the socket (send FIN) Pinging will also be turned off... if you want to keep pinging, you will need to call .ping() again after you connect again

Kind: instance method of SockhopClient

"connect" (sock)

connect event

Kind: event emitted by SockhopClient

Param	Type	Description
sock	net.Socket	the socket that just connected

"receive" (object, meta)

receive object event

We have successfully received an object from the server

Kind: event emitted by SockhopClient

Param	Type	Description
object	object	the received object
meta	object	metadata
meta.type	string	the received object constructor ("Object", "String", "Widget", etc)

"request" (req, res)

receive request event

We have successfully received a request object from the client

Kind: event emitted by SockhopClient

Param	Type
req	SockhopRequest
res	SockhopResponseWriteableStream

"disconnect" (sock)

disconnect event

Kind: event emitted by SockhopClient

Param	Type	Description
sock	net.Socket	the socket that just disconnected

SockhopError ⇐ Error

Custom sockhop errors

Error types, should only change with major versions

• ERR_MULTICONNECT : attempting to call connect while a socket is already connecting
• ERR_SOCKET_DESTROYED : attempting to interact with a destroyed socket
• ERR_REMOTE_CALLBACK_TYPE : attempting to use remote callbacks with wrong message types, or not a callback function
• ERR_REQUEST_TYPE : attempting to use requests with wrong message types
• ERR_NO_SOCKET : attempting to send a message with no socket
• ERR_BAD_DATA : attempting to send a message with no data payload
• ERR_OBJECTBUFFER_BAD_BUFFER : attempting to do a buffer operation with a non-buffer
• ERR_OBJECTBUFFER_BAD_BUFFER_DATA : attempting to do a buffer operation with bad data in the buffer
• ERR_OBJECTBUFFER_BAD_OBJECT : attempting to do an object operation with a non-serializable object
• ERR_RESPONSE_TIMEOUT : the response timed out
• ERR_RESPONSE_SEND : the response could not be sent

Kind: global class
Extends: Error

new SockhopError(message, code)

Constructs a new SockhopError

Param	Type	Description
message	string	A message string describing the error
code	string	A standardized code for filtering error types

SockhopPing

TCP Ping

Used internally when .ping() is called

Kind: global class

• SockhopPing
  • .unanswered() ⇒ boolean
  • .conclude_with_pong(pong)

sockhopPing.unanswered() ⇒ boolean

Unanswered

Is this ping Unanswered?

Kind: instance method of SockhopPing

sockhopPing.conclude_with_pong(pong)

Conclude a ping

Sets the returned, finished values

Kind: instance method of SockhopPing

Param	Type	Description
pong	SockhopPong	the pong (ping reply) that is finishing this ping

SockhopPong

TCP Ping reply

Used internally when .ping() is replied

Kind: global class

SockhopRequest

A SockhopRequest object

This is used (primarially internally) to wrap requests to the peer connection, and for them to generate and return SockhopResponses.

On the "requester-side" this object is never actually touched by the user, it is auto-generated by the .request(...) method. On the "responder-side", a copy of this object is emitted by the request event, which the responder can use to de-payload the request via the .type and .data attributes.

Kind: global class

• SockhopRequest
  • new SockhopRequest([opts])
  • .parse(obj) ⇒ SockhopRequest
  • .from_data(data) ⇒ SockhopRequest

new SockhopRequest([opts])

Constructor

Param	Type	Default	Description
[opts]	object		an object containing configuration options
[opts.uuid]	string		the identifier of this request/response pair (default is autogenerated)
[opts.data]	*	{}	the data of this request
[opts.type]	string		the type (class-name) of the data (default is autogenerated)

SockhopRequest.parse(obj) ⇒ SockhopRequest

Parse a serialized SockhopRequest

Kind: static method of SockhopRequest

Param	Type	Description
obj	object	the serialized request object

SockhopRequest.from_data(data) ⇒ SockhopRequest

Create a request from a new data payload

Kind: static method of SockhopRequest

Param	Type	Description
data	*	the object to be included as a payload

SockhopResponsePacket

A SockhopResponsePacket object

These are used internally to pass back responses to requests

Kind: global class

• SockhopResponsePacket
  • new SockhopResponsePacket([opts])
  • .parse(obj) ⇒ SockhopRequest
  • .for_data(data, uuid, [last]) ⇒ SockhopRequest

new SockhopResponsePacket([opts])

Constructor

Param	Type	Default	Description
[opts]	object		an object containing configuration options
[opts.uuid]	string		the identifier of this request/response pair (default is autogenerated)
[opts.data]	*	{}	the data of this request
[opts.type]	string		the type (class-name) of the data (default is autogenerated)

SockhopResponsePacket.parse(obj) ⇒ SockhopRequest

Parse a serialized SockhopResponsePacket

Kind: static method of SockhopResponsePacket

Param	Type	Description
obj	object	the serialized response object

SockhopResponsePacket.for_data(data, uuid, [last]) ⇒ SockhopRequest

Create a response packet from a data object

Kind: static method of SockhopResponsePacket

Param	Type	Default	Description
data	*		data payload
uuid	string		the uuid for this packet
[last]	boolean	false	flag indicating this is the last packet in the stream

SockhopResponseReadableStream ⇐ EventEmitter

A SockhopResponseReadableStream object

This is used by the requester to catch all the response packets that the responder is sending back, it functions vaguely like an ReadableStream from the core library, but is not yet fully featured for that.

Kind: global class
Extends: EventEmitter
Emits: data, end

• SockhopResponseReadableStream ⇐ EventEmitter
  • new SockhopResponseReadableStream([opts])
  • instance
    • .ended : boolean
    • .receive_packet(pkt)
    • .end([err])
    • .next() ⇒ Promise.<ResponsePacketPayload>
    • .all() ⇒ Promise.<Array.<ResponsePacketPayload>>
    • "data" (data, type)
    • "end" ([err])
  • static
    • .from_request(req) ⇒ SockhopResponseStream

new SockhopResponseReadableStream([opts])

Constructor

Param	Type	Description
[opts]	object	an object containing configuration options
[opts.uuid]	string	the identifier of this request/response pair (default is autogenerated)

sockhopResponseReadableStream.ended : boolean

Flag indicating if the stream has ended

Kind: instance property of SockhopResponseReadableStream

sockhopResponseReadableStream.receive_packet(pkt)

Handle received packets

Kind: instance method of SockhopResponseReadableStream
Emits: data, end

Param	Type
pkt	SockhopResponsePacket

sockhopResponseReadableStream.end([err])

End this stream

Kind: instance method of SockhopResponseReadableStream

Param	Type	Description
[err]	SockhopError	optional error for why the stream was ended, no error means graceful ending

sockhopResponseReadableStream.next() ⇒ Promise.<ResponsePacketPayload>

Wait for the next packet to arrive, then close the stream

Kind: instance method of SockhopResponseReadableStream

sockhopResponseReadableStream.all() ⇒ Promise.<Array.<ResponsePacketPayload>>

Wait for all packets

Kind: instance method of SockhopResponseReadableStream

"data" (data, type)

A packet of data has arrived

Kind: event emitted by SockhopResponseReadableStream

Param	Type	Description
data	*	the serialized payload from the responder
type	string	The type (class name) of the data

"end" ([err])

The stream has ended

Kind: event emitted by SockhopResponseReadableStream

Param	Type	Description
[err]	SockhopError	if the stream was ended due to an error, it will show up here

SockhopResponseReadableStream.from_request(req) ⇒ SockhopResponseStream

Create a response readable stream for use by requester

Kind: static method of SockhopResponseReadableStream

Param	Type
req	SockhopRequest

SockhopResponseWriteableStream

A SockhopResponseWriteableStream object

This is used by the responder to stream out all the response packets to the requester, it functions vaguely like an WriteableStream from the core library, but is not yet fully featured for that.

Kind: global class

• SockhopResponseWriteableStream
  • new SockhopResponseWriteableStream([opts], sockhop)
  • instance
    • .send(data) ⇒ Promise
    • .write(data) ⇒ Promise
    • .end() ⇒ Promise
  • static
    • .from_request(req_obj, sockhop) ⇒ SockhopResponseStream

new SockhopResponseWriteableStream([opts], sockhop)

Constructor

Param	Type	Description
[opts]	object	an object containing configuration options
[opts.uuid]	string	the identifier of this request/response pair (default is autogenerated)
sockhop	SockhopClient | SockhopSession	A reference to the sockhop object which will be used to return the finished response

sockhopResponseWriteableStream.send(data) ⇒ Promise

Send a reponse packet back to the peer connection, closing the stream

Kind: instance method of SockhopResponseWriteableStream
Returns: Promise - resolves on message send
Throws:

• SockhopError

Param	Type	Description
data	*	The payload to send back to the requester

sockhopResponseWriteableStream.write(data) ⇒ Promise

Send this response back to the peer connection, keeping the stream open

Kind: instance method of SockhopResponseWriteableStream
Returns: Promise - resolves on message send
Throws:

• SockhopError

Param	Type	Description
data	*	The payload to send back to the requester

sockhopResponseWriteableStream.end() ⇒ Promise

Closing the stream, notifying the requester

Kind: instance method of SockhopResponseWriteableStream
Returns: Promise - resolves on message send
Throws:

• SockhopError

SockhopResponseWriteableStream.from_request(req_obj, sockhop) ⇒ SockhopResponseStream

Create a response object from a received request object

Kind: static method of SockhopResponseWriteableStream

Param	Type	Description
req_obj	object	the serialized request object
sockhop	SockhopClient | SockhopSession	a reference to the sockhop object used to send back response packets

SockhopServer ⇐ EventEmitter

Wrapped TCP server

When data is received by the server, the received Buffer is concatenated with previously received Buffers until a delimiter (usually "\n") is received. The composite Buffer is then treated like a JSON string and converted to an object, which is triggers a "receive" event. If the client is a SockhopClient, it will further wrap sent data in metadata that describes the type - this allows you to pass custom objects (prototypes) across the wire, and the other end will know it has received your Widget, or Foo, or whatever. Plain objects, strings, etc. are also similarly labelled. The resulting receive event has a "meta" parameter; meta.type will list the object type.

Of course, if your client is not a SockhopClient, you don't want this wrapping/unwrapping behavior and you might want a different delimiter for JSON. Both these parameters are configurable in the constructor options.

Kind: global class
Extends: EventEmitter
Emits: connect, disconnect, receive, request, event:SockhopError

• SockhopServer ⇐ EventEmitter
  • new SockhopServer([opts])
  • .sockets : Array.<net.Socket>
  • .sessions : Array.<SockhopSession>
  • .emit_async()
  • .ping(delay)
  • .listen() ⇒ Promise.<net.server>
  • .get_bound_address() ⇒ string
  • .send(socket, object, [callback]) ⇒ Promise
  • .request(sock, object, config) ⇒ Promise.<SockhopResponseReadableStream>
  • .sendall(object) ⇒ Promise
  • .kill_socket(sock) ⇒ Promise
  • .disconnect() ⇒ Promise
  • .close() ⇒ Promise
  • "connect" (sock, session)
  • "receive" (object, meta)
  • "request" (req, res, meta)
  • "disconnect" (sock, session)

new SockhopServer([opts])

Constructs a new SockhopServer

Param	Type	Default	Description
[opts]	object		an object containing configuration options
[opts.path]	string		the path for a Unix domain socket. If used, this will override the address and port values.
[opts.address]	string	""127.0.0.1""	the IP address to bind to
[opts.port]	number	50000	the TCP port to use
[opts.auto_reconnect_interval]	number	2000	the auto reconnection interval, in ms.
[opts.terminator]	string | array	""\n""	the JSON object delimiter. Passed directly to the ObjectBuffer constructor.
[opts.allow_non_objects]	boolean	false	allow non objects to be received and transmitted. Passed directly to the ObjectBuffer constructor.
[opts.peer_type]	string	""SockhopClient""	the type of client to expect. Defaults to "SockhopClient" and expects wrapped JSON objects. Set to "json" to expect and deliver raw JSON objects
[opts.session_type]	Object	SockhopSession	the identifier for a SockhopSession class (or inhereted class)
[opts.response_timeout]	number		the length of time in ms that this map should hold values by default

sockhopServer.sockets : Array.<net.Socket>

Socket getter

Kind: instance property of SockhopServer

sockhopServer.sessions : Array.<SockhopSession>

Session getter

Kind: instance property of SockhopServer

sockhopServer.emit_async()

Emit async

We end up with odd event loops sometimes, e.g. if an on("disconnect") calls .sendall(), another "disconnect" will be emitted. This functon emits evens asynchronously and breaks the chain //HACK -- THIS IS A HACKY FIX -- //HACK

Kind: instance method of SockhopServer

sockhopServer.ping(delay)

Ping

Ping all clients, detect timeouts. Only works if connected to a SockhopClient.

Kind: instance method of SockhopServer

Param	Type	Default	Description
delay	number	0	in ms (0 disables ping)

sockhopServer.listen() ⇒ Promise.<net.server>

Listen

Bind and wait for incoming connections

Kind: instance method of SockhopServer

sockhopServer.get_bound_address() ⇒ string

Get bound address

Kind: instance method of SockhopServer
Returns: string - the IP address we are bound to

sockhopServer.send(socket, object, [callback]) ⇒ Promise

Send

Send an object to one clients

Kind: instance method of SockhopServer
Throws:

• SockhopError

Param	Type	Description
socket	net.socket	on which to send it
object	object	that we want to send
[callback]	function	Callback when remote side calls meta.done (see receive event) - this is basically a remote Promise

sockhopServer.request(sock, object, config) ⇒ Promise.<SockhopResponseReadableStream>

Make a request

Send a request to the server

Kind: instance method of SockhopServer
Throws:

• SockhopError

Param	Type	Description
sock	net.socket
object	object	to be sent over the wire
config	object
[config.timeout]	number

sockhopServer.sendall(object) ⇒ Promise

Sendall

Send an object to all clients

Kind: instance method of SockhopServer

Param	Type	Description
object	object	to send to all connected clients

sockhopServer.kill_socket(sock) ⇒ Promise

Stops a client connection

Kind: instance method of SockhopServer

Param	Type	Description
sock	net.Socket	the client socket to kill

sockhopServer.disconnect() ⇒ Promise

Disconnect

Disconnect all clients Does not close the server - use close() for that

Kind: instance method of SockhopServer
Returns: Promise - resolves when all sockets are killed

sockhopServer.close() ⇒ Promise

Close

Disconnects any clients and closes the server

Kind: instance method of SockhopServer
Returns: Promise - resovles when all sockets are killed and the server closed

"connect" (sock, session)

connect event

Kind: event emitted by SockhopServer

Param	Type	Description
sock	net.Socket	the socket that just connected
session	SockhopSession	the session of the socket

"receive" (object, meta)

receive object event

We have successfully received an object from the client

Kind: event emitted by SockhopServer

Param	Type	Description
object	object	the received object
meta	object	metadata
meta.type	string	the received object constructor ("Object", "String", "Widget", etc)
meta.socket	net.Socket	the socket that sent us this object
meta.session	SockhopSession	the session of the socket
[meta.callback]	function	the callback function, if the client is requesting a callback. Pass an object you want returned to the client

"request" (req, res, meta)

receive request event

We have successfully received a request object from the client

Kind: event emitted by SockhopServer

Param	Type	Description
req	SockhopRequest
res	SockhopResponseWriteableStream
meta	object	metadata
meta.socket	net.Socket	the socket that sent us this object
meta.session	SockhopSession	the session of the socket

"disconnect" (sock, session)

disconnect event

Kind: event emitted by SockhopServer

Param	Type	Description
sock	net.Socket	the socket that just disconnected
session	SockhopSession	the session of the socket

SockhopSession ⇐ EventEmitter

Base class wrapper for server-side sockets

When a new connection is received by the server, the server will wrap that socket with an instance of this (or child of this) class -- configurable with the session_type option in the server's constructor. This class allows for arbitrary user-data to be assigned to the clients (for example, authentication state information) without having to abuse the underlying net.Socket object.

This class does almost nothing, apart from holding internal references to the net.Socket and SockhopServer instances, and is really intended to be extended. As such, there are several 'virtual' methods included here, which users are encouraged to implement for their specific application.

Sessions are the preferred way for users to interact with client connections, in that users should write child classes which inhert from this base class to interact with the net.Socket instance, and then have their applications call the session methods, rather than calling socket methods directly. For instance, users are discouraged from directly calling socket.end() to terminate clients connection from the server. Rather, users should call session.kill().

Kind: global class
Extends: EventEmitter

• SockhopSession ⇐ EventEmitter
  • new SockhopSession(sock, server)
  • .sock : net.Socket
  • .server : SockhopServer
  • .send(obj) ⇒ Promise
  • .request(obj, config) ⇒ Promise.<SockhopResponseReadableStream>
  • .kill() ⇒ Promise
  • .start() ⇒ Promise
  • .end() ⇒ Promise

new SockhopSession(sock, server)

Constructor

By default, I just save references to the socket and the server

Param	Type	Description
sock	net.Socket	the socket object
server	SockhopServer	a reference to the SockhopServer

sockhopSession.sock : net.Socket

Getter for the underlying session socket

Kind: instance property of SockhopSession

sockhopSession.server : SockhopServer

Getter for the server

Kind: instance property of SockhopSession

sockhopSession.send(obj) ⇒ Promise

Send a message over this session

Kind: instance method of SockhopSession
Returns: Promise - resolves on send
Throws:

• SockhopError

Param	Type
obj	object

sockhopSession.request(obj, config) ⇒ Promise.<SockhopResponseReadableStream>

Send a request over this session

Kind: instance method of SockhopSession
Returns: Promise.<SockhopResponseReadableStream> - resolves to peer response
Throws:

• SockhopError

Param	Type
obj	object
config	object

sockhopSession.kill() ⇒ Promise

Kill this session

Kind: instance method of SockhopSession
Returns: Promise - resolves on socket end

sockhopSession.start() ⇒ Promise

Start this session

Override me to do any setup of the session.

I get called internally by the SockhopServer immediately after a new client connects to the server, before the server emits the 'connect' event. (before even the socket gets registered in the server's server._sockets list).

Kind: instance abstract method of SockhopSession
Returns: Promise - resolves when setup is complete

sockhopSession.end() ⇒ Promise

End this session

Override me to do any teardown of the session

I get called internally by the SockhopServer immediately after the client's socket emits the 'end' event, and when I resolve, I then trigger the server to emit the 'disconnect' event.

Kind: instance abstract method of SockhopSession
Returns: Promise - resolves when teardown is complete

TimedMap

A timed map object

This is a wrapper around a map, which keeps a timer going to automatically remove values that have been present for too long.

Kind: global class

• TimedMap
  • new TimedMap([opts])
  • .set(key, value, cb, [timeout])
  • .get(key) ⇒ *
  • .delete(key)
  • .stop()

new TimedMap([opts])

Constructor

Param	Type	Description
[opts]	object	an object containing configuration options
[opts.timeout]	number	the length of time in ms that this map should hold values by default

timedMap.set(key, value, cb, [timeout])

Insert a new value

Kind: instance method of TimedMap

Param	Type	Description
key	*
value	*
cb	function	callback for when the value is returned, giving you the reason. Signature: (reason) => {}
[timeout]	number

timedMap.get(key) ⇒ *

Get a value

Kind: instance method of TimedMap

Param	Type
key	*

timedMap.delete(key)

Remove a value, also trigger the callback

Kind: instance method of TimedMap

Param	Type
key	*

timedMap.stop()

Remove all values, also trigger the callback

Kind: instance method of TimedMap

ResponsePacketPayload : object

Kind: global typedef
Properties

Name	Type
data	*
type	string