upcloud_api/
lib.rs

1//! **`upcloud-api` — the UpCloud API 1.3 surface as ONE trait, ONE wire, ONE
2//! decision about which cloud answers.**
3//!
4//! # Why this crate exists
5//!
6//! On 2026-09-21 the nordisk estates had **five** UpCloud clients:
7//! `private-gunnar-ops`'s xtask (two of them, until lane T3 made them one),
8//! `gunnar/deploy/upcloud` (the re-image procedure, with its OWN scripted fake),
9//! `gunnar-loadbench`, `private-holger-ops`'s xtask, and `monetize-cloud-impl`.
10//! Each one spelled `https://api.upcloud.com/1.3` for itself. Each one decided
11//! for itself whether a run was aimed at a fake. Four bugs that day were the
12//! same bug: **a mock run reached the account because one client in the chain
13//! decided differently from the rest** — the worst of them was
14//! `gunnar-upcloud`'s `Api::new(DEFAULT_BASE)`, so `cargo xtask mock reimage
15//! --apply` would have re-imaged the LIVE appliance with the estate's token
16//! while the banner said FAKE.
17//!
18//! A test against the fake is only worth something if the code under test is
19//! the SAME code that runs against the account. So:
20//!
21//! * [`UpCloudApi`] is the only surface. **No method takes a path, a query
22//!   string or a base URL**, so no caller can name an endpoint.
23//! * There is **one** wire implementation. It builds every request for the
24//!   account and for a mock the same way, from the same code — only the base
25//!   differs. A run against `mock-upcloud` therefore exercises the exact URL,
26//!   body and header construction a run against the account does.
27//! * The base comes from an [`Endpoint`], and an `Endpoint` is decided ONCE, at
28//!   the edge of the program, from what the operator TYPED
29//!   ([`Endpoint::account`] / [`Endpoint::mock`]). A mock endpoint is
30//!   loopback-only by construction; the account endpoint refuses to exist while
31//!   the shell carries a mock variable ([`MOCK_ENVS`]).
32//! * The in-process fake — `FakeUpCloud` over `mock-upcloud`'s `Estate` — lives
33//!   beside that state machine in the `mock-upcloud` crate, so a fault armed
34//!   once applies to terraform (the HTTP face) and to Rust callers (the trait
35//!   face) alike: one world, two faces.
36//! * [`guard`] is the test every consuming repository runs: nothing outside the
37//!   files it names may spell the provider or build an API path.
38//!
39//! # The method set is DERIVED, not designed
40//!
41//! Every method exists because a real call site in one of the ported clients
42//! calls that endpoint. The doc on each names the caller. A general-purpose
43//! UpCloud client is a second thing to keep true; this is not one.
44
45use std::path::Path;
46
47use serde_json::Value;
48
49pub mod guard;
50pub mod net;
51mod wire;
52
53pub use wire::{connect, Credential, Options};
54
55/// **The account.** Private: the one spelling of the provider in this crate,
56/// used by [`wire`] as the base of [`Endpoint::Account`]. A consumer can print
57/// it through [`ACCOUNT_BASE_FOR_DISPLAY`] and can build nothing from it.
58const ACCOUNT_BASE: &str = "https://api.upcloud.com/1.3";
59
60/// The account's base, for a REPORT and a display comparison — never to build a
61/// request from; nothing can be called on a `&'static str`.
62pub const ACCOUNT_BASE_FOR_DISPLAY: &str = ACCOUNT_BASE;
63
64/// The variable a mock-selected run reads its loopback base from. On an
65/// account-selected run its PRESENCE is a refusal ([`Endpoint::account`]).
66pub const MOCK_BASE_ENV: &str = "UPCLOUD_API_BASE";
67
68/// The terraform provider's own debug knob. Not read here — named so an
69/// account run can refuse when the shell carries it.
70pub const TF_MOCK_BASE_ENV: &str = "UPCLOUD_DEBUG_API_BASE_URL";
71
72/// Every variable whose presence means "this shell is aimed at a fake".
73pub const MOCK_ENVS: &[&str] = &[MOCK_BASE_ENV, TF_MOCK_BASE_ENV];
74
75// ── the endpoint: decided once, at the edge ─────────────────────────────────
76
77/// **Which UpCloud answers.** Built only by [`Endpoint::account`] (refuses in a
78/// mock-carrying shell) or [`Endpoint::mock`] (refuses anything off loopback).
79#[derive(Debug, Clone, PartialEq, Eq)]
80pub enum Endpoint {
81    /// `https://api.upcloud.com/1.3`. Real machines, a real bill.
82    Account,
83    /// A `mock-upcloud` on loopback. The base always ends `/1.3`.
84    Mock(MockBase),
85}
86
87/// A loopback base ending `/1.3`. The field is private, so the only way to hold
88/// one is [`Endpoint::mock`] — which is what makes "a fake pointed at a real
89/// host" unrepresentable rather than merely refused.
90#[derive(Debug, Clone, PartialEq, Eq)]
91pub struct MockBase(String);
92
93impl MockBase {
94    pub fn as_str(&self) -> &str {
95        &self.0
96    }
97}
98
99impl Endpoint {
100    /// The account — unless the shell carries a mock variable, in which case the
101    /// run does not start. An operator who exported [`MOCK_BASE_ENV`] for a fake
102    /// run and then typed a real verb in the same shell used to get writes to the
103    /// account from some clients and to the fake from others.
104    pub fn account() -> Result<Endpoint, String> {
105        Endpoint::account_given(|k| std::env::var(k).ok())
106    }
107
108    /// [`Endpoint::account`] over an injected environment, for tests.
109    pub fn account_given(env: impl Fn(&str) -> Option<String>) -> Result<Endpoint, String> {
110        let set: Vec<&str> = MOCK_ENVS.iter().copied().filter(|k| env(k).map(|v| !v.trim().is_empty()).unwrap_or(false)).collect();
111        if set.is_empty() {
112            return Ok(Endpoint::Account);
113        }
114        Err(format!(
115            "REFUSED [mock-variable-on-an-account-run] this shell carries {s}, which means it was set up to talk to \
116             a FAKE UpCloud — and this run was selected to talk to THE ACCOUNT. One of the two is wrong and this \
117             process will not guess which. Select the mock explicitly (the verb's `mock` word, or `--mock-api \
118             <loopback base>`), or unset {s} to use the account.",
119            s = set.join(" and ")
120        ))
121    }
122
123    /// A `mock-upcloud` at `base`. **Loopback or nothing**: a fake that can be
124    /// pointed off this machine is a fake that can be pointed at something real.
125    /// `http://127.0.0.1:8099` and `http://127.0.0.1:8099/1.3` are the same door.
126    pub fn mock(base: &str) -> Result<Endpoint, String> {
127        let mut b = base.trim().trim_end_matches('/').to_string();
128        if !is_loopback(&b) {
129            return Err(format!(
130                "REFUSED [mock-base-not-loopback] {b:?} does not name loopback (http://127.0.0.1:PORT or \
131                 http://localhost:PORT). mock-upcloud binds 127.0.0.1 and nothing else, so nothing off this \
132                 machine can be one."
133            ));
134        }
135        if !b.ends_with("/1.3") {
136            b.push_str("/1.3");
137        }
138        Ok(Endpoint::Mock(MockBase(b)))
139    }
140
141    /// A mock from [`MOCK_BASE_ENV`], for a run that has ALREADY been selected
142    /// as a mock run by what the operator typed. Unset is a refusal by name.
143    pub fn mock_from_env() -> Result<Endpoint, String> {
144        let raw = std::env::var(MOCK_BASE_ENV).ok().map(|v| v.trim().to_string()).filter(|v| !v.is_empty()).ok_or_else(|| {
145            format!(
146                "REFUSED [no-mock-base] the run says use the fake and {MOCK_BASE_ENV} is not set, so there is no \
147                 fake to use. Start one — `mock-upcloud --port 8099 --speed 0` — and export \
148                 {MOCK_BASE_ENV}=http://127.0.0.1:8099."
149            )
150        })?;
151        Endpoint::mock(&raw)
152    }
153
154    pub fn is_account(&self) -> bool {
155        matches!(self, Endpoint::Account)
156    }
157
158    /// Where `/…` goes — for a report. Never build a request from it; hold an
159    /// implementation from [`connect`] instead.
160    pub fn base_for_display(&self) -> &str {
161        match self {
162            Endpoint::Account => ACCOUNT_BASE,
163            Endpoint::Mock(b) => b.as_str(),
164        }
165    }
166
167    /// The one line that goes at the top of anything a person might read as a
168    /// measurement of the account.
169    pub fn banner(&self) -> String {
170        match self {
171            Endpoint::Account => format!("provider: THE ACCOUNT — {ACCOUNT_BASE}. Real machines, a real bill."),
172            Endpoint::Mock(b) => format!(
173                "provider: MOCK_UPCLOUD at {} — a FAKE. Nothing here is a machine, nothing here is a bill, and \
174                 nothing measured here says anything about the account.",
175                b.as_str()
176            ),
177        }
178    }
179
180    /// The argv a parent hands a CHILD process so the child makes the same
181    /// choice: `["--mock-api", base]` for a mock, nothing for the account. A
182    /// child that receives nothing and finds a mock variable in its environment
183    /// refuses ([`Endpoint::account`]) — which is how the choice cannot be lost
184    /// crossing a process boundary.
185    pub fn child_args(&self) -> Vec<String> {
186        match self {
187            Endpoint::Account => Vec::new(),
188            Endpoint::Mock(b) => vec![MOCK_API_FLAG.to_string(), b.as_str().to_string()],
189        }
190    }
191}
192
193/// The flag [`Endpoint::child_args`] emits and [`Endpoint::from_flag`] reads.
194pub const MOCK_API_FLAG: &str = "--mock-api";
195
196impl Endpoint {
197    /// A child's side of [`Endpoint::child_args`]: `Some(base)` from
198    /// `--mock-api` is the mock (loopback-checked); `None` is the account (and
199    /// refuses in a mock-carrying shell). There is no third answer.
200    pub fn from_flag(mock_api: Option<&str>) -> Result<Endpoint, String> {
201        match mock_api {
202            Some(b) => Endpoint::mock(b),
203            None => Endpoint::account(),
204        }
205    }
206}
207
208/// `http://127.0.0.1:PORT` or `http://localhost:PORT`, and nothing else. No
209/// IPv6 — these estates have none by law, and `[::1]` is refused with the rest.
210pub fn is_loopback(url: &str) -> bool {
211    let host = url.strip_prefix("http://").unwrap_or("").split('/').next().unwrap_or("").split(':').next().unwrap_or("");
212    host == "127.0.0.1" || host == "localhost"
213}
214
215// ── the answer ──────────────────────────────────────────────────────────────
216
217/// **One answer from the API, with NO judgement about its status.** The callers
218/// decide what a code means, because they genuinely disagree: a `404` on
219/// `GET /server/{uuid}` is a FACT for a sweep and a REFUSAL for a resize. A
220/// transport failure is the `Err` and is never a status.
221#[derive(Debug, Clone)]
222pub struct Reply {
223    pub status: u16,
224    /// The body as JSON; `Null` when it was empty or not JSON.
225    pub body: Value,
226    /// The body exactly as it arrived, so a non-JSON error page from a proxy
227    /// reaches the operator intact instead of becoming a parse error that names
228    /// nothing.
229    pub text: String,
230}
231
232impl Reply {
233    pub fn ok(&self) -> bool {
234        (200..300).contains(&self.status)
235    }
236
237    /// `error.error_code`, or `""`.
238    pub fn error_code(&self) -> &str {
239        self.body.pointer("/error/error_code").and_then(Value::as_str).unwrap_or("")
240    }
241
242    /// `error.error_message`, or the raw text.
243    pub fn error_message(&self) -> &str {
244        self.body.pointer("/error/error_message").and_then(Value::as_str).unwrap_or_else(|| self.text.trim())
245    }
246
247    /// `409 SERVER_STATE_ILLEGAL — server state is started`: status, code and
248    /// message, because each answers a different question.
249    pub fn describe_failure(&self, what: &str) -> String {
250        let code = self.error_code();
251        if code.is_empty() {
252            format!("{what} answered {} — {}", self.status, self.error_message())
253        } else {
254            format!("{what} answered {} {code} — {}", self.status, self.error_message())
255        }
256    }
257}
258
259// ── the words a caller uses instead of UpCloud's spelling ───────────────────
260
261/// How a server is stopped. `Soft` carries a grace in seconds; `Hard` pulls the
262/// plug, and is the word a delete needs first.
263#[derive(Debug, Clone, Copy, PartialEq, Eq)]
264pub enum Stop {
265    Soft { timeout_s: u32 },
266    Hard,
267}
268
269/// Whether a server's delete takes its storages with it, and what becomes of
270/// their backups. UpCloud spells this as a query string; no caller spells it.
271#[derive(Debug, Clone, Copy, PartialEq, Eq)]
272pub enum WithStorages {
273    /// `?storages=1&backups=delete` — the server and everything under it.
274    /// Caller: private-gunnar-ops orphan sweep.
275    AndTheirBackups,
276    /// `?storages=1&backups=keep` — the server and its volumes; the backups
277    /// stay. Caller: monetize-cloud-impl `destroy`.
278    AndKeepBackups,
279    /// The server alone; its volumes are left behind (and become orphans).
280    LeaveThem,
281}
282
283/// What a storage's delete does with the storage's backups.
284#[derive(Debug, Clone, Copy, PartialEq, Eq)]
285pub enum Backups {
286    /// No `backups=` is sent; the account's default applies. Callers:
287    /// gunnar-upcloud (seed media), private-gunnar-ops.
288    Unsaid,
289    /// `?backups=keep`. Caller: monetize-cloud-impl `destroy`.
290    Keep,
291    /// `?backups=delete`.
292    Delete,
293}
294
295/// How a device rides on a server.
296#[derive(Debug, Clone, Copy, PartialEq, Eq)]
297pub enum DeviceKind {
298    /// What the firmware boots. UpCloud is SeaBIOS-only.
299    Cdrom,
300    /// A virtio disk.
301    Disk,
302}
303
304impl DeviceKind {
305    pub fn as_str(self) -> &'static str {
306        match self {
307            DeviceKind::Cdrom => "cdrom",
308            DeviceKind::Disk => "disk",
309        }
310    }
311}
312
313/// What the hypervisor boots first on its next START (a guest reboot does not
314/// re-read it — MEASURED 2026-09-14).
315#[derive(Debug, Clone, Copy, PartialEq, Eq)]
316pub enum BootOrder {
317    Cdrom,
318    Disk,
319}
320
321impl BootOrder {
322    pub fn as_str(self) -> &'static str {
323        match self {
324            BootOrder::Cdrom => "cdrom",
325            BootOrder::Disk => "disk",
326        }
327    }
328}
329
330/// The VNC console. `Vnc` re-provisions host AND port; the reply carries them.
331#[derive(Debug, Clone, PartialEq, Eq)]
332pub enum Console<'a> {
333    Off,
334    Vnc { password: &'a str },
335}
336
337/// One label, `key=value`. UpCloud filters lists by it (`?label=key%3Dvalue`)
338/// and carries it on storages and servers.
339pub type Label<'a> = (&'a str, &'a str);
340
341/// A new storage.
342#[derive(Debug, Clone, PartialEq, Eq)]
343pub struct NewStorage<'a> {
344    pub title: &'a str,
345    pub zone: &'a str,
346    pub size_gib: u64,
347    /// `maxiops`, `standard`, …
348    pub tier: &'a str,
349    /// Empty sends no `labels` key at all.
350    pub labels: &'a [Label<'a>],
351}
352
353// ── the surface ─────────────────────────────────────────────────────────────
354
355/// **The UpCloud API 1.3 surface the nordisk estates actually use.** Typed in,
356/// typed out. Not one method takes a path, a query string or a base URL.
357pub trait UpCloudApi {
358    /// A word for what answered, for a report that must never read as a
359    /// measurement of the account when it was not one.
360    fn describe(&self) -> String;
361
362    /// Is this the real account? A question about the implementation, never a
363    /// handle to one.
364    fn is_the_account(&self) -> bool;
365
366    // ── reads ───────────────────────────────────────────────────────────────
367    /// `GET /account`. Callers: private-gunnar-ops, gunnar-loadbench,
368    /// private-holger-ops, monetize-cloud-impl (credential probe, grow judge).
369    fn account(&self) -> Result<Reply, String>;
370    /// `GET /price`. Caller: monetize-cloud-impl `price`.
371    fn price(&self) -> Result<Reply, String>;
372    /// `GET /server`. Callers: private-gunnar-ops / private-holger-ops orphan
373    /// sweeps, gunnar-loadbench.
374    fn servers(&self) -> Result<Reply, String>;
375    /// `GET /server?label=…` — every label must match. Caller:
376    /// monetize-cloud-impl (the label search, and the inventory with none).
377    fn servers_labelled(&self, labels: &[Label<'_>]) -> Result<Reply, String>;
378    /// `GET /server/{uuid}`. Callers: everywhere.
379    fn server(&self, uuid: &str) -> Result<Reply, String>;
380    /// `GET /server/{uuid}/firewall_rule`. Caller: private-gunnar-ops estate.
381    fn firewall_rules(&self, uuid: &str) -> Result<Reply, String>;
382    /// `GET /storage/private`. Callers: the orphan sweeps, gunnar-upcloud
383    /// (adopting media already on the account).
384    fn storages_private(&self) -> Result<Reply, String>;
385    /// `GET /storage?label=…` — every label must match; no label lists
386    /// everything the account can see. Caller: monetize-cloud-impl.
387    fn storages_labelled(&self, labels: &[Label<'_>]) -> Result<Reply, String>;
388    /// `GET /storage/{uuid}`. Callers: grow, gunnar-upcloud's online wait,
389    /// monetize-cloud-impl.
390    fn storage(&self, uuid: &str) -> Result<Reply, String>;
391    /// `GET /zone`. Caller: gunnar-loadbench `--from-upcloud`.
392    fn zones(&self) -> Result<Reply, String>;
393    /// `GET /plan`. Caller: gunnar-loadbench `--from-upcloud`.
394    fn plans(&self) -> Result<Reply, String>;
395
396    // ── server writes ───────────────────────────────────────────────────────
397    /// `POST /server` with the caller's server document (`{"server": {…}}`).
398    /// The DOCUMENT is the caller's — a plan, a template clone, labels, SSH
399    /// keys; the PATH is not. Caller: monetize-cloud-impl `ensure`.
400    fn create_server(&self, document: &Value) -> Result<Reply, String>;
401    /// `POST /server/{uuid}/stop`.
402    fn stop_server(&self, uuid: &str, stop: Stop) -> Result<Reply, String>;
403    /// `POST /server/{uuid}/start`.
404    fn start_server(&self, uuid: &str) -> Result<Reply, String>;
405    /// `PUT /server/{uuid}` with a plan — a plan change, which ALSO mints a
406    /// `Resize Backup`. Callers: private-gunnar-ops grow, monetize-cloud-impl.
407    fn modify_server_plan(&self, uuid: &str, plan: &str) -> Result<Reply, String>;
408    /// `PUT /server/{uuid}` with a boot order. Caller: gunnar-upcloud.
409    fn set_boot_order(&self, uuid: &str, order: BootOrder) -> Result<Reply, String>;
410    /// `PUT /server/{uuid}` toggling the VNC console. Caller: gunnar-upcloud
411    /// `console::open` (the toggle that defeats the stale port).
412    fn set_console(&self, uuid: &str, console: Console<'_>) -> Result<Reply, String>;
413    /// `POST /server/{uuid}/storage/attach`, optionally AT an address
414    /// (`virtio`, `virtio:5`). Callers: gunnar-upcloud (no address),
415    /// monetize-cloud-impl (always an address).
416    fn attach_storage(&self, server: &str, kind: DeviceKind, storage: &str, at: Option<&str>) -> Result<Reply, String>;
417    /// `POST /server/{uuid}/storage/detach` — names an ADDRESS (`ide:0:0`,
418    /// `virtio:5`), never a storage uuid. Callers: gunnar-upcloud,
419    /// monetize-cloud-impl.
420    fn detach_storage(&self, server: &str, address: &str) -> Result<Reply, String>;
421    /// `POST /server/{uuid}/cdrom/eject` — legal on a STARTED server
422    /// (MEASURED). Caller: gunnar-upcloud (the never-loop primitive).
423    fn eject_cdrom(&self, server: &str) -> Result<Reply, String>;
424    /// `DELETE /server/{uuid}`. **This really deletes.**
425    fn delete_server(&self, uuid: &str, with: WithStorages) -> Result<Reply, String>;
426
427    // ── storage writes ──────────────────────────────────────────────────────
428    /// `POST /storage`. Callers: gunnar-upcloud (the seed a medium is imported
429    /// into), monetize-cloud-impl (a labelled volume).
430    fn create_storage(&self, new: &NewStorage<'_>) -> Result<Reply, String>;
431    /// `POST /storage/{uuid}/clone`. Caller: gunnar-upcloud `clone_probe`.
432    fn clone_storage(&self, uuid: &str, title: &str, zone: &str, tier: &str) -> Result<Reply, String>;
433    /// `POST /storage/{uuid}/import` with `source: direct_upload` — the reply
434    /// carries the URL [`UpCloudApi::upload_direct`] PUTs to. Caller:
435    /// gunnar-upcloud.
436    fn import_direct_upload(&self, uuid: &str) -> Result<Reply, String>;
437    /// `PUT <direct_upload_url>` with the file's bytes. The URL is the one
438    /// [`UpCloudApi::import_direct_upload`] answered, **is itself a
439    /// credential** (never printed whole; no bearer sent), and must belong to
440    /// the same cloud this implementation talks to — the account's upload host
441    /// for the account, loopback for a mock. Caller: gunnar-upcloud.
442    fn upload_direct(&self, url: &str, file: &Path) -> Result<Reply, String>;
443    /// `PUT /storage/{uuid}` with a new size — the volume grows. Callers:
444    /// private-gunnar-ops grow, monetize-cloud-impl grow.
445    fn modify_storage_size(&self, uuid: &str, gb: u64) -> Result<Reply, String>;
446    /// `POST /storage/{uuid}/resize` — the FILESYSTEM grows, and the provider
447    /// mints a `Resize Backup` that nothing deletes.
448    fn resize_filesystem(&self, uuid: &str) -> Result<Reply, String>;
449    /// `DELETE /storage/{uuid}`. **This really deletes.**
450    fn delete_storage(&self, uuid: &str, backups: Backups) -> Result<Reply, String>;
451}
452
453/// Forward every method through a pointer, so `&T` and `Box<T>` are
454/// implementations too.
455macro_rules! forward {
456    ($($ty:tt)*) => {
457        impl<T: UpCloudApi + ?Sized> UpCloudApi for $($ty)* {
458            fn describe(&self) -> String { (**self).describe() }
459            fn is_the_account(&self) -> bool { (**self).is_the_account() }
460            fn account(&self) -> Result<Reply, String> { (**self).account() }
461            fn price(&self) -> Result<Reply, String> { (**self).price() }
462            fn servers(&self) -> Result<Reply, String> { (**self).servers() }
463            fn servers_labelled(&self, labels: &[Label<'_>]) -> Result<Reply, String> { (**self).servers_labelled(labels) }
464            fn server(&self, uuid: &str) -> Result<Reply, String> { (**self).server(uuid) }
465            fn firewall_rules(&self, uuid: &str) -> Result<Reply, String> { (**self).firewall_rules(uuid) }
466            fn storages_private(&self) -> Result<Reply, String> { (**self).storages_private() }
467            fn storages_labelled(&self, labels: &[Label<'_>]) -> Result<Reply, String> { (**self).storages_labelled(labels) }
468            fn storage(&self, uuid: &str) -> Result<Reply, String> { (**self).storage(uuid) }
469            fn zones(&self) -> Result<Reply, String> { (**self).zones() }
470            fn plans(&self) -> Result<Reply, String> { (**self).plans() }
471            fn create_server(&self, document: &Value) -> Result<Reply, String> { (**self).create_server(document) }
472            fn stop_server(&self, uuid: &str, stop: Stop) -> Result<Reply, String> { (**self).stop_server(uuid, stop) }
473            fn start_server(&self, uuid: &str) -> Result<Reply, String> { (**self).start_server(uuid) }
474            fn modify_server_plan(&self, uuid: &str, plan: &str) -> Result<Reply, String> { (**self).modify_server_plan(uuid, plan) }
475            fn set_boot_order(&self, uuid: &str, order: BootOrder) -> Result<Reply, String> { (**self).set_boot_order(uuid, order) }
476            fn set_console(&self, uuid: &str, console: Console<'_>) -> Result<Reply, String> { (**self).set_console(uuid, console) }
477            fn attach_storage(&self, server: &str, kind: DeviceKind, storage: &str, at: Option<&str>) -> Result<Reply, String> { (**self).attach_storage(server, kind, storage, at) }
478            fn detach_storage(&self, server: &str, address: &str) -> Result<Reply, String> { (**self).detach_storage(server, address) }
479            fn eject_cdrom(&self, server: &str) -> Result<Reply, String> { (**self).eject_cdrom(server) }
480            fn delete_server(&self, uuid: &str, with: WithStorages) -> Result<Reply, String> { (**self).delete_server(uuid, with) }
481            fn create_storage(&self, new: &NewStorage<'_>) -> Result<Reply, String> { (**self).create_storage(new) }
482            fn clone_storage(&self, uuid: &str, title: &str, zone: &str, tier: &str) -> Result<Reply, String> { (**self).clone_storage(uuid, title, zone, tier) }
483            fn import_direct_upload(&self, uuid: &str) -> Result<Reply, String> { (**self).import_direct_upload(uuid) }
484            fn upload_direct(&self, url: &str, file: &Path) -> Result<Reply, String> { (**self).upload_direct(url, file) }
485            fn modify_storage_size(&self, uuid: &str, gb: u64) -> Result<Reply, String> { (**self).modify_storage_size(uuid, gb) }
486            fn resize_filesystem(&self, uuid: &str) -> Result<Reply, String> { (**self).resize_filesystem(uuid) }
487            fn delete_storage(&self, uuid: &str, backups: Backups) -> Result<Reply, String> { (**self).delete_storage(uuid, backups) }
488        }
489    };
490}
491forward!(&T);
492forward!(Box<T>);
493
494/// The query a delete sends — ONE spelling, for the wire and for any fake that
495/// records what a call means.
496pub fn delete_server_query(with: WithStorages) -> &'static str {
497    match with {
498        WithStorages::AndTheirBackups => "?storages=1&backups=delete",
499        WithStorages::AndKeepBackups => "?storages=1&backups=keep",
500        WithStorages::LeaveThem => "",
501    }
502}
503
504/// See [`delete_server_query`].
505pub fn delete_storage_query(backups: Backups) -> &'static str {
506    match backups {
507        Backups::Unsaid => "",
508        Backups::Keep => "?backups=keep",
509        Backups::Delete => "?backups=delete",
510    }
511}
512
513/// `?label=k%3Dv&label=…`, or `""` — every character outside RFC 3986's
514/// unreserved set percent-encoded, so a label is never read as query syntax.
515pub fn label_query(labels: &[Label<'_>]) -> String {
516    fn enc(s: &str, out: &mut String) {
517        for b in s.bytes() {
518            if b.is_ascii_alphanumeric() || b"-._~".contains(&b) {
519                out.push(b as char);
520            } else {
521                out.push_str(&format!("%{b:02X}"));
522            }
523        }
524    }
525    let mut q = String::new();
526    for (k, v) in labels {
527        q.push(if q.is_empty() { '?' } else { '&' });
528        q.push_str("label=");
529        enc(&format!("{k}={v}"), &mut q);
530    }
531    q
532}
533
534// ── request bodies: ONE spelling, shared by the wire and by any fake ────────
535
536/// The JSON each write sends. Public so an in-process fake reads the SAME
537/// bodies the wire sends rather than a parallel copy of UpCloud's quirks.
538pub mod body {
539    use super::{BootOrder, Console, DeviceKind, NewStorage, Stop};
540    use serde_json::{json, Value};
541
542    /// UpCloud's 1.3 API wants the timeout as a STRING. It was sent as a
543    /// number once and the call was accepted and IGNORED.
544    pub fn stop(stop: Stop) -> Value {
545        match stop {
546            Stop::Soft { timeout_s } => json!({"stop_server": {"stop_type": "soft", "timeout": timeout_s.to_string()}}),
547            Stop::Hard => json!({"stop_server": {"stop_type": "hard"}}),
548        }
549    }
550    pub fn storage_size(gb: u64) -> Value {
551        json!({"storage": {"size": gb.to_string()}})
552    }
553    pub fn server_plan(plan: &str) -> Value {
554        json!({"server": {"plan": plan}})
555    }
556    pub fn boot_order(order: BootOrder) -> Value {
557        json!({"server": {"boot_order": order.as_str()}})
558    }
559    pub fn console(c: &Console<'_>) -> Value {
560        match c {
561            Console::Off => json!({"server": {"remote_access_enabled": "no"}}),
562            Console::Vnc { password } => json!({"server": {
563                "remote_access_enabled": "yes",
564                "remote_access_type": "vnc",
565                "remote_access_password": password,
566            }}),
567        }
568    }
569    pub fn attach(kind: DeviceKind, storage: &str, at: Option<&str>) -> Value {
570        match at {
571            None => json!({"storage_device": {"type": kind.as_str(), "storage": storage}}),
572            Some(a) => json!({"storage_device": {"type": kind.as_str(), "address": a, "storage": storage}}),
573        }
574    }
575    /// Detach names an **address**, never a storage uuid.
576    pub fn detach(address: &str) -> Value {
577        json!({"storage_device": {"address": address}})
578    }
579    pub fn create_storage(n: &NewStorage<'_>) -> Value {
580        let mut v = json!({"storage": {"size": n.size_gib, "tier": n.tier, "title": n.title, "zone": n.zone}});
581        if !n.labels.is_empty() {
582            v["storage"]["labels"] = json!(n.labels.iter().map(|(k, v)| json!({"key": k, "value": v})).collect::<Vec<_>>());
583        }
584        v
585    }
586    /// A clone names the new title and zone; the tier rides along.
587    pub fn clone_storage(title: &str, zone: &str, tier: &str) -> Value {
588        json!({"storage": {"tier": tier, "title": title, "zone": zone}})
589    }
590    pub fn direct_upload() -> Value {
591        json!({"storage_import": {"source": "direct_upload"}})
592    }
593}
594
595/// `https://fi-hel1.img.upcloud.com/uploader/session/<secret>` →
596/// `…/uploader/session/…`: the session id IS a credential (anyone holding it
597/// can write the storage a box boots from), so it is never printed whole.
598pub fn redact_upload_url(url: &str) -> String {
599    match url.find("/session/") {
600        Some(i) => format!("{}/session/…", &url[..i]),
601        None => match url.rfind('/') {
602            Some(i) => format!("{}/…", &url[..i]),
603            None => "…".to_string(),
604        },
605    }
606}
607
608#[cfg(test)]
609mod tests {
610    use super::*;
611
612    #[test]
613    fn a_mock_endpoint_is_loopback_or_nothing() {
614        assert!(Endpoint::mock("http://127.0.0.1:8099").is_ok());
615        assert!(Endpoint::mock("http://localhost:8099/1.3/").is_ok());
616        for bad in ["https://api.upcloud.com/1.3", "http://10.13.0.247:8099", "http://[::1]:8099", "api.upcloud.com", ""] {
617            let e = Endpoint::mock(bad).unwrap_err();
618            assert!(e.contains("mock-base-not-loopback"), "{bad}: {e}");
619        }
620    }
621
622    #[test]
623    fn both_spellings_of_a_mock_base_reach_the_same_door() {
624        assert_eq!(Endpoint::mock("http://127.0.0.1:8099").unwrap(), Endpoint::mock("http://127.0.0.1:8099/1.3").unwrap());
625        assert_eq!(Endpoint::mock("http://127.0.0.1:8099").unwrap().base_for_display(), "http://127.0.0.1:8099/1.3");
626    }
627
628    /// **FAILS-BEFORE, BY NEUTRALISATION**: make `account_given` ignore the
629    /// environment and the first assertion below fails — an account run in a
630    /// shell aimed at a fake is exactly the ambiguity that must not start.
631    #[test]
632    fn an_account_run_refuses_in_a_shell_that_carries_a_mock_variable() {
633        for k in MOCK_ENVS {
634            let e = Endpoint::account_given(|q| (q == *k).then(|| "http://127.0.0.1:8099".to_string())).unwrap_err();
635            assert!(e.contains("mock-variable-on-an-account-run") && e.contains(k), "{e}");
636        }
637        assert_eq!(Endpoint::account_given(|_| None).unwrap(), Endpoint::Account);
638        // An empty value is not a choice.
639        assert_eq!(Endpoint::account_given(|_| Some("  ".into())).unwrap(), Endpoint::Account);
640    }
641
642    #[test]
643    fn the_choice_crosses_a_process_boundary_as_argv_and_only_as_argv() {
644        let m = Endpoint::mock("http://127.0.0.1:8099").unwrap();
645        let args = m.child_args();
646        assert_eq!(args, vec![MOCK_API_FLAG.to_string(), "http://127.0.0.1:8099/1.3".to_string()]);
647        assert_eq!(Endpoint::from_flag(Some(&args[1])).unwrap(), m);
648        assert!(Endpoint::Account.child_args().is_empty());
649        assert!(Endpoint::from_flag(Some("https://api.upcloud.com/1.3")).is_err(), "the flag cannot name the account");
650    }
651
652    #[test]
653    fn a_banner_for_a_fake_never_reads_as_a_measurement_of_the_account() {
654        let b = Endpoint::mock("http://127.0.0.1:8099").unwrap().banner();
655        assert!(b.contains("FAKE") && !b.contains("api.upcloud.com"), "{b}");
656        assert!(Endpoint::Account.banner().contains("a real bill"));
657    }
658
659    #[test]
660    fn the_stop_timeout_goes_out_as_a_string() {
661        let b = body::stop(Stop::Soft { timeout_s: 60 });
662        assert_eq!(b["stop_server"]["timeout"], serde_json::json!("60"));
663        assert_eq!(body::stop(Stop::Hard)["stop_server"]["stop_type"], serde_json::json!("hard"));
664    }
665
666    #[test]
667    fn a_label_filter_is_one_encoded_pair_per_label() {
668        assert_eq!(label_query(&[]), "");
669        assert_eq!(label_query(&[("monetize_ref", "abc")]), "?label=monetize_ref%3Dabc");
670        assert_eq!(label_query(&[("a", "b c"), ("k", "x&y")]), "?label=a%3Db%20c&label=k%3Dx%26y");
671    }
672
673    #[test]
674    fn a_delete_says_what_happens_to_backups_in_one_spelling() {
675        assert_eq!(delete_server_query(WithStorages::AndTheirBackups), "?storages=1&backups=delete");
676        assert_eq!(delete_server_query(WithStorages::AndKeepBackups), "?storages=1&backups=keep");
677        assert_eq!(delete_server_query(WithStorages::LeaveThem), "");
678        assert_eq!(delete_storage_query(Backups::Unsaid), "");
679        assert_eq!(delete_storage_query(Backups::Keep), "?backups=keep");
680    }
681
682    #[test]
683    fn an_attach_names_an_address_only_when_asked() {
684        assert!(body::attach(DeviceKind::Cdrom, "s", None)["storage_device"].get("address").is_none());
685        assert_eq!(body::attach(DeviceKind::Disk, "s", Some("virtio"))["storage_device"]["address"], serde_json::json!("virtio"));
686        let n = NewStorage { title: "t", zone: "z", size_gib: 1, tier: "maxiops", labels: &[] };
687        assert!(body::create_storage(&n)["storage"].get("labels").is_none(), "no labels, no key");
688    }
689
690    #[test]
691    fn an_upload_session_is_never_printed_whole() {
692        let r = redact_upload_url("https://fi-hel1.img.upcloud.com/uploader/session/9f2b3cSECRET");
693        assert!(!r.contains("SECRET") && r.starts_with("https://fi-hel1.img.upcloud.com/uploader/session"), "{r}");
694    }
695
696    #[test]
697    fn a_failure_names_the_api_error_code() {
698        let r = Reply {
699            status: 409,
700            body: serde_json::json!({"error":{"error_code":"SERVER_STATE_ILLEGAL","error_message":"server state is started"}}),
701            text: String::new(),
702        };
703        let m = r.describe_failure("POST /server/{uuid}/storage/attach");
704        assert!(m.contains("409 SERVER_STATE_ILLEGAL — server state is started"), "{m}");
705        let page = Reply { status: 502, body: Value::Null, text: "<html>bad gateway</html>".into() };
706        assert!(page.describe_failure("GET /x").contains("bad gateway"));
707    }
708}
upcloud_api/lib.rs

upcloud_api/
lib.rs
