Servidor HTTP

Um http.service possui um listener e hospeda roteadores, endpoints e handlers de arquivos estáticos.

Classificação: referência de configuração do servidor. Os blocos são fragmentos parciais do registro, a menos que definam todas as entradas de rede, ambiente, sistema de arquivos, roteador, certificado, ator e política referenciadas.

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

Timeouts

Configure timeouts para evitar esgotamento de recursos:

timeouts:
  read: "10s"    # Max time to read the entire request (headers + body)
  write: "60s"   # Max time to write response
  idle: "120s"   # Keep-alive timeout

• 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

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

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 de base para todas as requisições. Para requisições autenticadas, o middleware token_auth substitui o ator com base 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
  requires:
    - app:database

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:
  # Public API
  - name: public
    kind: http.service
    addr: ":8080"
    lifecycle:
      auto_start: true

  # Admin (localhost only)
  - 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 — o driver de rede os fornece.

Certificado manual

Sob mode: manual, cert e key carregam conteúdo PEM. Forneça esse conteúdo de uma de três formas (escolha uma por campo, nunca misture):

1. PEM inline — a string PEM literal.
2. Referência file:// — caminho relativo ao manifesto, resolvido e embutido no momento do carregamento (seguro contra traversal).
3. Referência ao registro de ambiente — obtém o PEM de uma variável de ambiente registrada no momento da decodificação, usando um placeholder ${env:NAME}.

- 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:app.env:tls_cert}
    key:  ${env:app.env:tls_key}

O placeholder ${env:NAME} resolve NAME através do registro de ambiente — o nome público de uma variável registrada ou o ID da sua entrada (ex. app.env:tls_cert). Não é uma variável de ambiente bruta do SO; um valor do SO só é alcançável quando uma variável com backend env.storage.os está registrada sob aquele nome. Um padrão pode ser fornecido com ${env:NAME|default}.

Mutual TLS (mTLS)

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

tls:
  mode: manual
  cert: ${env:app.env:tls_cert}
  key:  ${env:app.env:tls_key}
  client_ca: file://./certs/clients-ca.pem
  client_auth: require_and_verify

client_ca aceita as mesmas três formas de cert/key (PEM inline, file:// ou ${env:NAME}). O campo companheiro legado client_ca_env está igualmente deprecado em favor de client_ca: ${env:NAME}.

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

• Roteamento - Roteadores e endpoints
• Arquivos Estáticos - Serviço de arquivos estáticos
• Middleware - Middleware disponível
• Segurança - Políticas de segurança
• WebSocket Relay - Mensageria WebSocket