Struct HeadscaleClient 

pub struct HeadscaleClient { /* private fields */ }

HTTP client for a running Headscale coordinator.

The Headscale REST API lives at <server_url>/api/v1/…. Requests are authenticated with an API key in the Authorization: Bearer <key> header. The API key must be created on the coordinator with headscale apikeys create or the equivalent API call; store it in the vault as headscale-api-key.

Implementations

impl HeadscaleClient

pub fn new( base_url: impl Into<String>, api_key: impl Into<String>, ) -> Result<Self>

Construct a client from explicit credentials.

pub fn from_vault_or_env() -> Result<Option<Self>>

Open a client from the vault (slot headscale-api-key + mesh-url) with env-var fallbacks (HEADSCALE_API_KEY + HEADSCALE_URL).

Returns Ok(None) when either credential is absent — callers can decide whether that’s fatal.

pub async fn create_preauth_key( &self, user: &str, tags: &[String], ) -> Result<PreauthKey>

Generate a single-use pre-auth key for the given ACL tags.

The key expires in 1 hour and is non-reusable — suitable for one-shot machine onboarding via cloud-init. Each yah cloud machine provision call that uses Headscale mesh should request its own key.

pub async fn list_nodes(&self) -> Result<Vec<NodeInfo>>

List all nodes currently in the tailnet.

Uses Headscale’s GET /api/v1/node (the endpoint was renamed from the pre-v0.23 /api/v1/machine, with the response key machines → nodes, when Headscale retired “machine” for “node”). The per-node JSON shape is otherwise unchanged (id, name, ipAddresses, online).

pub async fn list_users(&self) -> Result<Vec<String>>

List the Headscale users (namespaces) preauth keys can be minted against.

GET /api/v1/user. Headscale scopes every preauth key to a user, and a key minted against a user that does not exist fails at mint time.

pub async fn resolve_user(&self, preferred: Option<&str>) -> Result<String>

Resolve the user to mint a preauth key against, asking the coordinator instead of assuming a name.

R608-B19: this used to be the literal "default" at the yah cloud machine provision call site, and against the live coordinator that is simply wrong — POST /api/v1/preauthkey answers 500 for a user that does not exist. The two halves of the system disagree on the name: crate::mesh’s camp-local yah mesh start path creates default (its --user default), while yah mesh bootstrap creates yah (mint_bootstrap_preauth_key in yubaba’s lib.rs runs headscale users create yah). The production coordinator was bootstrapped, so it has only yah — every provision against it would have failed at the preauth step with an opaque 500.

Rather than swap one hardcoded guess for the other:

• preferred present and known to the coordinator → use it;
• preferred absent and the coordinator has exactly one user → use it, which is every yah mesh in existence today;
• otherwise → error naming the users that DO exist, so the operator can pick, instead of a 500 that names nothing.

pub async fn health(&self) -> HeadscaleHealth

Light health check — HEAD or GET the Headscale root, no auth required.