Rokad
Toute la documentation
Documentation dhal

Configuration

Comprenez dhal.json, les modes, la sécurité d’exécution et l’ordre de priorité.

Voir le dépôt
Documentation dhal
Page 2 sur 9

Dhal v1 utilise schemaVersion: "1". Le fichier par défaut est dhal.json, mais les adaptateurs et createDhal() acceptent un autre configPath.

Ordre de priorité

La configuration effective est construite dans cet ordre :

  1. valeurs par défaut intégrées ;
  2. fichier chargé depuis configPath ;
  3. surcharge config passée au moteur ou à l’adaptateur.

Les objets sont fusionnés récursivement et les tableaux sont remplacés.

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

const protection = createDhal({
  configPath: "dhal.json",
  config: {
    mode: "monitor",
    response: { message: "Requête refusée" }
  }
});

Configuration minimale

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": {}
  }
}

Sections principales

ChampRôle
modeMode global off, monitor, block ou strict.
trustProxyUtilise les en-têtes de transfert pour résoudre l’IP.
runtimeErreurs internes, budget d’inspection et bypass.
identityEn-têtes utilisateur, tenant et clé API.
ipListes d’autorisation/blocage et réputation.
rateLimitLimites globales et par route.
rulesSignatures, bots, payload, API, en-têtes et identifiants.
routesSurcharges par route.
policySévérité, suppressions, échantillonnage et CI.
observabilityRedaction, événements, OTel et webhooks.
responseStatut et message de blocage.

Sécurité d’exécution

Utilisez onInternalError: "allow" pendant l’adoption initiale lorsque la disponibilité prime. N’utilisez le fail-closed qu’après avoir validé les dépendances et les scénarios de panne.

Gardez les bypass limités aux endpoints qui ne traitent pas d’entrée non fiable.

Confiance proxy

Activez trustProxy uniquement derrière un proxy fiable qui remplace les en-têtes de transfert et lorsque l’accès direct à l’application est bloqué. Une mauvaise configuration peut permettre de falsifier l’IP utilisée pour les limites, la réputation et l’audit.

Secrets et validation

Les champs apiKeyEnv et secretEnv contiennent des noms de variables d’environnement, pas des secrets.

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

Le schéma est disponible via @rokadhq/dhal/dhal.schema.json et getDhalConfigJsonSchema().