Crate hws 

The Heyo Web Services SDK: a client for the app-lb admin API.

app-lb is a load balancer for heyvm Firecracker/KVM microVMs, and the door to everything a Heyo namespace runs. This crate drives it: create and replace workloads (Client::create_deployment, Client::start_rollout), scale pools, build and pull their images, run commands inside a VM, attach an interactive shell, and read their metrics and logs (Client::obs).

Every call works with a namespace-scoped token — the credential a tenant is handed — and is narrowed by the server to that namespace.

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 gate::Gate;

pub use gate::GatePath;

pub use obs::LogQuery;

pub use obs::NewAlert;

pub use obs::OBS_PLUGIN;

pub use obs::ObsClient;

pub use artifacts::ARTIFACTS_PLUGIN;

pub use artifacts::ArtifactsClient;

pub use postgres::NewDatabase;

pub use postgres::POSTGRES_PLUGIN;

pub use postgres::PostgresClient;

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).

artifacts

A namespace’s corner of the global artifact store, through app-lb’s artifacts plugin.

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.

gate

Putting a deployment behind sign-in, from a program.

images

heyvm’s image catalog, through app-lb: /images.

obs

Namespace plugins, and the telemetry the obs plugin collects.

postgres

A namespace’s Postgres databases, through app-lb’s postgres plugin.

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.