Skip to main content

Crate cordium

Crate cordium 

Source
Expand description

§Cordium Rust SDK

The async Rust SDK for Cordium: create isolated workspaces, run commands, move files, attach to persistent terminals, and manage the resources around them. Built on Tokio, tonic, and the shared Octelium authentication client. Rust 2024 edition; minimum supported Rust version (MSRV) 1.88.

§Installation

Add the crate from crates.io:

[dependencies]
cordium = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
futures-util = "0.3" # for StreamExt

For local development, use cordium = { path = "/path/to/sdk-rust/crates/cordium" }. Generated protobuf files are included: applications need neither protoc nor the protobuf source repository to compile.

§A usable workspace in one call

use cordium::{Client, Command, WorkspaceOptions};

let client = Client::builder().domain("example.com").build().await?;
let workspace = client.workspaces().run(
    WorkspaceOptions::new().image("python:3.14").ephemeral(true),
).await?;
let result = workspace.exec(Command::argv(["python", "--version"])).await?;
println!("{}", result.stdout_text());
workspace.files().write_text("/tmp/hello.txt", "Hello from Rust!\n").await?;
workspace.delete().await?;

create returns a stopped workspace with a cluster-assigned name. run creates, starts, and waits for RUNNING under a five-minute total deadline. Use run_with for start-time variable overrides, placement, or a different wait deadline. Once the workspace exists, a failure of a later step is reported as Error::RunFailed, which carries the workspace so that it can be inspected or deleted; deleting it is explicit. start on a starting or running workspace is a no-op, and wait_stopped reports a failed run as Error::WorkspaceFailed.

Dropping a client or workspace does not stop or delete remote workspaces. For cleanup after a command error, store its result, call delete, then propagate the result. The quickstart example shows this pattern.

§Authentication and connection settings

Explicit credentials take precedence over the environment:

use cordium::{Assertion, AuthenticationToken, Client};

let client = Client::builder()
    .domain("example.com")
    .authenticator(AuthenticationToken::new("<one-time authentication token>"))
    .build().await?;

let workload_client = Client::builder()
    .domain("example.com")
    .authenticator(Assertion::from_file("/var/run/identity/token"))
    .build().await?;

Client::from_env() reads CORDIUM_DOMAIN, falling back to OCTELIUM_DOMAIN. Credentials follow this order:

VariableBehavior
OCTELIUM_ACCESS_TOKENExternally managed bearer token, used directly.
OCTELIUM_ASSERTION_FILEAssertion file re-read on every authentication.
OCTELIUM_ASSERTIONFixed assertion, exchanged once.
OCTELIUM_AUTH_TOKENOne-time authentication token.

Use access_token_provider for rotating externally managed tokens, and Assertion::from_fn for renewable signed assertions. Authenticator and AccessTokenProvider remain extensible for new cluster authentication methods.

Authentication is lazy. Concurrent callers share token state and serialize exchanges. Canceling an individual request does not discard an ongoing exchange; it can complete for other callers. Authentication has its own default 30-second bound, customizable through configure_transport. One-time exchanges are never replayed after failure or expiry. Session refresh uses a separate connection and starts before token expiry. Credentials have redacted Debug implementations; access_token() deliberately returns a sensitive string.

The default endpoint is https://octelium-api.<domain>:443, with certificate verification. api_endpoint overrides it, including a plain HTTP endpoint for local testing. OCTELIUM_API_ENDPOINT and OCTELIUM_TLS_SERVER_NAME also apply. Advanced transport settings are exposed through the shared builder:

let client = cordium::Client::builder().domain("example.com")
    .configure_transport(|builder| {
        builder
            .add_root_ca_pem(b"<PEM CA certificate>".to_vec())
            .configure_endpoint(|endpoint| {
                endpoint.connect_timeout(std::time::Duration::from_secs(10))
            })
    })
    .build().await?;

Client::from_transport reuses an existing octelium::Client. Both clients share credentials and connections; the caller keeps ownership of that transport, so Cordium shutdown leaves it open.

§Workspace configuration

Consuming builders provide common settings; full generated specs cover the rest:

use cordium::{Application, EnvValue, Resources, Task, TaskPhase, WorkspaceOptions};

let options = WorkspaceOptions::new()
    .template("dev.team")
    .display_name("API development")
    .image("node:24")
    .repository("https://github.com/myorg/api.git")
    .branch("main")
    .env("NODE_ENV", "development")
    .env("API_TOKEN", EnvValue::secret("api-token.team"))
    .variable("VERSION", "v2")
    .resources(Resources::new().cpu_millicores(2000).memory_mb(4096))
    .application(Application::new("web", 3000).default_app())
    .task(Task::new("install", "npm ci"))
    .task(Task::new("serve", "npm run dev").phase(TaskPhase::Start).background(true))
    .mount("cache.team", "/cache", false);

Template and snapshot sources are mutually exclusive. Snapshot restoration needs persistent storage. Environment values can resolve Space Secrets without placing their content in the specification. Compute units are millicores and MB. Variables use the cluster’s ${{ vars.NAME }} substitution syntax. Mount paths must be absolute, canonical and non-overlapping; server policy checks reserved paths and storage compatibility.

WorkspaceOptions::from_spec, image_spec, repository_spec, and the proto module support private registries, repository credentials, devcontainers, additional repositories, capabilities, networking, and future configuration. Template creation accepts the same builder, while rejecting workspace-only applications, ephemeral storage, and source references. Set git_provider on a Template to obtain authenticated git operations in its workspaces.

Cloned Workspace handles share a cache. Accessors perform no network operations and return owned values. refresh, lifecycle methods, and modify update that cache; watch events are independent. watch yields typed WorkspaceEvents and logs yields LogEntry values (timestamp, stage, stream and bytes). proto(), spec(), and status() return owned copies. Unknown enum values remain accessible through their raw protobuf integer fields.

§Commands and streaming

String commands use remote shell syntax. Use Command::argv when arguments should be literal; every argument is POSIX-quoted without interpolation.

use cordium::{Command, Error};

let result = workspace.exec(Command::argv(["printf", "%s", "$(literal text)"]))
    .cwd("/workspace/repo")
    .env("MODE", "test")
    .timeout(Some(std::time::Duration::from_secs(60)))
    .await?;

match workspace.exec("exit 7").check(true).await {
    Err(Error::CommandFailed(result)) => {
        println!("exit {}: {}", result.exit_code, result.stderr_text());
    }
    other => { other?; }
}

Nonzero exit codes are normal results by default; .check(true), or ExecResult::check afterwards, turns them into Error::CommandFailed. Output is binary Bytes; text accessors use UTF-8 replacement while retaining the original bytes. Capture defaults to 1 MiB per stdout/stderr stream. Overflow sets truncated; streaming events still carry complete output. Zero capture size disables capture.

use cordium::ExecEvent;
use futures_util::StreamExt;

let mut session = workspace.exec("printf 'hello\n'").stream().await?;
while let Some(event) = session.next().await {
    match event? {
        ExecEvent::Stdout(bytes) => print!("{}", String::from_utf8_lossy(&bytes)),
        ExecEvent::Stderr(bytes) => eprint!("{}", String::from_utf8_lossy(&bytes)),
        ExecEvent::Exit(code) => println!("exit: {code}"),
        _ => {},
    }
}
let result = session.wait().await?;

Streams implement futures_core::Stream, are Send, and use backpressure instead of background output tasks or unbounded SDK queues. An Exit releases the RPC even if the server leaves it open. Dropping a session cancels its RPC; use session.input().kill().await for an explicit remote termination request. A killed command that the cluster does not report as exited within 10 seconds (.kill_grace(...)) ends the session with the exit code -1 and killed set.

For interactive stdin, call .stdin_enabled(true).stream().await, clone session.input(), and write while another task consumes output. Writes are serialized and chunked to 32 KiB through a bounded queue. For collected execution, .stdin(bytes) sends initial input while draining output. Cordium’s exec protocol has no stdin EOF message: commands must read a known amount or finish independently. Closing a write handle does not signal EOF. File upload handles this with exact-length base64 framing.

§Files and terminals

workspace.files() provides binary/text reads and writes, uploads, downloads, mkdir, and remove. Paths are literal: no $HOME, glob or tilde expansion. Reads cap memory at 64 MiB and reject larger files. max_read_bytes adjusts that bound; uploads, upload_reader, and download_to stream with bounded chunks. Text reads use strict UTF-8. as_root and timeout customize transfer commands.

Transfers require POSIX sh, head, base64, cat, mkdir, and rm in the image. Remote writes may leave partial content after failure. Local downloads use a private temporary file in the destination directory and replace an existing destination only after successful execution and flushing. Use repositories, object storage, or SSH/SFTP for bulk data.

use cordium::{TerminalOptions, TerminalEvent};
use futures_util::StreamExt;

let mut terminal = workspace.terminals().create(TerminalOptions::default().size(120, 40)).await?;
let input = terminal.input(); // can move to another task while consuming events
input.write("printf 'hello\n'\n").await?;
if let Some(Ok(TerminalEvent::Output(bytes))) = terminal.next().await {
    print!("{}", String::from_utf8_lossy(&bytes));
}
terminal.remove().await?; // terminate the persistent remote shell

Terminal Drop or detach ends only the local subscription. The shell survives and can be found with list and reattached with attach. remove explicitly terminates it. Several clients can attach to one terminal. Input and resize operations are available on a clonable TerminalInput; local raw terminal mode is the caller’s responsibility.

§Resources and pagination

CollectionCapabilities
workspacesCreate/run, get/update/delete, list/all, watch; handle lifecycle, logs, sharing, exec, files, terminals.
spacesCreate/update/delete, list/all, edit full specs, leave.
templatesCreate/update/delete, list/all, build/cancel, wait for an explicit build ID.
snapshotsCreate/get/delete, list/all, wait for READY.
volumesCreate/update/delete, list/all, monotonic capacity growth, wait for READY.
secretsWrite-only text/binary/JSON creation, metadata reads/list/all, delete.
user_secretsPersonal text/binary/JSON secrets, updates, cluster-generated SSH keys.
git_providersGitHub/GitLab/generic OAuth2 creation, get/update/delete, list/all.
membershipsAdd by User reference or email, read own membership, role edits, delete, list/all.
regionsList/all hosting Regions.
user_configGet/update/modify preferences, preferred Region, dotfiles.
managementAdministrator get/update/modify of the sole ClusterConfig.

Collection operations return complete generated resource types, preserving advanced server fields. modify fetches, invokes a synchronous edit callback, and updates exactly once; errors in the callback abort the update. There are no automatic mutation retries or conflict-resolution guesses. Full resource updates can race other writers; applications should handle any server conflict response.

use cordium::{ListOptions, Reference};
use futures_util::StreamExt;

let workspace = client.workspaces().get(Reference::uid("workspace-uid")).await?;
let mut all = client.workspaces().all(ListOptions::new().in_space("team.cordium").page_size(100));
while let Some(workspace) = all.next().await { println!("{}", workspace?.name()); }
client.spaces().modify("team.cordium", |space| {
    space.metadata.as_mut().expect("server metadata").display_name = "Team".into();
    Ok(())
}).await?;

Pages are zero-based, carry server pagination metadata, and all fetches lazily. Unsupported filters and pagination without progress fail explicitly. References encode exactly one name or UID. Organization Space creation qualifies short names with .cordium through SpaceOptions::organization.

Snapshots are taken online without stopping a Workspace. Wait for READY, then create with WorkspaceOptions::snapshot. A Volume is independent persistent storage, belongs to one Space and Region, and may require its first mount before provisioning. Shared volumes require a shared storage backend. Capacity cannot shrink. Template pre-build waits take an explicit ID to avoid mistaking a prior successful build for the requested one.

§Deadlines, cancellation, and errors

OperationDefault deadline
Unary SDK call, including authentication30 seconds, configurable on ClientBuilder.
Authentication/refresh exchange30 seconds, configured on the transport builder.
Workspace run or readiness wait300 seconds total, configured with WaitOptions.
File transfer300 seconds total.
Execution and server streamsUnlimited; set their total deadline explicitly.

Durations are std::time::Duration; None disables a deadline. Positive finite representable durations are required. Composite waits and stream deadlines cover all their work rather than restarting on each event. Polling is used for resources that do not publish readiness events; workspace watch streams are also exposed. Drop a pending future/stream to cancel, or use tokio::select! with your own cancellation signal. Streams progress when polled.

Client::close() cancels high-level SDK calls and subscriptions across clones, clears local credentials, and prevents new calls. Connections are released when all owners drop. Existing generated RPC calls and HTTP responses obtained through escape hatches have their own transport lifetimes and should be dropped directly. No remote resource is implicitly deleted and closing does not log out a Session.

Error is a non-exhaustive enum. Status preserves tonic status codes, details, and metadata; code() exposes known gRPC codes. CommandFailed keeps binary output and exit status, and WorkspaceFailed includes the last full resource. Caller cancellation is normal Rust future cancellation; no synthetic success or silent output loss is substituted. Non-idempotent API calls are never replayed.

§HTTP and extension APIs

With the default http feature, client.http() authenticates requests to workspace application URLs. The Octelium policy accepts HTTPS for the cluster domain and its subdomains; alternate hosts require explicit authorization through configure_transport. Use a request timeout and stream large response bodies. HTTP error status codes remain available on the reqwest response.

main_service, workspace_service, management_service, and transport are escape hatches. Generated clients authenticate automatically, but high-level SDK operation deadlines/cancellation are not applied to those raw calls. The proto, meta, and prost_types re-exports keep model and runtime versions aligned. The generated API crate is pinned to its tested version because additive protobuf fields can change Rust struct construction. Regenerate, update that pin, and run the workspace checks together when upgrading the API schema.

FeatureDefaultPurpose
httpyesAuthenticated reqwest HTTP client for applications.
tls-native-rootsyesHost certificate store for gRPC TLS.
tls-webpki-rootsnoBundled webpki roots for gRPC TLS.

No blocking facade or hidden runtime is created. Async clients work with a Tokio runtime, including a current-thread runtime. Reuse one client per cluster, then clone it cheaply for concurrent tasks.

§Examples and development

The examples include quickstart, streaming commands, lazy workspace listing, template pre-builds, and HTTP applications.

cargo run -p cordium --example quickstart
cargo test --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all --check
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps
python3 scripts/generate-cordium.py ../pb --check

Public APIs are documented in rustdoc, and missing public documentation is a compile error. Integration tests run real generated tonic servers and POSIX shell processes on loopback, including binary transfers and authentication cancellation. A real cluster smoke test remains a release check; local tests do not verify a particular cluster’s policies, storage backend, or deployment.

Release dependency order: octelium-apis 0.1.4, octelium 0.2.0, then cordium 0.3.0. Packaging all workspace crates together verifies the local dependency chain. Nothing is committed or published by the development commands above.

Re-exports§

pub use reqwest;
pub use octelium_apis::prost_types;
pub use tonic;

Modules§

meta
Common protobuf metadata, references, and list options. The octelium.api.main.meta.v1 protobuf package.
proto
Complete generated Cordium v1 messages and gRPC clients for advanced uses. The octelium.api.main.cordium.v1 protobuf package.

Structs§

AccessToken
Credential implementations and extension traits shared with the Octelium client. A bearer token for the Octelium Cluster and its known expiration time.
AccessTokenProviderFn
Credential implementations and extension traits shared with the Octelium client. An AccessTokenProvider backed by a closure.
Application
A named TCP application exposed through the Cordium HTTPS proxy.
Assertion
Credential implementations and extension traits shared with the Octelium client. Authenticates with a signed assertion, such as an OIDC ID token.
AuthenticationToken
Credential implementations and extension traits shared with the Octelium client. Exchanges a Credential authentication token for a Cluster Session.
Bytes
Reference-counted binary buffers used by streams and execution results. A cheaply cloneable and sliceable chunk of contiguous memory.
BytesMut
Reference-counted binary buffers used by streams and execution results. A unique reference to a contiguous slice of memory.
Client
Shared authenticated client. Cloning shares connections, credentials and shutdown.
ClientBuilder
Configures authentication, transport, and default unary RPC deadlines.
EventStream
An owned, backpressured async stream. Dropping it cancels its RPC.
ExecBuilder
Configures a command. Awaiting this builder collects output with bounded capture.
ExecInput
Clonable write/kill half of an exec session. Writes are serialized and chunked. Dropping an input handle does not send EOF; only dropping the session cancels the RPC.
ExecResult
Collected binary output and the command’s exit status.
ExecSession
An owned command output stream with bounded capture and an independent input half.
Files
Files transferred through the Workspace shell, with literal paths and bounded memory.
GitProviders
Git hosting OAuth2 provider configuration.
HttpClient
HTTP request and response types used by the authenticated application client. An HTTP client that attaches the Octelium access token to authorized destinations.
ListOptions
Pagination and filter configuration. Construct with Default and builder methods.
LogEntry
A single entry of a Workspace’s initialization logs.
Management
Cluster-wide administrator API.
Memberships
Space users and access roles.
Page
A single server page. Page numbering starts at zero.
Regions
Available cluster Regions that can host Workspaces.
RequestBuilder
HTTP request and response types used by the authenticated application client. Builds a request that carries the Octelium access token.
Resources
Compute allocations. Unset dimensions inherit platform defaults.
Secrets
Write-only Space secrets. Reads return metadata without sensitive content.
Snapshots
Point-in-time snapshots of private persistent workspace storage.
SpaceOptions
Options for Space creation. All complete protobuf spec fields remain available.
Spaces
Space namespaces, limits, runtime configuration, and membership.
StartOptions
Run-specific variables and placement; they do not alter the stored spec.
StaticAccessToken
Credential implementations and extension traits shared with the Octelium client. One externally managed access token with no known expiration time.
StreamOptions
Settings for a server stream. Streaming is unlimited in duration by default.
Task
A lifecycle shell task, configured using consuming builder methods.
Templates
Reusable workspace specifications and asynchronous pre-builds.
Terminal
An attached PTY event stream. Drop detaches; only remove terminates the persistent shell.
TerminalInput
A clonable terminal write/resize half, usable while another task consumes output.
TerminalOptions
Initial PTY dimensions and subscription deadline.
Terminals
Persistent Workspace terminals. Multiple callers may attach to the same shell.
UserConfig
User preferences, dotfiles, and runtime defaults.
UserSecrets
Personal write-only secrets and cluster-generated SSH key pairs.
VolumeOptions
Capacity, concurrency and placement options for a persistent Volume.
Volumes
Space-owned persistent volumes that outlive Workspaces.
WaitOptions
Total deadline and polling interval for composite operations.
Workspace
A cheap-to-clone Workspace handle with a shared, locally cached resource snapshot.
WorkspaceOptions
Workspace or Template configuration. Options override the matching fields of a base spec.
Workspaces
Workspace collection. Workspaces are created stopped with server-assigned names.

Enums§

Command
An explicit shell command or safely quoted argument vector.
EnvValue
An environment value supplied literally or resolved from a Space Secret.
Error
An SDK, transport, API, or command failure. New variants may be added.
ExecEvent
Binary command output or an explicit process exit event.
ListFilter
Resource list filter. A single enum prevents conflicting filters.
LogStage
The initialization stage that produced a log entry.
LogStream
The output stream on which a log entry was emitted.
Member
Target User of a new Space membership.
OrderBy
Sort key used by resource lists.
Reference
Exactly one resource name or cluster-wide UID. Strings convert to names.
Role
Generated Space membership role enum. Role is the level of access that the Member has inside the Space
SharingMode
Audience allowed to access a shared named Application.
SpaceMode
Which relationship selects Spaces in a list.
State
Generated lifecycle state enum. Unknown future values remain available in the raw status. State is the current state of the Workspace’s lifecycle
TaskPhase
When a lifecycle task runs.
TerminalEvent
Output, resize, or closure event from a persistent PTY shell.
WorkspaceEvent
A create, update or delete event of a watched Workspace.

Traits§

AccessTokenProvider
Credential implementations and extension traits shared with the Octelium client. Supplies externally managed Octelium access tokens.
Authenticator
Credential implementations and extension traits shared with the Octelium client. Creates a Cluster Session.
HttpAuthorizationPolicy
HTTP request and response types used by the authenticated application client. Decides whether an HTTP request may receive the Octelium access token.

Functions§

shell_quote
Quotes one literal POSIX shell word. NUL cannot be represented and is rejected.

Type Aliases§

Result
Result returned by Cordium SDK operations.