Fidelity.CloudEdge extends the Fidelity Framework to Cloudflare's edge platform, providing substrate-agnostic actor model support across bare metal and edge computing environments. Built on F#, Fable, and comprehensive type-safe bindings, it enables seamless actor migration between execution contexts while preserving semantic guarantees.
Fidelity.CloudEdge is a framework extension, not a standalone tool. It represents the edge computing layer of the broader Fidelity Framework architecture, which provides substrate-transparent actor model abstractions:
- Bare Metal: Actors compiled via MLIR through Fidelity.Firefly
- Edge Computing: Actors compiled to JavaScript via Fable for Cloudflare Workers
- Architectural Fidelity: Same
MailboxProcessorcode, different execution contexts
This dual-substrate approach enables:
- Actor Migration: Move actors between bare metal and edge without code changes
- Hybrid Deployments: Latency-sensitive operations at the edge, compute-intensive work on bare metal
- Unified Semantics: Sequential processing guarantees preserved across contexts
- Purpose: Operations inside Cloudflare Workers
- Source: TypeScript definitions via Glutinum
- Scope: 727 types covering the complete
@cloudflare/workers-typessurface - Usage: Direct platform access with microsecond latency
- Actor Context: Provides sequential execution guarantees for actor message processing
- Purpose: Infrastructure provisioning, monitoring, and orchestration
- Source: OpenAPI specifications via Hawaii
- Scope: 32 service clients covering the full Cloudflare Management API
- Usage: REST API clients for deployment tools and scripts
- Framework Role: Enables dynamic resource allocation for actor migrations
The runtime surface is distributed across focused packages. Worker.Context provides the core Worker API and generated Glutinum bindings; each additional service ships as a separate package with its own Types and Helpers modules.
| Package | Category | Key Types |
|---|---|---|
Worker.Context |
Core Worker APIs | Request, Response, Headers, FetchEvent, ExecutionContext, Fetch, Socket, URL, URLPattern, URLSearchParams |
Worker.Context |
Streams | ReadableStream, WritableStream, TransformStream, FixedLengthStream, CompressionStream, DecompressionStream |
Worker.Context |
Crypto | SubtleCrypto, CryptoKey, CryptoKeyPair, DigestStream |
Worker.Context |
Cache | Cache, CacheStorage, CacheQueryOptions |
Worker.Context |
HTMLRewriter | HTMLRewriter, Element, Comment, Text, DocumentEnd |
Worker.Context |
Networking | WebSocket (with hibernation), Encoding streams, FormData, Blob |
Worker.Context |
Media | Images (transform, draw, upload), Media Transforms, Markdown conversion |
Worker.Context |
EmailMessage, EmailEvent, ForwardableEmailMessage, SendEmail | |
Worker.Context |
Compute | Containers, Workflows, Service Bindings, Cron Triggers |
Worker.Context |
Observability | Tail, Trace, TraceLog, TraceMetrics, diagnostic channels |
D1 |
SQL Database | D1Database, D1PreparedStatement, D1Result<'T>, D1ExecResult |
KV |
Key-Value Store | KVNamespace, KVPutOptions, KVListOptions, KVListResult, KVKey |
R2 |
Object Storage | R2Bucket, R2Object, R2ObjectBody, R2PutOptions, R2HTTPMetadata |
DurableObjects |
Stateful Actors | DurableObjectId, DurableObjectStub, DurableObjectNamespace |
Queues |
Messaging | Queue<'Body>, Message<'Body>, MessageBatch<'Body>, QueueSendOptions |
AI |
AI/ML Inference | Workers AI (per-model typed I/O), AI Gateway, AI Search, AutoRAG |
Vectorize |
Vector Search | VectorizeVector, VectorizeMatches, VectorMatch, VectorizeQueryOptions |
Hyperdrive |
Database Proxy | Hyperdrive, connection pooling, PostgreSQL/MySQL URL builders |
| Category | Services |
|---|---|
| Compute and Storage | Workers, Pages, Durable Objects, Containers, KV, R2, R2 Catalog, D1, Queues, Hyperdrive, Secrets Store |
| AI and ML | AI, AI Gateway, AI Search, AutoRAG, Vectorize |
| Orchestration | Workflows, Pipelines |
| Media | Stream, Images, Browser Rendering, Calls |
| Networking and Security | Access, Gateway, Tunnels, Load Balancers, Waiting Rooms, Magic Transit, Email |
| Observability and Platform | Analytics, Logs, Builds |
dotnet add package Fidelity.CloudEdge.Runtimedotnet add package Fidelity.CloudEdge.Managementopen Fidelity.CloudEdge.Worker.Context
open Fidelity.CloudEdge.DurableObjects
open Fidelity.CloudEdge.D1
// Traditional actor pattern - works identically on bare metal or edge
type CounterMsg =
| Increment
| GetCount of AsyncReplyChannel<int>
type Counter() =
let agent = MailboxProcessor<CounterMsg>.Start(fun inbox ->
let rec loop count = async {
let! msg = inbox.Receive()
match msg with
| Increment -> return! loop (count + 1)
| GetCount reply ->
reply.Reply(count)
return! loop count
}
loop 0)
member _.Increment() = agent.Post(Increment)
member _.GetCount() = agent.PostAndReply(GetCount)
// On edge: Durable Object provides sequential execution context
[<DurableObject>]
type CounterDO(state: DurableObjectState, env: Env) =
let mutable count = 0
member this.fetch(request: Request) = async {
// Guaranteed sequential processing - no race conditions
match request.method with
| "POST" ->
count <- count + 1
return Response.json({| count = count |})
| "GET" ->
return Response.json({| count = count |})
| _ ->
return Response.methodNotAllowed()
}// 1. Infrastructure Setup (Management API - runs on your machine)
open Fidelity.CloudEdge.Management.D1
open System.Net.Http
let setupInfrastructure (accountId: string) (apiToken: string) = async {
let httpClient = new HttpClient()
httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiToken}")
let d1Client = D1Client(httpClient)
let! database = d1Client.CreateDatabase(
accountId = accountId,
name = "production-db",
primaryLocationHint = Some "wnam"
)
printfn $"Created database: {database.uuid}"
return database.uuid
}
// 2. Runtime Operations (Runtime API - runs in Worker)
open Fidelity.CloudEdge.D1
open Fidelity.CloudEdge.Worker.Context
[<Export>]
let fetch (request: Request) (env: Env) (ctx: ExecutionContext) =
async {
let db = env.DATABASE
match request.method with
| "GET" ->
let! users = db.prepare("SELECT * FROM users").all<User>()
return Response.json(users)
| "POST" ->
let! body = request.json<User>()
let! result =
db.prepare("INSERT INTO users (name, email) VALUES (?, ?)")
.bind(body.name, body.email)
.run()
return Response.json({| success = result.success |})
| _ -> return Response.methodNotAllowed()
}Basic Worker with KV storage:
cd samples/HelloWorker
dotnet fable . --outDir dist
npx wrangler devProduction-ready chat API featuring:
- User authentication via Cloudflare Secrets
- D1 database for message persistence
- PowerShell user management scripts
- Separate React UI with Tailwind CSS
cd samples/SecureChat
.\scripts\add-user.ps1 -Username alice -Password "Pass123!"
dotnet fable . --outDir dist
npx wrangler devBoth layers are generated from official Cloudflare specifications:
- Runtime:
@cloudflare/workers-typesTypeScript definitions processed by Glutinum, producing 727 F# types - Management: Cloudflare OpenAPI spec processed by Hawaii, producing 32 service clients
The generation pipeline includes automated preprocessing (preprocess-openapi.sh) to handle Hawaii compatibility issues, type sanitization for underscore variants, and query parameter overload resolution. All 32 management services compile cleanly with the current pipeline.
See generators/README.md for pipeline details and docs/03_gap_analysis.md for service-level status.
The test suite validates the full surface area:
- 501 tests across structural validation, client construction, serialization, and infrastructure checks
- All 32 management assemblies verified via reflection-based data-driven tests
- JSON round-trip serialization with
Fable.Remoting.Json+Newtonsoft.Json - OpenApiHttp infrastructure consistency across all services
Fidelity.CloudEdge is evolving toward deeper integration with the broader Fidelity Framework:
- Dynamic Substrate Selection: Framework-level orchestration to move actors between bare metal and edge
- Latency-Aware Placement: Actors automatically placed based on geographic and computational requirements
- Seamless State Transfer: Unified state management across execution contexts
The planned cfs CLI will provide type-safe, F#-first deployment with Framework integration:
// deploy.fsx - Framework-aware deployment
#r "nuget: Fidelity.CloudEdge"
open Fidelity.CloudEdge.Deployment
let deploy env = cloudflare {
account (getAccountId env)
worker $"api-service-{env}" {
actors [
actor<UserService> (durable "user-service")
actor<RAGAgent> (durable "rag-agent")
]
kv "CACHE" (ensureOrCreate "cache-namespace")
d1 "DATABASE" (ensureOrCreate "app-database" {
migrations = "./migrations"
location = "wnam"
})
route $"api-{env}.example.com/*"
}
}- Architecture Decisions - Key design choices and roadmap
- Dual Layer Architecture - Runtime vs Management APIs
- Code-First Deployment - Code-driven deployment strategies
- Gap Analysis - Service maturity and remaining gaps
- Tool Status - Glutinum/Hawaii limitations and mitigations
- Generators - Generation pipeline usage and configuration
- Actor Model Design - Durable Object actor model with tell/ask semantics
- Overview - Architecture summary, layering, phases
- Actor Core - DO substrate, WebSocket, BAREWire, lifecycle, supervision
- MailboxProcessor Intercept - API surface, push model, migration
- Persistence & Observability - Event sourcing, journals, instrumentation
- Management Infrastructure - Control plane provisioning, deployment orchestration
- Firetower Concept - Monitoring tool design
- Pulumi Insights - Lessons from Pulumi's approach
- Pages Direct Upload - Pages upload implementation
- Samples - Working examples demonstrating framework capabilities
We welcome contributions! See CONTRIBUTING.md for guidelines.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.
Fidelity.CloudEdge stands on the shoulders of giants:
-
Fable - The magnificent F# to JavaScript compiler enabling substrate-agnostic actors at the edge. Special thanks to Alfonso Garcia-Caro, Maxime Mangel, and all maintainers/contributors.
-
Glutinum - TypeScript to F# binding generator. Thanks to Maxime Mangel for this invaluable tool that makes Worker bindings possible.
-
Hawaii - OpenAPI to F# client generator. Thanks to Zaid Ajaj for creating this and pioneering F# on Cloudflare Workers.
-
Cloudflare - For building an incredible edge platform with Durable Objects, providing the sequential execution context necessary for actor guarantees at the edge.
This project is SpeakEZ's contribution to the F#, Fable, and Cloudflare communities, and a key component of the broader Fidelity Framework vision.