Add web_search binding kind support

Cloudflare Web Search is a new zero-config Workers binding. Declared
in wrangler.jsonc as a single object (there is exactly one shared web
corpus, so no namespace/instance/setting is required):

  { "web_search": { "binding": "WEBSEARCH" } }

At runtime the binding exposes a single `search()` method that
returns URLs and catalog metadata. The binding is always-remote --
Miniflare proxies to the production Web Search service via the
remote-bindings transport.

Changes in this PR:

@cloudflare/workers-utils
* environment.ts: `web_search` field (single-object shape)
* config.ts: default value
* validation.ts: `ConfigBindingFieldName` entry, friendly-name maps,
  `notInheritable` registration using `validateNamedSimpleBinding`,
  `safeBindings` entry
* worker.ts: `CfWebSearch` interface
* types.ts: `web_search` entries in `WorkerMetadataBinding` and
  `Binding` discriminated unions
* map-worker-metadata-bindings.ts: `case "web_search":` arm
* tests: validation tests for the new field

wrangler
* deployment-bundle/create-worker-upload-form.ts: extract +
  serialise into the upload metadata
* api/startDevWorker/utils.ts: config-to-bindings + metadata-to-bindings
  switches
* api/remoteBindings/index.ts: marked always-remote
* deploy/config-diffs.ts: `reorderableBindings` and
  `singleBindingFields` entries
* deploy/check-remote-secrets-override.ts: switch case
* dev/miniflare/index.ts: `WorkerOptionsBindings` pick, extract,
  `warnOrError`, pass to miniflare options
* type-generation/index.ts: emit `WebSearch` runtime type in both
  type-generation entry points
* user/user.ts: add `websearch:read` OAuth scope
* utils/print-bindings.ts: extract + render in startup banner

miniflare
* plugins/web-search/index.ts: new always-remote proxy plugin
* plugins/index.ts: register the plugin in PLUGINS, intersect
  WorkerOptions, re-export

Companion changes land in workerd (Web Search type definitions) and
edgeworker-config-service (binding kind + pipeline stage).

Author: G4brym

.changeset/add-web-search-binding.md

@@ -0,0 +1,27 @@
+---
+"miniflare": minor
+"wrangler": minor
+"@cloudflare/workers-utils": minor
+---
+
+Add support for the new `web_search` binding kind.
+
+Cloudflare Web Search is a managed, zero-setup web discovery primitive for
+agents and Workers. Declare the binding as a single object in
+`wrangler.jsonc`:
+
+```jsonc
+{
+  "web_search": { "binding": "WEBSEARCH" }
+}
+```
+
+There is exactly one shared web corpus, so there is no namespace, instance,
+or other field to specify -- only the variable name. The binding exposes a
+single `search()` method that returns URLs and catalog metadata for a
+query. Web Search is discovery-only -- to read a result's content the
+caller invokes the global `fetch()` API against the result's `url`.
+
+The binding is **always remote** in local development: Miniflare proxies
+to the production Web Search service via the remote-bindings transport.
+Adds the `websearch:read` OAuth scope to `wrangler login`.

packages/miniflare/src/plugins/index.ts

@@ -1,5 +1,6 @@
 import { AI_PLUGIN, AI_PLUGIN_NAME } from "./ai";
 import { AI_SEARCH_PLUGIN, AI_SEARCH_PLUGIN_NAME } from "./ai-search";
+import { WEB_SEARCH_PLUGIN, WEB_SEARCH_PLUGIN_NAME } from "./web-search";
 import {
 	ANALYTICS_ENGINE_PLUGIN,
 	ANALYTICS_ENGINE_PLUGIN_NAME,
@@ -66,6 +67,7 @@ export const PLUGINS = {
 	[ANALYTICS_ENGINE_PLUGIN_NAME]: ANALYTICS_ENGINE_PLUGIN,
 	[AI_PLUGIN_NAME]: AI_PLUGIN,
 	[AI_SEARCH_PLUGIN_NAME]: AI_SEARCH_PLUGIN,
+	[WEB_SEARCH_PLUGIN_NAME]: WEB_SEARCH_PLUGIN,
 	[BROWSER_RENDERING_PLUGIN_NAME]: BROWSER_RENDERING_PLUGIN,
 	[DISPATCH_NAMESPACE_PLUGIN_NAME]: DISPATCH_NAMESPACE_PLUGIN,
 	[IMAGES_PLUGIN_NAME]: IMAGES_PLUGIN,
@@ -134,6 +136,7 @@ export type WorkerOptions = z.input<typeof CORE_PLUGIN.options> &
 	z.input<typeof ANALYTICS_ENGINE_PLUGIN.options> &
 	z.input<typeof AI_PLUGIN.options> &
 	z.input<typeof AI_SEARCH_PLUGIN.options> &
+	z.input<typeof WEB_SEARCH_PLUGIN.options> &
 	z.input<typeof BROWSER_RENDERING_PLUGIN.options> &
 	z.input<typeof DISPATCH_NAMESPACE_PLUGIN.options> &
 	z.input<typeof IMAGES_PLUGIN.options> &
@@ -224,6 +227,7 @@ export * from "./email";
 export * from "./analytics-engine";
 export * from "./ai";
 export * from "./ai-search";
+export * from "./web-search";
 export * from "./browser-rendering";
 export * from "./dispatch-namespace";
 export * from "./images";

packages/miniflare/src/plugins/web-search/index.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import {
+	getUserBindingServiceName,
+	ProxyNodeBinding,
+	remoteProxyClientWorker,
+} from "../shared";
+import type { Plugin, RemoteProxyConnectionString } from "../shared";
+
+const WebSearchEntrySchema = z.object({
+	remoteProxyConnectionString: z
+		.custom<RemoteProxyConnectionString>()
+		.optional(),
+});
+
+export const WebSearchOptionsSchema = z.object({
+	webSearch: z.record(WebSearchEntrySchema).optional(),
+});
+
+export const WEB_SEARCH_PLUGIN_NAME = "web-search";
+
+const WEB_SEARCH_SCOPE = "web-search";
+
+export const WEB_SEARCH_PLUGIN: Plugin<typeof WebSearchOptionsSchema> = {
+	options: WebSearchOptionsSchema,
+	async getBindings(options) {
+		const bindings: {
+			name: string;
+			service: { name: string };
+		}[] = [];
+
+		for (const [bindingName, entry] of Object.entries(
+			options.webSearch ?? {}
+		)) {
+			bindings.push({
+				name: bindingName,
+				service: {
+					name: getUserBindingServiceName(
+						WEB_SEARCH_SCOPE,
+						bindingName,
+						entry.remoteProxyConnectionString
+					),
+				},
+			});
+		}
+
+		return bindings;
+	},
+	getNodeBindings(options: z.infer<typeof WebSearchOptionsSchema>) {
+		const nodeBindings: Record<string, ProxyNodeBinding> = {};
+
+		for (const bindingName of Object.keys(options.webSearch ?? {})) {
+			nodeBindings[bindingName] = new ProxyNodeBinding();
+		}
+
+		return nodeBindings;
+	},
+	async getServices({ options }) {
+		const services: {
+			name: string;
+			worker: ReturnType<typeof remoteProxyClientWorker>;
+		}[] = [];
+
+		for (const [bindingName, entry] of Object.entries(
+			options.webSearch ?? {}
+		)) {
+			services.push({
+				name: getUserBindingServiceName(
+					WEB_SEARCH_SCOPE,
+					bindingName,
+					entry.remoteProxyConnectionString
+				),
+				worker: remoteProxyClientWorker(
+					entry.remoteProxyConnectionString,
+					bindingName
+				),
+			});
+		}
+
+		return services;
+	},
+};

packages/workers-utils/src/config/config.ts

@@ -336,6 +336,7 @@ export const defaultWranglerConfig: Config = {
 	vectorize: [],
 	ai_search_namespaces: [],
 	ai_search: [],
+	web_search: undefined,
 	hyperdrive: [],
 	workflows: [],
 	secrets_store_secrets: [],

packages/workers-utils/src/config/environment.ts

@@ -1014,6 +1014,26 @@ export interface EnvironmentNonInheritable {
 		remote?: boolean;
 	}[];
 
+	/**
+	 * Cloudflare Web Search binding. There is exactly one shared web corpus, so the
+	 * binding is zero-config -- only the variable name is required, declared as a
+	 * single object (not an array).
+	 *
+	 * NOTE: This field is not automatically inherited from the top level environment,
+	 * and so must be specified in every named environment.
+	 *
+	 * @default {}
+	 * @nonInheritable
+	 */
+	web_search:
+		| {
+				/** The binding name used to refer to Web Search in the Worker. */
+				binding: string;
+				/** Whether the Web Search binding should be remote or not in local development */
+				remote?: boolean;
+		  }
+		| undefined;
+
 	/**
 	 * Specifies Hyperdrive configs that are bound to this Worker environment.
 	 *

packages/workers-utils/src/config/validation.ts

@@ -81,6 +81,7 @@ export type ConfigBindingFieldName =
 	| "vectorize"
 	| "ai_search_namespaces"
 	| "ai_search"
+	| "web_search"
 	| "hyperdrive"
 	| "r2_buckets"
 	| "logfwdr"
@@ -122,6 +123,7 @@ export const friendlyBindingNames: Record<ConfigBindingFieldName, string> = {
 	vectorize: "Vectorize Index",
 	ai_search_namespaces: "AI Search Namespace",
 	ai_search: "AI Search Instance",
+	web_search: "Web Search",
 	hyperdrive: "Hyperdrive Config",
 	r2_buckets: "R2 Bucket",
 	logfwdr: "logfwdr",
@@ -178,6 +180,7 @@ const bindingTypeFriendlyNames: Record<Binding["type"], string> = {
 	vectorize: "Vectorize Index",
 	ai_search_namespace: "AI Search Namespace",
 	ai_search: "AI Search Instance",
+	web_search: "Web Search",
 	hyperdrive: "Hyperdrive Config",
 	service: "Worker",
 	fetcher: "Service Binding",
@@ -1727,6 +1730,16 @@ function normalizeAndValidateEnvironment(
 			validateBindingArray(envName, validateAISearchBinding),
 			[]
 		),
+		web_search: notInheritable(
+			diagnostics,
+			topLevelEnv,
+			rawConfig,
+			rawEnv,
+			envName,
+			"web_search",
+			validateNamedSimpleBinding(envName),
+			undefined
+		),
 		hyperdrive: notInheritable(
 			diagnostics,
 			topLevelEnv,
@@ -2982,6 +2995,7 @@ const validateUnsafeBinding: ValidatorFn = (diagnostics, field, value) => {
 			"ai",
 			"ai_search_namespace",
 			"ai_search",
+			"web_search",
 			"kv_namespace",
 			"durable_object_namespace",
 			"d1_database",

packages/workers-utils/src/map-worker-metadata-bindings.ts

@@ -288,6 +288,13 @@ export function mapWorkerMetadataBindings(
 							},
 						];
 						break;
+					case "web_search":
+						{
+							configObj.web_search = {
+								binding: binding.name,
+							};
+						}
+						break;
 					case "hyperdrive":
 						configObj.hyperdrive = [
 							...(configObj.hyperdrive ?? []),

packages/workers-utils/src/types.ts

@@ -39,6 +39,7 @@ import type {
 	CfVectorize,
 	CfVpcNetwork,
 	CfVpcService,
+	CfWebSearch,
 	CfWorkerLoader,
 	CfWorkflow,
 } from "./worker";
@@ -72,6 +73,7 @@ export type WorkerMetadataBinding =
 	| { type: "data_blob"; name: string; part: string }
 	| { type: "ai_search_namespace"; name: string; namespace: string }
 	| { type: "ai_search"; name: string; instance_name: string }
+	| { type: "web_search"; name: string }
 	| { type: "kv_namespace"; name: string; namespace_id: string; raw?: boolean }
 	| { type: "media"; name: string }
 	| {
@@ -328,6 +330,7 @@ export type Binding =
 	| ({ type: "vectorize" } & BindingOmit<CfVectorize>)
 	| ({ type: "ai_search_namespace" } & BindingOmit<CfAISearchNamespace>)
 	| ({ type: "ai_search" } & BindingOmit<CfAISearch>)
+	| ({ type: "web_search" } & BindingOmit<CfWebSearch>)
 	| ({ type: "hyperdrive" } & BindingOmit<CfHyperdrive>)
 	| ({ type: "service" } & BindingOmit<CfService>)
 	| { type: "fetcher"; fetcher: ServiceFetch }

packages/workers-utils/src/worker.ts

@@ -242,6 +242,11 @@ export interface CfAISearch {
 	remote?: boolean;
 }
 
+export interface CfWebSearch {
+	binding: string;
+	remote?: boolean;
+}
+
 export interface CfSecretsStoreSecrets {
 	binding: string;
 	store_id: string;

packages/workers-utils/tests/config/validation/normalize-and-validate-config.test.ts

@@ -2018,6 +2018,50 @@ describe("normalizeAndValidateConfig()", () => {
 			});
 		});
 
+		describe("[web_search]", () => {
+			it("should accept a valid web_search binding", ({ expect }) => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ web_search: { binding: "WEBSEARCH" } } as RawConfig,
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasErrors()).toBe(false);
+				expect(diagnostics.hasWarnings()).toBe(false);
+			});
+
+			it("should error if web_search is an array", ({ expect }) => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ web_search: [] } as unknown as RawConfig,
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasWarnings()).toBe(false);
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+					"Processing wrangler configuration:
+					  - The field "web_search" should be an object but got []."
+				`);
+			});
+
+			it("should error if web_search has no binding name", ({ expect }) => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ web_search: {} } as unknown as RawConfig,
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasWarnings()).toBe(false);
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+					"Processing wrangler configuration:
+					  - binding should have a string "binding" field."
+				`);
+			});
+		});
+
 		// Vectorize
 		describe("[vectorize]", () => {
 			it("should error if vectorize is an object", ({ expect }) => {