Le Contexte

Je construis un serveur MCP pour exposer un RAG et éviter les appels API redondants pendant le développement. Le cache filesystem se place entre l'application et l'API externe que j'utilise pour construire mon RAG.

La chaîne de clients HTTP suit un pattern decorator classique (du plus haut au plus bas dans la chaine de décoration):

flowchart TD
    A[Symfony\Component\HttpClient\HttpClient\ScopingHttpClient] --> B
    B["CachedHttpClient (stratégie de cache perso)"] --> C
    C["LoggedHttpClient (stratégie de logging perso)"] --> D
    D["Symfony\Component\HttpClient\HttpClient::create()"]

CachedHttpClient combine ScopingHttpClient de Symfony (pour le scoping et l'authentification auprès de l'API) avec un FilesystemAdapter pour persister les réponses HTTP dans var/http_cache/. Une classe CachedResponse implémente ResponseInterface pour que les réponses mises en cache ressemblent aux réponses fraîches.

Le Symptôme

app.DEBUG: Storing Response to cache with key c3f36f73afae200bb284436334b6647f.
app.DEBUG: Response stored to cache with key c3f36f73afae200bb284436334b6647f.

Les logs debug confirmaient les tentatives de mise en cache. Réalité : var/http_cache/ restait vide.

L'analyse

1. Le FilesystemAdapter la fausse piste qui m'a aidé a comprendre

Donc la question qui ce posait à ce moment était, Pourquoi ? Pourquoi ça ne sauvegarde pas mes reponses en cache ?

1.1. Y-a-t-il un problème avec le système de fichiers ?

J'ai d'abord pensé que ça venait de Symfony\Component\Cache\Adapter\FilesystemAdapter et en fouillant dans les fichiers du dossier vendor j'ai pu constater ce qui suit :

flowchart TD
    A["Symfony\Component\Cache\Adapter\FilesystemAdapter::save()"] --> B
    B["Symfony\Component\Cache\Traits\AbstractAdapterTrait::save()"] --> C
    C["Symfony\Component\Cache\Adapter\AbstractAdapter::commit()"] --> D
    D["Symfony\Component\Cache\Traits\FilesystemTrait::doSave()"] --> E
    E["Symfony\Component\Cache\Marshaller\DefaultMarshaller::marshall()"] --> F{"calls serialize()"}
    F["Symfony\Component\Cache\Traits\FilesystemCommonTrait::write()"]

Symfony\Component\Cache\Traits\FilesystemTrait::doSave() appelait Symfony\Component\Cache\Marshaller\DefaultMarshaller::marshall() qui lui utilisait serialize() de PHP avant d'en fournir le retour à Symfony\Component\Cache\Traits\FilesystemCommonTrait::write().

En ouvrant la fonction, j'ai constaté que FilesystemCommonTrait::write() executais la fonction mkdir() de PHP préfixée d'un @ qui supprimais les erreurs lié a la création du répertoire. Donc s'il y avait un problème avec mon repertoire de cache, il serait tû tout simplement. J'ai donc essayé de lancer un chmod -R 777 var/http_cache/ mais en vain.

1.2. Y-a-t-il un problème avec la serialisation ?

Il ne me restais plus qu'à voir si le problème pouvait venir de la serialisation. J'ai donc créé un script de reproduction minimaliste pour comprendre :

docker compose exec cli sh -c "php -r '
require \"/srv/vendor/autoload.php\";

use App\HTTP\CachedResponse;
use Symfony\Component\HttpClient\HttpClient;

\$client = HttpClient::create();
\$response = \$client->request(\"GET\", \"https://some.api.com/foo\", [
    \"headers\" => [
        \"User-Agent\" => \"Test\",
    ],
]);

\$cached = new CachedResponse(\$response);
try {
    \$serialized = serialize(\$cached);
    echo \"Serialization OK\\n\";
} catch (\Exception \$e) {
    echo \"Serialization FAILED: \" . \$e->getMessage() . \"\\n\";
}
' 2>&1
# Sortie :
# Serialization FAILED: Serialization of 'Closure' is not allowed

L'échec se produit pendant serialize() — bien avant les opérations de fichier. L'objet CachedResponse contenait des données non sérialisables, dans mon cas une Closure.

2. Localiser l'élément non sérialisable

La nouvelle question maintenant, où est-ce que je peut avoir une Closure dans ma CachedResponse.

2.1. CachedResponse

Cette classe est plutôt simple et est construite à partir d'une instance de Symfony\Contracts\HttpClient\ResponseInterface.

<?php

declare(strict_types=1);

namespace App\HTTP;

use Symfony\Contracts\HttpClient\ResponseInterface;

final class CachedResponse implements ResponseInterface
{
    private int $statusCode;
    private array $headers;
    private string $content;
    private array $toArray;
    private array $info;

    public function __construct(ResponseInterface $response)
    {
        $this->statusCode = $response->getStatusCode();
        $this->headers = $response->getHeaders();
        $this->content = $response->getContent();
        $this->toArray = $response->toArray();
        $this->info = $response->getInfo();
    }

    // ...
}

2.2. Procédons par élimination

En procédant par élimination, il ne nous reste que getInfo() qui peut avoir ce genre de choses à l'interieur puisque :

• statusCode: retourne un int qui corresponds au code de statut HTTP qui est aussi un entier.
• headers: retourne les entêtes HTTP qui ne sont basiquement que des tableaux d'int ou string.
• content: retourne le corps de la réponse qui n'est qu'une string donc aucune Closure là-dedans.
• toArray: aurait renvoyé une exception si le content n'avait pas été encodé en JSON.

Donc il doit y avoir quelque chose d'étrange que je n'avais pas anticipé dans getInfo() et inspecter getInfo() a révélé le coupable ce que j'ai fais via ce script :

docker compose exec cli php -r '
require "/srv/vendor/autoload.php";
use Symfony\Component\HttpClient\HttpClient;
\$client = HttpClient::create();
\$response = \$client->request("GET", "https://api.github.com/repos/symfony/symfony/pulls/64552", [
    "headers" => ["Accept" => "application/vnd.github+json", "User-Agent" => "Test"],
]);
foreach (\$response->getInfo() as \$k => \$v) {
    if (\$v instanceof \\Closure) echo "\$k => Closure\\n";
}
'
# Sortie :
pause_handler => Closure

Le client HTTP de Symfony inclut une clé pause_handler dans getInfo() contenant une Closure utilisée en interne pour la logique de retry (gestion des 429 Too Many Requests avec Retry-After) or PHP ne peut pas sérialiser les Closure.

3. Pourquoi l'échec était silencieux

Trois couches ont occulté la rééle cause :

Couche 1 — Valeur de retour ignorée / Mon erreure

Mon erreure a été de ne pas vérifier le retour de la fonction save() qui, je ne l'avais pas noté à ce moment là, retourne un booléen indiquant si l'enregistrement a bien été effectué.

Je suis donc passé de :

$this->cache->save($cacheItem); // returns false, ignored
$this->logger->debug("Response stored to cache with key {$key}.");

à:

$saved = $this->cache->save($cacheItem);
$this->logger->debug("Cache save: {result}", ['result' => $saved ? 'success' : 'FAILED']);

Ce qui m'a permis d'avoir des logs plus pertinent avec un message Cache save: FAILED qui était affiché à chaque tentatives. La méthodes save() ne fonctionnait pas et donc mon cache n'avais jamais fonctionné.

Couche 2 — Gestion d'exception silencieuse dans le marshallage

serialize() plantais silencieusement parce que dans Symfony\Component\Cache\Marshaller\DefaultMarshaller::marshall() en interne et par défaut Symfony attrape les exceptions de sérialisation et peuple un tableau d'id avec les serialisations échouées.

Voici une version simplifiée de la fonction :

public function marshall(array $values, ?array &$failed): array
{
    $serialized = $failed = [];

    foreach ($values as $id => $value) {
        try {
            $serialized[$id] = serialize($value);
        } catch (\Exception $e) {
            if ($this->throwOnSerializationFailure) {
                throw new \ValueError($e->getMessage(), 0, $e);
            }
            $failed[] = $id;
        }
    }

    return $serialized;
}

Avec throwOnSerializationFailure par défaut à false, les exceptions sont avalées. La clé de cache échouée va dans $failed, mais aucun avertissement n'est émis.

Couche 3 — Sérialisation complète d'un tableau de donneés mixte

Stocker complètement un tableau de données mixte dans le cache a été une autre de mes erreurs, quoique à moitié la mienne je n'avais pas anticipé la Closure dans getInfo(), avec le recule tout n'est pas peut-être pas bon a conserver.

La Correction

Valider les résultats de l'opération de cache:

if (!\$this->cache->save(\$cacheItem)) {
    \$this->logger->warning('Failed to save response to cache', ['key' => \$key]);
    return;
}
\$this->logger->debug("Response stored to cache with key {\$key}.");

Filtrer les \Closure de getInfo():

\$this->info = array_filter(
    \$response->getInfo(),
    static fn (\$v) => !\$v instanceof \Closure
);

Prévention

Ce bug n'était pas un problème avec le cache de Symfony — il fonctionnait comme conçu. L'échec venait de trois négligences alignées :

1. Oublier de vérifier les valeurs de retour
   Les méthodes retournent des valeurs pour une raison. Traite les méthodes avec bool comme save() comme des contrats.

2. Négliger la gestion d'exception silencieuse
   Les frameworks priorisent parfois le silence sur la visibilité. Saisis où basculer la verbosité (throwOnSerializationFailure: true en dev).

3. Supposer que getInfo() ne contient que des données scalaires
   Des internals comme pause_handler peuvent fuir dans les métadonnées. Valide toujours ce que tu caches.

C'était un vendredi soir, comme les autres. Je décide enfin de faire ce que tout bon développeur évite : mettre à jour son OS. Ubuntu 24.04 LTS → 25.10, la petite mise à jour de routine. "Ça ne peut que s'améliorer", me dis-je avec ce pessimisme propre à ceux qui ont vu trop de mises à jour mal se passer (Ubuntu 24.10 je te vois !).

Je lance la mise à jour en confiance. Tout se passe bien. Redémarrage. Tout fonctionne. Nickel.

Sauf que le lundi suivant, mes tests E2E ne passent plus. Le conteneur Docker selenium/standalone-chrome:4.5.3 qui fonctionnait parfaitement la veille refuse désormais de démarrer. Il plante en boucle avec ce magnifique message d'erreur :

chrome-1  | java.lang.reflect.InvocationTargetException
chrome-1  |     at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
chrome-1  |     at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
chrome-1  |     at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
chrome-1  |     at java.base/java.lang.reflect.Method.invoke(Method.java:566)
chrome-1  |     at org.openqa.selenium.grid.Bootstrap.runMain(Bootstrap.java:77)
chrome-1  |     at org.openqa.selenium.grid.Bootstrap.main(Bootstrap.java:70)
chrome-1  | Caused by: java.lang.NullPointerException
chrome-1  |     at java.base/jdk.internal.platform.cgroupv2.CgroupV2Subsystem.getInstance(CgroupV2Subsystem.java:81)
chrome-1  |     at java.base/jdk.internal.platform.CgroupSubsystemFactory.create(CgroupSubsystemFactory.java:113)
chrome-1  |     at java.base/jdk.internal.platform.CgroupMetrics.getInstance(CgroupMetrics.java:167)
chrome-1  |     at java.base/jdk.internal.platform.SystemMetrics.instance(SystemMetrics.java:29)
chrome-1  |     at java.base/jdk.internal.platform.Metrics.systemMetrics(Metrics.java:58)
chrome-1  |     at java.base/jdk.internal.platform.Container.metrics(Container.java:43)
chrome-1  |     at jdk.management/com.sun.management.internal.OperatingSystemImpl.<init>(OperatingSystemImpl.java:182)
chrome-1  |     at jdk.management/com.sun.management.internal.PlatformMBeanProviderImpl.getOperatingSystemMXBean(PlatformMBeanProviderImpl.java:281)
chrome-1  |     at jdk.management/com.sun.management.internal.PlatformMBeanProviderImpl$3.nameToMBeanMap(PlatformMBeanProviderImpl.java:198)
chrome-1  |     at java.management/java.lang.management.ManagementFactory.lambda$getPlatformMBeanServer$0(ManagementFactory.java:487)
chrome-1  |     at java.base/java.util.stream.ReferencePipeline$7$1.accept(ReferencePipeline.java:271)
chrome-1  |     at java.base/java.util.stream.ReferencePipeline$2$1.accept(ReferencePipeline.java:177)
chrome-1  |     at java.base/java.util.HashMap$ValueSpliterator.forEachRemaining(HashMap.java:1693)
chrome-1  |     at java.base/java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:484)
chrome-1  |     at java.base/java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:474)
chrome-1  |     at java.base/java.util.stream.ForEachOps$ForEachOp.evaluateSequential(ForEachOps.java:150)
chrome-1  |     at java.base/java.util.stream.ForEachOps$ForEachOp$OfRef.evaluateSequential(ForEachOps.java:173)
chrome-1  |     at java.base/java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234)
chrome-1  |     at java.base/java.util.stream.ReferencePipeline.forEach(ReferencePipeline.java:497)
chrome-1  |     at java.management/java.lang.management.ManagementFactory.getPlatformMBeanServer(ManagementFactory.java:488)
chrome-1  |     at org.openqa.selenium.grid.jmx.JMXHelper.register(JMXHelper.java:29)
chrome-1  |     at org.openqa.selenium.grid.server.BaseServerOptions.<init>(BaseServerOptions.java:48)
chrome-1  |     at org.openqa.selenium.grid.commands.Standalone.createHandlers(Standalone.java:124)
chrome-1  |     at org.openqa.selenium.grid.TemplateGridServerCommand.asServer(TemplateGridServerCommand.java:41)
chrome-1  |     at org.openqa.selenium.grid.commands.Standalone.execute(Standalone.java:245)
chrome-1  |     at org.openqa.selenium.grid.TemplateGridCommand.lambda$configure$4(TemplateGridCommand.java:129)
chrome-1  |     at org.openqa.selenium.grid.Main.launch(Main.java:83)
chrome-1  |     at org.openqa.selenium.grid.Main.go(Main.java:57)
chrome-1  |     at org.openqa.selenium.grid.Main.main(Main.java:42)
chrome-1  |     ... 6 more

Ma première pensée :

Je suis développeur PHP, pas Java.

Mon reflexe:

Demandons à plus fort que soi. Gemini cricket (🤖🦗) 🥲.

L'Enquête

Mon ami le cricket met le doigt sur cgroupv2 dans la ligne CgroupV2Subsystem.java:81 et fait le lien avec la mise à jour de mon système. Mais cgroupv2, c'est quoi ?

🤖🦗:

Pour faire court, c'est ce qui permet à Docker 🐋 de limiter le CPU ou la RAM d'un container.

Concrètement :

• Docker dit à la JVM : "Tu as le droit à 2Go de RAM".
• Java lit ces infos dans les cgroups (fichiers de gestion des ressources).
• Java ajuste son comportement (mémoire Heap, etc.) en conséquence.

C'est censé être une bonne chose. Cela évite que Java ne se fasse abattre par le OOM Killer du système hôte. Mais Java doit parser ces fichiers, et c'est là que le bât blesse.

Pourquoi un crash et pas juste une erreur ? Dans le code source des anciennes JVM, si le chemin retourné par l'interface système n'est pas exactement celui attendu, la variable mountPoint reste à null. La JVM tente ensuite d'appeler une méthode sur cet objet inexistant. C'est l'arroseur arrosé : la fonction censée protéger votre application devient la cause de son exécution sommaire.

Le Plot Twist : La différence subtile entre Ubuntu 24.04 et 25.10

C'est ici que l'affaire devient fascinante.

Le véritable coupable, c'est l'évolution de systemd (passé en version 258 sur la version d'Ubuntu 25.10). Depuis la v256, systemd impose un 'durcissement' de la hiérarchie cgroup v2. Il ne se contente plus d'exposer les contrôleurs ; il les organise de façon beaucoup plus granulaire pour isoler les services. Les anciennes versions de Java, conçues à une époque où la hiérarchie était plus prévisible et moins protégée, se retrouvent littéralement 'aveugles' face à cette nouvelle structure.

Et devinez quoi ? La vieille logique d'initialisation de Java (avant Java 17) est beaucoup trop rigide pour comprendre ce nouveau format.

Au démarrage, le Java de notre conteneur fouille dans le système, ne trouve pas le contrôleur "memory" exactement là où il l'attendait, et assigne silencieusement null à sa variable interne. À la ligne suivante, le code tente d'appeler la méthode .getMountPoint() sur cet objet vide.

BOOM. NullPointerException. Mort instantanée du processus.

Le coupable n'était ni notre code, ni notre configuration Docker, mais une ancienne JVM incapable de s'adapter à la nouvelle hiérarchie d'un noyau Linux moderne. Normale aussi vous me direz.

LA Solution

La solution propre, celle qu'on devrait toujours utiliser en production :

# Mettre à jour vers une version récente de l'image
docker pull selenium/standalone-chrome:4.20.0

# OU utiliser une image avec Java 17+
docker pull selenium/standalone-chrome:latest

Le Hack de survie — Désactiver UseContainerSupport

Si vous ne pouvez pas mettre à jour l'image (contraintes legacy, validation QA, etc.), vous pouvez désactiver la détection de conteneur :

# Option 1 : Via variable d'environnement Docker
docker run -d \
  -e JAVA_OPTS="-XX:-UseContainerSupport" \
  selenium/standalone-chrome:4.5.3

# Option 2 : Via docker-compose.yml
services:
  chrome:
    image: selenium/standalone-chrome:4.5.3
    environment:
      - JAVA_OPTS=-XX:-UseContainerSupport

La morale de cette histoire

Nos écosystèmes logiciels sont fragiles. Une simple mise à jour du noyau Linux — via une mise à jour d'Ubuntu dans mon cas — peut casser des conteneurs qui fonctionnaient parfaitement d'une version à l'autre.

Les conseils philosophiques :

Penser à nettoyer sa chambre régulièrement (je suis sûr que vous comprenez l'image) peut faire gagner beaucoup de temps.

Ne faites jamais de mise à jour d'OS un vendredi.

Prenez soin de toujours tester vos conteneurs Docker sur un environnement de staging après une mise à jour système.

"Works on my machine" — jusqu'à la mise à jour du kernel.

Sources et Références

• Oracle Docs : Java Container Support
• Ubuntu 25.10 Release Notes
• Docker & Java : Best Practices
• cgroup v2 kernel documentation
• Systemd News : Changes in unified cgroup hierarchy handling (v256+)

Je n'avais aucune idée au début… 😅 Voici comment j'ai compris.

La configuration

J'avais un EventSubscriber qui vérifiait l'accès aux pages basé sur une liste blanche de routes. C'était du code legacy — le refactoriser n'était pas à l'ordre du jour à ce moment-là.

<?php

namespace App\EventSubscriber;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

class WhitelistRouteSubscriber implements EventSubscriberInterface
{
    private const WHITELISTED_ROUTES = [
        'app_login',
        'app_homepage',
        'app_healthcheck',
    ];

    public static function getSubscribedEvents(): array
    {
        return [
            KernelEvents::REQUEST => ['onKernelRequest', 0],
        ];
    }

    public function onKernelRequest(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $route = $request->attributes->get('_route');

        // Allow whitelisted routes
        if (in_array($route, self::WHITELISTED_ROUTES, true)) {
            return;
        }

        // Deny access for non-whitelisted routes
        throw new AccessDeniedHttpException('Route not whitelisted');
    }
}

Objectif : Bloquer toutes les routes sauf la liste blanche. Simple, non ?

Le problème

Les logs montraient des AccessDeniedHttpException sur des routes que je savais être dans la liste blanche. Premier geste classique : mettre un dump() dans le subscriber pour voir ce qui arrivait.

public function onKernelRequest(RequestEvent $event): void
{
    $request = $event->getRequest();
    $route = $request->attributes->get('_route');

    dump($route); // 🔍 Voyons ce qui se passe
    // ...
}

Première découverte surprenante : le subscriber était appelé deux fois pour une seule requête. Le premier appel avait la route attendue, le second avait $route = null.

Question évidente : pourquoi _route est-il null ?

J'ai creusé plus loin avec dump($request->getPathInfo()) pour voir quelle URL était traitée lors du second appel :

// 1er appel
dump($request->getPathInfo()); // "/foo"

// 2e appel
dump($request->getPathInfo()); // "/foo" ← identique. Attends, quoi ?

Même URL, appelée deux fois. Cela n'avait aucun sens — si c'était la même requête, pourquoi _route était-il null la deuxième fois ? Je tournais en rond.

J'ai donc dumpé l'objet $event complet pour avoir plus de contexte, et j'ai réduit le champ à _controller dans les attributs de la requête :

dump($request->attributes->get('_controller'));
// "Symfony\Component\HttpKernel\Controller\ErrorController"

Voilà. _controller ne pointait pas vers mon code du tout. Symfony avait forgé une toute nouvelle requête vers son propre ErrorController, réutilisant l'URL d'origine — ce qui explique pourquoi getPathInfo() était si trompeur — mais en contournant complètement le routeur. C'est pourquoi _route était null.

Cause racine

Le flux réel était :

Requête → /foo
  └── WhitelistSubscriber (1er appel) → _route = 'app_foo' ✅ Accès accordé
      └── Controller → lève RealException 💥
          └── Symfony l'attrape
              └── Sous-requête → ErrorController (contourne le routeur, pas de _route)
                  └── WhitelistSubscriber (2e appel) → _route = null ❌ AccessDenied levé
                      └── RealException est maintenant silencieuse 🔇

Le piège : l'AccessDeniedHttpException du subscriber masquait complètement l'exception originale — celle qui contenait réellement les informations de débogage utiles.

Lorsqu'une exception est levée, le HttpKernel de Symfony distribue un événement KernelEvents::EXCEPTION, puis délègue le rendu de l'erreur à ErrorController via une sous-requête interne. Cette sous-requête réutilise l'URL d'origine — ce qui explique pourquoi getPathInfo() était trompeur — mais elle contourne complètement la couche de routage, laissant _route à null.

La solution

Vérifiez si la requête est la requête principale (pas une sous-requête) :

<?php

namespace App\EventSubscriber;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

class WhitelistRouteSubscriber implements EventSubscriberInterface
{
    private const WHITELISTED_ROUTES = [
        'app_login',
        'app_homepage',
        'app_healthcheck',
    ];

    public static function getSubscribedEvents(): array
    {
        return [
            KernelEvents::REQUEST => ['onKernelRequest', 0],
        ];
    }

    public function onKernelRequest(RequestEvent $event): void
    {
        // Skip sub-requests (like error handling)
        if (!$event->isMainRequest()) {
            return;
        }

        $request = $event->getRequest();
        $route = $request->attributes->get('_route');

        // Allow whitelisted routes
        if (in_array($route, self::WHITELISTED_ROUTES, true)) {
            return;
        }

        // Deny access for non-whitelisted routes
        throw new AccessDeniedHttpException('Route not whitelisted');
    }
}

isMainRequest() retourne false pour toute sous-requête interne — gestion d'erreurs, fragments ESI, hinclude — donc votre logique ne s'exécute que sur les vraies requêtes distribuées par le routeur.

Note : isMainRequest() a remplacé l'ancien isMasterRequest() dans Symfony 5.3. Si vous êtes sur une version plus ancienne, utilisez isMasterRequest() à la place.

Conclusion

Chaque fois que votre subscriber fait quelque chose de destructeur — lever une exception, rediriger, définir une réponse — demandez-vous : que se passe-t-il quand Symfony appelle ceci sur une sous-requête ?

Les sous-requêtes sont omniprésentes dans Symfony : gestion d'erreurs, ESI, fragments. Elles n'ont pas le même contexte qu'une requête principale, et votre subscriber ne connaît pas la différence à moins que vous ne lui disiez.

isMainRequest() est cette vérification. Faites-en un réflexe. 🎉