Cloudflare Workers

[dahlia]

Background

Fedify currently supports three JavaScript runtimes: Node.js, Bun, and Deno. However, there has been significant community demand for supporting Cloudflare Workers, a popular edge function platform. Despite Cloudflare Workers offering Node.js compatibility mode, it's not 100% compatible with Node.js, which necessitates adaptations to our codebase.

Objectives

• Add first-class support for Cloudflare Workers to Fedify
• Create a Cloudflare Workers integration module similar to our existing framework integrations
• Document the deployment process and limitations
• Provide examples for common use cases

Technical Challenges

1. Runtime Compatibility: Cloudflare Workers lacks full Node.js API support, particularly for:

   • crypto module (specifically for RSA and Ed25519 operations)
   • fetch() behavior differences
   • Stream implementations
   • Environment variable handling

2. KV and Message Queue: We need to implement:

   • KvStore implementation using Cloudflare Workers KV
   • MessageQueue implementation using Cloudflare Queues

3. Resource Limitations:

   • Workers have CPU time limits (10–50ms in free tier, up to 30s in paid tier)
   • Memory constraints (128MB)
   • Request body size limits

Porting Strategy

Phase 1: Compatibility Assessment

• Create a matrix of Fedify features vs. Cloudflare Workers capabilities
• Identify polyfills and alternatives for unsupported APIs
• Evaluate Cloudflare D1 as a PostgreSQL alternative

Phase 2: Core Adaptation

• Refactor cryptographic operations to use Web Crypto API compatible with Workers
• Adapt document loaders to work with Workers' fetch() implementation
• Create WorkersKvStore implementation

Phase 3: Message Processing

• Implement WorkersMessageQueue using Cloudflare Queues
• Adjust retry policies to accommodate Cloudflare's execution constraints

Phase 4: Integration & Examples

• Create a Workers-specific integration similar to Hono integration
• Develop deployment templates using Wrangler
• Create example applications

Parent Issue Structure

This issue serves as a parent issue tracking the overall Cloudflare Workers support initiative. It will be broken down into several sub-issues for each implementation phase and specific components. These sub-issues will be linked here for tracking progress:

• Compatibility assessment and feature matrix
• Web Crypto API adaptations
• WorkersKvStore
• WorkersMessageQueue
• Workers integration module
• Documentation and examples

Progress on these sub-issues will be tracked here to provide an overview of the entire initiative.

Questions

• Should we focus on Workers + D1 (SQL) or Workers + KV (NoSQL) first?
• Should we provide a compatibility module or refactor the core for Workers?
• How do we handle the execution time limits in relation to processing activities?

References

• Cloudflare Workers Runtime APIs
• Cloudflare Workers Limits
• Cloudflare D1 Documentation
• Cloudflare Queues Documentation