Rokad
Gesamte Dokumentation
dhal-Dokumentation

Konfiguration

Verstehen Sie dhal.json, Betriebsmodi, Laufzeitsicherheit und Priorität.

Repository ansehen
dhal-Dokumentation
Seite 2 von 9

Dhal v1 verwendet schemaVersion: "1". Die Standarddatei ist dhal.json; Adapter und createDhal() akzeptieren jedoch einen anderen configPath.

Priorität

Die wirksame Konfiguration entsteht in dieser Reihenfolge:

  1. integrierte Standardwerte;
  2. Datei aus configPath;
  3. Inline-Überschreibung config am Motor oder Adapter.

Objekte werden rekursiv zusammengeführt, Arrays ersetzt.

ts
import { createDhal } from "@rokadhq/dhal";

const protection = createDhal({
  configPath: "dhal.json",
  config: {
    mode: "monitor",
    response: { message: "Request abgelehnt" }
  }
});

Minimale Konfiguration

json
{
  "schemaVersion": "1",
  "mode": "monitor",
  "trustProxy": false,
  "runtime": {
    "onInternalError": "allow",
    "internalErrorStatusCode": 500,
    "maxInspectionMs": 25,
    "bypass": {
      "enabled": true,
      "paths": ["/health", "/ready"],
      "methods": ["OPTIONS"]
    }
  },
  "rateLimit": {
    "enabled": true,
    "store": "memory",
    "keyBy": ["ip", "route"],
    "default": { "windowSeconds": 60, "max": 120 },
    "routes": {}
  }
}

Hauptbereiche

FeldZweck
modeGlobales Verhalten off, monitor, block oder strict.
trustProxyVertraut Forwarding-Headern zur IP-Ermittlung.
runtimeInterne Fehler, Inspektionsbudget und Bypass.
identityHeader für Benutzer, Tenant und API-Schlüssel.
ipAllow-/Blocklisten und Reputation.
rateLimitGlobale und routenbezogene Limits.
rulesSignaturen, Bots, Payload, API, Header und Credentials.
routesRoutenbezogene Überschreibungen.
policySchweregrad, Suppressions, Sampling und CI.
observabilityRedaction, Events, OTel und Webhooks.
responseStatus und Meldung bei Blockierung.

Laufzeitsicherheit

Verwenden Sie während der Einführung onInternalError: "allow", wenn Verfügbarkeit Vorrang hat. Fail-closed sollte erst nach Tests von Abhängigkeiten und Fehlerfällen eingesetzt werden.

Bypasses sollten nur Endpoints umfassen, die keine nicht vertrauenswürdigen Anwendungsdaten verarbeiten.

Proxy-Vertrauen

Aktivieren Sie trustProxy nur hinter einem vertrauenswürdigen Proxy, der Forwarding-Header überschreibt und direkten Zugriff auf die Anwendung verhindert. Eine falsche Einstellung kann IP-basierte Limits, Reputation und Audit schwächen.

Secrets und Validierung

apiKeyEnv und secretEnv enthalten Namen von Umgebungsvariablen, keine Secrets.

bash
npx dhal test-config
npx dhal migrate --check

Das JSON-Schema steht unter @rokadhq/dhal/dhal.schema.json und über getDhalConfigJsonSchema() bereit.