Servidor HTTP

O servidor HTTP (http.service) escuta em uma porta e hospeda roteadores, endpoints e handlers de arquivos estáticos.

Configuração

- name: gateway
  kind: http.service
  addr: ":8080"
  timeouts:
    read: "5s"
    write: "30s"
    idle: "60s"
  host:
    buffer_size: 1024
    worker_count: 4
  lifecycle:
    auto_start: true
    security:
      actor:
        id: "http-gateway"
      policies:
        - app:http_policy
Campo Tipo Padrão Descrição
addr string obrigatório Endereço de escuta (:8080, 0.0.0.0:443)
timeouts.read duration - Timeout de leitura de requisição
timeouts.write duration - Timeout de escrita de resposta
timeouts.idle duration - Timeout de conexão keep-alive
host.buffer_size int 1024 Tamanho do buffer do relay de mensagens
host.worker_count int NumCPU Workers do relay de mensagens
network ID do Registro - Vincula o listener através de uma rede overlay (ex. Tailscale, I2P)
tls object - Terminação TLS (ver TLS)

Timeouts

Configure timeouts para evitar esgotamento de recursos:

timeouts:
  read: "10s"    # Tempo máximo para ler headers de requisição
  write: "60s"   # Tempo máximo para escrever resposta
  idle: "120s"   # Timeout keep-alive
  • read - Curto (5-10s) para APIs, maior para uploads
  • write - Deve corresponder ao tempo esperado de geração de resposta
  • idle - Balanço entre reutilização de conexão e uso de recursos
Formato de duração: 30s, 1m, 2h15m. Use 0 para desabilitar.

Configuração de Host

A seção host configura o relay interno de mensagens do servidor, usado por componentes como WebSocket relay:

host:
  buffer_size: 2048
  worker_count: 8
Campo Padrão Descrição
buffer_size 1024 Capacidade da fila de mensagens por worker
worker_count NumCPU Goroutines paralelas de processamento de mensagens
Aumente esses valores para aplicações WebSocket de alto throughput. O relay de mensagens trata a entrega assíncrona entre componentes HTTP e processos.

Segurança

Servidores HTTP podem ter um contexto de segurança padrão aplicado através da configuração de lifecycle:

lifecycle:
  auto_start: true
  security:
    actor:
      id: "gateway-service"
    policies:
      - app:http_access_policy

Isso define um ator e políticas base para todas as requisições. Para requisições autenticadas, o middleware token_auth sobrescreve o ator baseado no token validado, permitindo políticas de segurança por usuário.

Lifecycle

Servidores são gerenciados pelo supervisor:

lifecycle:
  auto_start: true
  start_timeout: 30s
  stop_timeout: 60s
  depends_on:
    - app:database
Campo Descrição
auto_start Iniciar quando a aplicação iniciar
start_timeout Tempo máximo de espera pelo início do servidor
stop_timeout Tempo máximo para shutdown graceful
depends_on Iniciar após essas entradas estarem prontas

Conectando Componentes

Roteadores e handlers estáticos referenciam o servidor via metadados:

entries:
  - name: gateway
    kind: http.service
    addr: ":8080"

  - name: api
    kind: http.router
    meta:
      server: gateway
    prefix: /api

  - name: static
    kind: http.static
    meta:
      server: gateway
    path: /
    fs: app:public

Múltiplos Servidores

Execute servidores separados para propósitos diferentes:

entries:
  # API pública
  - name: public
    kind: http.service
    addr: ":8080"
    lifecycle:
      auto_start: true

  # Admin (apenas localhost)
  - name: admin
    kind: http.service
    addr: "127.0.0.1:9090"
    lifecycle:
      auto_start: true

TLS

O servidor pode terminar TLS diretamente. Defina tls.mode como manual (forneça seu próprio certificado) ou auto (certificado fornecido por um driver de rede overlay, ex. network.tailscale). Listeners clearnet simples não suportam auto. Omita tls ou deixe o mode vazio para executar HTTP simples.

No modo auto o servidor não deve especificar cert/key/cert_env/key_env — o driver de rede os fornece.

Certificado manual

Forneça cert e key inline/carregados de arquivo ou via variáveis de ambiente (nunca ambos):

- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert: file://./certs/server.pem
    key:  file://./certs/server.key

- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert_env: TLS_SERVER_CERT
    key_env:  TLS_SERVER_KEY
Campo Descrição
mode "" (off), auto ou manual
cert / key Conteúdo PEM (tipicamente carregado via file://)
cert_env / key_env Nomes de variáveis de ambiente resolvidas via o registro env

Mutual TLS (mTLS)

Sob mode: manual o servidor pode adicionalmente verificar certificados de cliente:

tls:
  mode: manual
  cert_env: TLS_SERVER_CERT
  key_env:  TLS_SERVER_KEY
  client_ca: file://./certs/clients-ca.pem
  client_auth: require_and_verify
Campo Descrição
client_auth request, require_any, verify_if_given, require_and_verify
client_ca Bundle PEM de CAs de cliente confiáveis
client_ca_env Variável de ambiente contendo o bundle da CA (mutuamente exclusiva com client_ca)

verify_if_given e require_and_verify exigem uma CA. request e require_any aceitam qualquer certificado de cliente sem verificação de CA.

Veja Também