API and v1 contract — dhal Documentation

dhal documentation

Page 9 of 9

Dhal 1.x provides a stable package, CLI, and configuration contract. Experimental surfaces are explicitly identified and are not covered by the same compatibility guarantee.

Core engine

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

const protection = createDhal({
  configPath: "dhal.json"
});

createDhal() returns a DhalEngine with:

Member	Purpose
`config`	Fully resolved and validated configuration.
`events`	Application event bus for decisions and signals.
`inspect(request)`	Evaluates a normalized request and returns a decision.
`recordOutcome(request, outcome)`	Records response outcomes used by credential-failure controls.
`flush(timeoutMs?)`	Drains managed telemetry.
`close(timeoutMs?)`	Closes the engine and drains managed telemetry.
`getRuntimeSnapshot()`	Returns counters, lifecycle state, and telemetry health.

Decisions

interface DhalDecision {
  action: "allow" | "block" | "log";
  statusCode: number;
  reason: string;
  ruleId?: string;
  score: number;
  severity?: "info" | "low" | "medium" | "high" | "critical";
  wouldBlock?: boolean;
  meta?: Record<string, unknown>;
}

In monitor mode, a decision that would otherwise block is returned as allowed with wouldBlock: true.

Options

interface DhalOptions {
  config?: PartialDeep<DhalConfig>;
  configPath?: string;
  logger?: Pick<Console, "log" | "warn" | "error">;
  rateLimitStore?: RateLimitStore;
  signalStore?: DhalSignalStore;
  ipReputationProvider?: IpReputationProvider;
  telemetry?: DhalTelemetry;
}

Stable package subpaths

Import	Surface
`@rokadhq/dhal`	Core engine, configuration, stores, telemetry, policy, diagnostics, and stable types.
`@rokadhq/dhal/express`	Express adapter.
`@rokadhq/dhal/fastify`	Fastify adapter.
`@rokadhq/dhal/node-http`	Raw Node HTTP adapter.
`@rokadhq/dhal/stores/redis`	Redis-compatible rate-limit store.
`@rokadhq/dhal/stores/redis-signal`	Redis-compatible signal store.
`@rokadhq/dhal/stores/memory-signal`	In-memory signal store.
`@rokadhq/dhal/reputation/abuseipdb`	AbuseIPDB provider.
`@rokadhq/dhal/telemetry/otel`	OpenTelemetry adapter.
`@rokadhq/dhal/telemetry/webhook`	Webhook telemetry adapter.
`@rokadhq/dhal/config-schema`	Programmatic JSON Schema access.
`@rokadhq/dhal/doctor`	Doctor API.
`@rokadhq/dhal/rules/catalog`	Rule catalog API.
`@rokadhq/dhal/presets`	Preset API.
`@rokadhq/dhal/report`	Support-report API.
`@rokadhq/dhal/compatibility`	Compatibility matrix.
`@rokadhq/dhal/readiness`	Readiness API.
`@rokadhq/dhal/migrations`	Configuration migration API.
`@rokadhq/dhal/stability`	API stability report.
`@rokadhq/dhal/v1-contract`	Machine-readable v1 contract.

The package also exports @rokadhq/dhal/dhal.schema.json.

Machine-readable contract

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

Use validateDhalV1Contract() in release tooling when you need to verify that the package still satisfies the frozen inventory.

Compatibility promise

Within 1.x:

stable exports will not be removed or renamed;
stable CLI commands remain available;
schema version 1 remains backward compatible;
deprecated APIs receive migration guidance before removal in a future major version;
experimental APIs can evolve while explicitly marked experimental.

AI-assisted autosetup is experimental and should not be treated as part of the stable production contract.

The v1 release process validates Node.js 20, 22, and 24; Express 4 and 5; Fastify 4 and 5; raw node:http; Redis 7; Valkey 8; ESM; CommonJS; TypeScript; packed installation; and release performance budgets.

Upgrade workflow

Before upgrading within v1:

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

Review the changelog, commit configuration changes separately, and retain a tested rollback to the previously pinned version and monitor mode.