Report-To vs Reporting-Endpoints, migrer hors du header déprécié

Il existe deux générations du header HTTP qui indique au navigateur où envoyer les rapports, et copier-coller le mauvais depuis un vieux tutoriel est une façon courante de finir avec des rapports qui silencieusement n'arrivent jamais. Report-To est venu en premier et est désormais déprécié. Reporting-Endpoints l'a remplacé et est plus simple. Pour presque tout, vous devriez utiliser Reporting-Endpoints ; la seule exception, le Network Error Logging, a encore besoin de l'ancien header. Voici ce qui a changé et comment migrer.

C'est la version au niveau du header de l'histoire report-uri vs report-to, qui porte sur les directives CSP. Couche différente, même direction : la plateforme se consolide autour d'un seul mécanisme de reporting.

Les deux headers côte à côte

Report-To (v0) déclare des groupes d'endpoints en JSON, avec plusieurs URL par groupe, une durée de cache et des poids de répartition de charge. Il est expressif, et c'est exactement cette expressivité qui n'a jamais été normalisée.

Report-To: { "group": "csp-endpoint", "max_age": 10886400,
             "endpoints": [ { "url": "https://<Endpoint-ID>.report.centralcsp.com" } ] }

Reporting-Endpoints (v1) déclare de simples paires nom et URL, une seule URL chacune, limitées à la réponse sur laquelle elles sont servies. Pas de groupes, pas de cache, pas de bascule de secours, juste un nom associé à une URL.

Reporting-Endpoints: csp-endpoint="https://<Endpoint-ID>.report.centralcsp.com"

Une politique référence le nom de la même façon dans les deux générations : report-to csp-endpoint en CSP, ou un paramètre report-to="csp-endpoint" sur COOP et COEP. Migrer consiste donc surtout à remplacer le header qui déclare l'endpoint, pas les politiques qui l'utilisent.

Ce qui a changé et pourquoi

La spécification Reporting du W3C ne définit que Reporting-Endpoints. Report-To était un mécanisme de l'ère Chromium qui n'est jamais devenu un standard, ce qui explique pourquoi MDN le marque à la fois déprécié et non standard, et pourquoi il n'a jamais existé que dans les navigateurs Chromium. La v1 a abandonné le modèle de groupes, de cache et de répartition de charge au profit d'un header plus simple, par réponse, que d'autres moteurs de navigateur étaient prêts à adopter. Ce header plus simple est déjà multi-navigateurs et fonctionne dans les navigateurs actuels, dont Chrome, Edge, Firefox et Safari. Tout le détail est sur la référence Report-To vs Reporting-Endpoints.

La confusion report-to à quatre entrées

L'essentiel de la difficulté ici vient du nommage. L'expression « report-to » apparaît à quatre endroits différents, et les gens en câblent les deux mauvais ensemble. Gardez-les bien distincts :

• le header Reporting-Endpoints (moderne, déclare des endpoints)
• le header Report-To (déprécié, déclare des endpoints)
• la directive CSP report-to (nomme un endpoint depuis l'intérieur d'une politique)
• le paramètre report-to= sur les headers COOP et COEP (nomme un endpoint pour cette politique)

La directive et le paramètre ne font que référencer un nom ; ce nom doit être déclaré par l'un des deux headers sur la même réponse.

Le seul cas où vous avez encore besoin de Report-To

Le Network Error Logging (NEL) est le récalcitrant. Il n'est pas supporté par Reporting-Endpoints : le header NEL nomme un groupe qui doit être défini dans un header Report-To. Tant qu'un remplaçant n'existe pas, tout site utilisant NEL conserve Report-To à cette seule fin. Tout le reste, CSP, COOP, COEP, deprecations, interventions, crashs, devrait passer à Reporting-Endpoints.

Comment migrer

La migration est à faible risque parce que les deux headers n'entrent pas en conflit, et comme Reporting-Endpoints est déjà multi-navigateurs, il n'y a aucune raison d'attendre. Envoyez Reporting-Endpoints partout, et ne conservez Report-To que sur les réponses qui envoient aussi le header NEL. Si vous voulez être prudent pendant le basculement, envoyez les deux un moment et confirmez que les rapports arrivent toujours avant de retirer l'ancien. Pour en savoir plus sur où vont les rapports du navigateur et comment les recevoir, CentralCSP accepte les rapports des deux headers sur un seul endpoint, vous pouvez donc faire la transition progressivement sans trou dans vos données.

Étapes suivantes

• Câblez le header moderne dans comment configurer le Reporting API.
• Découvrez le flux d'erreurs réseau dans qu'est-ce que NEL.
• Voir le rapport d'erreur réseau.

Comme NEL vous maintient sur les deux headers pour l'instant, le résultat pratique est deux déclarations qui pointent vers un seul collecteur. Un site CentralCSP vous donne une unique URL d'endpoint à nommer dans les deux, si bien que les flux v0 et v1 arrivent au même endroit et que vous n'avez pas deux stocks de rapports à réconcilier pendant la migration.

Collectez chaque type de rapport sur un seul endpoint.

Sources

• W3C, Reporting API
• W3C, Network Error Logging
• MDN, Reporting-Endpoints
• MDN, Report-To (déprécié)