Skip to content

RAG-1300: Add web_search binding kind support#13955

Merged
dario-piotrowicz merged 1 commit into
cloudflare:mainfrom
G4brym:gmassadas/add-web-search-binding
May 28, 2026
Merged

RAG-1300: Add web_search binding kind support#13955
dario-piotrowicz merged 1 commit into
cloudflare:mainfrom
G4brym:gmassadas/add-web-search-binding

Conversation

@G4brym

@G4brym G4brym commented May 18, 2026

Copy link
Copy Markdown
Member

Adds wrangler / miniflare / workers-utils support for the new web_search Workers binding plus a wrangler websearch search command.

includes:

  • binding
  • cli
  • oauth scopes

Binding

Declared as a single object in wrangler.jsonc (one shared corpus, no namespace/instance):

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

At runtime the binding exposes a single search() method returning { items, metadata }. Always-remote in local dev: Miniflare proxies to the production service via the remote-bindings transport.

CLI

npx wrangler websearch search "cloudflare workers"
npx wrangler websearch search "cloudflare workers" --limit 5
npx wrangler websearch search "cloudflare workers" --json

--limit and --json are optional. Default output is a pretty table; --json prints the raw response.


  • Tests
    • Tests included/updated
    • Automated tests not possible - manual testing has been completed as follows:
    • Additional testing not necessary because:
  • Public documentation
    • Cloudflare docs PR(s):
    • Documentation not necessary because: we will add docs when we release this to the public

Open in Devin Review

@G4brym G4brym requested a review from workers-devprod as a code owner May 18, 2026 16:04
@changeset-bot

changeset-bot Bot commented May 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 6b9ed38

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages
Name Type
miniflare Minor
wrangler Minor
@cloudflare/workers-utils Minor
@cloudflare/pages-shared Patch
@cloudflare/vite-plugin Patch
@cloudflare/vitest-pool-workers Patch
@cloudflare/cli-shared-helpers Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-project-automation github-project-automation Bot moved this to Untriaged in workers-sdk May 18, 2026
@workers-devprod workers-devprod requested review from a team and dario-piotrowicz and removed request for a team May 18, 2026 16:05
@workers-devprod

workers-devprod commented May 18, 2026

Copy link
Copy Markdown
Contributor

Codeowners approval required for this PR:

  • @cloudflare/wrangler
Show detailed file reviewers
  • .changeset/add-web-search-binding.md: [@cloudflare/wrangler]
  • packages/miniflare/src/plugins/index.ts: [@cloudflare/wrangler]
  • packages/miniflare/src/plugins/web-search/index.ts: [@cloudflare/wrangler]
  • packages/workers-utils/src/config/config.ts: [@cloudflare/wrangler]
  • packages/workers-utils/src/config/environment.ts: [@cloudflare/wrangler]
  • packages/workers-utils/src/config/validation.ts: [@cloudflare/wrangler]
  • packages/workers-utils/src/map-worker-metadata-bindings.ts: [@cloudflare/wrangler]
  • packages/workers-utils/src/types.ts: [@cloudflare/wrangler]
  • packages/workers-utils/src/worker.ts: [@cloudflare/wrangler]
  • packages/workers-utils/tests/config/validation/normalize-and-validate-config.test.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/tests/deploy/core.test.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/tests/index.test.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/tests/user.test.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/tests/whoami.test.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/api/remoteBindings/index.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/api/startDevWorker/utils.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/core/teams.d.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/deploy/check-remote-secrets-override.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/deploy/config-diffs.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/deployment-bundle/create-worker-upload-form.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/dev/miniflare/index.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/index.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/type-generation/index.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/user/user.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/utils/add-created-resource-config.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/utils/print-bindings.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/websearch/client.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/websearch/index.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/websearch/search.ts: [@cloudflare/wrangler]
  • packages/wrangler/src/websearch/types.ts: [@cloudflare/wrangler]

@G4brym G4brym marked this pull request as draft May 18, 2026 16:11
@G4brym G4brym changed the title Add web_search binding kind support RAG-1300: Add web_search binding kind support May 18, 2026
@G4brym G4brym force-pushed the gmassadas/add-web-search-binding branch from ffac1d2 to 344d2a1 Compare May 21, 2026 10:39
@pkg-pr-new

pkg-pr-new Bot commented May 21, 2026

Copy link
Copy Markdown
create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@13955

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/@cloudflare/deploy-helpers@13955

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@13955

miniflare

npm i https://pkg.pr.new/miniflare@13955

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@13955

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@13955

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@13955

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@13955

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@13955

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@13955

wrangler

npm i https://pkg.pr.new/wrangler@13955

commit: 6b9ed38

@G4brym G4brym force-pushed the gmassadas/add-web-search-binding branch from d17a336 to 9c09fcf Compare May 21, 2026 13:52
@G4brym G4brym marked this pull request as ready for review May 21, 2026 13:52
devin-ai-integration[bot]

This comment was marked as resolved.

@G4brym G4brym marked this pull request as draft May 21, 2026 14:26
@G4brym G4brym force-pushed the gmassadas/add-web-search-binding branch from 9c09fcf to 4d668aa Compare May 27, 2026 11:24
@G4brym G4brym marked this pull request as ready for review May 27, 2026 11:41
@workers-devprod

workers-devprod commented May 27, 2026

Copy link
Copy Markdown
Contributor

Codeowners approval required for this PR:

  • ✅ @cloudflare/wrangler
Show detailed file reviewers

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 new potential issue.

View 8 additional findings in Devin Review.

Open in Devin Review

Comment thread packages/wrangler/src/websearch/client.ts Outdated
@G4brym

G4brym commented May 27, 2026

Copy link
Copy Markdown
Member Author

/bonk

@G4brym G4brym force-pushed the gmassadas/add-web-search-binding branch 5 times, most recently from bf2e71d to de2c85e Compare May 27, 2026 14:14
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.

A new top-level CLI command is also added:

  wrangler websearch search "cloudflare workers" [--limit N] [--json]

which calls the public REST endpoint `POST /accounts/:id/websearch/search`
directly (no Worker required).

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
* config/binding-local-support.ts: register `web_search` as
  `DO-NOT-USE-this-resource-will-never-have-a-local-simulator`
* 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
* 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.run` OAuth scope (dot, not colon -- matches
  Bach source-of-truth)
* user/whoami.ts: handle dot-separated OAuth scopes in the expected-scope
  diff (previous code split on ':' then re-joined with ':', producing
  `websearch.run:undefined` which never matched the expected literal)
* utils/print-bindings.ts: extract + render in startup banner; always
  remote (matches ai_search/ai_search_namespace pattern)
* websearch/{types,client,index,search}.ts: new `wrangler websearch search`
  command, calling REST `/accounts/:id/websearch/search`. Field names mirror
  the REST API (snake_case); the Worker binding stays camelCase per workerd
  type defs.
* core/teams.d.ts: add "Product: Web Search" entry
* utils/add-created-resource-config.ts: exclude `web_search` from
  `ValidKeys` (singleton binding)

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).
@G4brym G4brym force-pushed the gmassadas/add-web-search-binding branch from de2c85e to 6b9ed38 Compare May 28, 2026 08:40

@dario-piotrowicz dario-piotrowicz left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me 🙂

@workers-devprod workers-devprod left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Codeowners reviews satisfied

@github-project-automation github-project-automation Bot moved this from Untriaged to Approved in workers-sdk May 28, 2026
@dario-piotrowicz dario-piotrowicz merged commit a2ef1a3 into cloudflare:main May 28, 2026
55 checks passed
@github-project-automation github-project-automation Bot moved this from Approved to Done in workers-sdk May 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants