secondsky/claude-skills / plugins/cloudflare-workers/skills/cloudflare-workers-runtime-apis
cloudflare-workers-runtime-apis
VerifiedCloudflare Workers Runtime APIs including Fetch, Streams, Crypto, Cache, WebSockets, and Encoding. Use for HTTP requests, streaming, encryption, caching, real-time connections, or encountering API compatibility, response handling, stream processing errors.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.0 KB |
| references/cache-api.md | markdown | 6.9 KB |
| references/crypto-api.md | markdown | 8.7 KB |
| references/encoding-api.md | markdown | 7.4 KB |
| references/fetch-api.md | markdown | 8.5 KB |
| references/streams-api.md | markdown | 8.9 KB |
| references/websockets.md | markdown | 8.7 KB |
| templates/crypto-operations.ts | script | 9.7 KB |
| templates/fetch-patterns.ts | script | 8.6 KB |
| templates/stream-processing.ts | script | 8.8 KB |
| templates/websocket-handler.ts | script | 8.6 KB |
templates/websocket-handler.ts
View on GitHub/**
* WebSocket Handler with Durable Objects
*
* Features:
* - WebSocket connections with hibernation
* - Room-based messaging
* - User presence tracking
* - Message persistence
* - Rate limiting
*
* Usage:
* 1. Copy to src/room.ts (Durable Object)
* 2. Configure wrangler.jsonc durable_objects binding
* 3. Create entry worker that routes to rooms
*/
// ============================================
// TYPES
// ============================================
interface UserInfo {
id: string;
name: string;
joinedAt: number;
lastSeen: number;
}
interface ChatMessage {
type: 'chat';
from: UserInfo;
content: string;
timestamp: number;
}
interface SystemMessage {
type: 'system';
event: 'user_joined' | 'user_left' | 'error';
user?: UserInfo;
message?: string;
timestamp: number;
}
interface PresenceMessage {
type: 'presence';
users: UserInfo[];
timestamp: number;
}
type ServerMessage = ChatMessage | SystemMessage | PresenceMessage;
interface ClientMessage {
type: 'chat' | 'typing' | 'ping';
content?: string;
}
interface Env {
ROOMS: DurableObjectNamespace;
}
// ============================================
// DURABLE OBJECT: CHAT ROOM
// ============================================
export class ChatRoom {
private state: DurableObjectState;
private storage: DurableObjectStorage;
private messageHistory: ChatMessage[] = [];
private rateLimits: Map<string, number[]> = new Map();
constructor(state: DurableObjectState) {
this.state = state;
this.storage = state.storage;
// Load message history on wake
state.blockConcurrencyWhile(async () => {
const stored = await this.storage.get<ChatMessage[]>('messages');
if (stored) {
this.messageHistory = stored.slice(-100); // Keep last 100
}
});
}
async fetch(request: Request): Promise<Response> {
const url = new URL(request.url);
const upgradeHeader = request.headers.get('Upgrade');
// Handle non-WebSocket requests
if (upgradeHeader !== 'websocket') {
// API endpoints
if (url.pathname === '/history') {
return Response.json(this.messageHistory);
}
if (url.pathname === '/users') {
return Response.json(this.getUsers());
}
return new Response('Expected websocket upgrade', { status: 426 });
}
// Get user info from query params
const userId = url.searchParams.get('userId') || crypto.randomUUID();
const userName = url.searchParams.get('name') || 'Anonymous';
// Create WebSocket pair
const pair = new WebSocketPair();
const [client, server] = Object.values(pair);
// Attach user info
const userInfo: UserInfo = {
id: userId,
name: userName,
joinedAt: Date.now(),
lastSeen: Date.now(),
};
// Accept with hibernation
this.state.acceptWebSocket(server, [userId]);
server.serializeAttachment(userInfo);
// Send welcome message with history
server.send(
JSON.stringify({
type: 'welcome',
userId,
history: this.messageHistory.slice(-50),
users: this.getUsers(),
})
);
// Notify others
this.broadcast({
type: 'system',
event: 'user_joined',
user: userInfo,
timestamp: Date.now(),
}, server);
return new Response(null, { status: 101, webSocket: client });
}
async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
const userInfo = ws.deserializeAttachment() as UserInfo;
userInfo.lastSeen = Date.now();
ws.serializeAttachment(userInfo);
// Rate limiting
if (!this.checkRateLimit(userInfo.id)) {
ws.send(JSON.stringify({
type: 'system',
event: 'error',
message: 'Rate limit exceeded. Please slow down.',
timestamp: Date.now(),
}));
return;
}
try {
const data = JSON.parse(
typeof message === 'string' ? message : new TextDecoder().decode(message)
) as ClientMessage;
switch (data.type) {
case 'chat':
await this.handleChat(ws, userInfo, data.content || '');
break;
case 'typing':
this.handleTyping(ws, userInfo);
break;
case 'ping':
ws.send(JSON.stringify({ type: 'pong', timestamp: Date.now() }));
break;
}
} catch {
ws.send(JSON.stringify({
type: 'system',
event: 'error',
message: 'Invalid message format',
timestamp: Date.now(),
}));
}
}
async webSocketClose(
ws: WebSocket,
code: number,
reason: string,
wasClean: boolean
): Promise<void> {
const userInfo = ws.deserializeAttachment() as UserInfo;
// Notify others
this.broadcast({
type: 'system',
event: 'user_left',
user: userInfo,
timestamp: Date.now(),
});
ws.close(code, reason);
}
async webSocketError(ws: WebSocket, error: unknown): Promise<void> {
console.error('WebSocket error:', error);
ws.close(1011, 'Internal error');
}
// ============================================
// MESSAGE HANDLING
// ============================================
private async handleChat(
ws: WebSocket,
user: UserInfo,
content: string
): Promise<void> {
// Validate
const sanitized = content.trim().slice(0, 1000);
if (!sanitized) return;
const message: ChatMessage = {
type: 'chat',
from: user,
content: sanitized,
timestamp: Date.now(),
};
// Store
this.messageHistory.push(message);
if (this.messageHistory.length > 100) {
this.messageHistory = this.messageHistory.slice(-100);
}
await this.storage.put('messages', this.messageHistory);
// Broadcast to all including sender
this.broadcast(message);
}
private handleTyping(ws: WebSocket, user: UserInfo): void {
// Broadcast typing indicator to others
this.broadcast(
{
type: 'typing',
userId: user.id,
userName: user.name,
timestamp: Date.now(),
} as unknown as ServerMessage,
ws
);
}
// ============================================
// UTILITIES
// ============================================
private broadcast(message: ServerMessage, exclude?: WebSocket): void {
const json = JSON.stringify(message);
for (const socket of this.state.getWebSockets()) {
if (socket !== exclude) {
socket.send(json);
}
}
}
private getUsers(): UserInfo[] {
return this.state.getWebSockets().map((ws) => {
return ws.deserializeAttachment() as UserInfo;
});
}
private checkRateLimit(userId: string): boolean {
const now = Date.now();
const window = 10000; // 10 seconds
const maxMessages = 20; // 20 messages per window
let timestamps = this.rateLimits.get(userId) || [];
timestamps = timestamps.filter((t) => now - t < window);
if (timestamps.length >= maxMessages) {
return false;
}
timestamps.push(now);
this.rateLimits.set(userId, timestamps);
return true;
}
}
// ============================================
// WORKER ENTRY POINT
// ============================================
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
// Parse room name from path: /room/<name>
const match = url.pathname.match(/^\/room\/([^/]+)/);
if (!match) {
return new Response('Room not found. Use /room/<name>', { status: 404 });
}
const roomName = match[1];
// Get or create room
const roomId = env.ROOMS.idFromName(roomName);
const room = env.ROOMS.get(roomId);
// Forward request to room
return room.fetch(request);
},
};
// ============================================
// WRANGLER CONFIGURATION
// ============================================
/*
// wrangler.jsonc
{
"name": "chat-worker",
"main": "src/index.ts",
"compatibility_date": "2024-01-01",
"durable_objects": {
"bindings": [
{
"name": "ROOMS",
"class_name": "ChatRoom"
}
]
},
"migrations": [
{
"tag": "v1",
"new_classes": ["ChatRoom"]
}
]
}
*/
// ============================================
// CLIENT USAGE
// ============================================
/*
// Browser client
const ws = new WebSocket(
'wss://my-chat.workers.dev/room/general?userId=123&name=John'
);
ws.onmessage = (event) => {
const message = JSON.parse(event.data);
console.log('Received:', message);
};
ws.onopen = () => {
// Send a chat message
ws.send(JSON.stringify({ type: 'chat', content: 'Hello everyone!' }));
};
ws.onclose = () => {
// Reconnect logic
setTimeout(() => reconnect(), 1000);
};
*/
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |