feat: add the human cache analysis

Author: serhalp

app/app.vue

@@ -78,6 +78,7 @@ main {
 
 .run-panels {
   flex-wrap: wrap;
+  align-items: stretch;
 }
 
 .run-panels>* {

app/components/CacheAnalysis.vue

@@ -0,0 +1,82 @@
+<script setup lang="ts">
+const props = defineProps<{
+  cacheHeaders: Record<string, string>;
+}>();
+
+const { servedBy, cacheStatus } = getCacheAnalysis(props.cacheHeaders);
+</script>
+
+<template>
+  <div>
+    <dl>
+      <dt>Served by</dt>
+      <dd>{{ servedBy }}</dd>
+    </dl>
+
+    <hr />
+
+    <dl>
+      <template v-for="{ cacheName, parameters } in cacheStatus">
+        <!-- This is a bit of a hack to use the pretty <dt> styling but with sections. -->
+        <!-- I should probably just do something custom instead. -->
+        <dt class="cache-heading">
+          <h4>{{ cacheName }}</h4>
+        </dt>
+        <dd></dd>
+
+        <dt>Hit</dt>
+        <dd>{{ parameters.hit ? "✅" : "❌" }}</dd>
+
+        <template v-if="parameters.fwd">
+          <dt>Forwarded because</dt>
+          <dd>{{ parameters.fwd }}</dd>
+        </template>
+
+        <template v-if="parameters['fwd-status']">
+          <dt>Forwarded status</dt>
+          <dd>{{ parameters["fwd-status"] }}</dd>
+        </template>
+
+        <template v-if="parameters.ttl">
+          <dt>TTL</dt>
+          <dd>{{ parameters.ttl }}</dd>
+        </template>
+
+        <template v-if="parameters.stored">
+          <dt>Stored the response</dt>
+          <dd>{{ parameters.stored ? "✅" : "❌" }}</dd>
+        </template>
+
+        <template v-if="parameters.collapsed">
+          <dt>Collapsed w/ other reqs</dt>
+          <dd>{{ parameters.collapsed ? "✅" : "❌" }}</dd>
+        </template>
+
+        <template v-if="parameters.key">
+          <dt>Cache key</dt>
+          <dd>{{ parameters.key }}</dd>
+        </template>
+
+        <template v-if="parameters.detail">
+          <dt>Extra details</dt>
+          <dd>{{ parameters.detail }}</dd>
+        </template>
+      </template>
+    </dl>
+  </div>
+</template>
+
+<style scoped>
+.cache-heading h4 {
+  padding: 0;
+  /* I'm sorry */
+  margin-left: -0.5em;
+
+  font-size: 1.1em;
+}
+
+/* Default Netlify Examples styles add ": " */
+.cache-heading::after {
+  content: none;
+}
+</style>

app/components/RawCacheHeaders.vue

@@ -19,7 +19,18 @@ onUpdated(highlightJson);
 </template>
 
 <style scoped>
+/* FIXME(serhalp) This is leaky. I'm doing this:
+ * https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_flexbox#alignment_and_auto_margins.
+ * But this component shouldn't "know" about its parent's layout needs.
+ */
+pre {
+  margin-top: auto;
+}
+
 code {
   font-size: 0.7em;
+
+  max-width: 40vw;
+  overflow-x: scroll;
 }
 </style>

app/components/RunPanel.vue

@@ -8,17 +8,28 @@ const props = defineProps<{
 </script>
 
 <template>
-  <div>
+  <div class="panel run-panel">
     <h3>{{ props.url }}</h3>
 
     <small>HTTP {{ props.status }} ({{ props.durationInMs }} ms)</small>
 
+    <CacheAnalysis :cacheHeaders="props.cacheHeaders" />
     <RawCacheHeaders :cacheHeaders="props.cacheHeaders" />
   </div>
 </template>
 
 <style scoped>
-h3 {
+.run-panel {
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-start;
+  align-content: center;
+
+  margin: 1em;
+}
+
+.run-panel h3 {
   font-size: 1em;
+  align-self: start;
 }
 </style>

app/utils/getCacheAnalysis.ts

@@ -0,0 +1,125 @@
+export enum ServedBy {
+  CDN = "CDN",
+  DurableCache = "Durable Cache",
+  Function = "Function",
+  EdgeFunction = "Edge Function",
+}
+
+interface ParsedCacheStatusEntry {
+  cacheName: string;
+  parameters: {
+    hit: boolean;
+    fwd?:
+    | "bypass"
+    | "method"
+    | "uri-miss"
+    | "vary-miss"
+    | "miss"
+    | "request"
+    | "stale"
+    | "partial";
+    "fwd-status"?: number;
+    ttl?: number;
+    stored?: boolean;
+    collapsed?: boolean;
+    key?: string;
+    detail?: string;
+  };
+}
+export const parseCacheStatus = (
+  // See https://httpwg.org/specs/rfc9211.html
+  // example string:
+  // "\"Next.js\"; hit, \"Netlify Durable\"; fwd=miss; stored, \"Netlify Edge\"; fwd=miss"
+  cacheStatus: string,
+): ParsedCacheStatusEntry[] => {
+  return (
+    cacheStatus
+      .split(", ")
+      .map((entry): null | ParsedCacheStatusEntry => {
+        const [cacheName, ...parameters] = entry.split("; ");
+        if (!cacheName || parameters.length === 0) {
+          console.warn("Ignoring invalid cache status entry", { entry });
+          return null;
+        }
+
+        const parametersByKey = new Map(
+          parameters
+            .map((parameter) => {
+              const [key, value] = parameter.split("=");
+              if (!key || !value) {
+                console.warn("Ignoring invalid cache status entry", { entry });
+                return null;
+              }
+              return [key, value];
+            })
+            .filter((kv): kv is [string, string] => kv != null),
+        );
+        return {
+          cacheName: cacheName.slice(1, -1), // "Netlify Edge" -> Netlify Edge
+          parameters: {
+            hit: parametersByKey.has("hit"),
+            fwd: parametersByKey.get(
+              "fwd",
+            ) as ParsedCacheStatusEntry["parameters"]["fwd"],
+            "fwd-status": Number(parametersByKey.get("fwd-status")),
+            ttl: Number(parametersByKey.get("ttl")),
+            stored: parametersByKey.has("stored"),
+            collapsed: parametersByKey.has("collapsed"),
+            key: parametersByKey.get("key"),
+            detail: parametersByKey.get("detail"),
+          },
+        };
+      })
+      .filter((e): e is ParsedCacheStatusEntry => e != null)
+      // Per the spec, these are sorted from "the cache closest to the origin server" to "the cache closest to the user".
+      // As a user interpreting what happened, you want these to start from yourself.
+      .toReversed()
+  );
+};
+
+const getServedBy = (
+  cacheHeaders: Headers,
+  cacheStatus: ParsedCacheStatusEntry[],
+): ServedBy => {
+  // Per the spec, these are sorted from "the cache closest to the origin server" to "the cache closest to the user".
+  // So, the first cache hit (starting from the user) is the one that served the request.
+  // But we don't quite want to return exactly the same concept of "caches" as in `Cache-Status`, so
+  // we need a bit of extra logic to map to other sources.
+  for (const {
+    cacheName,
+    parameters: { hit },
+  } of cacheStatus) {
+    if (!hit) continue;
+
+    if (cacheName === "Netlify Edge") return ServedBy.CDN;
+    if (cacheName === "Netlify Durable") return ServedBy.DurableCache;
+  }
+
+  // NOTE: the order is important here, since a response can be served by a Function even
+  // though one or more Edge Functions are also invoked (as middleware).
+  if (cacheHeaders.has("X-NF-Function-Type")) return ServedBy.Function;
+
+  if (cacheHeaders.has("X-NF-Edge-Functions")) return ServedBy.EdgeFunction;
+
+  throw new Error(
+    `Could not determine who served the request. Cache status: ${cacheStatus}`,
+  );
+};
+
+export interface CacheAnalysis {
+  servedBy: ServedBy;
+  cacheStatus: ParsedCacheStatusEntry[];
+}
+
+export default function getCacheAnalysis(
+  cacheHeadersObj: Record<string, string>,
+): CacheAnalysis {
+  // Use a Headers instance for case insensitivity and multi-value handling
+  const cacheHeaders = new Headers(cacheHeadersObj);
+  const cacheStatus = parseCacheStatus(cacheHeaders.get("Cache-Status") ?? "");
+
+  return {
+    servedBy: getServedBy(cacheHeaders, cacheStatus),
+    cacheStatus,
+  };
+}

app/utils/getCacheHeaders.ts

@@ -3,18 +3,28 @@ const CACHE_HEADER_NAMES = [
   "CDN-Cache-Control",
   "Cache-Control",
   "Cache-Status",
+  "Cache-Tag",
   "Content-Encoding",
+  "Content-Language",
   "Content-Type",
   "Date",
   "ETag",
   "Netlify-CDN-Cache-Control",
+  "Netlify-Cache-Tag",
+  "Netlify-Vary",
   "Vary",
   "X-BB-Deploy-Id",
   "X-BB-Gen",
   "X-NF-Cache-Info",
   "X-NF-Cache-Result",
+  // TODO(serhalp) These two probably shouldn't be here but I use it to determine who served the
+  // request. Need to refactor to pass the whole headers obj to `getServedBy` to remove this.
+  "X-NF-Edge-Functions",
+  "X-NF-Function-Type",
+  "X-Nextjs-Cache",
 ];
 
+// TODO(serhalp) Magically parse `Netlify-Vary` if present and also include headers referenced by it
 export default function getCacheHeaders(headersObj: Record<string, string>) {
   // Use a Headers instance for case insensitivity and multi-value handling
   const headers = new Headers(headersObj);

server/api/inspect-url/[url].get.ts

@@ -9,6 +9,7 @@ export default defineEventHandler(async (event) => {
   }
 
   const startTime = Date.now();
+  // TODO(serhalp) `$fetch` automatically throws on 4xx, but we'd like to treat those as valid.
   const { status, headers } = await $fetch.raw(url, {
     headers: {
       "x-nf-debug-logging": "1",