Explain better the reasoning for specific Cache-Control headers

Author: sandhose

synapse/rest/client/auth_metadata.py

@@ -50,7 +50,16 @@ def __init__(self, hs: "HomeServer"):
 
     async def on_GET(self, request: SynapseRequest) -> tuple[int, JsonDict]:
         # This endpoint is unauthenticated and the response only depends on
-        # the upstream OIDC provider metadata, so it can be cached.
+        # the metadata we get from Matrix Authentication Service. Internally,
+        # MasDelegatedAuth/MSC3861DelegatedAuth.issuer() are already caching the
+        # response in memory anyway. Ideally we would follow any Cache-Control directive
+        # given by MAS, but this is fine for now.
+        #
+        # - `public` means it can be cached both in the browser and in caching proxies
+        # - `max-age` controls how long we cache on the browser side. 1h is sane enough
+        # - `s-maxage` controls how long we cache on the proxy side. Since caching
+        #   proxies usually have a way to purge caches, it is fine to cache there for
+        #   longer (24h), and issue cache invalidations in case we need it
         request.setHeader(b"Cache-Control", b"public, max-age=600, s-maxage=3600")
 
         if self._config.mas.enabled:
@@ -99,7 +108,16 @@ def __init__(self, hs: "HomeServer"):
 
     async def on_GET(self, request: SynapseRequest) -> tuple[int, JsonDict]:
         # This endpoint is unauthenticated and the response only depends on
-        # the upstream OIDC provider metadata, so it can be cached.
+        # the metadata we get from Matrix Authentication Service. Internally,
+        # MasDelegatedAuth/MSC3861DelegatedAuth.issuer() are already caching the
+        # response in memory anyway. Ideally we would follow any Cache-Control directive
+        # given by MAS, but this is fine for now.
+        #
+        # - `public` means it can be cached both in the browser and in caching proxies
+        # - `max-age` controls how long we cache on the browser side. 1h is sane enough
+        # - `s-maxage` controls how long we cache on the proxy side. Since caching
+        #   proxies usually have a way to purge caches, it is fine to cache there for
+        #   longer (24h), and issue cache invalidations in case we need it
         request.setHeader(b"Cache-Control", b"public, max-age=3600, s-maxage=86400")
 
         if self._config.mas.enabled:

synapse/rest/client/versions.py

@@ -84,6 +84,12 @@ async def on_GET(self, request: SynapseRequest) -> tuple[int, JsonDict]:
         else:
             # Allow caching of unauthenticated responses, as they only depend
             # on server configuration which rarely changes.
+            #
+            # - `public` means it can be cached both in the browser and in caching proxies
+            # - `max-age` controls how long we cache on the browser side. 10m is sane enough
+            # - `s-maxage` controls how long we cache on the proxy side. Since caching
+            #   proxies usually have a way to purge caches, it is fine to cache there for
+            #   longer (1h), and issue cache invalidations in case we need it
             request.setHeader(b"Cache-Control", b"public, max-age=600, s-maxage=3600")
 
         # Tell caches to vary on the Authorization header, so that