Beta / v1 Readiness

Dhal v0.12.0-beta.0 is the first v1-readiness beta release.

This means Dhal is no longer positioned as a public-alpha experiment. It is now entering the stabilization phase before v1.0.0, with a stronger focus on API stability, configuration compatibility, runtime safety, production diagnostics, and real-world framework testing.

Install the beta

Install the current beta track explicitly:

npm install @rokadhq/dhal@beta

Initialize a config file:

npx dhal init

Run diagnostics:

npx dhal doctor
npx dhal readiness
npx dhal compat

What beta means

The beta track is intended for:

• Real application integration testing
• Compatibility validation across Node.js frameworks
• Production-readiness evaluation
• API and config stabilization before v1.0.0
• Feedback from early adopters before the stable release

The beta track is not intended for reckless automatic enforcement. Dhal should be introduced carefully:

1. Start in monitor mode.
2. Review rule hits and telemetry.
3. Replay known-good traffic.
4. Add route-level suppressions where needed.
5. Enable block mode only on selected routes.
6. Move toward broader enforcement after confidence increases.

Recommended beta rollout

A safe beta rollout should look like this:

npm install @rokadhq/dhal@beta
npx dhal init
npx dhal doctor
npx dhal rules
npx dhal readiness --production
npx dhal report --output dhal.report.json

Then run Dhal in monitor mode:

{
  "mode": "monitor"
}

After reviewing events, enable block mode only for specific high-risk routes:

{
  "mode": "monitor",
  "routes": {
    "/api/login": {
      "mode": "block",
      "rateLimit": {
        "windowSeconds": 60,
        "max": 5,
        "keyBy": ["ip", "route"]
      },
      "rules": {
        "credentialStuffing": true,
        "bot": true
      }
    }
  }
}

New beta commands

Dhal v0.12.0-beta.0 adds two v1-readiness commands:

npx dhal readiness
npx dhal compat

dhal readiness

The readiness command evaluates whether your Dhal setup is close to production-ready.

npx dhal readiness

For stricter evaluation:

npx dhal readiness --production

Require a minimum readiness score:

npx dhal readiness --production --min-score 85

JSON output:

npx dhal readiness --json

Use this before enabling block mode in production.

dhal compat

The compat command prints Dhal’s supported compatibility matrix.

npx dhal compat

JSON output:

npx dhal compat --json

Use this to check supported Node.js versions, framework adapters, module formats, stores, telemetry integrations, and release-channel status.

Public beta API

The beta release adds public APIs for readiness and compatibility checks.

import {
  runDhalReadiness,
  getDhalCompatibilityMatrix,
  DHAL_PACKAGE_VERSION,
  DHAL_RELEASE_CHANNEL
} from "@rokadhq/dhal";

Subpath imports are also available:

import { runDhalReadiness } from "@rokadhq/dhal/readiness";
import { getDhalCompatibilityMatrix } from "@rokadhq/dhal/compatibility";

These APIs are part of the v1-readiness track and are expected to become stable before v1.0.0.

Release channels

Dhal uses npm dist-tags to separate release maturity levels.

Channel	npm tag	Meaning
Alpha	alpha	Public experimentation and hardening
Beta	beta	v1-readiness and API stabilization
RC	rc	Release candidate for v1
Next	next	Current pre-1.0 normal track
Stable	latest	Stable v1+ releases

Install the beta:

npm install @rokadhq/dhal@beta

Install the current pre-1.0 normal track:

npm install @rokadhq/dhal@next

Install the future stable release:

npm install @rokadhq/dhal@latest

Stable vs experimental surface

Before v1.0.0, Dhal is separating stable public surface area from experimental internals.

Expected stable for v1

The following areas are intended to become stable for v1.0.0:

• dhal.json configuration model
• Express adapter
• Fastify adapter
• raw node:http adapter
• Core request inspection engine
• Rate limiting model
• IP allow/block rules
• CIDR matching
• Route-level policies
• Runtime safety controls
• CLI commands
• Presets
• Support reports
• Readiness checks
• Compatibility checks
• Public schema export

Still evolving before v1

The following areas may still evolve before v1.0.0:

• AI autosetup internals
• Provider/model abstraction for autosetup
• Advanced bot scoring details
• Rule confidence tuning
• Reputation provider abstraction
• Telemetry internals
• Rule-pack internals
• Experimental framework adapters

Production-readiness checklist

Before using Dhal in production enforcement mode, complete this checklist:

• Pin the package version.
• Start with mode: "monitor".
• Run npx dhal doctor.
• Run npx dhal readiness --production.
• Run npx dhal compat.
• Review the enabled rule catalog with npx dhal rules.
• Confirm trustProxy is correct for your deployment.
• Use Redis or Valkey for distributed rate limiting in multi-instance deployments.
• Configure runtime bypasses for health checks and preflight requests.
• Configure observability redaction.
• Generate a support report with npx dhal report.
• Replay known-good traffic fixtures.
• Enable block mode route by route.
• Review webhook and OTel output before broad rollout.

Runtime safety expectations

For beta and v1-readiness deployments, Dhal should be configured with explicit runtime safety behavior:

{
  "runtime": {
    "onInternalError": "allow",
    "internalErrorStatusCode": 500,
    "maxInspectionMs": 25,
    "bypass": {
      "enabled": true,
      "paths": ["/health", "/healthz", "/ready", "/readyz", "/live", "/livez"],
      "methods": ["OPTIONS"]
    }
  }
}

Recommended default for most applications:

{
  "runtime": {
    "onInternalError": "allow"
  }
}

This keeps Dhal fail-open by default if an unexpected internal inspection error occurs.

For highly sensitive APIs, teams may choose fail-closed behavior after testing:

{
  "runtime": {
    "onInternalError": "block",
    "internalErrorStatusCode": 500
  }
}

Use fail-closed mode carefully.

Privacy-first diagnostics

Dhal beta includes privacy-aware diagnostics and support reporting.

Recommended redaction settings:

{
  "observability": {
    "redaction": {
      "enabled": true,
      "ip": "mask",
      "identity": "hash",
      "userAgent": "full"
    }
  }
}

Generate a redacted report:

npx dhal report --output dhal.report.json

Use this report when debugging integration issues or filing GitHub issues.

Compatibility validation

Run compatibility checks before production trials:

npx dhal compat

This helps confirm your environment against Dhal’s supported matrix, including:

• Node.js runtime support
• Framework adapter support
• ESM and CommonJS package support
• Redis / Valkey store support
• OpenTelemetry integration support
• Release-channel metadata

Upgrade guidance

During beta:

• Pin exact versions for production trials.
• Read the changelog before upgrading.
• Avoid unattended automatic upgrades.
• Re-run doctor, readiness, and compat after each upgrade.
• Keep dhal.json in version control.
• Use npx dhal migrate when migration support is provided.

Recommended upgrade sequence:

npm install @rokadhq/dhal@beta
npx dhal doctor
npx dhal readiness --production
npx dhal compat
npx dhal test-config

Path to v1

The expected path toward v1.0.0 is:

v0.12.x-beta.x  → v1-readiness beta
v0.14.x-rc.x    → release candidate
v1.0.0          → stable release

Before v1, the focus is:

• API stability
• Config schema stability
• Compatibility test coverage
• False-positive controls
• Migration discipline
• Documentation completeness
• Production rollout safety

Recommended next step

For most teams evaluating Dhal beta:

npm install @rokadhq/dhal@beta
npx dhal init
npx dhal doctor
npx dhal readiness --production

Then run in monitor mode and review what Dhal observes before enabling route-level blocking.