# User Script Dispatcher (/docs/experiments/user-script-dispatcher)



Workers for Platforms style **dispatch** - register customers and run tenant response handlers via a `DispatchNamespace` binding, with a KV fallback for local demos. Stored scripts return a fixed JSON response (safe demo - no dynamic JS eval).

## API Reference [#api-reference]

### POST /scripts [#post-scripts]

Store a JSON response handler.

**`name`** `string` (required)

Tenant/script name (`a-zA-Z0-9_-`).

**`response`** `object` (required)

JSON object returned on KV dispatch. Max serialized size: 10,000 bytes.

#### Example Request [#example-request]

```bash
curl -X POST "https://your-worker.workers.dev/scripts" \
  -H "Content-Type: application/json" \
  -d '{"name":"tenant-a","response":{"hello":"world"}}'
```

### GET /scripts [#get-scripts]

**`name`** `string` (required)

Returns `{ name, updatedAt, hasResponse }`.

#### Example Request [#example-request-1]

```bash
curl "https://your-worker.workers.dev/scripts?name=tenant-a"
```

### POST /dispatch/:name [#post-dispatchname]

* If `DISPATCHER` is bound: forwards the request to `env.DISPATCHER.get(name).fetch(request)`.
* If `DISPATCHER.get` throws: `{ error, code: "DISPATCH_ERROR" }` (502).
* Without `DISPATCHER` (or when using the KV path): returns the stored KV `response` object.

#### Example Request [#example-request-2]

```bash
curl -X POST "https://your-worker.workers.dev/dispatch/tenant-a"
```

### POST /register [#post-register]

Record a customer name in KV for listing.

**`name`** `string` (required)

#### Example Request [#example-request-3]

```bash
curl -X POST "https://your-worker.workers.dev/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"tenant-a"}'
```

### GET /customers [#get-customers]

Returns `{ customers: string[] }`.

#### Example Request [#example-request-4]

```bash
curl "https://your-worker.workers.dev/customers"
```

#### Error Codes [#error-codes]

* `400` - Invalid name, response, body, or oversized script (`INVALID_NAME`, `INVALID_RESPONSE`, `INVALID_BODY`, `SCRIPT_TOO_LARGE`)
* `404` - Script not found (`NOT_FOUND`)
* `502` - Dispatch namespace failure (`DISPATCH_ERROR`)

## Use Cases [#use-cases]

* Learn Workers for Platforms dispatch namespace patterns
* Prototype multi-tenant routing with a KV fallback
* Register and list customers before wiring real scripts
* Teach safe demos that avoid eval while showing dispatch shape

## Limitations [#limitations]

* KV path returns a stored JSON object - no dynamic JS execution
* Dispatch namespace (`demo-customers`) may require Workers for Platforms
* Script payload capped at 10,000 bytes
* No authentication on register/dispatch endpoints

## Deployment [#deployment]

<Steps>
  <Step>
    ### Click the deploy button [#click-the-deploy-button]

    [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/shrinathsnayak/cloudflare-experiments/tree/main/apps/experiments/user-script-dispatcher)
  </Step>

  <Step>
    ### Configure KV and dispatch namespace [#configure-kv-and-dispatch-namespace]

    Create a KV namespace bound as `SCRIPTS`. For production dispatch, create a dispatch namespace matching `demo-customers` in `wrangler.json`. Local/KV fallback works without the paid feature.
  </Step>

  <Step>
    ### Test your deployment [#test-your-deployment]

    ```bash
    curl -X POST "https://your-worker.workers.dev/scripts" \
      -H "Content-Type: application/json" \
      -d '{"name":"tenant-a","response":{"hello":"world"}}'
    curl -X POST "https://your-worker.workers.dev/dispatch/tenant-a"
    ```
  </Step>
</Steps>

## Local Development [#local-development]

```bash
cd apps/experiments/user-script-dispatcher
npm install
npm run dev
```

```bash
curl -X POST "http://localhost:8787/scripts" \
  -H "Content-Type: application/json" \
  -d '{"name":"tenant-a","response":{"hello":"world"}}'
curl -X POST "http://localhost:8787/dispatch/tenant-a"
```

## Configuration [#configuration]

`wrangler.json` declares:

* **KV namespace** `SCRIPTS`
* **Dispatch namespace** `DISPATCHER` → `demo-customers`

## Cloudflare Features Used [#cloudflare-features-used]

* **[Workers](https://developers.cloudflare.com/workers/)** - Edge compute runtime
* **[Workers KV](https://developers.cloudflare.com/kv/)** - Script metadata and KV fallback responses
* **[Workers for Platforms](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/)** - Optional `dispatch_namespaces` binding