/cloudflare-workers-runtime-apis

name: cloudflare-workers-runtime-apis
description: Cloudflare 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.
license: MIT

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

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

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

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

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

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

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

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

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionC