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

> Explore the denoland/celld API, a comprehensive guide to its exposed Rust interfaces for distributed compute, KV storage, telemetry, WebSockets, and more.

- Repository: [Deno/celld](https://github.com/denoland/celld)
- Tags: api-reference
- Published: 2026-09-05

---

**The `denoland/celld` repository exposes a Rust library API centered on [`crates/celld/lib.rs`](https://github.com/denoland/celld/blob/main/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)](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.

```rust
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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L30-L80) and [[`crates/celld/asyncrt.rs`](https://github.com/denoland/celld/blob/main/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.

```rust
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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L55-L71)

## 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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L32-L46)

## 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

```rust
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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L21-L28) and [[`crates/celld/storage.rs`](https://github.com/denoland/celld/blob/main/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

```rust
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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L20-L23) and [[`crates/celld/telemetry.rs`](https://github.com/denoland/celld/blob/main/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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L63-L66)

## 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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L41-L44) and [[`crates/celld/js.rs`](https://github.com/denoland/celld/blob/main/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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L25-L28) |
| `runtime` | Core event loop driving `WorkerJob` processing | [re-export](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L58-L61) |
| `fleet` | Peer cluster management | [re-export](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L25-L28) |
| `startup` | Graceful initialization | [re-export](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L25-L28) |

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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L44-L46)

## Peer Communication APIs

| Module | Purpose | Source |
|--------|---------|--------|
| `pool` | Connection management to other celld nodes | [re-export](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L53-L55) |
| `peer_probe` | Liveness probing | [re-export](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L53-L55) |
| `peer_auth` | Mutual authentication | [re-export](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L53-L55) |

## 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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L54-L57) and [[`crates/celld/protocol.rs`](https://github.com/denoland/celld/blob/main/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](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs#L22-L24)

## 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`](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs), which re-exports all public modules through `pub mod` declarations. The `main` binary in [`crates/celld/main.rs`](https://github.com/denoland/celld/blob/main/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`](https://github.com/denoland/celld/blob/main/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.