Requests

Requests allow you to issue an event and expect a single response from the receiver.

They use the same methods of Events. Waiting for the response determines whether the issue is processed as an event or as a request.

Errors related to requests are communicated through the event life cycle error.

Client to server

The client uses await on emit() to wait for the server response:

const message = await socket.emit("ping", "Hola, George")

The server records the request by On(). The handler must return exactly a value with the type gox.EventReply:

socket.On("ping", func(message string) gox.EventReply {
    return "Pong: " + message
})

Handler signature:func(values...) gox.EventReply

gox.EventReply indicates that the event supports requests and returns a response.

A handler that doesn't return gox.EventReply only supports unanswered emissions. If the client tries to wait for it by await, GOX shoots the event error.

The returned value must be compatible with the JavaScript-Go communication system.

Server to client

The server adds Await() to an issue to wait for the client's response:

var message string

err := socket.Emit("ping", "Hola, George").Await(&message)

Firma:func (*SocketEmission) Await(out any) error

Await() He gets a pointer where GOX stores the response.

The value provided in out:

• It must be a pointer.
• It can't be nil.
• You must accept the value returned by the client.

The client records the event by on() and returns the response from the handler:

socket.on("ping", message => {
    return `Pong: ${message}`
})

GOX expects the returned value and sends it to the server.

Await() returns an error when the response cannot be converted to the type of out. The other problems are communicated through the event error life cycle.

Response

Each request produces exactly one response.

The returned value can be any type admitted by the JavaScript-Go communication system.

If the JavaScript handler does not return a value, GOX responds with null. On receiving him, Await() assigns the zero value corresponding to the type of out.

Requests do not use a separate response to represent errors. If the handler fails, GOX shoots the event error and the request does not receive a valid value.

Timeout

GOX is waiting for the response for a maximum of 10 seconds.

If the receiver does not respond within that period:

• The pending request is deleted.
• A later response is ignored.
• GOX shoots the event error with the code REQUEST_TIMEOUT.

In the client, the promise is resolved with undefined when the request fails or exceeds the waiting time.

On the server, out retains its previous value when a valid response is not received.

See WebSocket Settings to learn how to set up the waiting time of the requests.

Full example

The client requests a pong the server and the server requests another to the client.

Servidor:

module websocket

import "github.com/gox-lang/gox"

func Index(socket *gox.Socket) gox.WebSocket {
    socket.On("clientPing", func(message string) gox.EventReply {
        return "Pong: " + message
    })

    socket.When("connect", func(isReconnect bool) {
        var response string

        if err := socket.Emit("serverPing", "Hola, George").Await(&response); err != nil {
            log.Println(err)
            return
        }

        log.Println(response)
    })
}

Cliente:

import { Socket } from "@gox/websocket"

const socket = new Socket()

socket.on("serverPing", message => {
    return `Pong: ${message}`
})

socket.when("connect", async () => {
    const response = await socket.emit("clientPing", "Hola, George")
    console.log(response)
})

clientPing expects the value returned by gox.EventReply. serverPing store in response the value returned by the handler of on().

Best practices

• It uses requests only when the issuer needs a response.
• Returns exactly a value from each request handler.
• Use gox.EventReply on the go handlers who accept requests.
• Always provides a valid pointer to Await().
• Check the error returned by Await().
• Manage the event error on both sides of the connection.
• Do not use a request to disseminate information to several sockets.
• Avoid operations that can exceed the maximum time set.

To learn more about EventsSee your documentation. To learn more about Lifecycle, check your documentation.

See also

• Events
• Lifecycle
• Communication
• WebSocket Settings