expose cf object from Miniflare instances (#4905)

* expose cf object from Miniflare instances

---------

Co-authored-by: MrBBot <bcoll@cloudflare.com>

.changeset/gentle-chairs-pull.md

@@ -0,0 +1,21 @@
+---
+"miniflare": minor
+---
+
+feature: add a `getCf` method to Miniflare instances
+
+add a new `getCf` method attached to instances of `Miniflare`, this `getCf` returns
+the `cf` object that the Miniflare instance provides to the actual workers and it
+depends of the core option of the same name
+
+Example:
+
+```ts
+import { Miniflare } from "miniflare";
+
+const mf = new Miniflare({ ... });
+
+const cf = await mf.getCf();
+
+console.log(`country = ${cf.country} ; colo = ${cf.colo}`); // logs 'country = GB ; colo = LHR'
+```

packages/miniflare/README.md

@@ -406,7 +406,7 @@ parameter in module format Workers.
             await this.STORE.fetch(this.baseURL + key, { method: "DELETE" });
           }
         }
-    
+
         // env has the type { STORE: Fetcher, NAMESPACE?: string }
         export default function (env) {
           return new MiniKV(env);
@@ -770,3 +770,7 @@ defined at the top-level.
   `Miniflare#dispatchFetch()` cannot be called. Additionally, calling this
   function will invalidate any values returned by the `Miniflare#get*()`
   methods, preventing them from being used.
+
+- `getCf(): Promise<Record<string, any>>`
+
+  Returns the same object returned from incoming `Request`'s `cf` property. This object depends on the `cf` property from `SharedOptions`.

packages/miniflare/src/index.ts

@@ -615,6 +615,8 @@ export class Miniflare {
 	#runtimeDispatcher?: Dispatcher;
 	#proxyClient?: ProxyClient;
 
+	#cfObject?: Record<string, any> = {};
+
 	// Path to temporary directory for use as scratch space/"in-memory" Durable
 	// Object storage. Note this may not exist, it's up to the consumers to
 	// create this if needed. Deleted on `dispose()`.
@@ -962,6 +964,7 @@ export class Miniflare {
 		const sharedOpts = this.#sharedOpts;
 
 		sharedOpts.core.cf = await setupCf(this.#log, sharedOpts.core.cf);
+		this.#cfObject = sharedOpts.core.cf;
 
 		const durableObjectClassNames = getDurableObjectClassNames(allWorkerOpts);
 		const wrappedBindingNames = getWrappedBindingNames(
@@ -1324,6 +1327,13 @@ export class Miniflare {
 		return this.#waitForReady();
 	}
 
+	async getCf(): Promise<Record<string, any>> {
+		this.#checkDisposed();
+		await this.ready;
+
+		return JSON.parse(JSON.stringify(this.#cfObject));
+	}
+
 	async getInspectorURL(): Promise<URL> {
 		this.#checkDisposed();
 		await this.ready;

packages/miniflare/test/index.spec.ts

@@ -733,17 +733,16 @@ test("Miniflare: python modules", async (t) => {
 			{
 				type: "PythonModule",
 				path: "index",
-				contents: "from test_module import add; from js import Response;\ndef fetch(request):\n  return Response.new(add(2,2))",
+				contents:
+					"from test_module import add; from js import Response;\ndef fetch(request):\n  return Response.new(add(2,2))",
 			},
 			{
 				type: "PythonModule",
 				path: "test_module",
 				contents: `def add(a, b):\n  return a + b`,
 			},
 		],
-		compatibilityFlags: [
-			"experimental"
-		]
+		compatibilityFlags: ["experimental"],
 	});
 	t.teardown(() => mf.dispose());
 	const res = await mf.dispatchFetch("http://localhost");
@@ -1736,3 +1735,29 @@ test("Miniflare: prohibits invalid wrapped bindings", async (t) => {
 		}
 	);
 });
+
+test("Miniflare: getCf() returns a standard cf object", async (t) => {
+	const mf = new Miniflare({ script: "", modules: true });
+	t.teardown(() => mf.dispose());
+
+	const cf = await mf.getCf();
+	t.like(cf, {
+		colo: "DFW",
+		city: "Austin",
+		regionCode: "TX",
+	});
+});
+
+test("Miniflare: getCf() returns a user provided cf object", async (t) => {
+	const mf = new Miniflare({
+		script: "",
+		modules: true,
+		cf: {
+			myFakeField: "test",
+		},
+	});
+	t.teardown(() => mf.dispose());
+
+	const cf = await mf.getCf();
+	t.deepEqual(cf, { myFakeField: "test" });
+});