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 ReferenceCopy Anchor Link

POST /scriptsCopy Anchor Link

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 RequestCopy Anchor Link

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

GET /scriptsCopy Anchor Link

name string (required)

Returns { name, updatedAt, hasResponse }.

Example RequestCopy Anchor Link

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

POST /dispatch/:nameCopy Anchor Link

• 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 RequestCopy Anchor Link

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

POST /registerCopy Anchor Link

Record a customer name in KV for listing.

name string (required)

Example RequestCopy Anchor Link

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

GET /customersCopy Anchor Link

Returns { customers: string[] }.

Example RequestCopy Anchor Link

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

Error CodesCopy Anchor Link

• 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 CasesCopy Anchor Link

• 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

LimitationsCopy Anchor Link

• 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

DeploymentCopy Anchor Link

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"

Local DevelopmentCopy Anchor Link

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

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"

ConfigurationCopy Anchor Link

wrangler.json declares:

• KV namespace SCRIPTS
• Dispatch namespace DISPATCHER → demo-customers

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• Workers KV - Script metadata and KV fallback responses
• Workers for Platforms - Optional dispatch_namespaces binding