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( tamanu_version: impl Into<String>, device_key_pem: Option<&str>, make_builder: impl Fn() -> ClientBuilder + Send + Sync + 'static, ) -> Result<Option<Self>>

Build a canopy client, preferring tailscale and falling back to mTLS.

Probes the tailscale canopy 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.

tamanu_version is the version of the Tamanu install this client speaks for; sent on every request via the X-Version header.

make_builder supplies the base reqwest::ClientBuilder — see ClientBuilderFactory. Use client_builder for a sensible default.

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.

pub async fn post_status( &self, base_url: &Url, server_id: &str, payload: &Value, ) -> Result<Vec<String>>

POST a status snapshot to the canopy server.

In tailscale mode, base_url is ignored and a {TAILSCALE_URL}/public/status/{server_id} URL is used. In mTLS mode, posts to {base_url}/status/{server_id}.

The payload is free-form JSON; the canopy /status contract reserves the top-level health: [] key, whose entries each carry a result of passed | warning | failed | broken | skipped. The body is gzip-encoded with Content-Encoding: gzip.

Returns backup_now: the backup-type names canopy says this server should back up right now (operator one-offs + schedule-due). Empty means nothing to do. A response that predates the field (no backup_now) yields an empty list, so older canopy deployments keep working.

pub async fn get( &self, base_url: &Url, tailscale_path: &str, mtls_path: &str, ) -> Result<Response>

GET a path on the canopy server, routed via tailscale when available.

In tailscale mode, the request goes to {TAILSCALE_URL}{tailscale_path} (typically /public/..., the only mount that accepts tagged-device tailscale callers). In mTLS mode, the request goes to {base_url}{mtls_path}.

Returns the raw response — the caller is responsible for status checks and body parsing so they can choose how to fall back if the response isn’t usable.

pub async fn post_event( &self, base_url: &Url, event: NewEvent<'_>, ) -> Result<()>

POST an event to the canopy server.

In tailscale mode, base_url is ignored and TAILSCALE_URL is used. In mTLS mode, posts to {base_url}/events.

pub async fn request( &self, method: Method, base_url: &Url, path: &str, ) -> Result<RequestBuilder>

Start a request to an arbitrary canopy endpoint on the current auth path.

This is the generic escape hatch behind the typed endpoint methods: it resolves the right HTTP client and URL for the active auth mode, begins the request, and sets the X-Version header. The returned builder is yours to finish — add query params, a body, or extra headers, then .send() and parse the response however suits.

path is the mTLS-mode path (e.g. /backup-target); over tailscale the same endpoint is mounted under /public, so this routes it there, the same convention the other endpoint methods follow.

pub async fn request_json<Res: DeserializeOwned>( &self, method: Method, base_url: &Url, path: &str, body: Option<&(impl Serialize + ?Sized)>, ) -> Result<Res>

Call an arbitrary canopy endpoint and parse its JSON response.

Builds the request via Self::request, attaches body as JSON when it’s Some, sends it, and on a 2xx response parses the body into Res. A non-success status becomes an error carrying the status and response body, matching the other endpoint methods. This absorbs the status-check and parse boilerplate.

Use serde_json::Value for Res (and/or the body) for fully dynamic calls, or any concrete type for typed calls. When passing no body, pin the inference with a turbofish, e.g. None::<&()>.

path follows the same mTLS/tailscale convention as Self::request.

pub async fn backup_capabilities( &self, base_url: &Url, types: &[String], ) -> Result<()>

Register the backup types this server can run (POST /backup-capabilities).

pub async fn backup_credentials( &self, base_url: &Url, backup_type: &str, purpose: Purpose, ) -> Result<BackupCredentials>

Obtain short-lived S3 credentials for a backup type (POST /backup-credentials).

Returns the credential_process-shaped creds; the caller translates them to the container-creds shape for kopia. 412/409/502 surface as errors.

pub async fn backup_target(&self, base_url: &Url) -> Result<TargetOutcome>

Fetch the S3 repo target (GET /backup-target).

412/409 mean the device isn’t yet authorised for backups; these map to TargetOutcome::Dormant (a benign idle state) rather than an error.

pub async fn backup_report( &self, base_url: &Url, report: &BackupReport<'_>, ) -> Result<()>

Report a completed backup/restore run (POST /backup-report).

pub async fn restore_capabilities( &self, base_url: &Url, intents: &[&str], ) -> Result<()>

Register the restore intents this consumer supports (POST /restore-capabilities).

Replaces the registered intent set wholesale. Canopy dispatches only matching worklist entries.

pub async fn restore_worklist( &self, base_url: &Url, ) -> Result<Vec<WorklistEntry>>

Fetch the desired-state worklist of replicas to restore (GET /restore-worklist).

pub async fn restore_credentials( &self, base_url: &Url, backup_type: &str, group: Uuid, ) -> Result<RestoreCredentials>

Obtain read-only S3 credentials and the repo password for a group (POST /restore-credentials).

Creds are 1-hour chained STS; refresh by re-calling. 403/409/502 surface as errors.

pub async fn restore_verification( &self, base_url: &Url, report: &RestoreVerification<'_>, ) -> Result<()>

Report a restore’s health (POST /restore-verification).

Trait Implementations

impl Debug for CanopyClient

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

Formats the value using the given formatter.