Add CF-Cache-Status to Workers Assets (cloudflare#8373)

* Move util final op methods to a more appropriate place

* Add CF-Cache-Status header to Workers Assets

Author: WalshyDev

.changeset/thirty-emus-find.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/workers-shared": minor
+---
+
+Add `CF-Cache-Status` to Workers Assets responses to indicate if we returned a cached asset or not. This will also populate zone cache analytics and Logpush logs.

packages/workers-shared/asset-worker/src/analytics.ts

@@ -36,6 +36,8 @@ type Data = {
 	version?: string;
 	// blob7 - Region of the colo (e.g. WEUR)
 	coloRegion?: string;
+	// blob8 - The cache status of the request
+	cacheStatus?: string;
 };
 
 export class Analytics {
@@ -78,6 +80,7 @@ export class Analytics {
 				this.data.error?.substring(0, 256), // blob5 - trim to 256 bytes
 				this.data.version, // blob6
 				this.data.coloRegion, // blob7
+				this.data.cacheStatus, // blob8
 			],
 		});
 	}

packages/workers-shared/asset-worker/src/handler.ts

@@ -14,6 +14,7 @@ import {
 import { attachCustomHeaders, getAssetHeaders } from "./utils/headers";
 import { generateRulesMatcher, replacer } from "./utils/rules-engine";
 import type { AssetConfig } from "../../utils/types";
+import type { Analytics } from "./analytics";
 import type EntrypointType from "./index";
 import type { Env } from "./index";
 
@@ -176,7 +177,8 @@ const resolveAssetIntentToResponse = async (
 	assetIntent: AssetIntent,
 	request: Request,
 	env: Env,
-	getByETag: typeof EntrypointType.prototype.unstable_getByETag
+	getByETag: typeof EntrypointType.prototype.unstable_getByETag,
+	analytics: Analytics
 ) => {
 	const { pathname } = new URL(request.url);
 	const method = request.method.toUpperCase();
@@ -191,7 +193,13 @@ const resolveAssetIntentToResponse = async (
 		return await getByETag(assetIntent.eTag);
 	});
 
-	const headers = getAssetHeaders(assetIntent.eTag, asset.contentType, request);
+	const headers = getAssetHeaders(
+		assetIntent.eTag,
+		asset.contentType,
+		asset.cacheStatus,
+		request
+	);
+	analytics.setData({ cacheStatus: asset.cacheStatus });
 
 	const strongETag = `"${assetIntent.eTag}"`;
 	const weakETag = `W/${strongETag}`;
@@ -252,7 +260,8 @@ export const handleRequest = async (
 	env: Env,
 	configuration: Required<AssetConfig>,
 	exists: typeof EntrypointType.prototype.unstable_exists,
-	getByETag: typeof EntrypointType.prototype.unstable_getByETag
+	getByETag: typeof EntrypointType.prototype.unstable_getByETag,
+	analytics: Analytics
 ) => {
 	const responseOrAssetIntent = await getResponseOrAssetIntent(
 		request,
@@ -268,7 +277,8 @@ export const handleRequest = async (
 					responseOrAssetIntent,
 					request,
 					env,
-					getByETag
+					getByETag,
+					analytics
 				);
 
 	return attachCustomHeaders(request, response, configuration);

packages/workers-shared/asset-worker/src/index.ts

@@ -1,13 +1,13 @@
 import { WorkerEntrypoint } from "cloudflare:workers";
 import { PerformanceTimer } from "../../utils/performance";
-import { InternalServerErrorResponse } from "../../utils/responses";
 import { setupSentry } from "../../utils/sentry";
 import { mockJaegerBinding } from "../../utils/tracing";
 import { Analytics } from "./analytics";
 import { AssetsManifest } from "./assets-manifest";
 import { applyConfigurationDefaults } from "./configuration";
 import { ExperimentAnalytics } from "./experiment-analytics";
 import { canFetch, handleRequest } from "./handler";
+import { handleError, submitMetrics } from "./utils/final-operations";
 import { getAssetWithMetadataFromKV } from "./utils/kv";
 import type {
 	AssetConfig,
@@ -16,44 +16,6 @@ import type {
 	UnsafePerformanceTimer,
 } from "../../utils/types";
 import type { Environment, ReadyAnalytics } from "./types";
-import type { Toucan } from "toucan-js";
-
-function handleError(
-	sentry: Toucan | undefined,
-	analytics: Analytics,
-	err: unknown
-) {
-	try {
-		const response = new InternalServerErrorResponse(err as Error);
-
-		// Log to Sentry if we can
-		if (sentry) {
-			sentry.captureException(err);
-		}
-
-		if (err instanceof Error) {
-			analytics.setData({ error: err.message });
-		}
-
-		return response;
-	} catch (e) {
-		console.error("Error handling error", e);
-		return new InternalServerErrorResponse(e as Error);
-	}
-}
-
-function submitMetrics(
-	analytics: Analytics,
-	performance: PerformanceTimer,
-	startTimeMs: number
-) {
-	try {
-		analytics.setData({ requestTime: performance.now() - startTimeMs });
-		analytics.write();
-	} catch (e) {
-		console.error("Error submitting metrics", e);
-	}
-}
 
 export type Env = {
 	/*
@@ -157,7 +119,8 @@ export default class extends WorkerEntrypoint<Env> {
 					this.env,
 					config,
 					this.unstable_exists.bind(this),
-					this.unstable_getByETag.bind(this)
+					this.unstable_getByETag.bind(this),
+					analytics
 				);
 
 				analytics.setData({ status: response.status });
@@ -171,7 +134,7 @@ export default class extends WorkerEntrypoint<Env> {
 		}
 	}
 
-	// TODO: Trace unstable methods
+	// TODO: Add observability to these methods
 	async unstable_canFetch(request: Request): Promise<boolean> {
 		// TODO: Mock this with Miniflare
 		this.env.JAEGER ??= mockJaegerBinding();
@@ -187,11 +150,16 @@ export default class extends WorkerEntrypoint<Env> {
 	async unstable_getByETag(eTag: string): Promise<{
 		readableStream: ReadableStream;
 		contentType: string | undefined;
+		cacheStatus: "HIT" | "MISS";
 	}> {
+		const performance = new PerformanceTimer(this.env.UNSAFE_PERFORMANCE);
+		const startTime = performance.now();
 		const asset = await getAssetWithMetadataFromKV(
 			this.env.ASSETS_KV_NAMESPACE,
 			eTag
 		);
+		const endTime = performance.now();
+		const assetFetchTime = endTime - startTime;
 
 		if (!asset || !asset.value) {
 			throw new Error(
@@ -202,12 +170,17 @@ export default class extends WorkerEntrypoint<Env> {
 		return {
 			readableStream: asset.value,
 			contentType: asset.metadata?.contentType,
+			// KV does not yet provide a way to check if a value was fetched from cache
+			// so we assume that if the fetch time is less than 100ms, it was a cache hit.
+			// This is a reasonable assumption given the data we have and how KV works.
+			cacheStatus: assetFetchTime <= 100 ? "HIT" : "MISS",
 		};
 	}
 
 	async unstable_getByPathname(pathname: string): Promise<{
 		readableStream: ReadableStream;
 		contentType: string | undefined;
+		cacheStatus: "HIT" | "MISS";
 	} | null> {
 		const eTag = await this.unstable_exists(pathname);
 		if (!eTag) {

packages/workers-shared/asset-worker/src/utils/final-operations.ts

@@ -0,0 +1,41 @@
+import { InternalServerErrorResponse } from "../../../utils/responses";
+import type { PerformanceTimer } from "../../../utils/performance";
+import type { Analytics } from "../analytics";
+import type { Toucan } from "toucan-js";
+
+export function handleError(
+	sentry: Toucan | undefined,
+	analytics: Analytics,
+	err: unknown
+) {
+	try {
+		const response = new InternalServerErrorResponse(err as Error);
+
+		// Log to Sentry if we can
+		if (sentry) {
+			sentry.captureException(err);
+		}
+
+		if (err instanceof Error) {
+			analytics.setData({ error: err.message });
+		}
+
+		return response;
+	} catch (e) {
+		console.error("Error handling error", e);
+		return new InternalServerErrorResponse(e as Error);
+	}
+}
+
+export function submitMetrics(
+	analytics: Analytics,
+	performance: PerformanceTimer,
+	startTimeMs: number
+) {
+	try {
+		analytics.setData({ requestTime: performance.now() - startTimeMs });
+		analytics.write();
+	} catch (e) {
+		console.error("Error submitting metrics", e);
+	}
+}

packages/workers-shared/asset-worker/src/utils/headers.ts

@@ -12,6 +12,7 @@ import type { AssetConfig } from "../../../utils/types";
 export function getAssetHeaders(
 	eTag: string,
 	contentType: string | undefined,
+	cacheStatus: string,
 	request: Request
 ) {
 	const headers = new Headers({
@@ -26,6 +27,10 @@ export function getAssetHeaders(
 		headers.append("Cache-Control", CACHE_CONTROL_BROWSER);
 	}
 
+	// Attach CF-Cache-Status, this will show to users that we are caching assets
+	// and it will also populate the cache fields through the logging pipeline.
+	headers.append("CF-Cache-Status", cacheStatus);
+
 	return headers;
 }