Updated cache headers.

Author: isoos

CHANGELOG.md

@@ -4,6 +4,7 @@ AppEngine version, listed here to ease deployment and troubleshooting.
 ## Next Release (replace with git tag when deployed)
  * Bump runtimeVersion to `2025.10.21`.
  * Upgraded stable Flutter analysis SDK to `3.35.6`.
+ * Added more explicitly public `cache-control` to content pages.
 
 ## `20251017t101000-all`
  * Bump runtimeVersion to `2025.10.17`.

app/lib/frontend/handlers/cache_control.dart

@@ -62,6 +62,20 @@ final class CacheControl {
     public: true,
   );
 
+  /// `Cache-Control` headers for package content pages, returning content that
+  /// is not updated frequently.
+  static const packageContentPage = CacheControl(
+    maxAge: Duration(minutes: 30),
+    public: true,
+  );
+
+  /// `Cache-Control` headers for package listing pages, returning content that
+  /// is may be updated frequently.
+  static const packageListingPage = CacheControl(
+    maxAge: Duration(minutes: 5),
+    public: true,
+  );
+
   /// `Cache-Control` headers for API end-points returning completion data for
   /// use in IDE integrations.
   static const completionData = CacheControl(

app/lib/frontend/handlers/documentation.dart

@@ -23,6 +23,12 @@ import '../../shared/urls.dart';
 ///
 /// - `/documentation/<package>/<version>`
 Future<shelf.Response> documentationHandler(shelf.Request request) async {
+  final requestMethod = request.method.toUpperCase();
+  if (requestMethod != 'HEAD' && requestMethod != 'GET') {
+    // TODO: Should probably be "method not supported"!
+    return notFoundHandler(request);
+  }
+
   final docFilePath = parseRequestUri(request.requestedUri);
   if (docFilePath == null) {
     return notFoundHandler(request);
@@ -58,12 +64,6 @@ Future<shelf.Response> documentationHandler(shelf.Request request) async {
       ),
     );
   }
-  final String requestMethod = request.method.toUpperCase();
-
-  if (requestMethod != 'HEAD' && requestMethod != 'GET') {
-    // TODO: Should probably be "method not supported"!
-    return notFoundHandler(request);
-  }
 
   final package = docFilePath.package;
   final version = docFilePath.version!;

app/lib/frontend/handlers/landing.dart

@@ -5,6 +5,7 @@
 import 'dart:async';
 
 import 'package:_pub_shared/search/tags.dart';
+import 'package:pub_dev/frontend/handlers/cache_control.dart';
 import 'package:pub_dev/search/top_packages.dart';
 import 'package:shelf/shelf.dart' as shelf;
 
@@ -49,7 +50,10 @@ Future<shelf.Response> indexLandingHandler(shelf.Request request) async {
   }
 
   if (requestContext.uiCacheEnabled) {
-    return htmlResponse((await cache.uiIndexPage().get(_render))!);
+    return htmlResponse(
+      (await cache.uiIndexPage().get(_render))!,
+      headers: CacheControl.packageListingPage.headers,
+    );
   }
   return htmlResponse(await _render());
 }

app/lib/frontend/handlers/listing.dart

@@ -7,6 +7,8 @@ import 'dart:async';
 import 'package:_pub_shared/search/search_form.dart';
 import 'package:_pub_shared/search/tags.dart';
 import 'package:logging/logging.dart';
+import 'package:pub_dev/frontend/handlers/cache_control.dart';
+import 'package:pub_dev/frontend/request_context.dart';
 import 'package:shelf/shelf.dart' as shelf;
 
 import '../../package/name_tracker.dart';
@@ -94,6 +96,9 @@ Future<shelf.Response> _packagesHandlerHtmlCore(shelf.Request request) async {
       openSections: openSections,
     ),
     status: statusCode,
+    headers: statusCode == 200 && requestContext.uiCacheEnabled
+        ? CacheControl.packageListingPage.headers
+        : null,
   );
   _searchOverallLatencyTracker.add(sw.elapsed);
   return result;

app/lib/frontend/handlers/package.dart

@@ -301,6 +301,7 @@ Future<shelf.Response> _handlePackagePage({
   Entry<String>? cacheEntry,
 }) async {
   checkPackageVersionParams(packageName, versionName);
+  final cacheEnabled = requestContext.uiCacheEnabled && cacheEntry != null;
 
   final canonicalUrl = canonicalUrlFn(
     await _canonicalPackageName(packageName),
@@ -314,7 +315,7 @@ Future<shelf.Response> _handlePackagePage({
   }
   final Stopwatch sw = Stopwatch()..start();
   String? cachedPage;
-  if (requestContext.uiCacheEnabled && cacheEntry != null) {
+  if (cacheEnabled) {
     cachedPage = await cacheEntry.get();
   }
 
@@ -350,12 +351,15 @@ Future<shelf.Response> _handlePackagePage({
     } else {
       throw StateError('Unknown result type: ${renderedResult.runtimeType}');
     }
-    if (requestContext.uiCacheEnabled && cacheEntry != null) {
+    if (cacheEnabled) {
       await cacheEntry.set(cachedPage);
     }
     _packageDoneLatencyTracker.add(sw.elapsed);
   }
-  return htmlResponse(cachedPage);
+  return htmlResponse(
+    cachedPage,
+    headers: cacheEnabled ? CacheControl.packageContentPage.headers : null,
+  );
 }
 
 /// Returns the optionally lowercased version of [name], but only if there

app/lib/frontend/request_context.dart

@@ -110,7 +110,7 @@ Future<RequestContext> buildRequestContext({
       // don't cache if client session is active
       !clientSessionCookieStatus.isPresent &&
       // sanity check, this should be covered by client session cookie
-      (csrfToken?.isNotEmpty ?? false);
+      !(csrfToken?.isNotEmpty ?? false);
   return RequestContext(
     indentJson: indentJson,
     blockRobots: !enableRobots,

app/lib/task/handlers.dart

@@ -6,6 +6,7 @@ import 'package:path/path.dart' as p;
 
 import 'package:pub_dev/dartdoc/dartdoc_page.dart';
 import 'package:pub_dev/dartdoc/models.dart';
+import 'package:pub_dev/frontend/handlers/cache_control.dart';
 import 'package:pub_dev/shared/exceptions.dart';
 import 'package:pub_dev/shared/handlers.dart';
 import 'package:pub_dev/shared/redis_cache.dart';
@@ -90,7 +91,10 @@ Future<shelf.Response> handleDartDoc(
     );
     final htmlBytes = await htmlBytesCacheEntry.get();
     if (htmlBytes != null) {
-      return htmlBytesResponse(htmlBytes);
+      return htmlBytesResponse(
+        htmlBytes,
+        headers: CacheControl.packageContentPage.headers,
+      );
     }
 
     // check cached status for redirect or missing pages
@@ -211,7 +215,10 @@ Future<shelf.Response> handleDartDoc(
     switch (status.code) {
       case DocPageStatusCode.ok:
         await htmlBytesCacheEntry.set(bytes!);
-        return htmlBytesResponse(bytes);
+        return htmlBytesResponse(
+          bytes,
+          headers: CacheControl.packageContentPage.headers,
+        );
       case DocPageStatusCode.redirect:
         return redirectPathResponse(status.redirectPath!);
       case DocPageStatusCode.missing:
@@ -236,13 +243,14 @@ Future<shelf.Response> handleDartDoc(
   }
 
   if (request.method.toUpperCase() == 'HEAD') {
-    return htmlResponse('');
+    return htmlResponse('', headers: CacheControl.packageContentPage.headers);
   }
 
   final acceptsGzip = request.acceptsGzipEncoding();
   return shelf.Response.ok(
     acceptsGzip ? dataGz : gzip.decode(dataGz),
     headers: {
+      ...CacheControl.packageContentPage.headers,
       'Content-Type': mime,
       'Vary': 'Accept-Encoding', // body depends on accept-encoding!
       if (acceptsGzip) 'Content-Encoding': 'gzip',

pkg/pub_integration/lib/src/fake_test_context_provider.dart

@@ -58,14 +58,20 @@ class TestContextProvider {
     await _fakePubServerProcess.kill();
   }
 
-  Future<TestUser> createAnonymousTestUser() async {
+  Future<TestUser> createAnonymousTestUser({
+    bool expectAllResponsesToBeCacheControlPublic = true,
+  }) async {
     final session = await _testBrowser.createSession();
     return TestUser(
       email: '',
       browserApi: PubApiClient(pubHostedUrl),
       serverApi: PubApiClient(pubHostedUrl),
       withBrowserPage: <T>(Future<T> Function(Page) fn) async {
-        return await session.withPage<T>(fn: fn);
+        return await session.withPage<T>(
+          fn: fn,
+          expectAllResponsesToBeCacheControlPublic:
+              expectAllResponsesToBeCacheControlPublic,
+        );
       },
       readLatestEmail: () async => throw UnimplementedError(),
       createCredentials: () async => throw UnimplementedError(),

pkg/pub_integration/lib/src/test_browser.dart

@@ -185,7 +185,10 @@ class TestBrowserSession {
   TestBrowserSession(this._browser, this._context);
 
   /// Creates a new page and setup overrides and tracking.
-  Future<R> withPage<R>({required Future<R> Function(Page page) fn}) async {
+  Future<R> withPage<R>({
+    required Future<R> Function(Page page) fn,
+    bool expectAllResponsesToBeCacheControlPublic = false,
+  }) async {
     final clientErrors = <ClientError>[];
     final serverErrors = <String>[];
     final page = await _context.newPage();
@@ -261,20 +264,31 @@ class TestBrowserSession {
         }
       }
 
-      if (!rs.url.startsWith('data:') &&
-          // exempt the image URL from markdown_samples.md
-          rs.url != 'https://pub.dev/static/img/pub-dev-logo.svg') {
+      if (rs.status == 200 &&
+          rs.request.method.toUpperCase() == 'GET' &&
+          // filters out data: and other-domain URLs
+          rs.url.startsWith(_browser._origin)) {
         final uri = Uri.parse(rs.url);
-        if (uri.pathSegments.length > 1 && uri.pathSegments.first == 'static') {
+        final firstPathSegment = uri.pathSegments.firstOrNull;
+
+        if (firstPathSegment == 'static') {
           if (!uri.pathSegments[1].startsWith('hash-')) {
             serverErrors.add('Static URL ${rs.url} is without hash segment.');
           }
+        }
 
+        final shouldBePublic =
+            firstPathSegment == 'static' ||
+            firstPathSegment == 'documentation' ||
+            expectAllResponsesToBeCacheControlPublic;
+        final knownExemption =
+            firstPathSegment == 'experimental' || firstPathSegment == 'report';
+        if (shouldBePublic && !knownExemption) {
           final cacheHeader = rs.headers[HttpHeaders.cacheControlHeader];
           if (cacheHeader == null ||
               !cacheHeader.contains('public') ||
               !cacheHeader.contains('max-age')) {
-            serverErrors.add('Static ${rs.url} is without public caching.');
+            serverErrors.add('${rs.url} is without public caching.');
           }
         }
       }