API et contrat v1 — Documentation dhal

Documentation dhal

Page 9 sur 9

Dhal 1.x fournit un contrat stable pour le paquet, la CLI et la configuration. Les surfaces expérimentales sont identifiées explicitement.

Moteur

import { createDhal } from "@rokadhq/dhal";
const protection = createDhal({ configPath: "dhal.json" });

DhalEngine expose :

config : configuration résolue ;
events : bus d’événements ;
inspect(request) : décision de sécurité ;
recordOutcome(request, outcome) : résultat utilisé par les signaux d’identifiants ;
flush(timeoutMs?) : vide la télémétrie ;
close(timeoutMs?) : ferme et vide ;
getRuntimeSnapshot() : compteurs et santé.

Une DhalDecision contient action, statusCode, reason, score et éventuellement ruleId, severity, wouldBlock et meta. En mode monitor, une décision bloquante est autorisée avec wouldBlock: true.

DhalOptions accepte config, configPath, logger, rateLimitStore, signalStore, ipReputationProvider et telemetry.

Sous-chemins stables

@rokadhq/dhal
@rokadhq/dhal/express
@rokadhq/dhal/fastify
@rokadhq/dhal/node-http
@rokadhq/dhal/stores/redis
@rokadhq/dhal/stores/redis-signal
@rokadhq/dhal/stores/memory-signal
@rokadhq/dhal/reputation/abuseipdb
@rokadhq/dhal/telemetry/otel
@rokadhq/dhal/telemetry/webhook
@rokadhq/dhal/config-schema
@rokadhq/dhal/doctor
@rokadhq/dhal/rules/catalog
@rokadhq/dhal/presets
@rokadhq/dhal/report
@rokadhq/dhal/compatibility
@rokadhq/dhal/readiness
@rokadhq/dhal/migrations
@rokadhq/dhal/stability
@rokadhq/dhal/v1-contract

Contrat lisible par machine

import {
  DHAL_V1_PUBLIC_EXPORTS,
  DHAL_V1_CLI_COMMANDS,
  getDhalV1Contract,
  validateDhalV1Contract
} from "@rokadhq/dhal/v1-contract";

Dans 1.x, les exports stables ne sont ni supprimés ni renommés, les commandes stables restent disponibles, le schéma 1 reste compatible et les dépréciations reçoivent un guide de migration avant une future version majeure.

L’autosetup assisté par IA est expérimental.

Mise à niveau

bash

npm install @rokadhq/dhal@latest
npx dhal migrate --check
npx dhal test-config
npx dhal doctor
npx dhal readiness --production
npx dhal replay fixtures.replay.json

Consultez le changelog et conservez un rollback testé vers la version précédente et le mode monitor.