secondsky/claude-skills / plugins/cloudflare-r2/skills/cloudflare-r2
cloudflare-r2
VerifiedCloudflare R2 S3-compatible object storage. Use for buckets, uploads, CORS, presigned URLs, or encountering R2_ERROR, CORS failures, multipart issues.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.8 KB |
| references/advanced-features.md | markdown | 14.4 KB |
| references/cloudflare-access-integration.md | markdown | 14.5 KB |
| references/common-patterns.md | markdown | 12.8 KB |
| references/cors-configuration.md | markdown | 2.7 KB |
| references/data-catalog-iceberg.md | markdown | 15.1 KB |
| references/event-notifications.md | markdown | 15.8 KB |
| references/performance-optimization.md | markdown | 15.8 KB |
| references/r2-sql-integration.md | markdown | 14.5 KB |
| references/s3-compatibility.md | markdown | 7.7 KB |
| references/setup-guide.md | markdown | 8.5 KB |
| references/workers-api.md | markdown | 9.7 KB |
| templates/r2-cors-config.json | config | 3.3 KB |
| templates/r2-multipart-upload.ts | script | 5.7 KB |
| templates/r2-presigned-urls.ts | script | 7.2 KB |
| templates/r2-simple-upload.ts | script | 5.1 KB |
| templates/wrangler-r2-config.jsonc | other | 1.1 KB |
references/event-notifications.md
View on GitHub# R2 Event Notifications
**Last Updated**: 2025-12-27
Configure Workers to automatically respond to R2 object changes (uploads, deletions) using event notifications and Cloudflare Queues integration.
---
## Overview
R2 event notifications enable event-driven workflows by automatically triggering Workers when objects are created, updated, or deleted in R2 buckets. Events are delivered through Cloudflare Queues for reliable, asynchronous processing.
**Common Use Cases**:
- Resize images on upload
- Generate thumbnails automatically
- Update database indexes when files are added
- Backup files to secondary storage on upload
- Clean up related resources when files are deleted
- Trigger webhooks for external systems
- Analytics and audit logging
---
## Event Subscription Setup
### 1. Create Queue for Events
```bash
# Create queue to receive R2 events
bunx wrangler queues create r2-events
```
### 2. Configure Event Notifications
**Option A: Wrangler Configuration**
Add to `wrangler.jsonc`:
```jsonc
{
"name": "r2-event-handler",
"main": "src/index.ts",
"compatibility_date": "2025-10-11",
// R2 bucket binding
"r2_buckets": [
{
"binding": "MY_BUCKET",
"bucket_name": "my-bucket",
// Configure event notifications
"event_notification_rules": [
{
"queue": "r2-events",
"rules": [
{
"prefix": "images/", // Only images folder
"suffix": ".jpg" // Only JPG files
}
]
}
]
}
],
// Queue consumer binding
"queues": {
"consumers": [
{
"queue": "r2-events",
"max_batch_size": 10,
"max_batch_timeout": 5,
"max_retries": 3,
"dead_letter_queue": "r2-events-dlq"
}
]
}
}
```
**Option B: Dashboard Configuration**
1. Navigate to R2 → Select bucket
2. Click "Settings" tab
3. Scroll to "Event Notifications"
4. Click "Create notification rule"
5. Configure:
- **Queue name**: Select your queue
- **Event types**: object-create, object-delete
- **Prefix filter**: Optional path prefix (e.g., "uploads/")
- **Suffix filter**: Optional file extension (e.g., ".png")
---
## Event Payload Structure
### Object Created Event
```typescript
interface R2ObjectCreatedEvent {
account: string; // Cloudflare account ID
action: 'PutObject'; // Event type
bucket: string; // Bucket name
object: {
key: string; // Object key
size: number; // File size in bytes
eTag: string; // Object ETag
};
eventTime: string; // ISO 8601 timestamp
}
```
### Object Deleted Event
```typescript
interface R2ObjectDeletedEvent {
account: string;
action: 'DeleteObject';
bucket: string;
object: {
key: string; // Deleted object key
};
eventTime: string;
}
```
---
## Event Handler Worker
### Basic Event Handler
```typescript
import { Hono } from 'hono';
type Bindings = {
MY_BUCKET: R2Bucket;
};
interface Env extends Bindings {
// Queue will be automatically available
}
export default {
async queue(batch: MessageBatch<R2Event>, env: Env): Promise<void> {
for (const message of batch.messages) {
const event = message.body;
try {
await handleR2Event(event, env);
message.ack(); // Acknowledge successful processing
} catch (error) {
console.error('Failed to process event:', error);
message.retry(); // Retry on failure
}
}
}
};
async function handleR2Event(event: R2Event, env: Env) {
console.log(`Event: ${event.action} on ${event.object.key}`);
if (event.action === 'PutObject') {
await handleObjectCreated(event, env);
} else if (event.action === 'DeleteObject') {
await handleObjectDeleted(event, env);
}
}
async function handleObjectCreated(event: R2ObjectCreatedEvent, env: Env) {
const key = event.object.key;
// Example: Process only images
if (key.startsWith('images/') && key.match(/\.(jpg|png|webp)$/)) {
console.log(`New image uploaded: ${key} (${event.object.size} bytes)`);
// Trigger image processing (resize, thumbnail generation, etc.)
await processImage(key, env);
}
}
async function handleObjectDeleted(event: R2ObjectDeletedEvent, env: Env) {
const key = event.object.key;
console.log(`Object deleted: ${key}`);
// Clean up related resources
await cleanupRelatedResources(key, env);
}
type R2Event = R2ObjectCreatedEvent | R2ObjectDeletedEvent;
```
---
## Common Patterns
### Pattern 1: Image Resize on Upload
```typescript
async function processImage(key: string, env: Env) {
// Get original image
const original = await env.MY_BUCKET.get(key);
if (!original) {
console.error(`Object not found: ${key}`);
return;
}
const imageData = await original.arrayBuffer();
// Resize image (using Cloudflare Images or external service)
const resized = await resizeImage(imageData, { width: 800, height: 600 });
// Store resized version
const resizedKey = key.replace('images/', 'images/resized/');
await env.MY_BUCKET.put(resizedKey, resized, {
httpMetadata: {
contentType: original.httpMetadata?.contentType || 'image/jpeg',
cacheControl: 'public, max-age=31536000, immutable',
},
customMetadata: {
originalKey: key,
processedAt: new Date().toISOString(),
},
});
console.log(`Resized image stored: ${resizedKey}`);
}
async function resizeImage(data: ArrayBuffer, options: { width: number; height: number }): Promise<ArrayBuffer> {
// Use Cloudflare Images API, sharp, or external image service
// Placeholder implementation
return data;
}
```
### Pattern 2: Thumbnail Generation
```typescript
async function generateThumbnails(key: string, env: Env) {
const original = await env.MY_BUCKET.get(key);
if (!original) return;
const imageData = await original.arrayBuffer();
// Generate multiple thumbnail sizes
const sizes = [
{ name: 'small', width: 150, height: 150 },
{ name: 'medium', width: 300, height: 300 },
{ name: 'large', width: 600, height: 600 },
];
for (const size of sizes) {
const thumbnail = await resizeImage(imageData, size);
const thumbnailKey = `thumbnails/${size.name}/${key}`;
await env.MY_BUCKET.put(thumbnailKey, thumbnail, {
httpMetadata: {
contentType: 'image/jpeg',
cacheControl: 'public, max-age=31536000, immutable',
},
customMetadata: {
size: size.name,
originalKey: key,
},
});
}
console.log(`Thumbnails generated for: ${key}`);
}
```
### Pattern 3: Database Index Update
```typescript
async function updateDatabaseIndex(event: R2ObjectCreatedEvent, env: Env) {
// Update database with new file metadata
await env.DB.prepare(
`INSERT INTO files (key, size, uploaded_at, etag)
VALUES (?, ?, ?, ?)`
)
.bind(
event.object.key,
event.object.size,
event.eventTime,
event.object.eTag
)
.run();
console.log(`Database updated for: ${event.object.key}`);
}
async function cleanupDatabaseIndex(event: R2ObjectDeletedEvent, env: Env) {
// Remove file from database
await env.DB.prepare(`DELETE FROM files WHERE key = ?`)
.bind(event.object.key)
.run();
console.log(`Database cleaned up for: ${event.object.key}`);
}
```
### Pattern 4: Backup to Secondary Storage
```typescript
async function backupToSecondary(key: string, env: Env) {
const object = await env.MY_BUCKET.get(key);
if (!object) return;
const data = await object.arrayBuffer();
// Store in backup bucket
await env.BACKUP_BUCKET.put(key, data, {
httpMetadata: object.httpMetadata,
customMetadata: {
...object.customMetadata,
backedUpAt: new Date().toISOString(),
originalBucket: env.MY_BUCKET.name,
},
});
console.log(`Backed up to secondary: ${key}`);
}
```
### Pattern 5: Webhook Notification
```typescript
async function sendWebhook(event: R2Event, env: Env) {
const webhookUrl = env.WEBHOOK_URL;
await fetch(webhookUrl, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Event-Type': event.action,
},
body: JSON.stringify({
action: event.action,
bucket: event.bucket,
object: event.object,
timestamp: event.eventTime,
}),
});
console.log(`Webhook sent for: ${event.object.key}`);
}
```
---
## Error Handling and Retries
### Retry Logic with Exponential Backoff
```typescript
async function handleEventWithRetry(event: R2Event, env: Env, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
await handleR2Event(event, env);
return; // Success
} catch (error) {
const isLastAttempt = attempt === maxRetries - 1;
if (isLastAttempt) {
console.error(`Failed after ${maxRetries} attempts:`, error);
throw error; // Will go to dead letter queue
}
// Exponential backoff: 1s, 2s, 4s
const delay = Math.min(1000 * Math.pow(2, attempt), 5000);
await new Promise(resolve => setTimeout(resolve, delay));
console.log(`Retry attempt ${attempt + 1}/${maxRetries}`);
}
}
}
```
### Dead Letter Queue Handling
```typescript
// Separate worker for processing failed events
export default {
async queue(batch: MessageBatch<R2Event>, env: Env): Promise<void> {
for (const message of batch.messages) {
const event = message.body;
// Log failed event for manual investigation
console.error('Event processing failed multiple times:', {
action: event.action,
key: event.object.key,
timestamp: event.eventTime,
retries: message.attempts,
});
// Store in persistent storage for later retry
await env.FAILED_EVENTS.put(
`failed/${Date.now()}-${event.object.key}`,
JSON.stringify(event)
);
message.ack(); // Acknowledge to prevent further retries
}
}
};
```
---
## Event Filtering
### Prefix and Suffix Filters
Filter events by object path:
```jsonc
{
"event_notification_rules": [
{
"queue": "image-processing",
"rules": [
{
"prefix": "uploads/images/",
"suffix": ".jpg"
},
{
"prefix": "uploads/images/",
"suffix": ".png"
}
]
},
{
"queue": "video-processing",
"rules": [
{
"prefix": "uploads/videos/",
"suffix": ".mp4"
}
]
}
]
}
```
### Application-Level Filtering
Filter events in Worker code:
```typescript
async function handleR2Event(event: R2Event, env: Env) {
const key = event.object.key;
// Filter by file type
if (key.match(/\.(jpg|png|webp)$/)) {
await processImage(key, env);
} else if (key.match(/\.(mp4|mov|avi)$/)) {
await processVideo(key, env);
} else if (key.match(/\.(pdf|doc|docx)$/)) {
await processDocument(key, env);
} else {
console.log(`Ignoring file: ${key}`);
}
}
```
---
## Performance Considerations
### Batch Processing
Process events in batches for efficiency:
```typescript
export default {
async queue(batch: MessageBatch<R2Event>, env: Env): Promise<void> {
// Group events by type
const createEvents: R2ObjectCreatedEvent[] = [];
const deleteEvents: R2ObjectDeletedEvent[] = [];
for (const message of batch.messages) {
if (message.body.action === 'PutObject') {
createEvents.push(message.body as R2ObjectCreatedEvent);
} else {
deleteEvents.push(message.body as R2ObjectDeletedEvent);
}
}
// Process batches
if (createEvents.length > 0) {
await processBatchCreated(createEvents, env);
}
if (deleteEvents.length > 0) {
await processBatchDeleted(deleteEvents, env);
}
// Acknowledge all messages
batch.messages.forEach(m => m.ack());
}
};
async function processBatchCreated(events: R2ObjectCreatedEvent[], env: Env) {
// Process multiple events in parallel
await Promise.all(
events.map(event => handleObjectCreated(event, env))
);
}
```
### Async Processing
Use Durable Objects for long-running tasks:
```typescript
async function handleLargeFileUpload(event: R2ObjectCreatedEvent, env: Env) {
// For large files, use Durable Object for processing
const id = env.FILE_PROCESSOR.idFromName(event.object.key);
const processor = env.FILE_PROCESSOR.get(id);
await processor.fetch(new Request('https://dummy/process', {
method: 'POST',
body: JSON.stringify(event),
}));
console.log(`Async processing started for: ${event.object.key}`);
}
```
---
## Monitoring and Debugging
### Logging Best Practices
```typescript
async function handleR2Event(event: R2Event, env: Env) {
const startTime = Date.now();
console.log('Event received:', {
action: event.action,
key: event.object.key,
size: event.object.size,
timestamp: event.eventTime,
});
try {
await processEvent(event, env);
const duration = Date.now() - startTime;
console.log('Event processed successfully:', {
key: event.object.key,
duration: `${duration}ms`,
});
} catch (error) {
console.error('Event processing failed:', {
key: event.object.key,
error: error.message,
stack: error.stack,
});
throw error;
}
}
```
### Testing Events Locally
Trigger test events manually:
```typescript
// Development endpoint to simulate events
app.post('/test/event', async (c) => {
const testEvent: R2ObjectCreatedEvent = {
account: 'test-account',
action: 'PutObject',
bucket: 'test-bucket',
object: {
key: 'test/image.jpg',
size: 1024,
eTag: 'test-etag',
},
eventTime: new Date().toISOString(),
};
await handleR2Event(testEvent, c.env);
return c.json({ success: true, message: 'Test event processed' });
});
```
---
## Security Best Practices
1. **Validate event payloads** - Verify event structure before processing
2. **Use dead letter queues** - Catch failed events for investigation
3. **Implement idempotency** - Handle duplicate events safely
4. **Set reasonable timeouts** - Prevent infinite processing loops
5. **Monitor queue depth** - Alert on backlog buildup
6. **Use environment variables** - Keep sensitive config out of code
7. **Limit batch sizes** - Prevent memory exhaustion
8. **Add authentication** - Secure webhook endpoints
---
## Troubleshooting
### Events Not Triggering
**Check**:
- Event notification rule configured correctly in wrangler.jsonc or Dashboard
- Queue exists and is bound to Worker
- Prefix/suffix filters match your objects
- Worker is deployed and queue consumer is active
**Test**:
```bash
# Check queue status
bunx wrangler queues list
# View queue consumer
bunx wrangler queues consumer list r2-events
```
### Events Stuck in Queue
**Check**:
- Worker queue handler is processing messages
- No infinite retry loops (check logs)
- Dead letter queue configured for failed messages
- Batch size and timeout settings appropriate
**Monitor**:
```bash
# View queue metrics in Dashboard
# R2 → Queues → [your-queue] → Metrics
```
### Duplicate Event Processing
**Solution**: Implement idempotency using event.object.eTag:
```typescript
// Track processed ETags to prevent duplicates
const processedEvents = new Set<string>();
async function handleR2Event(event: R2Event, env: Env) {
const eventId = `${event.object.key}-${event.object.eTag}`;
if (processedEvents.has(eventId)) {
console.log(`Duplicate event ignored: ${eventId}`);
return;
}
processedEvents.add(eventId);
await processEvent(event, env);
}
```
---
## Official Documentation
- **Event Notifications**: https://developers.cloudflare.com/r2/buckets/event-notifications/
- **Queues**: https://developers.cloudflare.com/queues/
- **Queue Consumers**: https://developers.cloudflare.com/queues/configuration/consumer-concurrency/
- **Dead Letter Queues**: https://developers.cloudflare.com/queues/configuration/dead-letter-queues/
---
**Ready to automate R2 workflows with event-driven architecture!**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |