Crate hws 

A client for the app-lb admin API.

app-lb is a load balancer for heyvm Firecracker/KVM microVMs. This crate drives it: register deployments, scale pools, run commands inside a VM, and attach an interactive shell.

It is also the library behind the heyctl CLI, which is the point — the CLI is this crate’s first consumer, so a field the client stops understanding becomes a compile error rather than a silently blank column at somebody’s terminal.

use hws::{Client, ExecRequest};

let lb = Client::builder("127.0.0.1:9090")
    .token(std::env::var("APP_LB_TOKEN").unwrap())
    .build()?;

let out = lb.exec("sb-7f3a9c", &ExecRequest::new("uname -a")).await?;
println!("{}", out.stdout);

Authentication

Prefer an app-token: scoped to particular deployments, revocable without a restart, and optionally expiring. Basic auth also works and is unscoped — it is the operator credential, and the one that mints tokens.

use hws::{AdminScope, Client, NewToken};

let admin = Client::builder("127.0.0.1:9090").basic("admin", "s3cret").build()?;
let minted = admin.mint_token(
    &NewToken::new("agent-runner")
        .admin(AdminScope::Admin)
        .for_deployments(["sb-7f3a9c"]),
).await?;

// The secret is in the reply and nowhere else, ever.
println!("{}", minted.token);

A token scoped to specific deployments is refused the fleet-wide routes — including minting — so it cannot widen itself.

Blocking callers

Everything here is async. Under the blocking feature, blocking::Client is the same surface with the awaits taken out.

What this crate does not smooth over

Three behaviours of app-lb are surprising enough that hiding them would be worse than surfacing them:

• A non-zero exit code from Client::exec is Ok, not Err. The command ran; it failed.
• exec’s timeout does not kill anything. It bounds app-lb’s call to the daemon — on expiry you get Error::Upstream and the command keeps running in the guest.
• A shell socket has no resume. If it drops, the session is gone; reconnecting gives a new shell. See shell.

Re-exports

pub use api::Client;

pub use api::ClientBuilder;

pub use api::ExecRequest;

pub use api::Gates;

pub use api::MetricsQuery;

pub use api::NewToken;

pub use error::Credential;

pub use error::Error;

pub use error::Result;

pub use shell::Shell;

pub use shell::ShellEvent;

pub use shell::ShellExit;

pub use shell::ShellOptions;

pub use transport::Auth;

pub use transport::Transport;

pub use wait::JobProgress;

pub use wait::PoolProgress;

pub use types::*;

Modules

api

The admin API, as methods.

artifactartifact

The HTTP client for an artifact store (art serve).

blockingblocking

The same surface, without await.

configconfig-file

The heyctl config file: named contexts, kubeconfig-style.

error

What can go wrong, as something a caller can branch on.

shell

An interactive PTY in a sandbox, over a WebSocket.

spec

Read-modify-write helpers over a deployment spec as a serde_json::Value.

transport

The seam between the API surface and an actual socket.

types

Read-side views of the admin API’s JSON.

wait

Waiting for things to converge.

Constants

DEFAULT_NAMESPACE

The namespace an object belongs to when nothing says otherwise.