📖Pingclairfile

Le Pingclairfile est le langage de configuration. Il suit les conventions de Caddyfile : un bloc d’options globales facultatif, puis des blocs de site contenant des directives. Cette page décrit le langage lui-même ; les directives qu’il accepte sont décrites dans la référence des directives.

🔤 Règles lexicales

Règle	Détail
Commentaires	# jusqu’à la fin de la ligne.
Guillemets	Une valeur contenant des espaces est mise entre ". Les guillemets sont retirés avant l’analyse de la valeur.
Durées	Écrites avec une unité : 30s, 5m, 1h. Un nombre nu est refusé là où une durée est attendue.
Casse	Les noms de directives et d’options sont en minuscules.
Placeholders	{host}, {path}, {args[0]}, {block} et le reste de l’ensemble des placeholders sont développés là où la directive le documente.

🌐 Adresses

Un bloc de site est nommé par une adresse. L’adresse détermine l’écouteur et, pour les noms publics, si HTTPS automatique s’applique.

example.com {              # host: ports 443 and 80, automatic HTTPS
localhost:8080 {           # host and port
:8080 {                    # any host on this port
http://example.com {       # force plaintext

Le port appartient à l’adresse plutôt qu’à une directive listen séparée : l’adresse et l’écouteur ne peuvent donc pas diverger.

🧭 Matchers

Une directive qui accepte un matcher ne s’applique qu’aux requêtes correspondantes. Les matchers s’écrivent en ligne ou sont déclarés avec @nom puis référencés par ce nom.

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

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

Les blocs handle regroupent les directives par route ; un handle sans matcher est le repli de son site.

🧩 Fragments et imports

Les fragments sont des morceaux réutilisables. Un fragment déclaré sous la forme (nom) { ... } est inclus avec import nom et peut recevoir un bloc de son appelant :

(proxied) {
    https://{args[0]} {
        encode zstd gzip
        {block}
    }
}

import proxied example.com {
    reverse_proxy 127.0.0.1:3000
}

Un placeholder qui ne reçoit rien n’insère rien : un fragment écrit avec {block} compile donc encore lorsque son appelant ne fournit aucun bloc.

🧰 Outillage en ligne de commande

La ligne de commande a sa propre référence : Ligne de commande liste chaque sous-commande avec ses options et ses valeurs par défaut. Trois d’entre elles relèvent de l’écriture d’une configuration : pingclair validate, qui compile un fichier et nomme le premier problème, pingclair adapt --pretty, qui affiche le JSON dans lequel ce fichier se compile, et pingclair fmt, qui le formate.

🚫 Ce qui ne fait pas partie du langage

Le format définit plus de noms que le serveur n’en implémente. Un nom reconnu mais non implémenté est refusé par son nom au chargement, avec un message indiquant que la fonctionnalité manque. La liste de référence des noms refusés se trouve dans le README du dépôt du serveur, et la page état du projet en résume les catégories.