feat(static): add custom Caddy modules support (#1210)

* feat: add custom Caddy modules to the static binary

* cs

* missing Docker ARG and docs

* fix

* improve

Author: dunglas

build-static.sh

@@ -96,7 +96,7 @@ else
 		if ! type "composer" >/dev/null; then
 			packages="composer"
 		fi
-		if ! type "go" >/dev/null; then
+		if ! type "go" >/dev/null 2>&1; then
 			packages="${packages} go"
 		fi
 		if [ -n "${RELEASE}" ] && ! type "gh" >/dev/null 2>&1; then
@@ -125,6 +125,10 @@ else
 	${spcCommand} build --debug --enable-zts --build-embed ${extraOpts} "${PHP_EXTENSIONS}" --with-libs="${PHP_EXTENSION_LIBS}"
 fi
 
+if ! type "xcaddy" >/dev/null 2>&1; then
+	go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
+fi
+
 curlGitHubHeaders=(--header "X-GitHub-Api-Version: 2022-11-28")
 if [ "${GITHUB_TOKEN}" ]; then
 	curlGitHubHeaders+=(--header "Authorization: Bearer ${GITHUB_TOKEN}")
@@ -265,10 +269,27 @@ if [ -n "${EMBED}" ] && [ -d "${EMBED}" ]; then
 	${md5binary} app.tar | awk '{printf $1}' >app_checksum.txt
 fi
 
-cd caddy/frankenphp/
+if [ -z "${XCADDY_ARGS}" ]; then
+	XCADDY_ARGS="--with github.com/dunglas/mercure/caddy --with github.com/dunglas/vulcain/caddy"
+fi
+
+XCADDY_DEBUG=0
+if [ -n "${DEBUG_SYMBOLS}" ]; then
+	XCADDY_DEBUG=1
+fi
+
 go env
-go build -buildmode=pie -tags "cgo,netgo,osusergo,static_build,nobadger,nomysql,nopgx" -ldflags "-linkmode=external -extldflags '-static-pie ${extraExtldflags}' ${extraLdflags} -X 'github.com/caddyserver/caddy/v2.CustomVersion=FrankenPHP ${FRANKENPHP_VERSION} PHP ${LIBPHP_VERSION} Caddy'" -o "../../dist/${bin}"
-cd ../..
+cd caddy/
+# shellcheck disable=SC2086
+CGO_ENABLED=1 \
+	XCADDY_GO_BUILD_FLAGS="-buildmode=pie -tags cgo,netgo,osusergo,static_build,nobadger,nomysql,nopgx -ldflags \"-linkmode=external -extldflags '-static-pie ${extraExtldflags}' ${extraLdflags} -X 'github.com/caddyserver/caddy/v2.CustomVersion=FrankenPHP ${FRANKENPHP_VERSION} PHP ${LIBPHP_VERSION} Caddy'\"" \
+	XCADDY_DEBUG="${XCADDY_DEBUG}" \
+	xcaddy build \
+	--output "../dist/${bin}" \
+	${XCADDY_ARGS} \
+	--with github.com/dunglas/frankenphp=.. \
+	--with github.com/dunglas/frankenphp/caddy=.
+cd ..
 
 if [ -d "${EMBED}" ]; then
 	truncate -s 0 app.tar

docs/cn/static.md

@@ -43,6 +43,24 @@ docker buildx bake \
   static-builder
 ```
 
+### 额外的 Caddy 模块
+
+要向 [xcaddy](https://github.com/caddyserver/xcaddy) 添加额外的 Caddy 模块或传递其他参数，请使用 `XCADDY_ARGS` Docker 参数：
+
+```console
+docker buildx bake \
+  --load \
+  --set static-builder.args.XCADDY_ARGS="--with github.com/darkweak/souin/plugins/caddy --with github.com/dunglas/mercure/caddy --with github.com/dunglas/vulcain/caddy" \
+  static-builder
+```
+
+在本例中，我们为 Caddy 添加了 [Souin](https://souin.io) HTTP 缓存模块，以及 [Mercure](https://mercure.rocks) 和 [Vulcain](https://vulcain.rocks) 模块。
+
+> [!TIP]
+>
+> 如果 `XCADDY_ARGS` 为空或未设置，则默认包含 Mercure 和 Vulcain 模块。
+> 如果自定义了 `XCADDY_ARGS` 的值，则必须显式地包含它们。
+
 参见：[自定义构建](#自定义构建)
 
 ### GitHub Token
@@ -75,6 +93,7 @@ cd frankenphp
 * `PHP_VERSION`: 要使用的 PHP 版本
 * `PHP_EXTENSIONS`: 要构建的 PHP 扩展（[支持的扩展列表](https://static-php.dev/zh/guide/extensions.html)）
 * `PHP_EXTENSION_LIBS`: 要构建的额外库，为扩展添加额外的功能
+* `XCADDY_ARGS`：传递给 [xcaddy](https://github.com/caddyserver/xcaddy) 的参数，例如用于添加额外的 Caddy 模块
 * `EMBED`: 要嵌入二进制文件的 PHP 应用程序的路径
 * `CLEAN`: 设置后，libphp 及其所有依赖项都是重新构建的（不使用缓存）
 * `DEBUG_SYMBOLS`: 设置后，调试符号将被保留在二进制文件内

docs/fr/static.md

@@ -42,6 +42,24 @@ docker buildx bake \
   static-builder
 ```
 
+### Modules supplémentaires de Caddy
+
+Pour ajouter des modules Caddy supplémentaires ou passer d'autres arguments à [xcaddy](https://github.com/caddyserver/xcaddy), utilisez l'argument Docker `XCADDY_ARGS` :
+
+```console
+docker buildx bake \
+  --load \
+  --set static-builder.args.XCADDY_ARGS="--with github.com/darkweak/souin/plugins/caddy --with github.com/dunglas/mercure/caddy --with github.com/dunglas/vulcain/caddy" \
+  static-builder
+```
+
+Dans cet exemple, nous ajoutons le module de cache HTTP [Souin](https://souin.io) pour Caddy ainsi que les modules [Mercure](https://mercure.rocks) et [Vulcain](https://vulcain.rocks).
+
+> [!TIP]
+>
+> Les modules Mercure et Vulcain sont inclus par défaut si `XCADDY_ARGS` est vide ou n'est pas défini.
+> Si vous personnalisez la valeur de `XCADDY_ARGS`, vous devez les inclure explicitement si vous voulez qu'ils soient inclus.
+
 Voir aussi comment [personnaliser la construction](#personnalisation-de-la-construction)
 
 ### Jeton GitHub
@@ -73,6 +91,7 @@ Les variables d'environnement suivantes peuvent être transmises à `docker buil
 * `PHP_VERSION` : la version de PHP à utiliser
 * `PHP_EXTENSIONS` : les extensions PHP à construire ([liste des extensions prises en charge](https://static-php.dev/en/guide/extensions.html))
 * `PHP_EXTENSION_LIBS` : bibliothèques supplémentaires à construire qui ajoutent des fonctionnalités aux extensions
+* `XCADDY_ARGS` : arguments à passer à [xcaddy](https://github.com/caddyserver/xcaddy), par exemple pour ajouter des modules Caddy supplémentaires
 * `EMBED` : chemin de l'application PHP à intégrer dans le binaire
 * `CLEAN` : lorsque défini, `libphp` et toutes ses dépendances sont construites à partir de zéro (pas de cache)
 * `DEBUG_SYMBOLS` : lorsque défini, les symboles de débogage ne seront pas supprimés et seront ajoutés dans le binaire

docs/static.md

@@ -43,6 +43,24 @@ docker buildx bake \
   static-builder
 ```
 
+### Extra Caddy Modules
+
+To add extra Caddy modules or pass other arguments to [xcaddy](https://github.com/caddyserver/xcaddy), use the `XCADDY_ARGS` Docker ARG:
+
+```console
+docker buildx bake \
+  --load \
+  --set static-builder.args.XCADDY_ARGS="--with github.com/darkweak/souin/plugins/caddy --with github.com/dunglas/mercure/caddy --with github.com/dunglas/vulcain/caddy" \
+  static-builder
+```
+
+In this example, we add the [Souin](https://souin.io) HTTP cache module for Caddy as well as the [Mercure](https://mercure.rocks) and [Vulcain](https://vulcain.rocks) modules.
+
+> [!TIP]
+>
+> The Mercure and Vulcain modules are included by default if `XCADDY_ARGS` is empty or not set.
+> If you customize the value of `XCADDY_ARGS`, you must include them explicitly if you want them to be included.
+
 See also how to [customize the build](#customizing-the-build)
 
 ### GitHub Token
@@ -75,6 +93,7 @@ script to customize the static build:
 * `PHP_VERSION`: the version of PHP to use
 * `PHP_EXTENSIONS`: the PHP extensions to build ([list of supported extensions](https://static-php.dev/en/guide/extensions.html))
 * `PHP_EXTENSION_LIBS`: extra libraries to build that add features to the extensions
+* `XCADDY_ARGS`: arguments to pass to [xcaddy](https://github.com/caddyserver/xcaddy), for instance to add extra Caddy modules
 * `EMBED`: path of the PHP application to embed in the binary
 * `CLEAN`: when set, libphp and all its dependencies are built from scratch (no cache)
 * `NO_COMPRESS`: don't compress the resulting binary using UPX

docs/tr/static.md

@@ -43,6 +43,24 @@ docker buildx bake \
   static-builder
 ```
 
+### Ekstra Caddy Modülleri
+
+Ekstra Caddy modülleri eklemek veya [xcaddy](https://github.com/caddyserver/xcaddy) adresine başka argümanlar iletmek için `XCADDY_ARGS` Docker ARG'sini kullanın:
+
+```console
+docker buildx bake \
+  --load \
+  --set static-builder.args.XCADDY_ARGS="--with github.com/darkweak/souin/plugins/caddy --with github.com/dunglas/mercure/caddy --with github.com/dunglas/vulcain/caddy" \
+  static-builder
+```
+
+Bu örnekte, Caddy için [Souin](https://souin.io) HTTP önbellek modülünün yanı sıra [Mercure](https://mercure.rocks) ve [Vulcain](https://vulcain.rocks) modüllerini ekliyoruz.
+
+> [!TIP]
+>
+> Mercure ve Vulcain modülleri, `XCADDY_ARGS` boşsa veya ayarlanmamışsa varsayılan olarak dahil edilir.
+> Eğer `XCADDY_ARGS` değerini özelleştirirseniz, dahil edilmelerini istiyorsanız bunları açıkça dahil etmelisiniz.
+
 Derlemeyi nasıl [özelleştireceğinize](#yapıyı-özelleştirme) de bakın.
 
 ### GitHub Token
@@ -75,6 +93,7 @@ statik derlemeyi özelleştirmek için betik:
 * `PHP_VERSION`: kullanılacak PHP sürümü
 * `PHP_EXTENSIONS`: oluşturulacak PHP eklentileri ([desteklenen eklentiler listesi](https://static-php.dev/en/guide/extensions.html))
 * `PHP_EXTENSION_LIBS`: eklentilere özellikler ekleyen oluşturulacak ekstra kütüphaneler
+* `XCADDY_ARGS`: [xcaddy](https://github.com/caddyserver/xcaddy) adresine iletilecek argümanlar, örneğin ekstra Caddy modülleri eklemek için
 * `EMBED`: binary dosyaya gömülecek PHP uygulamasının yolu
 * `CLEAN`: ayarlandığında, libphp ve tüm bağımlılıkları sıfırdan oluşturulur (önbellek yok)
 * `DEBUG_SYMBOLS`: ayarlandığında, hata ayıklama sembolleri ayıklanmayacak ve binary dosyaya eklenecektir

static-builder.Dockerfile

@@ -14,6 +14,7 @@ ENV PHP_VERSION=${PHP_VERSION}
 
 ARG PHP_EXTENSIONS=''
 ARG PHP_EXTENSION_LIBS=''
+ARG XCADDY_ARGS=''
 ARG CLEAN=''
 ARG EMBED=''
 ARG DEBUG_SYMBOLS=''
@@ -86,7 +87,8 @@ WORKDIR /goroot/src
 ENV GOHOSTARCH="$TARGETARCH"
 RUN ./make.bash
 ENV PATH="/goroot/bin:$PATH"
-RUN go version
+RUN go version && \
+	go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
 
 # https://getcomposer.org/doc/03-cli.md#composer-allow-superuser
 ENV COMPOSER_ALLOW_SUPERUSER=1