Basic

Options

Options is a variable you can create for handler settings. May not be declared.

It is declared like this:

options = {
    Address = "/websocket", -- The path for the user.
    WebSocket = true, -- Is it WebSocket?
}

Now more about each value.

Address - needed to determine the path along which the handler is called. No ad required. According to the standard, it has values relative to the web folder (without specifying the folder itself in the path). Required Only has a String data type.

WebSocket - needed to define a WebSocket handler. Doesn't require an announcement. The default is false. Must have only the Bool data type.

HTTP Handler

It is always required to have a Handler function in it. The function, in turn, must take 1 parameter - request (the name can be anything). The function should look like this:

function Handler (request)
    request.write("Hello world!")
end

The function is always called on any HTTP request. The function name should always be "Handler".

HTTP Request

Here it will be about the parameter passed to the Handler function. The parameter has the following functionality:

request.method -- Used to determine the type of HTTP request
request.write("") -- Used to send a response to the client.
request.getQuery("") -- Used to get data from Query parameters.
request.getHeader("") -- Used to get data from HTTP headers.
request.getFormData({""}) -- Used to get data from HTTP POST requests.

- request.method

Created to determine the type of HTTP request.

Usage:

if request.method == "POST" then
    postData = request.getFormData({"message"})
    request.write(postData.message)
end

- request.write("")

Used to send a response to the client. It takes only a string as a parameter.

Usage:

request.send("Hello world!")

- request.getQuery("key")

Used only to get Query parameters passed by the client. It takes only the parameter key as a string as an argument. The function returns only a string.

Usage: localhost:8080/?index=1234

index = request.getQuery("index") 
request.write(query) -- The user will be shown "1234"

- request.getHeader("key")

Works on the principle of request.getQuery(). But only used to get headers.

Usage:

token = req.getHeader("Token")
if token == "1234" then
   req.write("The token is valid.") 
end

- request.getFormData({"message"})

Used to get the data provided in the POST request. It takes as an argument only the table containing the keys of the values you want to get. Returns a table containing the key values.

Usage:

postData = req.getFormData({"message", "user"}) -- Getting message values
req.write(postData.message) -- Return message values
req.write(postData.user) -- Return user values

WebSocket Handler

Blomma has native support for WebSocket. The WebSocket handler is almost the same as a regular HTTP handler, i.e. by creating a .lua file in the web folder. In the handler file, we create options and set WebSocket = true.

options = {
    WebSocket = true,
}

Instead of creating a Handler function like in an HTTP handler, we create a WSHandler (short for WebSocket Handler).

function WSHandler(conn)
    while true do
        data = conn.read()

        conn.write(data.mt, data.data)
    end
end

This function (WSHandler) will be called each time a connection is created. Also, when creating a connection, the WebSocket handler file will be loaded into a new state of the Lua virtual machine. Those. in a handler websocket file, you are always interacting with only 1 connection. To interact connections with each other, use valueController.

The WSHandler function always takes 1 parameter, which accepts client connections.

Also in the handler there should be a function to close the processing of closing the connection. This function always takes 1 parameter to which data about closing is passed. It looks like this:

function onClose(data)
end

First project with WebSocket

Explore BlommaChat (If there is nothing there, then don't worry, I will describe how it works and a lesson on how to repeat it soon)

Echo server with WebSocket and Blomma

Writing an Echo server with Blomma is very easy. The whole code might look like this:

options = {
    WebSocket = true,
}

function WSHandler(conn)
    while true do
        local msg = conn.read()

        conn.write(msg.mt, msg.data)
    end
end

function onClose()
end

Looks very simple, right? But I recommend adding a check to see if the connection is open, this will save us from unnecessary bugs and errors during work. So our code now looks like this:

options = {
    WebSocket = true,
}

local connectionIsOpen = false

function WSHandler(conn)
    connectionIsOpen = true

    while true do
        local msg = conn.read()

        if connectionIsOpen ~= true then
            return
        end

        conn.write(msg.mt, msg.data)
    end
end

function onClose()
    connectionIsOpen = false
end

WebSocket Connection

The client connection is passed as an argument to the WebSocket handler function. Usually the parameter is named conn

function WSHandler(conn)
end

conn.write("")

A function to send data to the client. The first argument it takes is the message type, which must always be an INT type, the second argument is the data to be sent, the data type of which must always be a string.

Usage:

conn.write(msg.mt, "Hello world!")

conn.read()

Function for reading data from the client. Always returns a table with the read information.

Usage:

msg = conn.read()

conn.write(msg.mt, msg.data)

msg.mt

Contains the type of message read

msg.data

Contains read message data

conn.close()

Closes current connections.

Usage:

conn.close()

OnClose

function onClose(data)
end

Called if the connection has been closed, passes a table with information about the message as a parameter. The table is identical to the table returned by conn.read()