Integraciones con frameworks

Dhal v1.1 incluye adaptadores para Express, Fastify, NestJS, Koa, Hono sobre Node.js y node:http. Todos reutilizan el mismo motor, configuración, almacenes, telemetría y ciclo de decisiones.

Express

import { dhal } from "@rokadhq/dhal/express";
app.use(express.json({ limit: "1mb" }));
app.use(dhal({ configPath: "dhal.json" }));

Coloca los analizadores de cuerpo antes de Dhal cuando las reglas deban inspeccionar cargas ya analizadas. El adaptador lee req.body, req.rawBody opcional, identidades y el estado final de respuesta. Usa dhalFromEngine(engine) con un motor creado previamente.

Fastify

import { dhalFastify } from "@rokadhq/dhal/fastify";
await app.register(dhalFastify({ configPath: "dhal.json" }));

Dhal inspecciona en preHandler y registra resultados en onResponse. Usa dhalFastifyFromEngine(engine) para un motor existente.

NestJS

import { installDhalNest } from "@rokadhq/dhal/nest";
const app = await NestFactory.create(AppModule);
const dhal = await installDhalNest(app, { configPath: "dhal.json" });
await app.listen(3000);

Instala Dhal después de crear la aplicación y antes de app.listen(). Dhal detecta si Nest utiliza Express o Fastify e instala el adaptador estable correspondiente.

import { installDhalNestFromEngine } from "@rokadhq/dhal/nest";
const installation = await installDhalNestFromEngine(app, engine);

La instalación expone engine, la platform detectada y close(). Los transportes de microservicios Nest sin adaptador HTTP quedan fuera de esta integración.

Koa

import { dhalKoa } from "@rokadhq/dhal/koa";
app.use(dhalKoa({ configPath: "dhal.json" }));

Registra Dhal antes de las rutas. El adaptador inspecciona antes del middleware posterior, detiene la cadena al bloquear, añade x-dhal-action y x-dhal-rule, registra el estado final y lee identidades desde context.state. Usa dhalKoaFromEngine(engine) para gestionar el ciclo de vida.

Hono sobre Node.js

import { dhalHono } from "@rokadhq/dhal/hono";
app.use("*", dhalHono({ configPath: "dhal.json" }));

El adaptador usa objetos Web Request y Response, devuelve una respuesta controlada al bloquear y registra el resultado final. Las identidades pueden exponerse mediante context.var. El objetivo soportado de v1.1 es Hono sobre Node.js; los runtimes de borde no forman parte del compromiso de compatibilidad.

node:http

import { createNodeHttpDhal } from "@rokadhq/dhal/node-http";
const protection = createNodeHttpDhal({ configPath: "dhal.json" });

El adaptador normaliza método, URL, ruta, cabeceras, IP, identidad y content-length. No consume el flujo de la solicitud.

Integraciones personalizadas

import { createDhal, type DhalRequest } from "@rokadhq/dhal";
const protection = createDhal({ configPath: "dhal.json" });
const decision = await protection.inspect(request);
await protection.recordOutcome(request, { statusCode: 401 });

Llama a recordOutcome() cuando se conozca la respuesta para actualizar señales dependientes del resultado.

Ciclo de vida y respuestas de bloqueo

process.once("SIGTERM", async () => {
  await protection.close(5_000);
  process.exit(0);
});

Los adaptadores añaden x-dhal-action: block y x-dhal-rule: <rule id>, y devuelven el código configurado con una respuesta JSON controlada. No expongas metadatos privados de decisión a clientes no confiables.