[Workers for Platforms] Simplify custom bindings docs with R2 examples and clearer intent

Author: ivoryibu

src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/custom-bindings.mdx

@@ -1,7 +1,7 @@
 ---
 title: Custom bindings
 pcx_content_type: how-to
-description: Route resource operations through a platform-owned Worker to control per-tenant access.
+description: Intercept User Worker binding calls to log usage, enforce limits, and run platform-owned logic before operations reach a Cloudflare resource.
 sidebar:
   order: 6
 products:
@@ -17,18 +17,26 @@ import {
 	TabItem,
 } from "~/components";
 
-A custom binding routes a User Worker's resource operations through your Platform Worker before they reach the underlying resource. You wrap a Cloudflare resource (for example, a [D1](/d1/) database) inside a [`WorkerEntrypoint`](/workers/runtime-apis/bindings/service-bindings/rpc/#the-workerentrypoint-class) class and use [`props`](/workers/runtime-apis/context/#props) to pass the real resource connection to your Platform Worker at upload time.
+Custom bindings let your platform intercept calls that User Workers make to Cloudflare resource bindings. Instead of calling the underlying resource directly, each operation first passes through logic in a Platform Worker that you control.
 
-The User Worker calls the resource API as usual. It does not know that the binding routes through your Platform Worker first.
+For example, when a User Worker calls `env.BUCKET.put()`, your Platform Worker could:
+
+- Measure the size of the upload and record it for billing.
+- Check whether the customer has exceeded their storage limit.
+- Reject objects that do not meet your platform's requirements.
+- Forward allowed uploads to the underlying R2 bucket.
+
+From the User Worker's perspective, `BUCKET` still behaves like a normal R2 binding. The User Worker does not need to know about your interception logic or have direct access to the underlying resource.
 
 ## Use cases
 
-Use this pattern when you deploy [User Workers](/cloudflare-for-platforms/workers-for-platforms/) and need to:
+Use custom bindings when you need to run platform-owned logic around resource operations:
 
-- **Enforce query policy** — inspect and filter operations before they reach the resource.
-- **Scope access per tenant** — use `this.ctx.props` to select a tenant-specific resource or apply tenant-specific rules.
-- **Log or meter usage** — record every operation for auditing or billing.
-- **Rate-limit operations** — throttle operations per tenant or per plan tier.
+- **Log or meter usage** — Record operations, bytes, or other usage data for auditing and billing.
+- **Enforce limits** — Apply quotas or rate limits based on the customer or plan tier.
+- **Add custom logic** — Validate, transform, or reject operations according to your platform's requirements.
+- **Scope access per tenant** — Select the resource assigned to a customer and prevent access to other tenants' resources.
+- **Enforce resource policy** — Restrict which operations a User Worker can perform before they reach the resource.
 
 ## Supported resources
 
@@ -37,59 +45,76 @@ Use this pattern when you deploy [User Workers](/cloudflare-for-platforms/worker
 | [D1](/d1/) | Available         |
 | [R2](/r2/) | Not yet available |
 
-## The pattern
+The conceptual examples below use R2 because its `get()` and `put()` operations make the interception pattern easy to understand. The runnable implementation uses D1, which is currently the supported resource.
 
-Every custom binding follows the same three-step structure, regardless of the underlying resource.
+## How custom bindings work
 
-### Step 1: Define the Platform Worker
+There are three parts to a custom binding:
 
-Export a class that extends `WorkerEntrypoint`. This class wraps the target resource and implements a method that the binding calls for every operation.
+1. Define the platform-owned logic that handles intercepted resource operations.
+2. Give that logic the underlying resource and tenant-specific context it needs.
+3. Attach the custom binding so the User Worker can call the standard resource API.
 
-```ts
-import { WorkerEntrypoint } from "cloudflare:workers";
+### Step 1: Define where intercepted calls are handled
 
-export class MyCustomBinding extends WorkerEntrypoint {
-	async query(params) {
-		// Inspect params, then forward or reject.
-		return this.ctx.props.RESOURCE.query(params);
-	}
-}
-```
+Your platform needs a trusted place to receive each resource operation before it reaches the underlying resource. Define this logic as methods on a [`WorkerEntrypoint`](/workers/runtime-apis/bindings/service-bindings/rpc/#the-workerentrypoint-class) exported by your Platform Worker.
+
+The method that Cloudflare invokes depends on the resource. Using R2 as a conceptual example, an upload made with `env.BUCKET.put()` would be handled by a `put()` method in your Platform Worker.
+
+Inside that method, you can run your own logic. For example, you could measure the upload, record usage, check the customer's storage quota, and either reject the operation or forward it to the real bucket.
 
-Your policy logic runs inside this method. To forward an operation, call the corresponding method on the resource passed through `props`. To reject an operation, return an error.
+For D1, resource operations are passed to a `query()` method. Refer to the [D1 implementation](#d1-implementation) for runnable code.
 
-### Step 2: Access tenant context
+### Step 2: Provide the resource and tenant context
 
-When you upload a User Worker, you pass `props` in the binding configuration. These values are trusted and platform-owned — the User Worker cannot read or change them.
+The interception logic needs to know which resource and platform rules apply to the User Worker. Pass this trusted information through [`props`](/workers/runtime-apis/context/#props) when you configure the custom binding during the User Worker upload.
 
-Use `this.ctx.props` inside the Platform Worker to read per-tenant values such as:
+For example, `props` could contain:
 
-- The resource connection for a specific tenant.
-- A tenant or customer ID.
-- The maximum operations allowed per minute.
-- The plan tier.
+- The underlying resource assigned to the customer.
+- A customer or tenant ID.
+- The customer's plan tier.
+- A rate limit or storage quota.
 
-### Step 3: Call from the User Worker
+The Platform Worker reads these values from `this.ctx.props`. The User Worker cannot read or modify them.
 
-The User Worker calls the standard resource API (for example, `env.DB.prepare().all()` for D1). The `binding_interface` field on the binding configuration makes the service binding present the native resource API to the User Worker.
+Using the R2 example, your Platform Worker could receive the customer's bucket, tenant ID, and storage limit through `props`. Its `put()` method could then apply that customer's limits before forwarding the upload.
 
-The User Worker does not need any code changes. It does not know the binding routes through your Platform Worker.
+### Step 3: Call the resource from the User Worker
+
+The User Worker uses the standard API for the resource. It does not call your Platform Worker directly.
+
+Using R2 as a conceptual example, the User Worker would call:
+
+```js
+await env.BUCKET.put("image.png", image);
+```
+
+The `binding_interface` configuration makes the binding expose the resource's native API. Cloudflare routes the operation to the corresponding method in your Platform Worker, where your custom logic runs.
+
+For D1, the User Worker continues to call methods such as `env.DB.prepare().bind().all()`. No changes are required to its database code.
 
 ## D1 implementation
 
-D1 custom bindings use a `query()` method on the Platform Worker. The D1 binding translates the standard D1 API calls (`prepare()`, `bind()`, `all()`) into a single `query()` RPC call that your Platform Worker receives.
+D1 custom bindings use a `query()` method in the Platform Worker. Cloudflare translates the User Worker's standard D1 calls, such as `prepare()`, `bind()`, and `all()`, into a `query()` call.
+
+Your `query()` method can inspect the statements, record usage, enforce limits, or reject the operation. If the operation is allowed, it forwards the request to the D1 database provided through `this.ctx.props`.
 
 ### Request flow
 
-1. **User Worker** — calls `env.DB.prepare().bind().all()` like a normal D1 binding.
-2. **Platform Worker** — receives the call as a single `query()` invocation. Your code inspects, logs, rate-limits, rejects, or forwards it.
-3. **D1 database** — the real database, passed to the Platform Worker through `props`.
+1. The User Worker calls `env.DB.prepare().bind().all()` as it would with a normal D1 binding.
+2. Cloudflare sends the operation to the Platform Worker's `query()` method.
+3. The Platform Worker inspects the query and applies your custom logic.
+4. The Platform Worker either returns an error or forwards the query to `this.ctx.props.D1`.
+5. The result is returned to the User Worker through the standard D1 API.
+
+If the Platform Worker rejects the operation, the User Worker receives a `D1_ERROR`.
 
 <CustomBindingsDiagram />
 
 ### Set up a D1 custom binding
 
-The steps below use placeholders like `<YOUR_ACCOUNT_ID>` and `<YOUR_DATABASE_ID>`. Replace them with your own values.
+This procedure assumes that you already have a Workers for Platforms dispatch namespace and dynamic dispatch Worker. If you do not, complete the [Workers for Platforms get started guide](/cloudflare-for-platforms/workers-for-platforms/get-started/) first.
 
 #### 1. Create the Platform Worker
 
@@ -203,7 +228,7 @@ wrangler deploy
 
 #### 2. Write the User Worker
 
-The User Worker calls `env.DB.prepare().bind().all()` as usual. Save this file as `worker.js` — the file name must match the `main_module` value you send in step 4.
+The User Worker calls `env.DB.prepare().bind().all()` as usual. Save this file as `worker.js` — the file name must match the `main_module` value used when you upload the User Worker.
 
 <Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">
 
@@ -265,15 +290,7 @@ export default {
 
 </TabItem> </Tabs>
 
-#### 3. Create a dispatch namespace
-
-User Workers are uploaded into a dispatch namespace and invoked through a [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/dynamic-dispatch/). They are not routable directly.
-
-```sh
-wrangler dispatch-namespace create custom-binding-ns
-```
-
-#### 4. Upload the User Worker with the custom binding
+#### 3. Upload the User Worker with the custom binding
 
 Configure `env.DB` as a service binding to the Platform Worker, then add two fields that turn it into a custom D1 binding:
 
@@ -286,7 +303,7 @@ Upload with the [Workers for Platforms script upload API](/api/resources/workers
 
 ```bash
 curl -X PUT \
-  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/custom-binding-ns/scripts/user-worker" \
+  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/user-worker" \
   -H "Authorization: Bearer $API_TOKEN" \
   -F 'metadata={
     "main_module": "worker.js",
@@ -321,73 +338,9 @@ The multipart field name (`worker.js`) becomes the module name and must match `m
 Only `type: "d1"` is accepted inside `$binding`. Any other binding type returns a `400`.
 :::
 
-#### 5. Deploy a dispatch Worker
-
-Create a dispatch Worker that forwards requests into the namespace:
-
-<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">
-
-```js title="src/index.js"
-export default {
-	async fetch(request, env) {
-		const userWorker = env.DISPATCHER.get("user-worker");
-		return userWorker.fetch(request);
-	},
-};
-```
-
-</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
-
-```ts title="src/index.ts"
-interface Env {
-	DISPATCHER: DispatchNamespace;
-}
-
-export default {
-	async fetch(request, env): Promise<Response> {
-		const userWorker = env.DISPATCHER.get("user-worker");
-		return userWorker.fetch(request);
-	},
-} satisfies ExportedHandler<Env>;
-```
-
-</TabItem> </Tabs>
-
-Add a Wrangler configuration for the dispatch Worker:
-
-<WranglerConfig>
-
-```toml
-name = "custom-binding-dispatcher"
-main = "src/index.js"
-compatibility_date = "$today"
-
-[[dispatch_namespaces]]
-binding = "DISPATCHER"
-namespace = "custom-binding-ns"
-```
-
-</WranglerConfig>
-
-Deploy the dispatch Worker:
-
-```sh
-wrangler deploy
-```
-
-#### 6. Test the binding
-
-Send a read and a write to the dispatch Worker URL:
-
-```bash
-# Allowed: the SELECT is forwarded to D1.
-curl "https://custom-binding-dispatcher.<YOUR_SUBDOMAIN>.workers.dev"
-
-# Rejected: the DELETE returns a D1_ERROR to the User Worker.
-curl -X DELETE "https://custom-binding-dispatcher.<YOUR_SUBDOMAIN>.workers.dev"
-```
+#### 4. Test the binding
 
-To watch interception in real time, tail the Platform Worker in another terminal:
+Send requests through your dynamic dispatch Worker. To watch interception in real time, tail the Platform Worker in another terminal:
 
 ```sh
 wrangler tail custom-binding-platform-worker