ESI twig helper

.gitignore

@@ -1,3 +1,6 @@
 vendor
 composer.lock
 .env
+tests/_output
+tests/.env
+tests/_support/_generated

codeception.yml

@@ -0,0 +1,21 @@
+actor: Tester
+paths:
+  tests: tests
+  output: tests/_output
+  data: tests/_data
+  support: tests/_support
+  envs: tests/_envs
+bootstrap: _bootstrap.php
+params:
+  - tests/.env
+modules:
+  config:
+    \craft\test\Craft:
+      configFile: 'tests/_craft/config/test.php'
+      entryUrl: 'http://my-project.test/index.php'
+      projectConfig: {}
+      migrations: []
+      plugins: []
+      cleanup: true
+      transaction: true
+      dbSetup: {clean: true, setupCraft: true}

composer.json

@@ -20,12 +20,18 @@
   },
   "require-dev": {
     "craftcms/ecs": "dev-main",
-    "craftcms/phpstan": "dev-main"
+    "craftcms/phpstan": "dev-main",
+    "codeception/codeception": "^5.0",
+    "vlucas/phpdotenv": "^5.0",
+    "codeception/module-asserts": "~3.1.0",
+    "codeception/module-yii2": "^1.0"
   },
   "scripts": {
     "check-cs": "ecs check --ansi",
     "fix-cs": "ecs check --ansi --fix",
-    "phpstan": "phpstan --memory-limit=1G"
+    "phpstan": "phpstan --memory-limit=1G",
+    "test": "codecept run unit",
+    "test:coverage": "codecept run unit --coverage"
   },
   "autoload": {
     "psr-4": {

src/Esi.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace craft\cloud;
+
+use Craft;
+use craft\helpers\Html;
+use craft\helpers\Template;
+use craft\helpers\UrlHelper;
+use InvalidArgumentException;
+use Twig\Markup;
+
+class Esi
+{
+    public function __construct(
+        private readonly UrlSigner $urlSigner,
+        private readonly bool $useEsi = true,
+    ) {
+    }
+
+    /**
+     * Prepare response for ESI processing by setting the Surrogate-Control header
+     * Note: The Surrogate-Control header will cause Cloudflare to ignore
+     * the Cache-Control header: https://developers.cloudflare.com/cache/concepts/cdn-cache-control/#header-precedence
+     */
+    public function prepareResponse(): void
+    {
+        Craft::$app->getResponse()->getHeaders()->setDefault(
+            HeaderEnum::SURROGATE_CONTROL->value,
+            'content="ESI/1.0"',
+        );
+    }
+
+    public function render(string $template, array $variables = []): Markup
+    {
+        $this->validateVariables($variables);
+
+        if (!$this->useEsi) {
+            return Template::raw(
+                Craft::$app->getView()->renderTemplate($template, $variables)
+            );
+        }
+
+        $this->prepareResponse();
+
+        $url = UrlHelper::actionUrl('cloud/esi/render-template', [
+            'template' => $template,
+            'variables' => $variables,
+        ]);
+
+        $signedUrl = $this->urlSigner->sign($url);
+
+        // $html = Html::encodeParams('<esi:include src="{src}" />', [
+        //     'src' => $signedUrl,
+        // ]);
+
+        $html = sprintf('<esi:include src="%s" />',  $signedUrl);
+
+        Craft::info(['Rendering ESI', $html], __METHOD__);
+
+        return Template::raw($html);
+    }
+
+    private function validateVariables(array $variables): void
+    {
+        foreach ($variables as $value) {
+            if (is_array($value)) {
+                $this->validateVariables($value);
+            } elseif (!is_scalar($value) && !is_null($value)) {
+                $type = get_debug_type($value);
+
+                throw new InvalidArgumentException(
+                    "Value must be a primitive value or array, {$type} given."
+                );
+            }
+        }
+    }
+}

src/Helper.php

@@ -56,19 +56,6 @@ public static function makeGatewayApiRequest(iterable $headers): ResponseInterfa
         );
     }
 
-    /**
-     * Enable ESI processing
-     * Note: The Surrogate-Control header will cause Cloudflare to ignore
-     * the Cache-Control header: https://developers.cloudflare.com/cache/concepts/cdn-cache-control/#header-precedence
-     */
-    public static function enableEsi(): void
-    {
-        Craft::$app->getResponse()->getHeaders()->setDefault(
-            HeaderEnum::SURROGATE_CONTROL->value,
-            'content="ESI/1.0"',
-        );
-    }
-
     private static function createSigningContext(iterable $headers = []): Context
     {
         $headers = Collection::make($headers);

src/Module.php

@@ -59,6 +59,17 @@ public function bootstrap($app): void
 
         Craft::setAlias('@artifactBaseUrl', Helper::artifactUrl());
 
+        $this->setComponents([
+            'staticCache' => StaticCache::class,
+            'urlSigner' => fn() => new UrlSigner(
+                signingKey: $this->getConfig()->signingKey ?? '',
+            ),
+            'esi' => fn() => new Esi(
+                urlSigner: $this->getUrlSigner(),
+                useEsi: Helper::isCraftCloud(),
+            ),
+        ]);
+
         if (Helper::isCraftCloud()) {
             $this->bootstrapCloud($app);
         }
@@ -119,10 +130,6 @@ protected function bootstrapCloud(ConsoleApplication|WebApplication $app): void
             $app->getErrorHandler()->memoryReserveSize,
         );
 
-        $this->setComponents([
-            'staticCache' => StaticCache::class,
-        ]);
-
         $this->registerCloudEventHandlers();
 
         $app->getLog()->targets[] = Craft::createObject([
@@ -199,6 +206,16 @@ public function getStaticCache(): StaticCache
         return $this->get('staticCache');
     }
 
+    public function getUrlSigner(): UrlSigner
+    {
+        return $this->get('urlSigner');
+    }
+
+    public function getEsi(): Esi
+    {
+        return $this->get('esi');
+    }
+
     private function removeAttributeFromRule(array $rule, string $attributeToRemove): array
     {
         $attributes = Collection::wrap($rule[0])

src/UrlSigner.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace craft\cloud;
+
+use Craft;
+use craft\helpers\UrlHelper;
+
+class UrlSigner
+{
+    public function __construct(
+        private readonly string $signingKey,
+        private readonly string $signatureParameter = 's',
+    ) {
+    }
+
+    public function sign(string $url): string
+    {
+        return UrlHelper::urlWithParams($url, [
+            $this->signatureParameter => hash_hmac('sha256', $url, $this->signingKey),
+        ]);
+    }
+
+    public function verify(string $url): bool
+    {
+        $query = parse_url($url, PHP_URL_QUERY);
+
+        if (!$query) {
+            Craft::info('Missing signature', __METHOD__);
+
+            return false;
+        }
+
+        parse_str($query, $params);
+
+        $providedSignature = $params[$this->signatureParameter] ?? null;
+
+        if (!$providedSignature) {
+            Craft::info('Missing signature', __METHOD__);
+
+            return false;
+        }
+
+        $urlWithoutSignature = UrlHelper::removeParam($url, $this->signatureParameter);
+
+        $verified = hash_equals(
+            hash_hmac('sha256', $urlWithoutSignature, $this->signingKey),
+            $providedSignature,
+        );
+
+        if (!$verified) {
+            Craft::info([
+                'message' => 'Invalid signature',
+                'signatureParameter' => $this->signatureParameter,
+                'providedSignature' => $providedSignature,
+                'urlWithoutSignature' => $urlWithoutSignature,
+                'url' => $url,
+            ], __METHOD__);
+        }
+
+        return $verified;
+    }
+}

src/controllers/EsiController.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace craft\cloud\controllers;
+
+use Craft;
+use craft\cloud\Module;
+use yii\web\Response;
+
+class EsiController extends \craft\web\Controller
+{
+    public function beforeAction($action): bool
+    {
+        return Module::getInstance()
+            ->getUrlSigner()
+            ->verify(Craft::$app->getRequest()->getAbsoluteUrl());
+    }
+
+    public function actionRenderTemplate(string $template, array $variables = []): Response
+    {
+        return $this->renderTemplate($template, $variables);
+    }
+}

src/twig/CloudVariable.php

@@ -8,6 +8,8 @@
 namespace craft\cloud\twig;
 
 use craft\cloud\Helper;
+use craft\cloud\Module;
+use Twig\Markup;
 use yii\di\ServiceLocator;
 
 class CloudVariable extends ServiceLocator
@@ -24,6 +26,11 @@ public function isCraftCloud(): bool
 
     public function enableEsi(): void
     {
-        Helper::enableEsi();
+        Module::getInstance()->getEsi()->prepareResponse();
+    }
+
+    public function esi(string $template, $variables = []): Markup
+    {
+        return Module::getInstance()->getEsi()->render($template, $variables);
     }
 }

tests/.env.example

@@ -0,0 +1,8 @@
+CRAFT_DB_SERVER="127.0.0.1"
+CRAFT_DB_PORT="33066"
+CRAFT_DB_DATABASE="db"
+CRAFT_DB_USER="db"
+CRAFT_DB_PASSWORD="db"
+CRAFT_DB_DRIVER="mysql"
+SECURITY_KEY=""
+PRIMARY_SITE_URL="http://my-project.test/" # Set this to the `entryUrl` param in the `codeception.yml` file.

tests/_bootstrap.php

@@ -0,0 +1,25 @@
+<?php
+
+use craft\test\TestSetup;
+
+ini_set('date.timezone', 'UTC');
+
+define('CRAFT_ROOT_PATH', dirname(__DIR__));
+
+// Use the current installation of Craft
+define('CRAFT_TESTS_PATH', __DIR__);
+define('CRAFT_STORAGE_PATH', __DIR__ . '/_craft/storage');
+define('CRAFT_TEMPLATES_PATH', __DIR__ . '/_craft/templates');
+define('CRAFT_CONFIG_PATH', __DIR__ . '/_craft/config');
+define('CRAFT_MIGRATIONS_PATH', __DIR__ . '/_craft/migrations');
+define('CRAFT_TRANSLATIONS_PATH', __DIR__ . '/_craft/translations');
+define('CRAFT_VENDOR_PATH', dirname(__DIR__).'/vendor');
+
+// Load dotenv?
+if (class_exists(Dotenv\Dotenv::class)) {
+    // By default, this will allow .env file values to override environment variables
+    // with matching names. Use `createUnsafeImmutable` to disable this.
+    Dotenv\Dotenv::createUnsafeMutable(CRAFT_TESTS_PATH)->load();
+}
+
+TestSetup::configureCraft();

tests/_craft/config/test.php

@@ -0,0 +1,4 @@
+<?php
+use craft\test\TestSetup;
+
+return TestSetup::createTestCraftObjectConfig();

tests/_craft/storage/config-deltas/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

tests/_craft/storage/runtime/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

tests/_support/AcceptanceTester.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+
+/**
+ * Inherited Methods
+ * @method void wantTo($text)
+ * @method void wantToTest($text)
+ * @method void execute($callable)
+ * @method void expectTo($prediction)
+ * @method void expect($prediction)
+ * @method void amGoingTo($argumentation)
+ * @method void am($role)
+ * @method void lookForwardTo($achieveValue)
+ * @method void comment($description)
+ * @method void pause($vars = [])
+ *
+ * @SuppressWarnings(PHPMD)
+*/
+class AcceptanceTester extends \Codeception\Actor
+{
+    use _generated\AcceptanceTesterActions;
+
+    /**
+     * Define custom actions here
+     */
+}