What Are the Core Components of the denoland/celld System?

The celld system from Deno is built from eight tightly-coupled Rust crates that provide runtime orchestration, Durable Object-compatible cell logic, log-structured SQLite replication, peer networking, object storage abstraction, telemetry, async primitives, and CLI tooling.

The celld project implements a distributed, stateful platform for server-side JavaScript workloads in the style of Cloudflare Durable Objects. Its architecture is decomposed into specialized Rust crates, each handling a distinct subsystem. This guide examines the core components of the denoland/celld system, their responsibilities, and how they interact according to the source code.

The celld Crate: Runtime and Orchestration

The celld crate serves as the main entry point and orchestration layer for every node in the cluster.

According to crates/celld/main.rs, this component handles:

• Bootstrapping the node and parsing configuration
• Managing the public Worker listener for HTTP/WebSocket traffic
• Running the internal operator listener for administrative commands
• Peer discovery and authentication
• The high-level replication protocol

The runtime initialization creates a DurabilityOwner (defined in crates/celld/node_log.rs) and launches the background runtime loop in crates/celld/runtime.rs.

use celld::node_log::DurabilityOwner;

async fn start_node(bucket: &str) -> anyhow::Result<()> {
    // After node-log recovery, create the owner.
    let owner = DurabilityOwner::new(bucket).await?;
    // Run background maintenance (GC, log compaction, etc.).
    owner.start_background().await?;
    // The owner must be kept alive for the process lifetime.
    Ok(())
}

The logic Crate: Cell Logic and Durable Objects API

The logic crate implements the core Durable Object API surface that developers interact with.

Located in crates/logic/lib.rs, this subsystem provides:

• HTTP handling and WebSocket routing
• Alarms and scheduled task execution
• Queue processing
• KV storage operations
• Isolate management for JavaScript execution
• Scheduling and the cell state machine

Each cell is represented by a logic::cell::Cell object that owns a private SQLite database. The scheduler (logic::schedule) runs alarms, cron jobs, and queue processing, while the pressure manager (logic::pressure) monitors RSS memory and triggers shedding when usage approaches CELLD_MAX_RSS_MB.

The ltx Crate: Log-Structured Storage Engine

The ltx crate provides the LTX (Log-structured Transaction) engine that enables durable, replicated SQLite databases.

Key capabilities from crates/ltx/src/ltx.rs and crates/ltx/src/replica.rs:

• Write-ahead logging (WAL) for durability
• Compaction to reclaim space
• Snapshotting for cell migration

Writes are first recorded in the WAL, then passed through the replication pipeline (ltx::replica::Replica) to achieve the configured durability level specified by CELLD_DURABILITY.

For graceful shutdown, the replica can seal and snapshot:

use celld::ltx::replica::Replica;

async fn graceful_shutdown(replica: &Replica) -> anyhow::Result<()> {
    // Attempt to seal and snapshot within the remaining shutdown time.
    if replica.quiesce_and_seal_within(30_000).await? {
        // Successful snapshot – safe to shut down.
        replica.shutdown_local_within(10_000).await?;
    }
    Ok(())
}

Peer Authentication and Networking

The peer_* modules manage the distributed aspects of the system.

From crates/celld/peer_auth.rs and crates/celld/protocol.rs, these components handle:

• Peer-to-peer connections and connection pooling
• HMAC-based authentication for secure operator and peer traffic
• Probe health checks for cluster membership detection
• Cell ownership claims and handoff protocols

Ownership records live in the configured bucket, and the peer protocol ensures only one node claims a cell at any time. When a node shuts down, it hands off cells using drain tokens (crates/celld/drain_token.rs) and snapshots.

Storage Abstraction Layer

The storage module in crates/celld/storage.rs provides a uniform interface over multiple object store backends.

This wrapper exposes S3-compatible, GCS, and Azure Blob storage behind the object_store::ObjectStore interface, allowing the rest of the system to remain backend-agnostic.

Telemetry and Observability

The telemetry module (crates/celld/telemetry.rs) drives all observability concerns:

• Internal metrics collection
• OpenTelemetry integration
• Log-pipeline processing
• Log-eviction subsystems

All components emit structured events consumed by this pipeline. Operators query node health via the internal operator API endpoints /state, /reload, and /shutdown.

asyncrt: Async Selection Primitives

The asyncrt façade in crates/celld/asyncrt.rs exposes ergonomic async-selection primitives used throughout applications and internal tasks.

The select! and select_biased! macros provide cyclic start ordering to prevent source order bias:

use celld::asyncrt::select;

async fn fetch_two_sources(src1: impl Future<Output = Result<String, ()>>, src2: impl Future<Output = Result<String, ()>>) -> Result<String, ()> {
    // The macro chooses a cyclic start order, preventing source order bias.
    select! {
        res1 = src1 => res1,
        res2 = src2 => res2,
    }
}

CLI and Developer Tooling

The CLI subsystem in crates/celld/cli.rs provides user-facing commands:

• celld dev — local development server
• celld deploy — deployment from Wrangler projects
• celld kv, celld d1 — data operations

Run a local development node:

celld dev --port 3000 --bucket "s3://my-bucket/dev"

Deploy an application:

celld deploy ./my-worker \
  --bucket "$CELLD_BUCKET" \
  --endpoint "$S3_ENDPOINT" \
  --region "$AWS_REGION"

How Components Work Together

1. Node startup — main.rs parses flags, creates the DurabilityOwner, and launches the runtime.

2. Request handling — The Worker listener dispatches to logic::http, which resolves the target cell and forwards to the appropriate Cell instance.

3. State persistence — Cell data flows through the LTX engine for WAL recording and replication.

4. Ownership and migration — The peer protocol manages exclusive cell claims, with graceful handoff using drain tokens and LTX snapshots.

5. Background work — The scheduler and pressure manager run continuously, monitored by telemetry.

Summary

The core components of the denoland/celld system include:

• celld crate — runtime orchestration, listeners, and node lifecycle
• logic crate — Durable Object API implementation with HTTP, WebSocket, alarms, and isolates
• ltx crate — log-structured SQLite engine with WAL, replication, and snapshots
• Peer modules — distributed networking, authentication, and cell ownership
• storage module — unified object-store abstraction over S3, GCS, and Azure
• telemetry module — metrics, logging, and OpenTelemetry integration
• asyncrt façade — async selection macros for fair task scheduling
• CLI subsystem — developer commands for local development and deployment

These components deliver celld's guarantees: RPO = 0, configurable durability, and graceful handoff, while presenting a familiar JavaScript-compatible API.

Frequently Asked Questions

What programming language is celld written in?

The celld system is implemented in Rust. The codebase is organized as a Cargo workspace with multiple crates under the crates/ directory, leveraging Rust's async ecosystem through Tokio and related libraries for high-performance, concurrent operations.

How does celld achieve zero recovery point objective (RPO)?

Celld achieves RPO = 0 through the LTX engine's write-ahead logging and replication pipeline. Every write is first recorded to a WAL, then replicated according to the CELLD_DURABILITY configuration before acknowledgment. This ensures no committed writes are lost during node failures.

What database does celld use for cell state?

Each cell owns a private SQLite database persisted through the LTX engine. The logic::cell::Cell object manages this database, with the LTX layer providing durability, replication, and snapshot capabilities over standard SQLite.

Can celld run without cloud object storage?

No — celld requires an object store backend for durability and peer coordination. The storage module supports S3-compatible APIs, Google Cloud Storage, and Azure Blob Storage through a unified object_store::ObjectStore interface, but local-only operation without external storage is not supported.

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