Cloudflare Platform Products

What this skill does

# Cloudflare Platform Products

## Purpose

This skill provides guidance on Cloudflare's platform products and services that integrate with Workers. It covers storage options (KV, R2, D1), coordination services (Durable Objects, Queues), data services (Vectorize, Hyperdrive), and specialized services (Analytics Engine, Browser Rendering). Use this skill when choosing between platform products, designing system architecture, or integrating multiple Cloudflare services.

## Platform Products Overview

Cloudflare offers a comprehensive suite of platform products designed to work seamlessly with Workers:

| Product | Category | Use Case | Key Features |
|---------|----------|----------|--------------|
| **KV** | Storage | Key-value cache, static content | Eventually consistent, global, 25MB values |
| **D1** | Database | Relational data, SQL queries | SQLite, transactions, migrations |
| **R2** | Storage | Large files, object storage | S3-compatible, unlimited size, no egress fees |
| **Durable Objects** | Coordination | Stateful services, real-time | Strong consistency, WebSockets, single-threaded |
| **Queues** | Messaging | Async processing, event-driven | At-least-once delivery, batching |
| **Vectorize** | Data | Semantic search, embeddings | Vector similarity, RAG support |
| **Hyperdrive** | Database | Postgres connection pooling | Reduced latency, connection management |
| **Analytics Engine** | Analytics | Custom metrics, time-series | High-cardinality data, SQL queries |
| **Workers AI** | AI/ML | Inference, embeddings | Text generation, vision, audio |

See `references/platform-products-matrix.md` for detailed comparison and selection guide.

## Storage Services

### KV (Key-Value Storage)

**Best for**: Static content, configuration, caching, read-heavy workloads

**Characteristics**:
- Eventually consistent (writes propagate in ~60 seconds globally)
- Optimized for reads (not writes)
- 25 MB max value size
- Global replication included
- Metadata support

**When to use**:
- Caching API responses
- Storing static assets
- Configuration data
- Session data (with expiration)
- Read-heavy data with infrequent writes

**When NOT to use**:
- Frequently changing data
- Strong consistency requirements
- Large objects (> 25 MB)
- Complex queries

**Example use cases**:
```javascript
// Cache API responses
await env.CACHE.put(`api:users:${id}`, JSON.stringify(user), {
  expirationTtl: 3600
});

// Store configuration
await env.CONFIG.put('feature_flags', JSON.stringify(flags));

// Session storage
await env.SESSIONS.put(sessionId, userData, {
  expirationTtl: 86400 // 24 hours
});
```

### D1 (SQLite Database)

**Best for**: Relational data, complex queries, transactional workloads

**Characteristics**:
- SQLite database
- Strong consistency
- ACID transactions
- SQL query support
- Migrations support
- 25 MB database size (beta limit)

**When to use**:
- Structured relational data
- Complex queries with JOINs
- Transactional operations
- Data with relationships
- Migrations-driven schema

**When NOT to use**:
- Large datasets (> 25 MB in beta)
- Very high write throughput
- Unstructured data
- Simple key-value lookups (use KV instead)

**Example use cases**:
```javascript
// User management
await env.DB.prepare(
  'SELECT * FROM users WHERE email = ? AND active = 1'
).bind(email).first();

// Transactions (via batch)
await env.DB.batch([
  env.DB.prepare('INSERT INTO orders (user_id, total) VALUES (?, ?)').bind(userId, total),
  env.DB.prepare('UPDATE users SET last_order = ? WHERE id = ?').bind(Date.now(), userId)
]);

// Complex queries
await env.DB.prepare(`
  SELECT orders.*, users.email
  FROM orders
  JOIN users ON orders.user_id = users.id
  WHERE orders.status = ?
`).bind('pending').all();
```

### R2 (Object Storage)

**Best for**: Large files, user uploads, backups, media storage

**Characteristics**:
- S3-compatible API
- No size limits per object
- Zero egress fees (from Workers)
- Custom metadata
- Streaming support

**When to use**:
- Large files (> 25 MB)
- User-uploaded content
- Media files (images, videos)
- Backups and archives
- Static website hosting

**When NOT to use**:
- Small values (< 1 KB, use KV)
- Frequently updated small data
- Requires low-latency for small reads (KV is faster)

**Example use cases**:
```javascript
// Store user upload
await env.UPLOADS.put(`users/${userId}/avatar.jpg`, imageData, {
  httpMetadata: {
    contentType: 'image/jpeg'
  },
  customMetadata: {
    uploadedBy: userId,
    uploadedAt: Date.now().toString()
  }
});

// Stream large file
const object = await env.MEDIA.get('videos/large-video.mp4');
return new Response(object.body);

// Store backup
await env.BACKUPS.put(`db-backup-${Date.now()}.sql`, backupData);
```

See `references/storage-options-guide.md` for detailed storage selection criteria.

## Coordination Services

### Durable Objects

**Best for**: Coordination, real-time collaboration, WebSockets, rate limiting

**Characteristics**:
- Strong consistency
- Stateful instances
- Single-threaded execution per object
- Persistent storage
- WebSocket support
- Global coordination

**When to use**:
- Real-time collaboration (chat, docs)
- Rate limiting and quotas
- Coordination between distributed requests
- Persistent WebSocket connections
- Stateful game servers
- Sequential processing requirements

**When NOT to use**:
- Simple stateless operations
- Read-heavy workloads (use KV)
- Pure data storage (use D1/R2)
- High-throughput parallel processing

**Example use cases**:
```javascript
// Rate limiting
export class RateLimiter {
  constructor(state, env) {
    this.state = state;
  }

  async fetch(request) {
    const count = await this.state.storage.get('count') || 0;
    const limit = 100;

    if (count >= limit) {
      return new Response('Rate limit exceeded', { status: 429 });
    }

    await this.state.storage.put('count', count + 1);
    return new Response('OK');
  }
}

// Chat room coordination
export class ChatRoom {
  constructor(state, env) {
    this.state = state;
    this.sessions = [];
  }

  async fetch(request) {
    const pair = new WebSocketPair();
    this.sessions.push(pair[1]);

    pair[1].accept();
    pair[1].addEventListener('message', event => {
      // Broadcast to all sessions
      this.sessions.forEach(session => {
        session.send(event.data);
      });
    });

    return new Response(null, { status: 101, webSocket: pair[0] });
  }
}
```

### Queues

**Best for**: Asynchronous processing, background jobs, event-driven workflows

**Characteristics**:
- At-least-once delivery
- Message batching
- Dead letter queues
- Automatic retries
- Guaranteed ordering per message

**When to use**:
- Background processing
- Webhook handling
- Email sending
- Data pipeline stages
- Decoupling services
- Batch processing

**When NOT to use**:
- Synchronous request-response
- Exactly-once delivery required (handle idempotency in consumer)
- Real-time requirements (use Durable Objects + WebSockets)

**Example use cases**:
```javascript
// Producer: Queue email sending
await env.EMAIL_QUEUE.send({
  to: user.email,
  subject: 'Welcome',
  body: 'Welcome to our service!'
});

// Consumer: Process emails in batches
export default {
  async queue(batch, env) {
    for (const message of batch.messages) {
      const { to, subject, body } = message.body;

      try {
        await sendEmail(to, subject, body, env);
        message.ack();
      } catch (error) {
        console.error('Email failed:', error);
        message.retry();
      }
    }
  }
};
```

## Data Services

### Vectorize

**Best for**: Semantic search, RAG, recommendations, similarity matching

**Characteristics**:
- Vector similarity search
- Configurable dimensions (matching embedding model)
- Metadata storage
- Batch operations
- Cosine/Euclidean/Dot product metrics

**When to use**:
- Semantic search
- RAG (Retrieval Augmented Generation)
- Recommendation systems
- Image similarity
- Duplicate d