Relay WebSocket

Relay WebSocket

O middleware de relay WebSocket atualiza conexões HTTP para WebSocket e retransmite mensagens para um processo alvo.

Como Funciona

1. Handler HTTP define header X-WS-Relay com PID do processo alvo
2. Middleware atualiza conexão para WebSocket
3. Relay anexa ao processo alvo e o monitora
4. Mensagens fluem bidirecionalmente entre cliente e processo

A conexão WebSocket está vinculada ao processo alvo. Se o processo sair, a conexão fecha automaticamente.

Semântica de Processo

Conexões WebSocket são processos completos com seu próprio PID. Elas se integram com o sistema de processos:

• Endereçável - Qualquer processo pode enviar mensagens para um PID WebSocket
• Monitorável - Processos podem monitorar conexões WebSocket para eventos de saída
• Linkável - Conexões WebSocket podem ser vinculadas a outros processos
• Eventos EXIT - Quando a conexão fecha, monitores recebem notificações de saída

-- Monitora uma conexão WebSocket de outro processo
process.monitor(websocket_pid)

-- Envia mensagem para cliente WebSocket de qualquer processo.
-- O relay encapsula como JSON {topic, data}; o nome do tópico é arbitrário.
process.send(websocket_pid, "update", "hello")

O relay monitora o processo alvo. Se o alvo sair, a conexão WebSocket fecha automaticamente e o cliente recebe um frame de fechamento.

Transferência de Conexão

Conexões podem ser transferidas para um processo diferente enviando uma mensagem de controle:

process.send(websocket_pid, "ws.control", {
    target_pid = new_process_pid,
    message_topic = "ws.message"
})

Configuração

Adicione como middleware pós-match em um roteador:

- name: ws_router
  kind: http.router
  meta:
    server: gateway
  prefix: /ws
  post_middleware:
    - websocket_relay
  post_options:
    wsrelay.allowed.origins: "https://app.example.com"

Opção	Descrição
wsrelay.allowed.origins	Origens permitidas separadas por vírgula

Se nenhuma origem configurada, apenas requisições same-origin são permitidas.

Configuração do Handler

O handler HTTP cria um processo e configura o relay:

local http = require("http")
local json = require("json")

local function handler()
    local req = http.request()
    local res = http.response()

    -- Cria processo handler
    local pid = process.spawn("app.ws:handler", "app:processes")

    -- Configura relay
    res:header("X-WS-Relay", json.encode({
        target_pid = tostring(pid),
        message_topic = "ws.message",
        heartbeat_interval = "30s",
        metadata = {
            user_id = req:query("user_id")
        }
    }))
end

Campos de Configuração do Relay

Campo	Tipo	Padrão	Descrição
target_pid	string	obrigatório	PID do processo para receber mensagens
message_topic	string	ws.message	Tópico para mensagens do cliente
heartbeat_interval	duration	-	Frequência de heartbeat (ex: 30s)
metadata	object	-	Anexado a todas as mensagens

Tópicos de Mensagens

O relay envia estas mensagens para o processo alvo:

Tópico	Quando	Payload
ws.join	Cliente conecta	JSON {client_pid, metadata}
ws.message (ou seu message_topic)	Cliente envia mensagem	Payload bruto do cliente (frame de texto -> string, frame binário -> bytes); o PID de origem do pacote do relay é o PID do cliente
ws.heartbeat	Periódico (se configurado)	JSON {client_pid, uptime, message_count, metadata}
ws.leave	Cliente desconecta	JSON {client_pid, metadata}

Recebendo Mensagens

local json = require("json")

local function handler()
    local inbox = process.inbox()

    while true do
        local msg, ok = inbox:receive()
        if not ok then break end

        local topic = msg:topic()
        local from = msg:from()                -- PID da conexão do cliente

        if topic == "ws.join" then
            -- Cliente conectou -- payload é {client_pid, metadata}
            local data = msg:payload():data()
            local client_pid = data.client_pid

        elseif topic == "ws.message" then
            -- Mensagem bruta do cliente; from() é o PID do cliente
            local body = msg:payload():data()  -- string ou bytes
            handle_message(from, json.decode(body))

        elseif topic == "ws.leave" then
            -- Cliente desconectou -- payload é {client_pid, metadata}
            cleanup(from)
        end
    end
end

Enviando para o Cliente

Envia mensagens de volta usando o PID do cliente. Qualquer tópico que você escolher é encapsulado como JSON {topic, data} e encaminhado para o WebSocket. O tipo de frame é decidido pelo formato do payload: strings se tornam frames de texto, bytes se tornam frames binários (codificados em base64 dentro do envoltório JSON).

-- Envia uma mensagem estruturada (qualquer nome de tópico)
process.send(client_pid, "update", json.encode({event = "update", value = 42}))

-- Envia binário
process.send(client_pid, "data", binary_content)

-- Fecha conexão (payload é a string do motivo de fechamento)
process.send(client_pid, "ws.close", "Sessão encerrada")

Os tópicos reservados de servidor -> cliente são ws.control (reconfiguração do relay) e ws.close (fechar a conexão).

Broadcast

Rastreie PIDs de clientes para broadcast para múltiplos clientes:

local clients = {}

-- No join
clients[client_pid] = true

-- No leave
clients[client_pid] = nil

-- Broadcast
local function broadcast(message)
    local data = json.encode(message)
    for pid, _ in pairs(clients) do
        process.send(pid, "broadcast", data)
    end
end

Para cenários complexos de múltiplas salas, crie um processo handler separado por sala ou use um processo gerenciador central que rastreia membros de salas.

Veja Também

• Middleware - Configuração de middleware
• Processo - Mensagens de processo
• Cliente WebSocket - Conexões WebSocket de saída