Rust client SDK

Add the client#

[dependencies]
silicon-honeycomb-client = "0.1.0"
anyhow = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

The compilable examples are checked with the workspace.

The crate is imported as silicon_honeycomb_client. It re-exports the core model and package types. Source and API signatures provide the exact current interface.

Search with typed results#

use silicon_honeycomb_client::Client;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Client::new(
        "https://backend.honeycomb.teamofsilicons.com"
    )?.with_telemetry(false);
    let page = client.search("briefcase", 1, false).await?;
    for app in page.items {
        println!("{}: {}", app.app_id, app.name);
    }
    Ok(())
}

managed = false searches the visible catalog; true asks for the caller's managed applications. Client::new validates the origin and requires HTTPS outside loopback. The client declares API/client versions automatically and does not follow redirects carrying credentials.

Attach authorization#

async fn example() -> anyhow::Result<()> {
use silicon_honeycomb_client::Client;
let client = Client::new("https://backend.honeycomb.teamofsilicons.com")?;
let authenticated = client.with_token(std::env::var("HONEYCOMB_ACCESS_TOKEN")?);
let status = authenticated.login_status().await?;
assert_eq!(status["authenticated"], true);
Ok(()) }

This token must be a Honeycomb application session access token. Your application owns secure storage, refreshing, and revocation. The SDK does not read the CLI's session files. login(slt, mutation), refresh(refresh_token, mutation), and logout_session(...) expose the corresponding exchanges. Keep credential-bearing response values out of ordinary logs.

Explicit mutations#

async fn example() -> anyhow::Result<()> {
use silicon_honeycomb_client::{Client, Mutation};
use std::path::Path;
let client = Client::new("https://backend.honeycomb.teamofsilicons.com")?
    .with_token(std::env::var("HONEYCOMB_ACCESS_TOKEN")?);
let app = client.app("my-org>my-app").await?;
let mutation = Mutation {
    idempotency_key: "my-app-release-upload-0001".into(),
    revision: Some(app.revision),
};
let result = client.upload_release(
    &app.app_id, Path::new("my-app-1.0.0.tar.gz"), &mutation
).await?;
// Inspect accepted/pending state; do not log arbitrary credential results.
let _ = result;
Ok(()) }

Persist the mutation key and input before a request when crash recovery matters. Reuse that exact mutation when its outcome is uncertain. Mutation::new() generates a fresh key; creating a new one for every retry defeats idempotency. Mutation::at_revision(n) generates a key with a revision precondition.

Testing context#

fn example() -> anyhow::Result<()> {
use silicon_honeycomb_client::Client;
let client = Client::new("https://backend.honeycomb.teamofsilicons.com")?;
let isolated = client.with_environment(std::env::var("HONEYCOMB_TEST_KEY")?)?;
let _ = isolated;
Ok(()) }

The environment root key must be exactly 32 alphanumeric characters. The SDK sends X-Testing-Environment-Key; it never falls back to production if testing authorization fails. Some operations also require an appropriate user session.

Method families#

Local installation functions#

installer::install_archive_for(app_id, archive, state_dir, aliases, previous) installs an archive under the selected application ID. It validates and stages the payload, checks command collisions, and returns an Installed record. Your application owns the installation registry and concurrency lock. Pass the previous record for an update; do not overwrite another package's command. A command of the same name elsewhere on PATH returns installer::UnresolvedCommands when it is older than the package needs, carrying the version found and the version required so you can ask before acting; installer::install_archive_resolving(.., rewrite) performs the answered rewrite and records what it displaced. installer::uninstall(record, state_dir) removes only owned installation artifacts. The existing install_archive helper still works when the manifest declares app_id or a previous installation supplies it.

Client::download verifies hash, size, identity, and version and requires a destination that does not already exist. The maintenance module provides CLI release/update and service-registration helpers. A Rust library cannot replace a compiled dependency inside your running application; update dependency versions through your own build/release process.