CLI と本番準備 — dhalドキュメント

dhalドキュメント

9ページ中8ページ

dhal CLIは@rokadhq/dhalに含まれ、npx dhalで実行できます。

主なコマンド

bash

npx dhal add
npx dhal init
npx dhal test-config
npx dhal migrate --check
npx dhal doctor
npx dhal doctor --fix --dry-run
npx dhal openapi inspect openapi.json
npx dhal openapi generate openapi.yaml
npx dhal readiness --production
npx dhal compat
npx dhal stability
npx dhal rules
npx dhal presets list
npx dhal replay fixtures.replay.json
npx dhal simulate fixtures.simulation.json
npx dhal report --output dhal.report.json
npx dhal release-check --target stable --require-build

ガイド付きプロジェクト導入

bash

npx dhal add

dhal addはpackage.jsonからExpress、Fastify、NestJS、Koa、Honoを、ロックファイルからnpm、pnpm、Yarn、Bunを検出します。既定では読み取り専用で、フレームワークプリセット、監視モードのdhal.json、統合モジュール、インストールコマンド、登録手順をプレビューします。

確認後に作成します。

bash

npx dhal add --write

主なオプション:

text

--framework <name>       検出結果を上書き
--config <path>          設定ファイルのパス
--integration <path>     生成する統合モジュールのパス
--write                  提案ファイルを作成
--force                  既存の生成出力を上書き

既存のアプリケーションコードを自動変更することはありません。

初期化、検証、移行

bash

npx dhal init
npx dhal test-config
npx dhal migrate --check

initは監視優先の汎用設定を作成します。test-configは有効設定を検証し、migrate --checkはファイルを変更せずに移行要否を報告します。migrate --writeは提案内容を確認した後に使用してください。

Doctorと保守的な修復

bash

npx dhal doctor
npx dhal doctor --fix --dry-run
npx dhal doctor --fix

doctor --fixの範囲は意図的に限定されています。不足する監視モード設定の作成、schemaVersion以前の互換設定の移行、既存ファイル変更前のdhal.json.bak作成が可能です。

ブロック、プロキシ信頼、Redis、レピュテーション、OpenTelemetry、Webhookを自動有効化しません。確認には--dry-runを使い、別のバックアップがある場合のみ--no-backupを使用してください。

フレームワークプリセット

bash

npx dhal presets list
npx dhal presets show nestjs-api
npx dhal presets apply hono-node-api --output dhal.hono.json

バージョン1.1では次を追加しました。

text

express-api
fastify-api
nestjs-api
koa-api
hono-node-api
node-http-api

既存のstarter、api-production、auth-hardened、strict-json-api、behind-proxy、observabilityも利用できます。生成結果は必ずレビューして検証してください。

OpenAPI検査

bash

npx dhal openapi inspect openapi.json
npx dhal openapi inspect openapi.yaml

JSONは構造的に解析します。YAMLは一般的なパス、メソッド、タグ、セキュリティ、コンテンツタイプを保守的に走査します。アンカー、マージキー、外部参照を使う複雑なYAMLはJSONへ変換してください。

認証、multipartアップロード、Webhook、高コスト操作、明示的な公開操作、JSON本文などを分類します。

OpenAPIから監視ポリシーを生成

bash

npx dhal openapi generate openapi.yaml

パラメーターはDhalワイルドカードへ変換されます。

text

/users/{userId}              -> /users/*
/orgs/{orgId}/users/{userId} -> /orgs/*/users/*

生成ルートはすべてmonitorのままです。既存ルートプロファイルは保持され、preserve-existingとして報告されます。

bash

npx dhal openapi generate openapi.yaml --config dhal.json --write
npx dhal openapi generate openapi.json --output dhal.openapi.json

前者はバックアップを作成します。別出力の上書きには--force、バックアップ省略には--no-backup、生成上限の変更には--default-maxを使用します。

生成ポリシーはセキュリティ提案であり、認可モデルではありません。ブロック前に、まとめられたメソッド、分類、レート上限、コンテンツタイプの前提を確認してください。

準備状況、互換性、安定性

bash

npx dhal readiness --production
npx dhal compat
npx dhal stability

準備状況は本番設定を評価し、互換性はテスト済みマトリクスを示し、安定性は公開APIの契約レベルを示します。リプレイ試験やアプリ固有のレビューを置き換えるものではありません。

ルール、リプレイ、シミュレーション

bash

npx dhal rules
npx dhal replay fixtures.replay.json
npx dhal simulate fixtures.simulation.json

正常・悪意のあるトラフィックのfixtureをバージョン管理してください。正常通信が予期せずブロックされた場合や、悪意あるケースが想定ルールに一致しなくなった場合は昇格を失敗させます。

CIポリシー

bash

npx dhal ci

policy.ciで危険なモードの禁止、Webhook署名の要求、監視ルールの確認、期限切れ除外の拒否が可能です。

サポートレポートとリリース確認

bash

npx dhal report --output dhal.report.json
npx dhal release-check --target stable --require-build

共有前にレポートを確認し、秘密情報、資格情報、トークン、未秘匿の本番通信を公開しないでください。

適用前チェックリスト

blockまたはstrictを有効にする前に確認します。

Dhalの正確なバージョンが固定され、ランタイムが対応している
schemaVersionが"1"
導入またはOpenAPIの変更をレビュー済み
検証、移行、Doctor、準備状況が成功
正常・悪意あるリプレイfixtureが成功
複数インスタンスではRedisまたはValkeyを共有
署名、秘匿、close()による終了処理を設定
monitorへのロールバックを文書化し試験済み