HTTP-Server

Ein http.service besitzt einen Listener und hostet Router, Endpunkte und Handler für statische Dateien.

Klassifikation: Server-Konfigurationsreferenz. Blöcke sind Registry-Teilfragmente, sofern sie nicht jeden referenzierten Netzwerk-, Umgebungs-, Dateisystem-, Router-, Zertifikat-, Actor- und Richtlinieneintrag definieren.

Konfiguration

- 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

Konfigurieren Sie Timeouts, um Ressourcenerschöpfung zu verhindern:

timeouts:
  read: "10s"    # Max Zeit zum Lesen der gesamten Anfrage (Header + Body)
  write: "60s"   # Max Zeit zum Schreiben der Response
  idle: "120s"   # Keep-Alive-Timeout

• read — Für APIs kurz (5–10 Sekunden), für Uploads länger
• write — An die erwartete Dauer der Response-Erzeugung anpassen
• idle — Verbindungswiederverwendung gegen Ressourcenverbrauch abwägen

Host-Konfiguration

Der host-Abschnitt konfiguriert das interne Nachrichten-Relay des Servers, das von Komponenten wie WebSocket-Relay verwendet wird:

host:
  buffer_size: 2048
  worker_count: 8

Sicherheit

HTTP-Server können einen Standard-Sicherheitskontext über die Lebenszyklus-Konfiguration anwenden:

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

Dies setzt einen Basis-Actor und Richtlinien für alle Anfragen. Bei authentifizierten Anfragen überschreibt die token_auth-Middleware den Actor anhand des validierten Tokens und ermöglicht damit benutzerspezifische Sicherheitsrichtlinien.

Lebenszyklus

Server werden vom Supervisor verwaltet:

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

Komponenten verbinden

Router und statische Handler referenzieren den Server über Metadaten:

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

Mehrere Server

Separate Server für verschiedene Zwecke betreiben:

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

Der Server kann TLS direkt terminieren. Setzen Sie tls.mode auf manual (eigenes Zertifikat bereitstellen) oder auto (Zertifikat wird von einem Overlay-Netzwerktreiber bereitgestellt, z. B. network.tailscale). Reine Clearnet-Listener unterstützen auto nicht. Lassen Sie tls weg oder den Modus leer, um reines HTTP auszuführen.

Im auto-Modus darf der Server cert/key nicht angeben — der Netzwerktreiber stellt sie bereit.

Manuelles Zertifikat

Unter mode: manual tragen cert und key PEM-Inhalt. Stelle diesen Inhalt auf eine von drei Arten bereit (pro Feld genau eine Variante, niemals gemischt):

1. Inline-PEM — der wörtliche PEM-String.
2. file://-Referenz — manifest-relativer Pfad, der beim Laden aufgelöst und inline eingefügt wird (traversal-sicher).
3. Referenz auf die Env-Registry — hole das PEM beim Dekodieren aus einer registrierten Umgebungsvariable über einen ${env:NAME}-Platzhalter.

- 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}

Der Platzhalter ${env:NAME} löst NAME über die Umgebungs-Registry auf — den öffentlichen Namen einer registrierten Variable oder deren Entry-ID (z. B. app.env:tls_cert). Es handelt sich nicht um eine rohe Betriebssystem-Umgebungsvariable; ein Betriebssystemwert ist nur erreichbar, wenn unter diesem Namen eine von env.storage.os gestützte Variable registriert ist. Ein Standardwert lässt sich mit ${env:NAME|default} angeben.

Mutual TLS (mTLS)

Unter mode: manual kann der Server zusätzlich Client-Zertifikate verifizieren:

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 akzeptiert dieselben drei Formen wie cert/key (Inline-PEM, file:// oder ${env:NAME}). Das alte Begleitfeld client_ca_env ist ebenfalls veraltet zugunsten von client_ca: ${env:NAME}.

verify_if_given und require_and_verify benötigen eine CA. request und require_any akzeptieren jedes Client-Zertifikat ohne CA-Verifizierung.

Siehe auch

• Routing – Router und Endpunkte
• Statische Dateien – Bereitstellung statischer Dateien
• Middleware – Verfügbare Middleware
• Sicherheit – Sicherheitsrichtlinien
• WebSocket-Relay – WebSocket-Nachrichten