AGClientSocket

id The id of the socket connection. This is null initially and will change each time a new underlying connection is made.

clientId The id of the socket client. This does not change between connections.

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

pendingReconnect A boolean which indicates if the socket is about to be automatically reconnected.

pendingReconnectTimeout The number of milliseconds until the next reconnection attempt is executed.

connectAttempts The number of automatic connect/reconnect attempts which the socket has executed (including the current latest attempt). This value resets upon a successful connection.

authState The last known authentication state of the socket as a string. Can be either 'authenticated' (socket.AUTHENTICATED) or 'unauthenticated' (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.

signedAuthToken The signed auth token currently associated with the socket (encoded and signed in the JWT format). 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 which contains an error object.

'connect'

Emitted whenever the socket connects to the server (includes reconnections). The object produced by the listener will have an id, isAuthenticated, authToken, pingTimeout and processPendingSubscriptions property. If an issue occurred as part of the handshake, there will also be an authError property which will hold an error object.

The processPendingSubscriptions property represents a callback function which, when called, will send all pending channel subscriptions to the server (to activate pending channels). Note that this processPendingSubscriptions callback will only work if the client socket.options.autoSubscribeOnConnect option is set to false. See SocketCluster client API.

'disconnect' Happens when this socket becomes disconnected from the server. The object produced by the listener will have a code and reason property.

'connectAbort' Triggers when a new connection is aborted for whatever reason - This could be caused by a failure during the connection phase or it may be triggered intentionally by calling socket.disconnect() while the socket is connecting. The object produced by the listener will have a code and reason property.

'close' Triggers when a socket is disconnected or the connection is aborted - This is a catch-all event for both 'disconnect' and 'connectAbort'. The object produced by the listener will have a code and reason property.

'connecting' Triggers whenever the socket initiates a connection to the server - This includes reconnects. In order capture the very first 'connecting' event, you will need to set the initial autoConnect option to false when you create the socket with socketClusterClient.create(...) - You will need to register the handler before you call socket.connect().

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

'kickOut' Occurs when this socket is kicked out of a channel by the backend. The object produced by the listener will have a channel and message property.

'subscribe' When the subscription succeeds. The object produced by the listener will have a channel and subscriptionOptions property.

'subscribeFail' Happens when the subscription fails. The object produced by the listener will have an error, channel and subscriptionOptions property.

'unsubscribe' When the socket becomes unsubscribed from a channel. The object produced by the listener will have a channel property.

'authStateChange' Triggers whenever the client's authState changes between socket.AUTHENTICATED and socket.UNAUTHENTICATED states. The object produced by the listener will have at least two properties: oldAuthState and newAuthState. If newAuthState is 'authenticated', the object will also have an additional signedAuthToken property which will be the base64 signed JWT auth token as a string and an authToken property which will represent the token as a plain Object.

'subscribeStateChange' Triggers whenever a pub/sub channel's state transitions between 'pending', 'subscribed' and 'unsubscribed' states. The object produced by the listener will have a channel, oldChannelState, newChannelState and subscriptionOptions property.

'subscribeRequest' Emits the channel name when a subscribe action is invoked by the client. The object produced by the listener will have a channel and subscriptionOptions property.

'authenticate' Triggers whenever the client is successfully authenticated by the server. The object produced by the listener will have a signedAuthToken and authToken property.

'deauthenticate' Triggers whenever the client becomes unauthenticated. The object produced by the listener will have a oldSignedAuthToken and oldAuthToken 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.

connect() Connects/reconnects the client socket to its origin server.

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.

disconnect([code, data]) Disconnect this socket from the server. 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).

transmit(receiverName, data) Transmit the specified event to the corresponding server 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 server 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 server. This will trigger a 'raw' event on the server side which will carry the provided data.

authenticate(encryptedTokenString) Perform client-initiated authentication - This is useful if you already have a valid encrypted auth token string and would like to use it to authenticate directly with the server (without having to ask the user for login details). Typically, you should perform server-initiated authentication using the socket.setAuthToken() method from the server side. This method is useful if, for example, you received the token from a different browser tab via localStorage and you want to immediately authenticate the current socket without having to reconnect the socket. It may also be useful if you're getting the token from a third-party JWT-based system and you're using the same authKey (see the authKey option passed to the AGServer constructor). This method returns a Promise which resolves on success and rejects with an Error on failure (e.g. if the token was invalid).

deauthenticate() Perform client-initiated deauthentication - Deauthenticate (logout) the current socket.

getBackpressure() Get the aggregate backpressure for all streams on the current socket. The aggregate backpressure represents the highest backpressure of all consumers.

getAllListenersBackpressure() Get the aggregate backpressure of all listener streams on the current socket.

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() Get the aggregate backpressure of all receiver streams on the current socket.

getAllProceduresBackpressure() Get the aggregate backpressure of all procedure streams on the current socket.

getAllChannelsBackpressure() Get the aggregate backpressure of all channel streams on the current socket.

All of the following methods are related to pub/sub features of SocketCluster.
SocketCluster lets you interact with channels either directly through the socket or through AGChannel objects.

transmitPublish(channelName, data) Publish data to the specified channelName. Do not expect a response from the server. The channelName argument must be a string. The data argument can be any JSON-compatible object/array or primitive.

invokePublish(channelName, data) Publish data to the specified channelName. Expect a response from the server. The channelName argument must be a string. The data argument can be any JSON-compatible object/array or primitive. This method returns a Promise which will be rejected if the operation fails. For example, it can be rejected if the MIDDLEWARE_INBOUND middleware blocks the action on the server side. The promise will resolve once the server has processed the publish action.

subscribe(channelName, [options]) Subscribe to a channel. This function returns an AGChannel instance - This object is an asyncIterable and lets you consume data that is published to the channel. You can provide an optional options object in the form {waitForAuth: true, data: someCustomData} (all properties are optional) - If waitForAuth is true, the channel will wait for the socket to become authenticated before trying to subscribe to the server - These kinds of channels are called "private channels" - Note that in this case, "authenticated" means that the client socket has received a valid JWT authToken - Read about the server side socket.setAuthToken(tokenData) function here for more details. The data property can be used to pass data along with the subscription.

To consume a channel, it is recommended to use a for-await-of loop like this:

for await (
 let data of socket.channel('myChannel')
) {
 // Consume channel data...
}

Because the socket.subscribe(...) method returns an AGChannel instance, you can also consume it directly like this:

for await (
 let data of socket.subscribe('myChannel')
) {
 // Consume channel data...
}

Note that socket.subscribe(...) can be called multiple times for the same channel; if already subscribed, the method will only return the channel.

unsubscribe(channelName) Unsubscribe from the specified channel. This makes any associated AGChannel object inactive. You can reactivate the AGChannel object by calling subscribe(channelName) again at a later time.

channel(channelName) Returns an AGChannel instance - This object is an asyncIterable. This method is different from socket.subscribe(...) in that it will not try to subscribe to that channel. The returned channel will be inactive initially. You can call channel.subscribe() later to activate that channel when required.

closeChannel(channelName) This method will signal to all consuming for-await-of loops (for the channelName channel and all of its listeners) to break after they have finished iterating over their current backlogs of events.

channelCloseOutput(channelName) This method is like closeChannel(channelName) except that it only closes the main channel (output) stream. Listener consumers on the channel will not be affected.

channelCloseAllListeners(channelName) This method is like closeChannel(channelName) except that it only closes listener streams on the channel. The main channel output stream will not be affected. To close specific listeners (by eventName) on a specific channel, it's recommended that you use the AGChannel API.

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

killChannel(channelName) This method will signal to all consuming for-await-of loops for the channelName channel (and all of its listeners) to break immediately. This will reset the backpressure for that channel (and all of its event listeners) to 0.

channelKillOutput(channelName) This method is like killChannel(channelName) except that it only kills the main channel (output) stream. Listener consumers on the channel will not be affected.

channelKillAllListeners(channelName) This method is like killChannel(channelName) except that it only kills listener streams on the channel. The main channel output stream will not be affected. To kill specific listeners (by eventName) on a specific channel, it's recommended that you use the AGChannel API.

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

killAllChannelOutputs() This method is similar to killAllChannels() except that it only kills channel output streams; channel event listeners will not be affected. This will reset the aggregate backpressure for all channel output streams to 0.

killAllChannelListeners() This method is similar to killAllChannels() except that it only kills channel listener streams; channel output streams will not be affected. This will reset the aggregate backpressure for all channel listener streams to 0.

subscriptions(includePending) Returns an array of active channel subscriptions which this socket is bound to. If includePending is true, pending subscriptions will also be included in the list.

isSubscribed(channelName, [includePending]) Check if socket is subscribed to channelName. If includePending is true, pending subscriptions will also be included in the list.

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.

channelGetOutputConsumerStatsList(channelName) Get the list of consumers which are consuming output data from the specified channel. This method returns a list of objects which have an id and backpressure property.

channelGetAllListenersConsumerStatsList(channelName) Get the list of all consumers which are consuming events from any listener on the specified channel. This method returns a list of objects which have an id and backpressure property.

getAllChannelOutputsConsumerStatsList() Get the list of all consumers which are consuming output data from any channel which is bound to the socket. This method returns a list of objects which have an id and backpressure property.

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

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

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