設定モデル

Pingclairfile は読み込み時に一度だけコンパイルされ、サーバーが実際に実行する状態になります。そこから 2 つの帰結が生まれ、このプロジェクトの挙動のほとんどを説明します。設定が決められることは最初のリクエストより前に済みます。そして満たせない設定は、リクエスト時に妥協するのではなく、サーバーを停止させます。

🗂️ ファイル構造

ファイルは省略可能な global options ブロックと、それに続く 1 つ以上の site block で構成されます。

{
    email admin@example.com
}

example.com {
    encode zstd gzip
    reverse_proxy 10.0.0.10:8080 10.0.0.11:8080
}

:8080 {
    file_server ./public
}

Global options はファイル先頭の名前のないブロックに書き、サイト単位ではない状態を設定します。ACME アカウントのメールアドレス、Admin API、自動 HTTPS の挙動、trusted proxies、ホスト名上流の DNS 再解決などです。利用できるオプションはディレクティブ一覧にあります。
Site block はアドレスで名前を付けます。ホスト、ポート、またはその両方です。ポートは独立したディレクティブではなくアドレスの一部なので、両者の一致を保つ場所は 1 か所で済みます。
ディレクティブは site block 内の文です。引数リストを取るもの、ネストしたブロックを取るもの、両方を取るものがあります。
コメントは # から行末までです。
空白を含む値は引用符で囲みます。 時間の長さには単位が必要です。30s は 30 秒で、長さが求められる場所に裸の 30 を書くと拒否されます。

🧭 マッチャー

マッチャーは、あるディレクティブをどのリクエストに適用するかを選びます。名前付きマッチャーは @name で宣言し、名前で参照します。

example.com {
    @api path /api/*
    header @api Cache-Control "no-store"

    @assets path /assets/*
    header @assets Cache-Control "public, max-age=31536000, immutable"
}

handle ブロックはルートごとに挙動をまとめ、マッチャーを伴わないフォールバックも書けます。

example.com {
    handle /assets/* {
        file_server ./assets
    }

    handle {
        respond "Page Not Found" 404
    }
}

🧩 スニペットと import

スニペットは再利用可能な断片で、(name) { ... } として宣言し、import name で取り込みます。呼び出し側からブロックを受け取り、スニペット内の {block} の位置に挿入することもできます。

(site) {
    https://{args[0]} {
        {block}
    }
}

import site example.com {
    reverse_proxy 127.0.0.1:3000
}

import されたファイルで定義されたスニペットは、それより後の import から参照できます。引数リストの中に置かれたプレースホルダーは拒否されます。ディレクティブ木は、挿入後にその行をトークン層のように再解析できないためです。

🛡️ 検証

pingclair validate はファイルをコンパイルし、意味的な検査を行います。ディレクティブの引数、マッチャーの構文、証明書と鍵のパス、そして「どの対端がクライアント識別ヘッダーを主張できるか」といったポリシー制約です。

失敗は明示的で、閉じた方向に倒れます。

未実装の名前は名前で拒否されます。 形式が定義する名前はすべて認識され、実装がないものは「機能が存在しない」というメッセージを出します。綴り間違いとして扱われることも、無視されることもありません。それを含む設定は起動しません。
満たせないオプションは拒否され、降格しません。 たとえば encode に Brotli を指定するとコンパイルエラーになります。プロキシにストリーミングの Brotli エンコーダーがないためで、黙って gzip を配信することはありません。
構文が正しくても、存在しないものを参照するファイルは拒否されます。 リポジトリの examples/full_featured.pingclair は正しい Caddyfile 構文ですが、依然として拒否されます。そこに書かれた証明書パスが、検査を実行するマシンに存在しないからで、拒否は正しい判断です。

同じ検査は読み込み時にも実行されるため、再読み込みで検証に失敗しても直前の状態は保たれます。

🔁 再読み込み

pc service reload はプロセスを再起動せずに設定を読み直します。trusted_proxies のように起動時に確立されるプロセス全体のポリシーは、再起動後に反映されます。

🧠設定モデル