chore(workers-shared): Rename Asset Worker RPC methods as unstable (#6670)

The Asset Worker is currently set up as a `WorkerEntrypoint` class
so that it is able to accept RPC calls to any of its public methods.
There are currently four such public methods defined on this Worker:
`canFetch`, `getByETag`, `getByPathname` and `exists`. While we are
stabilising the implementation details of these methods, we would
like to prevent developers from having their Workers call these
methods directly. To that end, we are adopting the
`unstable_<method_name>` naming convention for all of the
aforementioned methods, to indicate that they are still in flux and
that they are not an established API contract.

Author: GregBrimble

.changeset/popular-snakes-report.md

@@ -0,0 +1,7 @@
+---
+"@cloudflare/workers-shared": patch
+---
+
+chore: Rename asset-worker RPC methods as unstable\_\*
+
+The Asset Worker is currently set up as a `WorkerEntrypoint` class so that it is able to accept RPC calls to any of its public methods. There are currently four such public methods defined on this Worker: `canFetch`, `getByETag`, `getByPathname` and `exists`. While we are stabilising the implementation details of these methods, we would like to prevent developers from having their Workers call these methods directly. To that end, we are adopting the `unstable_<method_name>` naming convention for all of the aforementioned methods, to indicate that they are still in flux and that they are not an established API contract.

fixtures/asset-config/html-handling.test.ts

@@ -10,7 +10,7 @@ const IncomingRequest = Request<unknown, IncomingRequestCfProperties>;
 vi.mock("../../packages/workers-shared/asset-worker/src/utils/kv.ts");
 vi.mock("../../packages/workers-shared/asset-worker/src/configuration");
 const existsMock = (fileList: Set<string>) => {
-	vi.spyOn(Worker.prototype, "exists").mockImplementation(
+	vi.spyOn(Worker.prototype, "unstable_exists").mockImplementation(
 		async (pathname: string) => {
 			if (fileList.has(pathname)) {
 				return pathname;

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

@@ -13,8 +13,8 @@ import type EntrypointType from "./index";
 export const handleRequest = async (
 	request: Request,
 	configuration: Required<AssetConfig>,
-	exists: typeof EntrypointType.prototype.exists,
-	getByETag: typeof EntrypointType.prototype.getByETag
+	exists: typeof EntrypointType.prototype.unstable_exists,
+	getByETag: typeof EntrypointType.prototype.unstable_getByETag
 ) => {
 	const { pathname, search } = new URL(request.url);
 
@@ -68,7 +68,7 @@ type Intent =
 export const getIntent = async (
 	pathname: string,
 	configuration: Required<AssetConfig>,
-	exists: typeof EntrypointType.prototype.exists,
+	exists: typeof EntrypointType.prototype.unstable_exists,
 	skipRedirects = false
 ): Promise<Intent> => {
 	switch (configuration.html_handling) {
@@ -105,7 +105,7 @@ export const getIntent = async (
 const htmlHandlingAutoTrailingSlash = async (
 	pathname: string,
 	configuration: Required<AssetConfig>,
-	exists: typeof EntrypointType.prototype.exists,
+	exists: typeof EntrypointType.prototype.unstable_exists,
 	skipRedirects: boolean
 ): Promise<Intent> => {
 	let redirectResult: Intent = null;
@@ -231,7 +231,7 @@ const htmlHandlingAutoTrailingSlash = async (
 const htmlHandlingForceTrailingSlash = async (
 	pathname: string,
 	configuration: Required<AssetConfig>,
-	exists: typeof EntrypointType.prototype.exists,
+	exists: typeof EntrypointType.prototype.unstable_exists,
 	skipRedirects: boolean
 ): Promise<Intent> => {
 	let redirectResult: Intent = null;
@@ -362,7 +362,7 @@ const htmlHandlingForceTrailingSlash = async (
 const htmlHandlingDropTrailingSlash = async (
 	pathname: string,
 	configuration: Required<AssetConfig>,
-	exists: typeof EntrypointType.prototype.exists,
+	exists: typeof EntrypointType.prototype.unstable_exists,
 	skipRedirects: boolean
 ): Promise<Intent> => {
 	let redirectResult: Intent = null;
@@ -521,7 +521,7 @@ const htmlHandlingDropTrailingSlash = async (
 const htmlHandlingNone = async (
 	pathname: string,
 	configuration: Required<AssetConfig>,
-	exists: typeof EntrypointType.prototype.exists
+	exists: typeof EntrypointType.prototype.unstable_exists
 ): Promise<Intent> => {
 	const exactETag = await exists(pathname);
 	if (exactETag) {
@@ -534,7 +534,7 @@ const htmlHandlingNone = async (
 const notFound = async (
 	pathname: string,
 	configuration: Required<AssetConfig>,
-	exists: typeof EntrypointType.prototype.exists
+	exists: typeof EntrypointType.prototype.unstable_exists
 ): Promise<Intent> => {
 	switch (configuration.not_found_handling) {
 		case "single-page-application": {
@@ -566,7 +566,7 @@ const safeRedirect = async (
 	file: string,
 	destination: string,
 	configuration: Required<AssetConfig>,
-	exists: typeof EntrypointType.prototype.exists,
+	exists: typeof EntrypointType.prototype.unstable_exists,
 	skip: boolean
 ): Promise<Intent> => {
 	if (skip) {

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

@@ -11,12 +11,16 @@ import { getAssetWithMetadataFromKV } from "./utils/kv";
 import type { AssetConfig } from "../../utils/types";
 
 type Env = {
-	// ASSETS_MANIFEST is a pipeline binding to an ArrayBuffer containing the
-	// binary-encoded site manifest
+	/*
+	 * ASSETS_MANIFEST is a pipeline binding to an ArrayBuffer containing the
+	 * binary-encoded site manifest
+	 */
 	ASSETS_MANIFEST: ArrayBuffer;
 
-	// ASSETS_KV_NAMESPACE is a pipeline binding to the KV namespace that the
-	// assets are in.
+	/*
+	 * ASSETS_KV_NAMESPACE is a pipeline binding to the KV namespace that the
+	 * assets are in.
+	 */
 	ASSETS_KV_NAMESPACE: KVNamespace;
 
 	CONFIG: AssetConfig;
@@ -27,6 +31,17 @@ type Env = {
 	SENTRY_ACCESS_CLIENT_SECRET: string;
 };
 
+/*
+ * The Asset Worker is currently set up as a `WorkerEntrypoint` class so
+ * that it is able to accept RPC calls to any of its public methods. There
+ * are currently four such public methods defined on this Worker:
+ * `canFetch`, `getByETag`, `getByPathname` and `exists`. While we are
+ * stabilising the implementation details of these methods, we would like
+ * to prevent developers from having their Workers call these methods
+ * directly. To that end, we are adopting the `unstable_<method_name>`
+ * naming convention for all of the aforementioned methods, to indicate that
+ * they are still in flux and that they are not an established API contract.
+ */
 export default class extends WorkerEntrypoint<Env> {
 	async fetch(request: Request): Promise<Response> {
 		let sentry: ReturnType<typeof setupSentry> | undefined;
@@ -42,8 +57,8 @@ export default class extends WorkerEntrypoint<Env> {
 			return handleRequest(
 				request,
 				applyConfigurationDefaults(this.env.CONFIG),
-				this.exists.bind(this),
-				this.getByETag.bind(this)
+				this.unstable_exists.bind(this),
+				this.unstable_getByETag.bind(this)
 			);
 		} catch (err) {
 			const response = new InternalServerErrorResponse(err as Error);
@@ -66,7 +81,7 @@ export default class extends WorkerEntrypoint<Env> {
 				...applyConfigurationDefaults(this.env.CONFIG),
 				not_found_handling: "none",
 			},
-			this.exists.bind(this)
+			this.unstable_exists.bind(this)
 		);
 		// if asset exists but non GET/HEAD method, 405
 		if (intent && ["GET", "HEAD"].includes(method)) {
@@ -78,7 +93,7 @@ export default class extends WorkerEntrypoint<Env> {
 		return true;
 	}
 
-	async getByETag(
+	async unstable_getByETag(
 		eTag: string
 	): Promise<{ readableStream: ReadableStream; contentType: string }> {
 		const asset = await getAssetWithMetadataFromKV(
@@ -98,18 +113,18 @@ export default class extends WorkerEntrypoint<Env> {
 		};
 	}
 
-	async getByPathname(
+	async unstable_getByPathname(
 		pathname: string
 	): Promise<{ readableStream: ReadableStream; contentType: string } | null> {
-		const eTag = await this.exists(pathname);
+		const eTag = await this.unstable_exists(pathname);
 		if (!eTag) {
 			return null;
 		}
 
-		return this.getByETag(eTag);
+		return this.unstable_getByETag(eTag);
 	}
 
-	async exists(pathname: string): Promise<string | null> {
+	async unstable_exists(pathname: string): Promise<string | null> {
 		const assetsManifest = new AssetsManifest(this.env.ASSETS_MANIFEST);
 		return await assetsManifest.get(pathname);
 	}

packages/workers-shared/asset-worker/wrangler.toml

@@ -12,4 +12,18 @@ account_id = "0f1b8aa119a907021f659042f95ea9ba"
 workers_dev = false
 main = "src/index.ts"
 compatibility_date = "2024-07-31"
-compatibility_flags = ["nodejs_compat"]
+compatibility_flags = ["nodejs_compat"]
+
+[[unsafe.bindings]]
+name = "ASSETS_MANIFEST"
+type = "param"
+param = "assetManifest"
+data_ref = true
+
+[[unsafe.bindings]]
+name = "ASSETS_KV_NAMESPACE"
+type = "internal_assets"
+
+[unsafe.metadata.build_options]
+stable_id = "cloudflare/cf_asset_worker"
+networks = ["cf","jdc"]

packages/workers-shared/router-worker/wrangler.toml

@@ -8,5 +8,20 @@
 # (see packages/wrangler/src/dev/miniflare.ts -> buildMiniflareOptions())
 ##
 name = "router-worker"
+account_id = "0f1b8aa119a907021f659042f95ea9ba"
+workers_dev = false
 main = "src/index.ts"
-compatibility_date = "2024-07-31"
+compatibility_date = "2024-07-31"
+
+[[unsafe.bindings]]
+name = "ASSET_WORKER"
+type = "internal_assets"
+fetcherApi = "fetcher"
+
+[[unsafe.bindings]]
+name = "USER_WORKER"
+type = "origin"
+
+[unsafe.metadata.build_options]
+stable_id = "cloudflare/cf_router_worker"
+networks = ["cf","jdc"]