@distilled.cloud/celld
v1.0.0-rc.20
Published
Keywords
Readme
@distilled.cloud/celld
Effect SDK generated from a source-derived Smithy description of Celld v0.6.0.
import { getNodeState } from "@distilled.cloud/celld/node";
import * as Endpoint from "@distilled.cloud/celld/Endpoint";
import * as Effect from "effect/Effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
const state = await Effect.runPromise(
getNodeState({}).pipe(
Effect.provide(Endpoint.of("http://127.0.0.1:8081")),
Effect.provide(FetchHttpClient.layer),
),
);
console.log(state.deployment);Use the port configured for your node's internal listener, not its public Worker listener.
Spec source
Celld does not publish a machine-readable API description. The models in
specs/ describe the implementation at
bad4649d01f0db84cdc9093527e72e64ca7a14bf.
These are Distilled-maintained contracts, not an official Celld specification.
Scope
The specification models administrative HTTP endpoints, the signed operator requests used for D1, KV, and Queues, and deployment artifact data structures. Worker bindings are JavaScript runtime APIs rather than administrative HTTP endpoints; they are not generated as HTTP operations.
Deployment publication uses an object store rather than a Celld REST endpoint.
The package describes its artifacts without inventing a deploy HTTP operation.
It does not include a deployment orchestrator, object-storage adapter, node
discovery, bundler, or CLI wrapper. Use the existing storage-provider SDK for
object-store requests.
Security and authentication
Configure Endpoint with the trusted internal listener of the intended node.
Some administrative endpoints are unauthenticated and can stop a node or alter
its operation. Keep this listener on loopback or an explicitly trusted private
network. The public Worker listener is a different endpoint.
Reserved-resource operations require Celld's peer-authentication headers. Those headers are explicit inputs in the specification. This package does not compute HMAC signatures: the caller must sign the exact encoded method, path, body, target node session, timestamp, and nonce. A retry needs a new signature and nonce; an ambiguous failure is not permission to repeat a non-idempotent operation.
Automatic retries are disabled. Explicit peer-version, target-session, and replay
rejections are typed errors; other HTTP failures use the shared REST error types
or UnknownCelldError. Operator application errors return HTTP 400. The node
state endpoint can instead return HTTP 200 with error: "actor_stopped"; callers
must check that modeled response field.
Regeneration
From the repository root:
pnpm generate celldconvert validates and finalizes the committed Smithy source, and generate
uses @distilled.cloud/dev/codegen. Update the specification rather than
editing src/services/. Regeneration requires neither a Celld deployment command
nor an upstream checkout.
The mirror registry records this provider as blocked on an upstream API spec; there is no speculative mirror repository or runtime code scraper.
Validation
pnpm exec tsc -b packages/celld/tsconfig.json packages/celld/tsconfig.scripts.json --noCheck falseCompatibility
This package targets v0.6.0, not arbitrary future Celld releases. Celld's administrative protocol is alpha. Review upstream route handlers, request/reply structures, and authentication rules before changing the pinned contract.
The v0.6.0 update adds allocator and isolate census fields to node state and
models completed eviction outcomes. evictCell can fail with EvictionRefused,
EvictionCancelled, or EvictionFailed; their messages retain the server's
kind: reason. HTTP 503 alone does not identify an eviction failure. Peer
signing remains protocol version 5, and deployment manifests, pointers, and
queue attachments retain their existing object-store formats.
For persistent fleets, upstream requires stopping the entire fleet before upgrading from v0.5.1 to v0.6.0 with fleet durability. Bucket durability permits a rolling update. S3-backed storage does not imply bucket durability: the node defaults to fleet durability. The release notes do not certify a direct v0.5.0-to-v0.6.0 rolling upgrade. Existing facets migrate on first open; do not discard node storage, recreate the bucket, or rotate the fleet peer secret as an upgrade step. This SDK does not orchestrate node upgrades or storage migrations.
Authoritative upstream sources include:
main.rs: HTTP routes.peer_auth.rs: authentication headers and signing contract.operator_cell.rs: reserved-resource operator transport.protocol.rs: deployment artifacts.deploy.rs: deployment normalization and publication.
