Módulo TCP

Este módulo fornece funcionalidades para conexões TCP e TCP+TLS a partir de scripts Lua. Oferece suporte para comunicação com sockets brutos, leitura/escrita de strings, JSON e pacotes JSON com tamanho prefixado.

O módulo tcp permite:

Conexões TCP simples com timeout configurável
Conexões TLS
Leitura e escrita de strings simples
Leitura e escrita de JSON
Leitura e escrita de pacotes JSON com tamanho prefixado (para comunicação binária segura)
Resolução DNS automática para conexões TLS

Funções Disponíveis

`tcp.connect(host, port, [timeout_secs])`

Estabelece uma conexão TCP simples com um servidor remoto.

Parâmetros:

host (string): Endereço do host ou IP do servidor
port (number): Porta TCP para conexão
timeout_secs (number, opcional): Timeout em segundos (padrão: 5)

Valor de retorno:

Objeto Connection que pode ser usado para leitura/escrita
Lança erro em caso de falha ou timeout

Exemplo:

-- Conectar a um servidor na porta 8080 com timeout de 10 segundos
local conn = tcp.connect("servidor.exemplo.com", 8080, 10)

-- Conectar com timeout padrão (5 segundos)
local conn2 = tcp.connect("192.168.1.100", 3000)

`tcp.connect_tls(host, port, [timeout_secs])`

Estabelece uma conexão TLS (SSL) com um servidor remoto.

Parâmetros:

host (string): Endereço do host do servidor
port (number): Porta TLS para conexão
timeout_secs (number, opcional): Timeout em segundos (padrão: 5)

Valor de retorno:

Objeto TlsConnection que pode ser usado para leitura/escrita
Lança erro em caso de falha ou timeout

Exemplo:

-- Conectar via TLS na porta 443
local conn = tcp.connect_tls("api.exemplo.com", 443)

-- Conectar com timeout personalizado
local conn2 = tcp.connect_tls("servidor-seguro.com", 8443, 15)

`tcp.send(data)`

Envia dados através da última conexão TCP aberta com a função connect(). Esta função é mantida para compatibilidade com versões anteriores. Para maior clareza e controle, prefira a forma local conn = connect("host", porta) e use os métodos do objeto de conexão retornado (ex: conn:write_json_packet()).

Parâmetros:

data (string): Dados a serem enviados

Valor de retorno:

nil em caso de sucesso
Lança erro se não houver conexão ativa

Nota: Esta função usa a última conexão TCP aberta com a função connect(). É útil para scripts simples que mantêm uma única conexão.

Exemplo:

-- Primeiro estabelece uma conexão
local conn = tcp.connect("servidor.exemplo.com", 8080)

-- Envia dados
send("GET / HTTP/1.1\r\nHost: servidor.exemplo.com\r\n\r\n")

`tcp.recv()`

Recebe dados da última conexão TCP aberta com a função connect() e armazenada no registro Lua. Esta função é mantida para compatibilidade com versões anteriores. Para maior clareza e controle, prefira a forma local conn = connect("host", porta) e use os métodos do objeto de conexão retornado (ex: conn:read_str() ou conn:read_json_packet()).

Parâmetros:

Nenhum

Valor de retorno:

string com os dados recebidos
Lança erro se não houver conexão ativa

Nota:

Esta função usa a última conexão TCP aberta com a função connect(). É útil para scripts simples que mantêm uma única conexão.
Lê até 8192 bytes por chamada. Para leitura completa, pode ser necessário chamar múltiplas vezes.

Exemplo:

-- Recebe resposta
local resposta = tcp.recv()
print("Resposta recebida:", resposta)

Métodos dos Objetos Connection

Os objetos retornados por connect() e connect_tls() possuem os seguintes métodos:

`conn:read_str()`

Lê uma string completa do socket até EOF.

Valor de retorno:

string com os dados lidos
Lança erro em caso de falha de leitura

Exemplo:

local conn = tcp.connect("servidor.exemplo.com", 8080)
local dados = conn:read_str()
print("Dados recebidos:", dados)

`conn:read_json()`

Lê uma string do socket e a interpreta como JSON.

Valor de retorno:

Valor Lua decodificado do JSON
Lança erro se os dados não forem JSON válido

Exemplo:

local conn = tcp.connect("api.exemplo.com", 3000)
local dados_json = conn:read_json()

-- Acessar dados decodificados
print("Status:", dados_json.status)
print("Mensagem:", dados_json.message)

`conn:read_json_packet()`

Lê um pacote JSON com tamanho prefixado (formato binário).

Formato do pacote:

4 bytes (uint32): Tamanho dos dados JSON
N bytes: Dados JSON serializados

Limite de tamanho: 512KB (512.000 bytes)

Valor de retorno:

Valor Lua decodificado do JSON
Lança erro se o pacote for muito grande ou JSON inválido

Exemplo:

local conn = tcp.connect("servidor-binario.com", 9000)
local pacote = conn:read_json_packet()
print("Pacote recebido:", pacote)

`conn:write_json_packet(packet)`

Escreve um pacote JSON com tamanho prefixado (formato binário).

Parâmetros:

packet (qualquer valor Lua): Dados a serem serializados como JSON

Valor de retorno:

nil em caso de sucesso
Lança erro em caso de falha de serialização ou escrita

Exemplo:

local conn = connect("servidor-binario.com", 9000)

-- Enviar um pacote JSON
local dados = {
    comando = "atualizar",
    id = 123,
    valores = {10, 20, 30}
}
conn:write_json_packet(dados)

Informações Adicionais

Timeout Configurável

Todas as funções de conexão aceitam timeout personalizado. Se não especificado, usa 5 segundos como padrão.

Resolução DNS Automática

A função connect_tls() resolve automaticamente o nome do host para um endereço IP antes de estabelecer a conexão.

Tamanho Máximo de Pacote

Pacotes JSON com tamanho prefixado têm um limite de 512KB para prevenir ataques de negação de serviço.

Exemplos de Uso

Comunicação HTTP Simples

function fazer_requisicao_http(host, porta, caminho)
    local conn = connect(host, porta, 10)

    -- Enviar requisição HTTP
    local requisicao = string.format(
        "GET %s HTTP/1.1\r\nHost: %s\r\nConnection: close\r\n\r\n",
        caminho, host
    )

    -- Usar o método send (conexão está no registro)
    send(requisicao)

    -- Ler resposta
    local resposta = recv()

    -- Extrair corpo da resposta (simplificado)
    local corpo = resposta:match("\r\n\r\n(.+)$")

    return corpo
end

Cliente de API JSON

function consultar_api_json(endpoint, dados)
    local conn = connect_tls("api.exemplo.com", 443)

    -- Enviar dados como pacote JSON
    conn:write_json_packet({
        endpoint = endpoint,
        dados = dados,
        timestamp = os.time()
    })

    -- Aguardar resposta
    local resposta = conn:read_json_packet()

    return resposta
end

-- Exemplo de uso
local resultado = consultar_api_json("/usuarios", {id = 123})
if resultado.success then
    print("Usuário:", resultado.usuario.nome)
end

Monitoramento de Serviço TCP

function verificar_servico_tcp(host, porta)
    local inicio = os.time()
    local sucesso, conn = pcall(connect, host, porta, 5)

    if sucesso then
        local tempo_resposta = os.time() - inicio

        -- Testar comunicação básica
        conn:write_json_packet({ping = true})
        local resposta = conn:read_json_packet()

        if resposta and resposta.pong then
            return {
                status = "online",
                tempo_resposta = tempo_resposta,
                versao = resposta.versao
            }
        end
    end

    return {
        status = "offline",
        erro = conn  -- conn contém a mensagem de erro quando pcall falha
    }
end

Comunicação Bidirecional

function chat_client(host, porta)
    local conn = connect(host, porta)

    -- Thread para receber mensagens
    local function receber_mensagens()
        while true do
            local mensagem = conn:read_json_packet()
            print("Recebido:", mensagem.texto)
        end
    end

    -- Thread para enviar mensagens (simplificado)
    local function enviar_mensagens()
        while true do
            io.write("Digite mensagem: ")
            local texto = io.read()
            if texto == "sair" then break end

            conn:write_json_packet({
                tipo = "mensagem",
                texto = texto,
                timestamp = os.time()
            })
        end
    end

    -- Em um ambiente real, isso seria feito com corrotinas
    -- Esta é uma simplificação para demonstração
end