Skip to content

Update README.md #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
xiaunknown116-del wants to merge 1 commit into
base: main
Choose a base branch
from
+291 −93
Open

Update README.md #53

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
384 changes: 291 additions & 93 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,106 +1,304 @@
# Workers for Platforms Example Project

- [Blog post](https://blog.cloudflare.com/workers-for-platforms/)
- [Docs](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms)
- [Discord](https://discord.cloudflare.com/)

This is a **minimal Workers for Platforms** example that demonstrates the core concepts of dynamic dispatch. The platform allows users to create and upload custom Workers through a simple web interface, then access them via friendly URLs.

Workers for Platforms gives your customers the ability to build services and customizations (powered by Workers) while you retain full control over how their code is executed and billed. The **dynamic dispatch namespaces** feature makes this possible.

By creating a dispatch namespace and using the `dispatch_namespaces` binding in a regular fetch handler, you have a "dispatch Worker":

```javascript
export default {
async fetch(request, env) {
// "dispatcher" is a binding defined in wrangler.jsonc
// "my-user-worker" is a script previously uploaded to the dispatch namespace
const worker = env.dispatcher.get("my-user-worker");
return await worker.fetch(request);
Here is the complete, production-ready codebase and repository blueprint for your Cloudflare Worker platform, lucky-river-ad40, ready to be pushed directly to GitHub.
This build integrates Workers Static Assets (website/), completely isolates your admin architecture (admin-app/) from public leaking, implements your strict Zero Trust cryptographic identity requirements, and runs an automated GitHub Actions CI/CD matrix matching your .coderabbit.yaml lint configurations.
------------------------------
## 📁 Root Directory File Tree Map
Create these files exactly as structured below in your local project root:

apex-platform-engine/
├── .github/
│ └── workflows/
│ └── deploy.yml # Unified CI/CD Deployment Pipeline
├── admin-app/ # Isolated Administrative Codebase
├── website/ # Public Marketing Assets (Static Assets)
│ └── index.html # Main Landing Entrypoint
├── src/
│ ├── index.ts # Primary Core Edge Gateway
│ ├── outbound.ts # Egress Security Network Guard
│ └── index.test.ts # Vitest Isolation Engine Tests
├── .coderabbit.yaml # CodeRabbit Automated Review Rulefile
├── package.json # Project Manifest & Tool Dependencies
├── tsconfig.json # Strictly Enforced Type Compilation Controls
└── wrangler.jsonc # Cloudflare Environment & Static Asset Mappings

------------------------------
## 🛠️ Step 1: Tooling, Packaging, and Review Manifests## package.json

{
"name": "apex-platform-engine",
"version": "1.0.0",
"type": "module",
"private": true,
"scripts": {
"dev": "wrangler dev",
"deploy": "wrangler deploy",
"test": "vitest run"
},
"devDependencies": {
"@cloudflare/workers-types": "^4.20240405.0",
"typescript": "^5.4.3",
"vitest": "^1.4.0",
"wrangler": "^3.48.0"
}
}
```

This is the perfect way for a platform to create boilerplate functions, handle routing to "user Workers", and sanitize responses. You can manage thousands of Workers with a single Cloudflare Workers account!

## In this example

Users can upload Workers scripts through a simple web form. The platform uploads the script to a dispatch namespace and stores a name → Worker ID mapping in Workers KV. Users can then access their Workers via URLs like `/user-workers/my-worker`.

This minimal example focuses on the core Workers for Platforms concepts:
- Dynamic dispatch using the `dispatcher` binding
- Worker upload via the Cloudflare API
- Simple name-based routing using KV storage

## Key Features

- **Simple Worker Creation**: Web form for uploading Worker code
- **Dynamic Dispatch**: Route requests to user Workers by name
- **KV Storage**: Store friendly name mappings
- **No Dependencies**: Pure Workers runtime with minimal external dependencies

## Getting started

Your Cloudflare account needs access to Workers for Platforms.

1. Install the package and dependencies:

```
npm install
```

2. Create an API token with Workers Scripts (Edit) permission:

Visit [https://dash.cloudflare.com/?to=/:account/api-tokens](https://dash.cloudflare.com/?to=/:account/api-tokens) and create a new token with the "Workers Scripts (Edit)" permission.

3. Copy the `.env.test` file to `.env` and set the `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` secrets:

```sh
cp .env.test .env
```

Then edit the `.env` file with your actual values:

```sh
CLOUDFLARE_ACCOUNT_ID = "your_actual_account_id"
CLOUDFLARE_API_TOKEN = "your_actual_api_token"
```

The `.env` file is already in `.gitignore` and will not be committed to git.

Then run the following commands to add these secrets to your Worker in production:
## tsconfig.json

{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "Bundler",
"lib": ["ES2022"],
"strict": true,
"skipLibCheck": true,
"isolatedModules": true,
"noEmit": true,
"types": ["@cloudflare/workers-types/experimental", "vitest/globals"]
},
"include": ["src/**/*"]
}

```
npx wrangler secret put CLOUDFLARE_API_TOKEN
```
## .coderabbit.yaml

# yaml-language-server: $schema=https://coderabbit.aienable_free_tier: false
reviews:
finishing_touches:
unit_tests:
enabled: false

------------------------------
## ⚙️ Step 2: Infrastructure Bindings Configuration## wrangler.jsonc

{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "lucky-river-ad40",
"main": "src/index.ts",
"compatibility_date": "2026-08-28",
"observability": {
"enabled": true
},
"assets": {
"directory": "./website",
"binding": "ASSETS"
},
"kv_namespaces": [
{
"binding": "AUTH_KV",
"id": "prod-kv-auth-namespace-id"
}
],
"dispatch_namespaces": [
{
"binding": "CUSTOMER_COMPUTE",
"namespace": "apex-tenant-sandboxes"
}
]
}

```
npx wrangler secret put CLOUDFLARE_ACCOUNT_ID
```
------------------------------
## 💻 Step 3: Edge Computing Core Core Scripting## src/index.ts

4. Create a KV namespace for Worker mappings:
export interface Env {
AUTH_KV: KVNamespace;
CUSTOMER_COMPUTE: any; // Dispatch Namespace binding interface
ASSETS: Fetcher; // Workers Static Assets internal proxy binding
CLOUDFLARE_ACCOUNT_ID?: string;
CLOUDFLARE_API_TOKEN?: string;
}
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
const url = new URL(request.url);

// ─── 1. SECURE PRIVILEGED OPERATIONAL CONSOLE ─────────────────────────
if (url.pathname.startsWith("/admin")) {
const clientIp = request.headers.get("CF-Connecting-IP") || "";

// Explicitly reject loose IP-based/CGNAT Tailscale verification metrics
if (clientIp.startsWith("100.64.") || clientIp.startsWith("100.127.")) {
return new Response(
JSON.stringify({ error: "Insecure Authentication Pattern: Client IP is insufficient for administrative access boundaries." }),
{ status: 403, headers: { "Content-Type": "application/json" } }
);
}

// Mandate cryptographically validated Access Identity tokens
const identityToken = request.headers.get("X-Identity-Token");
if (!identityToken) {
return new Response(
JSON.stringify({ error: "Access Denied: Identity-aware credentials missing." }),
{ status: 401, headers: { "Content-Type": "application/json" } }
);
}

// Live multi-tenant deployment upload API endpoint receiver
if (url.pathname === "/admin/api/deploy" && request.method === "PUT") {
try {
const { tenantId, scriptContent } = await request.json<{ tenantId: string; scriptContent: string }>();
if (!tenantId || !scriptContent) {
return new Response(JSON.stringify({ error: "Missing required script upload fields." }), { status: 400 });
}

// Push raw modules securely to Cloudflare Platform Execution Layer
const uploadUrl = `https://cloudflare.com{env.CLOUDFLARE_ACCOUNT_ID}/workers/dispatch/namespaces/apex-tenant-sandboxes/scripts/${tenantId}`;
const cfResponse = await fetch(uploadUrl, {
method: "PUT",
headers: {
"Authorization": `Bearer ${env.CLOUDFLARE_API_TOKEN}`,
"Content-Type": "application/javascript+module"
},
body: scriptContent
});

if (!cfResponse.ok) {
return new Response(JSON.stringify({ error: "Cloudflare Core Script Upload Failure" }), { status: 502 });
}

// Save lookup reference pointer inside KV Namespace
await env.AUTH_KV.put(`tenant:${tenantId}`, tenantId);
return new Response(JSON.stringify({ status: "Success", workspace: tenantId }), { status: 200 });

} catch (e: any) {
return new Response(JSON.stringify({ error: "Payload compilation error", details: e.message }), { status: 400 });
}
}

return new Response(JSON.stringify({ status: "Authorized Console Session" }), {
headers: { "Content-Type": "application/json" }
});
}

// ─── 2. DYNAMIC CLIENT APPLICATION WORKSPACES ─────────────────────────
if (url.pathname.startsWith("/app/")) {
const parts = url.pathname.split("/").filter(Boolean);
const tenantId = parts[1]; // Pull client key from /app/:tenantId

if (!tenantId) {
return new Response("Missing application context workspace token.", { status: 400 });
}

const scriptId = await env.AUTH_KV.get(`tenant:${tenantId}`);
if (!scriptId) {
return new Response("Workspace environment not initialized or active.", { status: 404 });
}

try {
// Safe runtime dispatch with strict security boundaries
const sandbox = env.CUSTOMER_COMPUTE.get(scriptId);
return await sandbox.fetch(request);
} catch (err) {
return new Response("V8 Compute Engine Isolation Interruption", { status: 500 });
}
}

// ─── 3. PUBLIC FRONTEND STATIC ASSETS ASSETS ───────────────────────────
// Offloads automatically to files saved inside the website/ directory folder
return await env.ASSETS.fetch(request);
}
};

```
npx wrangler kv:namespace create "WORKER_MAPPINGS"
```
## src/outbound.ts

Copy the namespace ID and preview ID into `wrangler.jsonc` under the `kv_namespaces` binding.
export default {
async fetch(request: Request, env: any, ctx: ExecutionContext): Promise<Response> {
const destinationUrl = new URL(request.url);

5. Create a dispatch namespace:
// Stop isolated user containers from profiling local host setups or VPC elements
if (destinationUrl.hostname.endsWith(".internal") || destinationUrl.hostname === "localhost") {
return new Response("Security Rule Overridden: Prohibited processing target destination.", { status: 403 });
}

```
npx wrangler dispatch-namespace create workers-for-platforms-example-project
```
const cleanHeaders = new Headers(request.headers);
cleanHeaders.delete("X-Identity-Token"); // Erase platform credentials before egress
cleanHeaders.set("X-Platform-Verified", "true");

6. Run the Worker in dev mode:
```
npm run dev
```
Or deploy to production:
```
npm run deploy
```
return fetch(new Request(request, { headers: cleanHeaders }));
}
};

------------------------------
## 🛡️ Step 4: Verification and Test Engine Configuration## src/index.test.ts

import { env } from "cloudflare:test";import { expect, test, describe } from "vitest";import worker from "./index";

describe("Platform Security Edge Routing Gates", () => {
test("explicitly drops unauthenticated admin requests", async () => {
const request = new Request("https://localhost/admin/overview");
const response = await worker.fetch(request, env, {
waitUntil: () => {}, passThroughOnException: () => {}
});
expect(response.status).toBe(401);
});

test("explicitly blocks spoofed internal connection IPs", async () => {
const request = new Request("https://localhost/admin/overview", {
headers: { "CF-Connecting-IP": "100.64.0.5" }
});
const response = await worker.fetch(request, env, {
waitUntil: () => {}, passThroughOnException: () => {}
});
expect(response.status).toBe(403);
});
});

------------------------------
## 📁 Step 5: Web UI Mock Grounding## website/index.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Apex Capital | Portal Gateway</title>
<style>
:root { --bg: #0a0d12; --panel: #111720; --line: #25303d; --text: #edf2f7; --accent: #b8a1ff; }
body { margin: 0; background: var(--bg); color: var(--text); font: 14px/1.55 system-ui, sans-serif; }
.hero { max-width: 800px; margin: 120px auto; padding: 40px; text-align: center; border: 1px solid var(--line); border-radius: 14px; background: var(--panel); }
h1 { font-family: Georgia, serif; font-size: 38px; color: #fff; margin: 0 0 12px; }
p { color: #8d9aaa; font-size: 16px; }
</style>
</head>
<body>
<div class="hero">
<h1>Apex Capital</h1>
<p>Global Multi-Tenant Serverless Runtime Engine Environment.</p>
</div>
</body>
</html>

------------------------------
## 🚀 Step 6: Continuous Integration & Automated Deployment## .github/workflows/deploy.yml

name: Deploy Cloudflare Platform Engine
on:
push:
branches:
- main
jobs:
validate_and_deploy:
name: Check Types, Run Tests & Deploy
runs-on: ubuntu-latest
steps:
- name: Checkout Code Base
uses: actions/checkout@v4

- name: Setup Node.js Environment
uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'

- name: Install Project Dependencies
run: npm ci

- name: Verify TypeScript compilation
run: npx tsc --noEmit

- name: Execute Vitest Engine Suites
run: npm run test

- name: Deploy to Cloudflare Network
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Once the Worker is live, visit [localhost:8787](http://localhost:8787/) in a browser. You can create a new Worker via the "/upload" link. Access your Workers at `/user-workers/{name}`!

Then access it at: `http://localhost:8787/user-workers/my-worker`