Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Um servidor HTTP no executável

cgd:rede continua sendo o cliente HTTP. Para receber requisições, importe cgd:servidor: o programa abre seus próprios sockets, sem Node, Python, shell ou um servidor externo no caminho da comunicação.

Esta é a primeira etapa da infraestrutura de serviços: TCP IPv4 e um perfil restrito de HTTP/1.1, com uma requisição por conexão. O servidor atende um cliente por vez. Isso permite definir propriedade dos recursos e comportamento das exceções antes de acrescentar concorrência ao runtime.

Primeiro programa

const Servidor: qualquer = importar("cgd:servidor")
var app: qualquer = Servidor.HTTP()

app.get("/", funcao(req: qualquer, res: qualquer): vazio {
    res.enviar("Olá, mundo!\n")
})
app.post("/usuarios", funcao(req: qualquer, res: qualquer): vazio {
    res.status(201).json({ criado: verdadeiro, usuario: req.json() })
})
app.escutar("127.0.0.1", 8080)

Compile normalmente e execute o binário. O exemplo completo em exemplos/servidor/http.delegua também mostra parâmetros e encerramento. No catálogo geral ele tem contrato de compilação, pois iniciar um serviço bloqueante não cabe no runner de exemplos. O teste testes/servidor.py inicia o serviço e faz requisições reais nos dois modos.

Os callbacks recebem a requisição e a resposta como argumentos. Continuam valendo as restrições do CGD: não capturam variáveis locais externas. Passe informações entre middleware e rota por req.contexto.

Rotas e middleware

get, post, put, patch, delete, head e options recebem um caminho e uma função (req: qualquer, res: qualquer): vazio. rota(metodo, caminho, tratar) é a forma geral, com método maiúsculo. Registrar a mesma combinação duas vezes lança uma exceção. A primeira rota compatível na ordem de registro é executada.

Um segmento :nome captura um parâmetro. /usuarios/:nome aceita /usuarios/Jos%C3%A9; req.parametro("nome") devolve José. Não há wildcards, expressões regulares ou conversão automática de parâmetros. A barra final faz parte do caminho. HEAD precisa de rota própria; não executa GET implicitamente. options("*", callback) atende OPTIONS * explicitamente.

Sem rota para o caminho, a resposta é 404. Havendo caminho mas não método, é 405 com Allow. Não há CORS, autenticação nem OPTIONS automático.

app.usar(funcao(req: qualquer, res: qualquer): vazio {
    req.contexto["origem"] = "middleware"
    res.cabecalho("x-aplicacao", "exemplo")
    se req.caminho == "/indisponivel" {
        res.status(503).enviar("Tente novamente depois")
    }
})

usar(callback) executa middleware na ordem de registro. Uma resposta definida por enviar ou json encerra o despacho; caso contrário, o próximo middleware e depois a rota são executados. Não existe next() assíncrono. Cada requisição tem seus próprios mapas de contexto e parâmetros e sua própria resposta.

Requisicao

MembroContrato
metodo: textoMétodo recebido, sensível a maiúsculas.
caminho: textoCaminho decodificado uma vez, sem query.
alvo: textoRequest target original, ainda com escapes e query.
cabecalhos: dicionarioNomes em minúsculas; valores textuais.
consulta: dicionarioCada chave contém um vetor de valores, preservando repetições.
parametros: dicionarioSegmentos capturados pela rota.
contexto: dicionarioDados explícitos da aplicação/middleware.
texto(): textoCorpo completo; o tamanho de transporte é medido em bytes.
json(): qualquerUsa o parser de cgd:json e seus limites próprios.
parametro(nome, alternativa = nulo): qualquerObtém um segmento ou a alternativa.
query(nome, alternativa = nulo): qualquerObtém o primeiro valor de query ou a alternativa.

Em query, + representa espaço e %2B representa +. Em caminhos, + permanece literal. Escapes inválidos, controles, NUL, barras codificadas, contrabarras e segmentos ./.. são recusados com 400. Não existe serviço de arquivos embutido: um caminho de URL nunca é usado como caminho do sistema de arquivos. A aplicação que construir seu próprio serviço de arquivos precisa confinar a raiz de acesso.

texto do runtime armazena bytes; não há validação de UTF-8 de todo corpo HTTP. Use JSON/texto válido nas operações Unicode. O transporte preserva inclusive NUL no corpo, mas não nos headers ou no caminho. O Content-Type recebido não altera o parser automaticamente. req.json() inválido lança; a rota pode capturar e responder 400. Uma exceção não tratada no handler resulta em 500 genérico.

Resposta

MétodoEfeito
status(codigo: inteiro): RespostaCódigo final 200..599; padrão 200.
cabecalho(nome: texto, valor: texto): RespostaDefine um header; o nome é normalizado.
enviar(corpo: texto = ""): RespostaDefine o corpo; não faz I/O imediatamente.
json(valor: qualquer): RespostaSerializa JSON e define Content-Type apropriado.
definida(): logicoInforma se enviar/json já foi chamado.
pararServidor(): RespostaSolicita fechar o listener após transmitir esta resposta.
deveParar(): logicoConsulta essa solicitação.

O tipo inicial é text/plain; charset=utf-8. A resposta fica em memória até o handler terminar; não há streaming. Uma rota que termina sem definir a resposta produz 204 vazio. Os status 204, 205 e 304 não aceitam corpo nesta API. HEAD transmite os headers e o tamanho do corpo que seria enviado, mas nenhum byte do corpo. O runtime calcula Content-Length em bytes, inclusive para Unicode.

Date, Content-Length, Transfer-Encoding, Connection, Trailer e Upgrade são reservados ao transporte. Não podem ser sobrescritos. Date usa UTC e nomes de meses/dias em inglês, sem depender do locale do processo. Nomes inválidos, CR/LF e outros controles nos valores são recusados antes do envio. Se a validação da resposta falhar, o servidor tenta responder 500 genérico. Se o transporte já falhou, fecha a conexão e segue atendendo. Nenhum detalhe da exceção, credencial ou corpo é registrado automaticamente.

Ciclo de vida e limites

HTTP(maxCabecalhos = 16384, maxCorpo = 1048576, leitura = 10000, escrita = 10000) recebe limites em bytes e prazos em milissegundos. Argumentos inválidos falham na construção, antes de abrir sockets.

RecursoLimite
Headers de requisiçãoConfigurável, 256..65536 bytes, incluindo request line.
Quantidade de headers100 por requisição e por resposta.
Corpo de requisiçãoConfigurável, 0..16777216 bytes.
Corpo de respostaAté 16777216 bytes.
Headers de respostaAté 65536 bytes.
Parâmetros de queryAté 256 ocorrências.
Leitura/escritaCada prazo entre 1 e 86400000 ms; relógio monotônico.
Conexões HTTP ativasUma por instância em atendimento sequencial.
Backlog64, sujeito ao limite do kernel.
Sockets vivos do runtime128, incluindo listeners e clientes TCP.
Requisições por conexãoUma; Connection: close em toda resposta.

O prazo de leitura cobre headers e corpo juntos e não reinicia a cada byte. O prazo de escrita cobre headers e corpo juntos. Assim, um cliente lento não mantém uma conexão indefinidamente. Ainda pode atrasar os próximos clientes até o prazo expirar: esta versão sequencial não promete resistência a uma inundação de conexões nem isolamento entre aplicações.

O parser exige HTTP/1.1, Host não vazio e CRLF. Host aceita nome ASCII sem escapes percentuais ou endereço IPv6 entre colchetes, com porta opcional 0..65535. Métodos fora dos sete disponíveis são recusados com 501; o alvo * é exclusivo de OPTIONS. Rejeita headers repetidos (inclusive Content-Length idênticos), folding e Content-Length inválido. Transfer-Encoding é recusado com 501; Expect, com 417. Corpo excessivo produz 413, headers excessivos 431 e prazo de leitura expirado 408. Mensagem incompleta ou inválida produz 400 quando ainda for possível responder. Não tenta recuperar a conexão ou interpretar uma segunda mensagem depois de erro.

Não há keep-alive, chunked, pipelining, streaming, WebSocket, SSE, multipart, upload, TLS, HTTP/2 ou compressão de resposta. Bytes extras depois da primeira requisição são descartados ao fechar; uma segunda requisição não executa rota. O perfil se baseia no framing de RFC 9112, com as restrições adicionais descritas aqui; não afirma implementar o protocolo inteiro.

abrir(endereco = "127.0.0.1", porta = 8080) abre o listener sem entrar no laço. portaLocal() permite descobrir a porta escolhida com porta = 0. atenderUma(timeout = 1000) aceita e trata uma conexão; devolve falso se a espera por conexão expirar. ativo() consulta o estado do listener. Isso permite que a aplicação controle seu próprio laço e condição de encerramento. escutar(endereco, porta) reúne abrir, laço e fechamento em finally.

fechar() é idempotente e fecha o listener; cada conexão aceita é fechada em finally, mesmo se o handler falhar. pararServidor() encerra após a resposta atual; não instala handlers globais de sinais nem oferece cancelamento entre threads. O destrutor chama fechar, mas use fechamento explícito/finally. Um finalizador GC é apenas contingência: não há prazo garantido para sua execução.

cgd:sockets

A camada TCP pode ser usada separadamente:

const Sockets: qualquer = importar("cgd:sockets")
var conexao: qualquer = Sockets.conectar("127.0.0.1", 9000, 1000)
tente {
    conexao.enviar("mensagem", 1000)
    var resposta: texto = conexao.receber(65536, 1000)
} finalmente {
    conexao.fechar()
}

conectar(endereco, porta, timeout = 30000) devolve Conexao. OuvinteTCP(endereco = "127.0.0.1", porta = 0) cria um listener; aceitar(timeout = 1000) devolve Conexao ou nulo no timeout. Ambos têm portaLocal() e fechar() idempotente. Conexao.enviar transmite integralmente até 16 MiB e devolve bytes enviados. receber(limite = 65536, timeout = 30000) lê até o limite (1..16777216 bytes); pode devolver um bloco menor. Texto vazio representa EOF. Timeout ou falha de I/O fecha a conexão e lança, evitando continuar um protocolo após uma operação incompleta.

Conexao.lerHTTP/responderHTTP são a adaptação usada pelo servidor. Não misture leituras TCP manuais e parsing HTTP na mesma conexão. Erros de validação antes do I/O lançam; o proprietário continua responsável por fechar em finally.

Os identificadores nativos são opacos e verificados por tag; não são números, FDs, ponteiros Delégua nem sessões curl. Aliases compartilham o mesmo recurso: fechar por um alias invalida os demais. Descritores são nonblocking/CLOEXEC, com espera síncrona via poll e envio sem SIGPIPE. Endereços de abertura aceitam IPv4 ou IPv6 numéricos sem DNS implícito; resolução explícita usa Sockets.resolverDNS(host, familia) e datagramas usam Sockets.abrirUDP.

Para atendimento concorrente com HTTP/1.1 keep-alive sobre o reactor epoll, HTTP oferece escutarAsync(endereco, porta, maxRequisicoesPorConexao) e atenderConexaoAsync(conexao, maxRequisicoes), reutilizando o mesmo parser validado e a mesma tabela de rotas e middlewares de HTTP. A implementação atual usa accept4 e flags de sockets do Linux; somente Linux x86_64 é a plataforma validada do projeto.

Validação e desempenho

python3 testes/servidor.py verifica rotas, os sete métodos, middleware, Unicode, JSON, corpos binários, framing hostil, tamanhos, timeout, mensagens parciais, pipelining recusado, desconexões, clientes simultâneos atendidos em sequência, fechamento e shutdown. python3 testes/sockets.py cobre cliente TCP, EOF, identificador inválido, reuso de porta e fechamento. Ambos compilam com e sem otimização. O parser puro tem regressões e corpus pseudoaleatório determinístico em testes/http_parser.c; o runner com sanitizadores fica em python3 testes/http_parser.py. Isso não substitui fuzzing contínuo ou auditoria.

scripts/benchmark_http.py mede várias rodadas de conexões novas, RPS, latências p50/p95/p99, RSS máximo observado, CPU do servidor e tempo de inicialização. Os resultados incluem configuração do cliente e sistema e ficam em JSON. Não há resultado de desempenho publicado nesta etapa nem comparação com outros servidores.