feat: add Flagship binding support

.changeset/add-flagship-binding.md

@@ -0,0 +1,9 @@
+---
+"miniflare": minor
+"wrangler": minor
+"@cloudflare/workers-utils": minor
+---
+
+feat: add Flagship feature flag binding support
+
+Adds end-to-end support for the Flagship feature flag binding, which allows Workers to evaluate feature flags from Cloudflare's Flagship service. Configure it in `wrangler.json` with a `flagship` array containing `binding` and `app_id` entries. In local dev, the binding returns default values for all flag evaluations; use `"remote": true` in the binding to evaluate flags against the live Flagship service.

packages/miniflare/src/index.ts

@@ -34,6 +34,7 @@ import {
 	BROWSER_RENDERING_PLUGIN_NAME,
 	D1_PLUGIN_NAME,
 	DURABLE_OBJECTS_PLUGIN_NAME,
+	FLAGSHIP_PLUGIN_NAME,
 	getDirectSocketName,
 	getGlobalServices,
 	getPersistPath,
@@ -148,6 +149,7 @@ import type {
 	D1Database,
 	DurableObjectNamespace,
 	Fetcher,
+	Flags,
 	ImagesBinding,
 	KVNamespace,
 	KVNamespaceListKey,
@@ -2957,6 +2959,9 @@ export class Miniflare {
 	}> {
 		return this.#getProxy(HELLO_WORLD_PLUGIN_NAME, bindingName, workerName);
 	}
+	getFlagshipBinding(bindingName: string, workerName?: string): Promise<Flags> {
+		return this.#getProxy(FLAGSHIP_PLUGIN_NAME, bindingName, workerName);
+	}
 	getStreamBinding(
 		bindingName: string,
 		workerName?: string

packages/miniflare/src/plugins/flagship/index.ts

@@ -0,0 +1,84 @@
+import BINDING_SCRIPT from "worker:flagship/binding";
+import { z } from "zod";
+import {
+	getUserBindingServiceName,
+	ProxyNodeBinding,
+	remoteProxyClientWorker,
+} from "../shared";
+import type { Worker_Binding } from "../../runtime";
+import type { Plugin, RemoteProxyConnectionString } from "../shared";
+
+const FlagshipSchema = z.object({
+	app_id: z.string(),
+	remoteProxyConnectionString: z
+		.custom<RemoteProxyConnectionString>()
+		.optional(),
+});
+
+export const FlagshipOptionsSchema = z.object({
+	flagship: z.record(FlagshipSchema).optional(),
+});
+
+export const FLAGSHIP_PLUGIN_NAME = "flagship";
+
+export const FLAGSHIP_PLUGIN: Plugin<typeof FlagshipOptionsSchema> = {
+	options: FlagshipOptionsSchema,
+	async getBindings(options) {
+		if (!options.flagship) {
+			return [];
+		}
+
+		return Object.entries(options.flagship).map<Worker_Binding>(
+			([name, config]) => ({
+				name,
+				service: {
+					name: getUserBindingServiceName(
+						FLAGSHIP_PLUGIN_NAME,
+						name,
+						config.remoteProxyConnectionString
+					),
+					entrypoint: "FlagshipBinding",
+				},
+			})
+		);
+	},
+	getNodeBindings(options: z.infer<typeof FlagshipOptionsSchema>) {
+		if (!options.flagship) {
+			return {};
+		}
+		return Object.fromEntries(
+			Object.keys(options.flagship).map((name) => [
+				name,
+				new ProxyNodeBinding(),
+			])
+		);
+	},
+	async getServices({ options }) {
+		if (!options.flagship) {
+			return [];
+		}
+
+		return Object.entries(options.flagship).map(
+			([name, { remoteProxyConnectionString }]) => {
+				return {
+					name: getUserBindingServiceName(
+						FLAGSHIP_PLUGIN_NAME,
+						name,
+						remoteProxyConnectionString
+					),
+					worker: remoteProxyConnectionString
+						? remoteProxyClientWorker(remoteProxyConnectionString, name)
+						: {
+								compatibilityDate: "2025-03-17",
+								modules: [
+									{
+										name: "binding.worker.js",
+										esModule: BINDING_SCRIPT(),
+									},
+								],
+							},
+				};
+			}
+		);
+	},
+};

packages/miniflare/src/plugins/index.ts

@@ -19,6 +19,7 @@ import {
 } from "./dispatch-namespace";
 import { DURABLE_OBJECTS_PLUGIN, DURABLE_OBJECTS_PLUGIN_NAME } from "./do";
 import { EMAIL_PLUGIN, EMAIL_PLUGIN_NAME } from "./email";
+import { FLAGSHIP_PLUGIN, FLAGSHIP_PLUGIN_NAME } from "./flagship";
 import { HELLO_WORLD_PLUGIN, HELLO_WORLD_PLUGIN_NAME } from "./hello-world";
 import { HYPERDRIVE_PLUGIN, HYPERDRIVE_PLUGIN_NAME } from "./hyperdrive";
 import { IMAGES_PLUGIN, IMAGES_PLUGIN_NAME } from "./images";
@@ -74,6 +75,7 @@ export const PLUGINS = {
 	[VPC_SERVICES_PLUGIN_NAME]: VPC_SERVICES_PLUGIN,
 	[MTLS_PLUGIN_NAME]: MTLS_PLUGIN,
 	[HELLO_WORLD_PLUGIN_NAME]: HELLO_WORLD_PLUGIN,
+	[FLAGSHIP_PLUGIN_NAME]: FLAGSHIP_PLUGIN,
 	[WORKER_LOADER_PLUGIN_NAME]: WORKER_LOADER_PLUGIN,
 	[MEDIA_PLUGIN_NAME]: MEDIA_PLUGIN,
 	[VERSION_METADATA_PLUGIN_NAME]: VERSION_METADATA_PLUGIN,
@@ -141,6 +143,7 @@ export type WorkerOptions = z.input<typeof CORE_PLUGIN.options> &
 	z.input<typeof VPC_SERVICES_PLUGIN.options> &
 	z.input<typeof MTLS_PLUGIN.options> &
 	z.input<typeof HELLO_WORLD_PLUGIN.options> &
+	z.input<typeof FLAGSHIP_PLUGIN.options> &
 	z.input<typeof WORKER_LOADER_PLUGIN.options> &
 	z.input<typeof MEDIA_PLUGIN.options> &
 	z.input<typeof VERSION_METADATA_PLUGIN.options>;
@@ -230,6 +233,7 @@ export * from "./vpc-networks";
 export * from "./vpc-services";
 export * from "./mtls";
 export * from "./hello-world";
+export * from "./flagship";
 export * from "./worker-loader";
 export * from "./media";
 export * from "./version-metadata";

packages/miniflare/src/workers/flagship/binding.worker.ts

@@ -0,0 +1,104 @@
+// Local stub for Flagship feature flag binding.
+// In local dev mode, all flag evaluations return the provided default value.
+// Use `wrangler dev --remote` to evaluate flags against the real Flagship service.
+
+import { WorkerEntrypoint } from "cloudflare:workers";
+
+interface EvaluationDetails<T> {
+	flagKey: string;
+	value: T;
+	variant?: string;
+	reason?: string;
+	errorCode?: string;
+	errorMessage?: string;
+}
+
+export class FlagshipBinding extends WorkerEntrypoint {
+	async get(
+		_flagKey: string,
+		defaultValue?: unknown,
+		_context?: Record<string, string | number | boolean>
+	): Promise<unknown> {
+		return defaultValue;
+	}
+
+	async getBooleanValue(
+		_flagKey: string,
+		defaultValue: boolean,
+		_context?: Record<string, string | number | boolean>
+	): Promise<boolean> {
+		return defaultValue;
+	}
+
+	async getStringValue(
+		_flagKey: string,
+		defaultValue: string,
+		_context?: Record<string, string | number | boolean>
+	): Promise<string> {
+		return defaultValue;
+	}
+
+	async getNumberValue(
+		_flagKey: string,
+		defaultValue: number,
+		_context?: Record<string, string | number | boolean>
+	): Promise<number> {
+		return defaultValue;
+	}
+
+	async getObjectValue<T extends object>(
+		_flagKey: string,
+		defaultValue: T,
+		_context?: Record<string, string | number | boolean>
+	): Promise<T> {
+		return defaultValue;
+	}
+
+	async getBooleanDetails(
+		flagKey: string,
+		defaultValue: boolean,
+		_context?: Record<string, string | number | boolean>
+	): Promise<EvaluationDetails<boolean>> {
+		return {
+			flagKey,
+			value: defaultValue,
+			reason: "DEFAULT",
+		};
+	}
+
+	async getStringDetails(
+		flagKey: string,
+		defaultValue: string,
+		_context?: Record<string, string | number | boolean>
+	): Promise<EvaluationDetails<string>> {
+		return {
+			flagKey,
+			value: defaultValue,
+			reason: "DEFAULT",
+		};
+	}
+
+	async getNumberDetails(
+		flagKey: string,
+		defaultValue: number,
+		_context?: Record<string, string | number | boolean>
+	): Promise<EvaluationDetails<number>> {
+		return {
+			flagKey,
+			value: defaultValue,
+			reason: "DEFAULT",
+		};
+	}
+
+	async getObjectDetails<T extends object>(
+		flagKey: string,
+		defaultValue: T,
+		_context?: Record<string, string | number | boolean>
+	): Promise<EvaluationDetails<T>> {
+		return {
+			flagKey,
+			value: defaultValue,
+			reason: "DEFAULT",
+		};
+	}
+}