app-lb API reference

These pages document every app-lb admin endpoint that the hws Rust crate calls, one resource per page, with the request each endpoint takes, the response it returns, the errors it answers with, and the crate method that wraps it.

HTTP API is the companion page. It covers base URLs, the managed namespace door, credentials, tiers and confinement in depth, and lists routes the crate does not call (retirement, route handoffs, disk mutations, fleet views, security rules, releases). These pages stay with the crate's surface and go one level deeper on each endpoint.

Pages

The client

[dependencies]
hws = { version = "0.2", default-features = false }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

The default feature set is cli, which links everything heyctl needs. A library consumer turns it off and picks what it uses:

use hws::{Client, ExecRequest};

let lb = Client::builder("https://admin.us5.heyo.work")
    .token(std::env::var("APP_LB_TOKEN")?)
    .build()?;

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

Client::builder(server) accepts a URL or a bare host:port, which becomes http://host:port. Trailing slashes are dropped. Through the managed door, the server is https://server.heyo.computer/namespaces/{ns}/lb and the token is a heyo_api_… key.

Client is cheap to clone. Client::with_transport builds one over any Transport (a stub, a recorder, a proxy); a client built that way cannot open shells.

Wire conventions

The crate follows these rules on every request. A client in another language should follow them too.

• Path segments are percent-encoded. Everything except A–Z a–z 0–9 - _ . ~ is escaped, so an id containing / or ? cannot address a different route. A static upstream such as us1.internal:8080 goes out as us1.internal%3A8080.
• Bodies are JSON with Content-Type: application/json. The job routes (build, pull, mounts/pull, update) get {} even when there is nothing to say. app-lb reads those bodies as optional, and a body with no content type is silently treated as absent rather than rejected, so a ref sent without the header would be lost.
• Query booleans are true or false. app-lb parses them strictly: ?force=1 is a 400, not a truthy value.
• Reads are typed, writes are serde_json::Value. PUT /deployments/:id replaces the whole spec. A client that parsed a spec into a struct and wrote it back would drop every field it did not know. The write methods take a Value and send it verbatim. To edit, read the raw spec, change it, and send it back (see Replace a deployment).
• Read types are lenient. Every field defaults, and fields this build does not name land in an extra map instead of being discarded. The crate's tests read app-lb's own response fixtures (app-lb/testdata/wire/) and fail if extra is not empty, so a field the crate stops understanding fails a test.
• Client::raw() returns responses as unparsed JSON. Use it to print a response or to read the half of a read-modify-write. Each page lists the Raw method next to the typed one where there is one.

Errors

app-lb answers a failure with {"error": "…"} from its handlers, or with plain text from the gate (401) and the framework (400 malformed JSON, 415 missing content type, 422 wrong shape, 413 too large). The crate tries the envelope, falls back to the text, and maps the status to a variant of hws::Error:

Errors raised without a response: Transport (no answer), Decode (a 2xx whose body did not parse), Shell (the WebSocket failed), Timeout (a wait_for_* helper gave up) and Invalid (bad input caught before sending, such as a blank exec command or an unnamed token).

Error::is_retryable() is true for ColdStartTimeout, Upstream and Transport only. A 409 is not retryable: the job that is running will still be running. Error::is_auth() is true for 401 and 403. Error::status() returns the HTTP status where there was one.

Waiting

Builds, pulls and spec changes return before the work is done. Two helpers poll for you:

Polling starts at 100 ms and doubles up to 3 seconds for jobs and 2 seconds for pools. .poll_every(d) fixes the interval, .timeout(d) changes the deadline, and .on_progress(f) gets each poll (for jobs, only the log lines that are new since the last call). Both builders can be awaited directly.

let job = lb.start_pull("demo", None, false).await?;
let done = lb.wait_for_job(&job.id)
    .in_deployment(&job.deployment)
    .on_progress(|p| for line in p.new_log { println!("{line}") })
    .await?;
if done.status != "succeeded" {
    eprintln!("pull failed: {:?}", done.error);
}
lb.wait_for_ready("demo").await?;

Use .in_deployment with a namespace token: app-lb releases before confined access to GET /jobs/:id refuse it that route, but always allow the deployment's job list.

Endpoint index

Tiers in these pages use the names from HTTP API: Tiers: View, CRUD, and operator for routes that need an unconfined credential.