Servidor HTTP

Un http.service posee un listener y aloja routers, endpoints y handlers de archivos estáticos.

Clasificación: referencia de configuración de servidor. Los bloques son fragmentos parciales de registro salvo que definan cada red, entorno, sistema de archivos, router, certificado, actor y entrada de política referenciados.

Configuración

- 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 prevenir el agotamiento 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 - Corto (5-10s) para APIs, mayor para uploads
• write - Debe coincidir con el tiempo esperado de generación de respuesta
• idle - Balance entre reutilización de conexiones y uso de recursos

Configuración de Host

La sección host configura el relay interno de mensajes del servidor, usado por componentes como WebSocket relay:

host:
  buffer_size: 2048
  worker_count: 8

Seguridad

Los servidores HTTP pueden tener un contexto de seguridad predeterminado aplicado mediante la configuración de lifecycle:

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

Esto establece un actor y políticas de base para todas las solicitudes. Para las solicitudes autenticadas, el middleware token_auth sustituye el actor según el token validado, lo que permite políticas de seguridad por usuario.

Lifecycle

Los servidores son gestionados por el supervisor:

lifecycle:
  auto_start: true
  start_timeout: 30s
  stop_timeout: 60s
  requires:
    - app:database

Conectando Componentes

Los routers y handlers estáticos referencian al servidor via metadatos:

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últiples Servidores

Ejecute servidores separados para distintos propósitos:

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

El servidor puede terminar TLS directamente. Configure tls.mode como manual (provea su propio certificado) o auto (certificado proporcionado por un driver de red overlay, ej. network.tailscale). Los listeners planos de clearnet no soportan auto. Omita tls o deje el mode vacío para ejecutar HTTP plano.

En modo auto el servidor no debe especificar cert/key — el driver de red los provee.

Certificado manual

Bajo mode: manual, cert y key llevan contenido PEM. Proporcione ese contenido de una de estas tres formas (elija una por campo, nunca las mezcle):

1. PEM inline — el string PEM literal.
2. Referencia file:// — ruta relativa al manifiesto, resuelta e incorporada en tiempo de carga (segura ante traversal).
3. Referencia al registro de entorno — obtiene el PEM de una variable de entorno registrada en tiempo de decodificación, usando un 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}

El placeholder ${env:NAME} resuelve NAME a través del registro de entorno — el nombre público de una variable registrada o su ID de entrada (ej. app.env:tls_cert). No es una variable de entorno cruda del SO; un valor del SO solo es alcanzable cuando hay registrada una variable respaldada por env.storage.os con ese nombre. Puede darse un valor por defecto con ${env:NAME|default}.

Mutual TLS (mTLS)

Bajo mode: manual el servidor puede además 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 acepta las mismas tres formas que cert/key (PEM inline, file://, o ${env:NAME}). El campo acompañante heredado client_ca_env también está obsoleto en favor de client_ca: ${env:NAME}.

verify_if_given y require_and_verify requieren una CA. request y require_any aceptan cualquier certificado de cliente sin verificación de CA.

Véase también

• Enrutamiento - Routers y endpoints
• Archivos estáticos - Servicio de archivos estáticos
• Middleware - Middleware disponible
• Seguridad - Políticas de seguridad
• Relay WebSocket - Mensajería WebSocket