Lifecycle

The WebSocket life cycle begins when the client tries to establish the connection and ends when it is closed definitely.

GOX manages the handshake, connection, disconnection and reconnection. The client and server can register handlers to react to these changes.

socket.When("handshake", func(ctx *gox.Context) bool {
    return socket.Handshake.Origin() == "https://example.com"
})

socket.When("connect", func(isReconnect bool) {
    socket.Emit("welcome", isReconnect)
})

socket.When("disconnect", func(details gox.WSDisconnectReason) {
    log.Printf("Conexión cerrada: %d", details.Code)
})

socket.When("error", func(err gox.GoxSocketError) {
    log.Printf("Error WebSocket: %s", err.Message)
})

socket.when("connect", isReconnect => {
    console.log("Conectado", { isReconnect })
})

socket.when("disconnect", details => {
    console.log("Desconectado", details)
})

socket.when("error", error => {
    console.error(error)
})

Both APIs describe the same communication, although each environment receives the information corresponding to its side of the connection.

See Socket to know the API of the server used during these stages. To learn how to create and configure the connection from JavaScript or TypeScript, see Client.

Events

handshake only exists on the server because it uses the HTTP context that started the connection.

Other events can be observed from both sides by When() in Go and when() in JavaScript.

Handshake

Handshake is the first stage of the connection.

The server can record the event handshake to authorize or reject the client before completing the upgrade to WebSocket:

socket.When("handshake", func(ctx *gox.Context) bool {
    return socket.Handshake.Origin() == "https://example.com"
})

The handler receives the original HTTP context and must return a boolean value:

• true Accept the connection.
• false He rejects the connection.

If the event is not recorded, GOX automatically applies its default validation of the same origin.

The context makes it possible to consult information necessary to make the decision:

socket.When("handshake", func(ctx *gox.Context) bool {
    return ctx.Session.Has("userID")
})

During this stage, the socket has not yet been registered and socket.ID() return an empty string.

If the handshake is rejected, the server responds with 403 Forbidden and does not run connectThe client first gets a mistake. HANDSHAKE_FAILED and then the event disconnectThe connection remains closed and GOX does not try to reconnect it automatically.

socket.when("error", error => {
    if (error.code === "HANDSHAKE_FAILED") {
        console.log("El handshake fue rechazado o no pudo completarse")
    }
})

The browser does not allow for a certain distinction between deliberate rejection and other problems that prevent the handshake from being completed.

Do not keep the context received after completion of the handler. To subsequently access the initial request data, use socket.Handshake.

Connect

The event connect is run when the connection is available.

Servidor:

socket.When("connect", func(isReconnect bool) {
    socket.Emit("welcome", "George", isReconnect)
})

Cliente:

socket.when("connect", isReconnect => {
    console.log("Conectado", { isReconnect })
})

The argument isReconnect indicates how the connection was established:

From connect, the server can already use socket.ID(), issue events, consult other sockets and work with groups or channels.

socket.When("connect", func(isReconnect bool) {
    log.Printf("Socket conectado: %s", socket.ID())
})

The client can use isReconnect to avoid repeating operations that only correspond to the initial connection:

socket.when("connect", isReconnect => {
    if (!isReconnect) {
        initializeApplication()
    }
})

Recording connect replace the previous handler of that event.

Disconnect

The event disconnect It runs when the connection ends.

Servidor:

socket.When("disconnect", func(details gox.WSDisconnectReason) {
    log.Printf("Socket cerrado: %d", details.Code)
})

Cliente:

socket.when("disconnect", details => {
    console.log(details.code)
    console.log(details.reason)
    console.log(details.willReconnect)
})

The information received describes the cause of the closure:

initiator may contain:

The server can close the connection by Disconnect():

socket.Disconnect(gox.WSClosePermanent)

The client can close it by disconnect():

import { Socket, WSCloseCode } from "@gox/websocket"
const socket = new Socket()
socket.disconnect(WSCloseCode.NORMAL)

A direct call to socket.disconnect() disable the automatic reconnection for that socket.

Reconnection

The automatic reconnection is default-active in the client.

GOX tries to recover the connection when the closing code represents a recoverable interruption. The wait gradually increases between attempts to reach the set limit.

const socket = new Socket({
    reconnect: {
        enabled: true,
        delay: 1000,
        maxDelay: 30000,
        attempts: 5
    }
})

It can also be completely deactivated:

const socket = new Socket({
    reconnect: false
})

When a reconnection occurs:

• The client retains the same instance of Socket.
• The handlers registered by when() and on() are preserved.
• The existing channels try to join again.
• The server creates a new instance of gox.Socket.
• The new connection receives another identifier.
• The session can be held if it remains valid.
• connect receives isReconnect with the value true.

The previous connection is over. For this reason, the new socket of the server does not retain its groups or the state stored only in the previous instance.

To keep information between connections, use the session or other persistent storage. Sessions to know their storage, persistence and life cycle.

Close codes

GOX provides shared codes between Go and JavaScript.

WSCloseDefault and WSCloseCode.DEFAULT They are equivalent to normal closure.

Use WSCloseReconnect when the server needs to close the current connection and ask the client to establish a new one:

socket.Disconnect(gox.WSCloseReconnect)

Use WSClosePermanent when the connection must not be automatically recovered:

socket.Disconnect(gox.WSClosePermanent)

The codes reserved for sessions are normally administered by GOX when a session expires or is destroyed.

The reconnection also depends on the client's configuration and the number of attempts available. A recoverable code does not guarantee a reconnection if it was disabled or reached its limit.

Error

The event error reports operational problems without assuming that the connection is over.

Servidor:

socket.When("error", func(err gox.GoxSocketError) {
    log.Printf("%s: %s", err.Code, err.Message)
})

Cliente:

socket.when("error", error => {
    console.error({
        code: error.code,
        phase: error.phase,
        event: error.event,
        retryable: error.retryable,
        message: error.message
    })
})

An error contains the following main information:

The main phases are:

The event error and the event disconnect perform different functions:

• error describes a problem.
• disconnect confirms the connection's over.

An error can occur without closing the socket. disconnect or state to determine the status of the connection.

Sequence

An accepted initial connection follows this order:

1. The client creates a Socket.
2. GOX starts the HTTP handshake.
3. The server runs Index.
4. The server runs handshake, if it was registered.
5. GOX accepts and records the connection.
6. The server runs connect.
7. The client runs connect.
8. The client and the server exchange events.
9. The connection is over.
10. The client and the server run disconnect.

If the closure allows to reconnect, the client expects and starts a new attempt. The server creates another socket and events connect receive isReconnect with the value true.

Best practices

• Search the life cycle handlers before starting to exchange events.
• Use handshake to authorize the connection before the upgrade.
• Do not use socket.ID() during Index or handshake.
• Check. isReconnect before repeating exclusive tasks of the initial connection.
• Store the recoverable status in the session or in persistent storage.
• Always handle the event error.
• Use disconnect to confirm that the connection is over.
• Select a closing code that correctly represents the cause.
• Use WSCloseReconnect only when the client has to recover the connection.
• Use WSClosePermanent where there should be no automatic reconnection.
• Do not keep the HTTP context received by handshake.

See also

• Socket
• Client
• Sessions