Struct CanopyClient 

pub struct CanopyClient { /* private fields */ }

HTTP client with auth configured for talking to a canopy server.

Tries two auth paths in order of preference:

1. Tailscale: if the canopy tailnet endpoint is reachable, plain HTTPS works (auth is implicit via tailscale identity).
2. mTLS: a fresh self-signed cert from the device key, short-lived ([CERT_VALIDITY_DAYS]); for long-running daemons, Self::renew should tick on CERT_RENEW_AFTER to swap in a fresh cert before expiry.

Self::refresh re-probes tailscale and swaps modes on reload.

Implementations

impl CanopyClient

pub async fn new( device_key_pem: Option<&str>, make_builder: impl Fn() -> ClientBuilder + Send + Sync + 'static, ) -> Result<Option<Self>>

Build a canopy client against the default public (DEFAULT_CANOPY_URL) and tailscale (TAILSCALE_URL) endpoints. Use Self::with_urls to override them.

Probes the tailscale endpoint first; if reachable, uses it. Otherwise, if a device key PEM is provided, builds an mTLS client. Returns Ok(None) if neither path is available.

make_builder supplies the base reqwest::ClientBuilder — see ClientBuilderFactory.

pub async fn with_urls( base_url: Url, tailscale_url: Url, device_key_pem: Option<&str>, make_builder: impl Fn() -> ClientBuilder + Send + Sync + 'static, ) -> Result<Option<Self>>

Build a canopy client against explicit endpoints.

base_url is canopy’s public API URL (the registration’s api_url), used on the mTLS path; tailscale_url is the tailnet endpoint used on the tailscale path. Both are fixed for the client’s lifetime. See Self::new for the other arguments and the default-endpoint form.

pub async fn is_tailscale(&self) -> bool

Returns true if the client is currently using the tailscale path.

pub async fn refresh(&self) -> Result<()>

Re-probe tailscale and swap modes if the picture has changed.

Intended to be called when the daemon receives a reload signal.

pub async fn renew(&self) -> Result<()>

Rebuild the underlying HTTP client with a fresh certificate.

No-op in tailscale mode (no cert to rotate). In mTLS mode, atomically replaces the live client; in-flight requests continue with the old client until they complete.

impl CanopyClient

pub async fn artifacts( &self, version: &str, artifact_type: &str, platform: &str, ) -> Result<Artifact>

Register a downloadable artifact for a version or version range.

Requires a device certificate with the releaser role (or admin). The path identifies the version the artifact belongs to — either an exact version (e.g. 2.10.5) or a semver range pattern (e.g. 2.10.x, ^2.10.0) — followed by the artifact’s type and target platform. The request body is the plain-text URL clients should download the artifact from.

When an exact version is given and it doesn’t exist yet, it is created automatically as an unpublished draft so the artifact has a version to attach to; publishing that version later (via the version-creation endpoint) is a separate step. When a range pattern is given instead, the artifact isn’t tied to one version — it matches whichever published version currently satisfies the range at lookup time.

Returns the created artifact record. Returns 400 if the version or range syntax can’t be parsed.

POST /artifacts/{version}/{artifact_type}/{platform}

pub async fn backup_capabilities( &self, body: &BackupCapabilitiesArgs, ) -> Result<()>

Register the backup types this server can run.

Declares the set of backup types the calling device is able to execute on its server. Types not seen before are added to the server’s capability set, starting out enabled or disabled according to the fleet-wide default for that type (disabled if the type has no default configured). Types already registered keep whatever enabled/disabled state an operator has set for them, so re-registering on every startup is safe and expected.

Only types that are registered here (and enabled) can later be issued credentials via POST /backup-credentials, outside of explicit operator-requested runs.

Errors: 412 when the calling device is not bound to a live server; 409 when the server is not in a group.

POST /backup-capabilities

pub async fn backup_credentials( &self, body: &BackupCredentialsArgs, ) -> Result<CredentialProcessOutput>

Mint short-lived S3 credentials for a backup or restore run.

Issues temporary AWS credentials scoped to the backup storage of the calling server’s group, in the credential_process output format. With purpose: backup the credentials can upload and manage backup data but cannot destroy existing backups; with purpose: restore they are strictly read-only. They expire after at most one hour, so request a fresh set for each run rather than caching them. Every issuance is recorded for audit.

The storage coordinates the credentials apply to (bucket, prefix, region) come from GET /backup-target.

Errors: 409 when the server is not in a group, when the group’s backup configuration is not ready, or when the requested type is neither an enabled capability of this server nor the subject of a pending operator-requested run of the given purpose; 412 when the device is not bound to a live server; 502 when the credential issuer is unavailable or not configured.

POST /backup-credentials

pub async fn backup_report(&self, body: &ReportArgs) -> Result<()>

Report the outcome of a backup or restore run.

Records the run against the calling server and its group. Send one report per run, on success and on failure alike. Reporting also clears any pending operator-requested run for the same type and purpose — regardless of outcome, since an operator request is for one attempt — so the server’s status responses stop asking for it (see the backup_now field of the status-push response).

Errors: 409 when the server is not in a group, or when the run_id has already been reported; 412 when the device is not bound to a live server.

POST /backup-report

pub async fn backup_target(&self) -> Result<BackupTarget>

Fetch the backup storage target for this server’s group.

Returns the bucket, prefix, region, and repository passphrase the device needs to connect to its group’s backup repository. Call it on every run rather than caching the result, as the target can change. S3 credentials are obtained separately via POST /backup-credentials.

Errors: 409 when the server is not in a group or the group’s backup configuration is not ready; 412 when the device is not bound to a live server; 502 when the passphrase store is unavailable or not configured.

GET /backup-target

pub async fn bestool_snippets(&self) -> Result<Value>

List all current bestool SQL snippets.

Returns the library of named SQL snippets that devices running bestool fetch and run, keyed by snippet name. Only the current version of each snippet is included: if a snippet has been superseded by a newer one under the same name, only the newer version is returned, and soft-deleted snippets are omitted entirely. This endpoint does not require device authentication.

GET /bestool/snippets

pub async fn events(&self, body: &NewEvent) -> Result<Issue>

Report an event against the calling device’s server.

Requires a device certificate with the server role (or admin). Used to push a status update — a healthcheck result, an alert condition, or a “condition cleared” notice — which canopy records as an issue and, if the server belongs to a group, may fold into an incident. An event with the same source and ref as an already-open issue on this server updates that issue instead of opening a new one.

The calling device must already be enrolled against exactly one server, otherwise the request fails with 412. The source value "manual" is reserved for operator-entered events and is rejected with 400 here, as is an empty ref.

Returns the issue the event was recorded against (existing or newly created).

POST /events

pub async fn restore_capabilities( &self, body: &RestoreCapabilitiesArgs, ) -> Result<()>

Register the restore intents this device can satisfy.

Declares the restore intents the calling device supports, replacing any previously advertised set. Only worklist entries whose intent is currently advertised are dispatched to this device via GET /restore-worklist, so register on startup and whenever the supported set changes.

POST /restore-capabilities

pub async fn restore_credentials( &self, body: &RestoreCredentialsArgs, ) -> Result<RestoreCredentials>

Mint read-only credentials for a group’s backup repository.

Issues temporary AWS credentials — always strictly read-only, scoped to the group’s backup storage — together with the repository passphrase, so the device can read the snapshot named in a worklist entry. Credentials expire after at most one hour; request a fresh set per restore rather than caching them. Every issuance is recorded for audit.

The device must hold an enabled restore declaration covering the requested group and type (i.e. the pair must appear in its worklist configuration); otherwise the request is rejected with 403.

Errors: 403 when no enabled declaration authorizes this group and type; 409 when the group has no ready backup configuration; 502 when the credential issuer or the passphrase store is unavailable or not configured.

POST /restore-credentials

pub async fn restore_verification(&self, body: &VerificationArgs) -> Result<()>

Report the outcome of a restore attempt and the replica’s health.

Records a verification report for a restore the device performed from its worklist. Send one report per attempt, on success and on failure alike. A report with a success outcome and replica_healthy: true marks the snapshot as verified; for run-once intents this is what removes the entry from GET /restore-worklist until a newer snapshot appears.

Authorization matches POST /restore-credentials: the device must hold an enabled restore declaration covering the reported group and type, otherwise the request is rejected with 403.

POST /restore-verification

pub async fn restore_worklist(&self) -> Result<Vec<WorklistEntry>>

Fetch the full set of replicas this device should maintain.

Returns the device’s complete desired state, computed fresh on every call: each enabled restore declaration whose intent this device currently advertises, expanded into one entry per server it covers. A group-wide declaration expands to every live server in its group; a server-scoped declaration yields a single entry and takes precedence over a group-wide one covering the same server, type, and intent. Entries for groups whose backup configuration is not ready are omitted, and entries for run-once intents disappear once the latest snapshot has a healthy verification report, reappearing when a newer snapshot exists.

An empty array means there is nothing to do. Poll this endpoint and reconcile: create or refresh the replicas listed, and tear down any the device is maintaining that no longer appear.

GET /restore-worklist

pub async fn servers(&self) -> Result<Vec<PublicServer>>

List publicly-listed central servers.

Returns every central server that has both a public display name and a reachable host configured, ordered by environment tier (production first, then clone, demo, test, dev) and then by name. Used by clients to let a user pick which server to connect to.

GET /servers

pub async fn servers_register_begin( &self, body: &BeginArgs, ) -> Result<BeginResponse>

Start device enrollment against a server.

Validates the enrollment token against the given server and, if valid, issues a short-lived (5 minute) signed challenge bound to the server ID, the token, and the caller’s public key. The device must sign this challenge and submit it to the completion endpoint to finish enrollment; the token itself is validated here but not yet consumed.

This endpoint is rate-limited per source IP and per target server; a tripped limit returns 429. Any other failure — an unknown or deleted server, or an invalid or expired token — is surfaced as a generic 403, deliberately not distinguishing which check failed.

POST /servers/register/begin

pub async fn servers_register_complete( &self, body: &CompleteArgs, ) -> Result<CompleteResponse>

Complete device enrollment by presenting a signed challenge.

Verifies the signature over the challenge transcript using the public key supplied here, then binds the device to the server: an existing device re-enrolling with the same key is reused as-is; a device re-enrolling with a different key replaces the server’s previous device (revoking that device’s access); otherwise a new device identity is created. On success the device is granted the server role, the enrollment token is consumed, and the server is marked as registered.

Enrollment is refused if the presented public key is already bound to a different live server. Like the start-enrollment endpoint, this one is rate-limited per source IP and per target server (429 on a tripped limit) and reports every other kind of failure as a generic 403.

POST /servers/register/complete

pub async fn status( &self, server_id: &str, body: &Value, ) -> Result<StatusResponse>

Submit a status heartbeat for a server.

Records a periodic status push against the server identified in the path: overall self-reported health, a per-check breakdown, and any free-form extra data. Each failed or warning check opens (or keeps open) an issue at that check’s operator-configured severity, and each passed check closes any issue it previously opened; the server’s tracked software version is also updated from the payload.

The calling device must be the one enrolled for this exact server (or hold the admin role). The response echoes back the stored status record, plus a backup_now list of backup types the server should back up immediately — devices should treat a non-empty list as a prompt to run those backups and report them afterwards.

POST /status/{server_id}

pub async fn tags(&self) -> Result<TagMap>

Get the tags for the calling device’s own server.

Returns the effective set of tags for the server the calling device is registered as: any tags set on the server itself, overlaid onto any tags inherited from its server group (a tag set on the server takes precedence over a group tag with the same key). If the server isn’t in a group, this returns just its own tags.

The result also includes a few read-only, synthetic tags describing the server, under the reserved canopy: key prefix: canopy:kind, canopy:rank (if the server has one set), and canopy:group-id / canopy:group-name (if the server belongs to a group). Operators cannot set tags under that prefix, so these never collide with tags you set yourself.

• 401: the request has no client certificate, or the certificate doesn’t match a known device.
• 409: the calling device is attached to more than one server, which should not normally happen; contact support if you see this.
• 412: the device is registered but has not yet been attached to a server.

GET /tags

pub async fn get_versions(&self) -> Result<Vec<Version>>

List published, ready-to-serve versions.

Returns every version currently in the published state, excluding any version a recorded known-issue range still covers (whether that issue is still open or has since been fixed in a later patch). Ordered newest first.

GET /versions

pub async fn versions_update_for( &self, version: &str, ) -> Result<Vec<ViewVersion>>

Check for available updates from a given version.

The path parameter is the caller’s currently-installed exact version. For each later minor release line within the same major version, returns the latest published version that hasn’t been excluded by a recorded known-issue range — falling back to an older ready patch within that same minor line rather than dropping the line entirely, if the newest patch isn’t ready. Clients use this to discover and offer available updates.

GET /versions/update-for/{version}

pub async fn delete_versions(&self, version: &str) -> Result<()>

Yank a version.

Requires a device certificate with the admin role. Marks the given exact version as yanked, hiding it from listings, update checks, and artifact lookups without deleting its history.

DELETE /versions/{version}

pub async fn post_versions(&self, version: &str) -> Result<Version>

Publish a version with its changelog.

Requires a device certificate with the releaser role (or admin). The path parameter is the exact version being published (e.g. 2.10.5); the request body is the changelog for that version, as up to 1 MiB of markdown text.

If the version already exists in the draft state — for example because an artifact was registered against it before its changelog was written — the draft is published in place, with this changelog replacing whatever it had before. Otherwise a new version is created directly in the published state. Publishing a version that already exists and is not a draft (already published, or yanked) fails.

Returns the resulting version record.

POST /versions/{version}

pub async fn versions_artifacts(&self, version: &str) -> Result<Vec<Artifact>>

List the artifacts available for a version or version range.

The path parameter accepts either an exact version or a semver range pattern (e.g. 2.10.x, ^2.10.0). It resolves to the latest published, ready version satisfying the input, then returns that version’s artifacts — both ones registered against the exact version and ones registered against a range pattern that covers it. Returns 404 if no published, ready version matches.

GET /versions/{version}/artifacts

Trait Implementations

impl Debug for CanopyClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.