denoland/celld API Reference: Complete Guide to the Exposed Interfaces

The denoland/celld repository exposes a Rust library API centered on crates/celld/lib.rs, providing modules for distributed compute, KV storage, telemetry, WebSocket clients, JavaScript adapters, and control-plane utilities.

celld implements a distributed, server-less compute platform in Rust. Developers use its public API to embed celld nodes or build Cloudflare-compatible Workers. The entire surface is defined through explicit pub mod re-exports in [crates/celld/lib.rs](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs), making it straightforward to discover available functionality.

Asynchronous Runtime API (asyncrt)

The asyncrt module provides a Tokio-based façade for awaiting multiple futures. It exports select! and select_biased! macros used throughout celld for fair or prioritized task selection.

use celld::asyncrt::select;

async fn example() {
    let fetch_fut = async { /* … */ };
    let rpc_fut   = async { /* … */ };

    select! {
        fetch_res = fetch_fut => println!("fetch completed: {:?}", fetch_res),
        rpc_res   = rpc_fut   => println!("rpc completed: {:?}", rpc_res),
        else => println!("all branches disabled"),
    }
}

Source: asyncrt module re-export and [crates/celld/asyncrt.rs](https://github.com/denoland/celld/blob/main/crates/celld/asyncrt.rs)

Worker Job Queue API (WorkerJob)

The WorkerJob enum represents the three execution types a celld node can perform:

• HTTP fetch — outbound HTTP requests
• RPC calls — inter-cell remote procedure calls
• Queue batch dispatch — message queue processing

Each variant carries operation data and a oneshot::Sender for the result.

use celld::{WorkerJob, js};
use tokio::sync::oneshot;

async fn submit_fetch(runtime_sender: tokio::sync::mpsc::Sender<WorkerJob>) {
    let (reply_tx, reply_rx) = oneshot::channel();
    let job = WorkerJob::Fetch {
        queued_at: std::time::Instant::now(),
        url: "https://example.com".into(),
        method: "GET".into(),
        body: js::RequestBody::Empty,
        headers: vec![],
        request_id: None,
        reply: reply_tx,
    };
    runtime_sender.send(job).await.unwrap();
    let response = reply_rx.await.unwrap()?;
}

Source: WorkerJob enum definition

Activity Tracking API (CellActivityGuard)

The CellActivityGuard struct is a RAII guard that signals when a cell becomes idle. The core decision engine uses this to track cell activity and make scheduling decisions.

Source: CellActivityGuard struct

KV Storage API (storage)

The storage module exposes CRUD operations for the key-value store:

• get, put, delete, list — basic KV operations
• set_alarm, get_alarm, delete_alarm — alarm handling
• sql_exec, sql_cursor_* — D1-compatible SQL execution

use celld::storage;

fn kv_example() -> anyhow::Result<()> {
    storage::put("my_scope", "greeting", "hello")?;
    let val = storage::get("my_scope", "greeting")?;
    assert_eq!(val, Some("hello".to_string()));
    Ok(())
}

Source: storage module re-export and [crates/celld/storage.rs](https://github.com/denoland/celld/blob/main/crates/celld/storage.rs)

Telemetry API (telemetry)

The telemetry module provides OpenTelemetry-style observability functions:

• Creating and recording spans
• Structured logging
• Traceparent propagation for distributed workflows

use celld::telemetry::{Span, TraceIds};

fn telemetry_example() {
    if let Some(trace) = telemetry::start_trace() {
        let span = Span::new(trace, "my_operation", 0);
        telemetry::record(span);
    }
}

Source: telemetry module re-export and [crates/celld/telemetry.rs](https://github.com/denoland/celld/blob/main/crates/celld/telemetry.rs)

WebSocket Client API (ws_client)

The ws_client module is a thin wrapper around Tokio's WebSocket implementation for making outbound connections from a cell.

Source: ws_client module re-export

JavaScript Adapters API (js)

The js module exposes Cloudflare Workers-compatible types:

• Request and Response — HTTP primitives
• QueueBatch — queue message batches
• Additional JS runtime adapters

This enables cells to run JavaScript code that interoperates with celld's KV, queue, and fetch capabilities.

Source: js module re-export and [crates/celld/js.rs](https://github.com/denoland/celld/blob/main/crates/celld/js.rs)

Control-Plane APIs

Multiple modules handle node lifecycle and cluster management:

Module	Purpose	Source
control_plane	Bootstrap and coordination	re-export
runtime	Core event loop driving WorkerJob processing	re-export
fleet	Peer cluster management	re-export
startup	Graceful initialization	re-export

The runtime entry point creates a DurabilityOwner and calls runtime::run to start processing.

Replication and Durability APIs

Low-level modules for distributed state management:

• ltx_repl — LTX (log-structured transaction) replication
• node_log — durability log management
• ownership_store — durability ownership tracking

Source: ltx_repl re-export

Peer Communication APIs

Module	Purpose	Source
pool	Connection management to other celld nodes	re-export
peer_probe	Liveness probing	re-export
peer_auth	Mutual authentication	re-export

Protocol Definitions (protocol)

The protocol module defines binary types for peer-to-peer communication: handshakes, peer messages, and wire format.

Source: protocol module re-export and [crates/celld/protocol.rs](https://github.com/denoland/celld/blob/main/crates/celld/protocol.rs)

CLI Helper APIs

Modules exposing command-line interfaces:

• kv_cli — KV store CLI
• cell_cli — Cell management CLI
• queue_cli — Queue operations CLI
• d1_cli — D1-compatible SQL CLI

Source: kv_cli re-export

Utility APIs

Additional public modules for embedder use:

• bucket — bucket creation utilities
• generation — generation counters
• host_services — host-service registration
• memory — memory management helpers
• wake — async wakeup utilities

Summary

The denoland/celld API surface includes:

• Async runtime (asyncrt) with select! macros for multi-future awaiting
• Job queue (WorkerJob) for fetch, RPC, and queue batch execution
• KV storage (storage) with CRUD, alarms, and D1 SQL support
• Telemetry (telemetry) for distributed tracing and logging
• WebSocket client (ws_client) for outbound connections
• JavaScript adapters (js) for Cloudflare Workers compatibility
• Control-plane modules (control_plane, runtime, fleet, startup) for node lifecycle
• Replication (ltx_repl, node_log, ownership_store) for distributed durability
• Peer management (pool, peer_probe, peer_auth) for cluster communication
• Protocol definitions (protocol) for peer wire format
• CLI utilities (*_cli modules) for operator interaction

Frequently Asked Questions

Where is the main celld API entry point?

The primary entry point is crates/celld/lib.rs, which re-exports all public modules through pub mod declarations. The main binary in crates/celld/main.rs demonstrates typical usage by creating a DurabilityOwner and calling runtime::run.

Can I use celld as an embedded library in my Rust application?

Yes. The celld crate is designed for embedding. Import the crate and use the public modules from lib.rs—particularly runtime, storage, and telemetry—to embed a celld node with KV storage and distributed compute capabilities.

How does celld's API compare to Cloudflare Workers?

The js module intentionally mirrors the Cloudflare Workers API, exposing compatible Request, Response, QueueBatch, and other types. This allows existing Workers JavaScript code to run on celld with minimal modification, while the Rust API provides lower-level control for native embedders.

What telemetry systems does celld integrate with?

The telemetry module emits OpenTelemetry-compatible spans and traces, plus built-in tracing collector support. You can export to any OpenTelemetry backend or use the internal tracing infrastructure for observability of distributed cell workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}