設定 — dhalドキュメント

dhalドキュメント

9ページ中2ページ

Dhal v1 は schemaVersion: "1" を使用します。既定のファイルは dhal.json ですが、各アダプターと createDhal() は別の configPath を受け取れます。

設定の優先順位

有効な設定は次の順序で構築されます。

組み込みの既定値
configPath から読み込んだ設定
エンジンまたはアダプターに渡した config の上書き

オブジェクトは再帰的にマージされ、配列は置き換えられます。

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

const protection = createDhal({
  configPath: "dhal.json",
  config: {
    mode: "monitor",
    response: { message: "リクエストを拒否しました" }
  }
});

最小構成

json

{
  "schemaVersion": "1",
  "mode": "monitor",
  "trustProxy": false,
  "runtime": {
    "onInternalError": "allow",
    "internalErrorStatusCode": 500,
    "maxInspectionMs": 25,
    "bypass": {
      "enabled": true,
      "paths": ["/health", "/ready"],
      "methods": ["OPTIONS"]
    }
  },
  "rateLimit": {
    "enabled": true,
    "store": "memory",
    "keyBy": ["ip", "route"],
    "default": { "windowSeconds": 60, "max": 120 },
    "routes": {}
  }
}

主なセクション

フィールド	目的
`mode`	`off`、`monitor`、`block`、`strict` のグローバル動作。
`trustProxy`	転送ヘッダーを信頼してクライアント IP を解決します。
`runtime`	内部エラー、検査時間、バイパス。
`identity`	ユーザー、テナント、API キーのヘッダー。
`ip`	許可・拒否リストと IP レピュテーション。
`rateLimit`	グローバルおよびルート別の制限。
`rules`	シグネチャ、ボット、ペイロード、API、ヘッダー、認証情報。
`routes`	ルート単位の上書き。
`policy`	重大度、抑制、サンプリング、CI 要件。
`observability`	リダクション、イベント、OTel、Webhook。
`response`	ブロック時のステータスとメッセージ。

ランタイム安全性

導入初期に可用性を優先する場合は onInternalError: "allow" を使用します。依存サービスと障害動作を検証した後にだけ fail-closed を使用してください。

バイパスは、信頼できないアプリケーション入力を処理しないエンドポイントだけに限定します。

プロキシの信頼

trustProxy は、信頼できるプロキシが転送ヘッダーを上書きし、アプリケーションへの直接アクセスが遮断されている場合だけ有効にします。誤った設定は IP ベースの制御を弱めます。

シークレットと検証

apiKeyEnv と secretEnv にはシークレット値ではなく環境変数名を指定します。

bash

npx dhal test-config
npx dhal migrate --check

JSON Schema は @rokadhq/dhal/dhal.schema.json と getDhalConfigJsonSchema() から利用できます。