AGServerSocket

id The socket id.

request The Node.js HTTP request which initiated the AGServerSocket handshake - This object is useful for accessing HTTP headers (including cookies) which relate to the current socket.

remoteAddress This socket's client IP address.

state The current state of the socket as a string - Can be socket.CONNECTING, socket.OPEN or socket.CLOSED.

authState The authentication state of the socket as a string. Can be either socket.AUTHENTICATED or socket.UNAUTHENTICATED.

authToken The auth token (as a plain Object) currently associated with the socket. This property will be null if no token is associated with this socket.

CONNECTING 'connecting' - A string constant which represents this socket's connecting state. See state property.

OPEN 'open' - A string constant which represents this socket's open/connected state. See state property.

CLOSED 'closed' - A string constant which represents this socket's closed state. See state property.

AUTHENTICATED 'authenticated' - A string constant which represents this socket's authenticated authState.

UNAUTHENTICATED 'unauthenticated' - A string constant which represents this socket's unauthenticated authState.

'error' This gets triggered when an error occurs on this socket. The object produced by the listener will have an error property

'raw' This gets triggered whenever the client socket on the other side calls socket.send(...). The object produced by the listener will have a message property.

'connect' Triggers when the socket completes the SocketCluster handshake phase and is fully connected. Note that if you capture a socket using the agServer.listener('connection') listener, then the socket-level 'connect' event will already have occurred by that point so you won't be able to capture it on the socket. The 'connect' event can only be handled from a socket which was captured from an agServer.listener('handshake') listener instead. The object produced by the listener will have an id, pingTimeout and isAuthenticated property. If an authentication error occured during the socket handshake phase, the event object will also have an authError property.

'disconnect' Happens when the client becomes disconnected from the server. Note that if the socket becomes disconnected during the SocketCluster handshake stage, then the 'connectAbort' event will be triggered instead. The object produced by the listener will have a code and reason property.

'connectAbort' Happens when the client disconnects from the server before the SocketCluster handshake has completed (I.e. while socket.state was 'connecting'). Note that the 'connectAbort' event can only be triggered during the socket's handshake phase before the server's 'connection' event is triggered. The object produced by the listener will have a code and reason property.

'close' Happens when the client disconnects from the server at any stage of the handshake/connection cycle. Note that this event is a catch-all for both 'disconnect' and 'connectAbort' events. The object produced by the listener will have a code and reason property.

'subscribe' Emitted when the matching client socket successfully subscribes to a channel. The object produced by the listener will have a channel and subscriptionOptions property.

'unsubscribe' Occurs whenever the matching client socket unsubscribes from a channel - This includes automatic unsubscriptions triggered by disconnects. The object produced by the listener will have a channel property.

'badAuthToken' Emitted when the client tries to authenticate itself with an invalid (or expired) token. Note that this event will typically be triggered as part of the socket handshake (before the socket is connected); therefore, it's generally better to listen for the 'badSocketAuthToken' event directly on the server instance instead. The object produced by the listener will have an authError and signedAuthToken property.

'authenticate' Triggers whenever the client becomes authenticated. The object produced by the listener will have an authToken property.

'deauthenticate' Triggers whenever the client becomes unauthenticated. The object produced by the listener will have an oldAuthToken property.

'authStateChange' Triggers whenever the socket's authState changes (e.g. transitions between authenticated and unauthenticated states). The object produced by the listener will have an oldAuthState and newAuthState property.

'message' All data that arrives on this socket is emitted through this event as a string. The object produced by the listener will have a message property.

disconnect([code, data]) Disconnect this socket client. This function accepts two optional arguments: A custom error code (a Number - Ideally between 4100 to 4500) and data (which can be either reason message String or an Object).

listener(eventName)

This method returns an event listener stream for the specified eventName. This object is an asyncIterable which can be consumed with a for-await-of loop.

See basic usage guide for examples of how to consume listener streams. For more advanced usage, see StreamDemux (this is the library which SocketCluster uses to implement listener streams).

closeListener(eventName) This method will signal to all consuming for-await-of loops (for the eventName listener) to break after they have finished iterating over their current backlogs of events.

closeAllListeners() This method will signal to all consuming for-await-of loops for all listeners to break after they have finished consuming their respective backlogs of events.

killListener(eventName) This method will signal to all consuming for-await-of loops for the eventName listener to break immediately and will reset the backpressure for that listener to 0.

killAllListeners() This method will signal to all consuming for-await-of loops for all listeners to break immediately and will reset the aggregate backpressure for all listeners to 0.

receiver(receiverName) This method returns a receiver stream for the specified receiverName. This object is an asyncIterable which can be consumed with a for-await-of loop.

closeReceiver(receiverName) This method will signal to all consuming for-await-of loops (for the receiverName receiver) to break after they have finished iterating over their current backlogs of data.

closeAllReceivers() This method will signal to all consuming for-await-of loops for all receivers to break after they have finished consuming their respective backlogs of data.

killReceiver(receiverName) This method will signal to all consuming for-await-of loops for the receiverName receiver to break immediately and will reset the backpressure for that receiver to 0.

killAllReceivers() This method will signal to all consuming for-await-of loops for all receivers to break immediately and will reset the aggregate backpressure for all receivers to 0.

procedure(procedureName) This method returns a procedure stream for the specified procedureName. This object is an asyncIterable which can be consumed with a for-await-of loop.

closeProcedure(procedureName) This method will signal to all consuming for-await-of loops (for the procedureName procedure) to break after they have finished iterating over their current backlogs of data.

closeAllProcedures() This method will signal to all consuming for-await-of loops for all procedures to break after they have finished consuming their respective backlogs of data.

killProcedure(procedureName) This method will signal to all consuming for-await-of loops for the procedureName procedure to break immediately and will reset the backpressure for that procedure to 0.

killAllProcedures() This method will signal to all consuming for-await-of loops for all procedures to break immediately and will reset the aggregate backpressure for all procedures to 0.

transmit(receiverName, data) Transmit the specified event to the corresponding client side socket receiver. You can pass any JSON-compatible object as data. This method doesn't return anything and doesn't throw or reject.

invoke(procedureName, data) Invoke the specified procedure (RPC) on the corresponding client side socket. You can pass any JSON-compatible object as data. This method returns a Promise. Note that there is a default timeout of 10 seconds to receive a response from the server. You can change this limit by setting ackTimeout when instantiating the client. If the client does not receive a response in time, the returned Promise will reject with a TimeoutError.

send(data, [options]); Send some raw data to the client. This will trigger a 'raw' event on the client which will carry the provided data.

setAuthToken(data, [options])

Authenticate the current socket's client by providing it some token data which you can use to validate their identity and/or access rights. Generally, you should call this method in response to a successful login attempt by the client (I.e. The client has provided a username and password combination which exists in your database).

When you call this method, a JWT (token) containing the specified data will be created and attached to both the current server socket and the client socket on the other side of the connection. This method can be called multiple times to update the token with new data - Avoid modifying the socket.authToken property directly because otherwise, the change will not propagate to the client.

In the simplest case, the data argument to this method would be an object in the form {username: 'bob123'}. For a more complex use case, you could also store a list of authorized channel names inside the token (that way, you will be able to check access privileges directly from the socket's token instead of having to read the database every time).

The optional options argument is an Object which can be used to modify the token's behavior - Valid properties include any option accepted by the node-jsonwebtoken library's sign method. See the list of options here. Note that if you use a different algorithm than the default 'HS256', you may need to provide an authPrivateKey and authPublicKey instead of the default authKey. See authKey, authPrivateKey and authPublicKey options in AGServer constructor here.

Using auth tokens has the following advantages:

• The user doesn't need to login again if their socket loses its connection - Works well with SocketCluster's auto-reconnect feature.
• An auth token is shared between sockets across multiple tabs in a browser (under the same domain name). If a user logs in on one tab, they will automatically be authenticated on any other tab that they have open. Tokens therefore allow you to attach a user's identity to multiple sockets.

deauthenticate() Disassociate the current socket from its auth token. This method will also tell the client socket to remove the token from the browser's cookies. This is useful for logging out the user.

kickOut([channel, message]) Forcibly unsubscribe this socket from the specified channel. It's also possible to provide an array of channel names. All arguments are optional - If no channel name is provided, it will unsubscribe this socket from all channels. In addition, the client side of this socket will emit a 'kickOut' event to signify that it was kicked out of the channel. Note that this doesn't prevent the client from resubscribing to that channel later. You will need to update your middleware if you want to achieve this.

subscriptions() Returns an array of active channel subscriptions which this socket's client is bound to.

isSubscribed(channelName) Check if socket is subscribed to channelName.

getBackpressure() Returns the aggregate backpressure for all streams associated with the socket.

getInboundBackpressure() Returns the aggregate backpressure for the socket's inbound stream.

getOutboundBackpressure() Returns the aggregate backpressure for the socket's outbound stream.

getAllListenersBackpressure() Returns the aggregate backpressure for the socket's event listener streams.

getListenerBackpressure(eventName) Get the aggregate backpressure for the eventName listener stream on the current socket. The aggregate backpressure represents the highest backpressure of all consumers for that listener.

getAllReceiversBackpressure() Returns the aggregate backpressure for the socket's receiver streams.

getAllProceduresBackpressure() Returns the aggregate backpressure for the socket's procedure streams.

getListenerConsumerStatsList(eventName) Get the list of consumers which are consuming data from the specified event listener. This method returns a list of objects which have an id and backpressure property.

getAllListenersConsumerStatsList() Get the list of all consumers which are consuming data from any listener on the socket. This method returns a list of objects which have an id and backpressure property.

killListenerConsumer(consumerId) This will cause the target listener consumer's for-await-of loop to break immediately.

getReceiverConsumerStatsList(receiverName) Get the list of consumers which are consuming data from the specified receiver. This method returns a list of objects which have an id and backpressure property.

getAllReceiversConsumerStatsList() Get the list of all consumers which are consuming data from all receivers on the socket. This method returns a list of objects which have an id and backpressure property.

killReceiverConsumer(consumerId) This will cause the target receiver consumer's for-await-of loop to break immediately.

getProcedureConsumerStatsList(procedureName) Get the list of consumers which are consuming data from the specified procedure. This method returns a list of objects which have an id and backpressure property.

getAllProceduresConsumerStatsList() Get the list of all consumers which are consuming data from all procedures on the socket. This method returns a list of objects which have an id and backpressure property.

killProcedureConsumer(consumerId) This will cause the target procedure consumer's for-await-of loop to break immediately.