cloudflare-workers-runtime-apis

# Cloudflare Workers Runtime APIs

Master the Workers runtime APIs: Fetch, Streams, Crypto, Cache, WebSockets, and text encoding.

## Quick Reference

| API | Purpose | Common Use |
|-----|---------|------------|
| **Fetch** | HTTP requests | External APIs, proxying |
| **Streams** | Data streaming | Large files, real-time |
| **Crypto** | Cryptography | Hashing, signing, encryption |
| **Cache** | Response caching | Performance optimization |
| **WebSockets** | Real-time connections | Chat, live updates |
| **Encoding** | Text encoding | UTF-8, Base64 |

## Quick Start: Fetch API

```typescript
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Basic fetch
    const response = await fetch('https://api.example.com/data');

    // With options
    const postResponse = await fetch('https://api.example.com/users', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${env.API_KEY}`,
      },
      body: JSON.stringify({ name: 'John' }),
    });

    // Clone for multiple reads
    const clone = response.clone();
    const json = await response.json();
    const text = await clone.text();

    return Response.json(json);
  }
};
```

## Critical Rules

1. **Always set timeouts for external requests** - Workers have a 30s limit, external APIs can hang
2. **Clone responses before reading body** - Body can only be read once
3. **Use streaming for large payloads** - Don't buffer entire response in memory
4. **Cache external API responses** - Reduce latency and API costs
5. **Handle Crypto operations in try/catch** - Invalid inputs throw errors
6. **WebSocket hibernation for cost** - Use Durable Objects with hibernation

## Top 10 Errors Prevented

| Error | Symptom | Prevention |
|-------|---------|------------|
| Body already read | `TypeError: Body has already been consumed` | Clone response before reading |
| Fetch timeout | Request hangs, worker times out | Use `AbortController` with timeout |
| Invalid JSON | `SyntaxError: Unexpected token` | Check content-type before parsing |
| Stream locked | `TypeError: ReadableStream is locked` | Don't read stream multiple times |
| Crypto key error | `DOMException: Invalid keyData` | Validate key format and algorithm |
| Cache miss | Returns `undefined` instead of response | Check cache before returning |
| WebSocket close | Connection drops unexpectedly | Handle close event, implement reconnect |
| Encoding error | `TypeError: Invalid code point` | Use TextEncoder/TextDecoder properly |
| CORS blocked | Browser rejects response | Add proper CORS headers |
| Request size | `413 Request Entity Too Large` | Stream large uploads |

## Fetch API Patterns

### With Timeout

```typescript
async function fetchWithTimeout(url: string, timeout: number = 5000): Promise<Response> {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeout);

  try {
    const response = await fetch(url, { signal: controller.signal });
    return response;
  } finally {
    clearTimeout(timeoutId);
  }
}
```

### With Retry

```typescript
async function fetchWithRetry(
  url: string,
  options: RequestInit = {},
  retries: number = 3
): Promise<Response> {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) return response;

      // Retry on 5xx errors
      if (response.status >= 500 && i < retries - 1) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
        continue;
      }

      return response;
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
    }
  }
  throw new Error('Max retries exceeded');
}
```

## Streams API

### Transform Stream

```typescript
function createUppercaseStream(): TransformStream<string, string> {
  return new TransformStream({
    transform(chunk, controller) {
      controller.enqueue(chunk.toUpperCase());
    }
  });
}

// Usage
const response = await fetch('https://example.com/text');
const transformed = response.body!
  .pipeThrough(new TextDecoderStream())
  .pipeThrough(createUppercaseStream())
  .pipeThrough(new TextEncoderStream());

return new Response(transformed);
```

### Stream Large Response

```typescript
async function streamLargeFile(url: string): Promise<Response> {
  const response = await fetch(url);

  // Stream directly without buffering
  return new Response(response.body, {
    headers: {
      'Content-Type': response.headers.get('Content-Type') || 'application/octet-stream',
    },
  });
}
```

## Crypto API

### Hashing

```typescript
async function sha256(data: string): Promise<string> {
  const encoder = new TextEncoder();
  const dataBuffer = encoder.encode(data);
  const hashBuffer = await crypto.subtle.digest('SHA-256', dataBuffer);
  const hashArray = Array.from(new Uint8Array(hashBuffer));
  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
}
```

### HMAC Signing

```typescript
async function signHMAC(key: string, data: string): Promise<string> {
  const encoder = new TextEncoder();
  const keyData = encoder.encode(key);
  const dataBuffer = encoder.encode(data);

  const cryptoKey = await crypto.subtle.importKey(
    'raw',
    keyData,
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );

  const signature = await crypto.subtle.sign('HMAC', cryptoKey, dataBuffer);
  return btoa(String.fromCharCode(...new Uint8Array(signature)));
}
```

## Cache API

```typescript
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const cache = caches.default;
    const cacheKey = new Request(request.url, { method: 'GET' });

    // Check cache
    let response = await cache.match(cacheKey);
    if (response) {
      return response;
    }

    // Fetch and cache
    response = await fetch(request);
    response = new Res