townos-api 0.0.3

Client for the Town OS control plane (systemcontroller) HTTP API
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
//! Object storage — `gfeh` — and the btrfs volumes beneath it.
//!
//! One partition per network. `gfehd`'s own administrative surface is a Unix
//! socket that checks no credential, so nothing here talks to it: the control
//! plane proxies every call and authenticates the caller the way it does
//! everywhere else. That is why this client needs no second endpoint and no
//! second credential.
//!
//! Reads need a session; writes need the `gfeh` grant (which an administrator
//! holds implicitly). See [`crate::Account::holds`].

use std::path::Path;

use serde::Deserialize;

use crate::{Client, Error, Filesystem, FilesystemPage, Result};

/// A published name for a partition, and the port it answers on.
#[derive(Debug, Clone, Deserialize)]
pub struct PartitionName {
    #[serde(default)]
    pub view: String,
    #[serde(default)]
    pub fqdn: String,
    #[serde(default)]
    pub port: u16,
    /// Whether the name is served over plain HTTP rather than HTTPS.
    #[serde(default)]
    pub http: bool,
}

impl PartitionName {
    /// The URL this name is reachable at.
    pub fn url(&self) -> String {
        let scheme = if self.http { "http" } else { "https" };
        let default_port = if self.http { 80 } else { 443 };
        if self.port == 0 || self.port == default_port {
            format!("{scheme}://{}", self.fqdn)
        } else {
            format!("{scheme}://{}:{}", self.fqdn, self.port)
        }
    }
}

/// One network's object storage partition.
#[derive(Debug, Clone, Deserialize)]
pub struct Partition {
    #[serde(default)]
    pub network: String,
    #[serde(default)]
    pub tld: String,
    /// Bytes; 0 means unlimited.
    #[serde(default)]
    pub quota: u64,
    #[serde(default)]
    pub running: bool,
    #[serde(default)]
    pub names: Vec<PartitionName>,
}

/// A principal in a partition's ACL forest.
#[derive(Debug, Clone, Deserialize)]
pub struct Principal {
    #[serde(default)]
    pub name: String,
    #[serde(default)]
    pub parent: Option<String>,
    /// The most this principal can ever hold, whatever it is granted.
    #[serde(default)]
    pub ceiling: Vec<String>,
    /// Whether this corresponds to a Town OS account, as opposed to a
    /// sub-principal created inside gfeh.
    #[serde(default)]
    pub account: bool,
}

/// Authority over a subtree of a partition.
#[derive(Debug, Clone, Deserialize)]
pub struct Grant {
    #[serde(default)]
    pub id: i64,
    #[serde(default)]
    pub principal: String,
    /// Relative to the partition root.
    #[serde(default)]
    pub path: String,
    #[serde(default)]
    pub perm: Vec<String>,
    /// Whether it extends beneath `path`.
    #[serde(default)]
    pub inheritable: bool,
}

/// A published link into a partition.
#[derive(Debug, Clone, Deserialize)]
pub struct Exposure {
    #[serde(default)]
    pub token: String,
    #[serde(default)]
    pub path: String,
    #[serde(default)]
    pub filename: Option<String>,
    #[serde(default)]
    pub enabled: bool,
}

/// The permissions a grant can carry, in the order the UI offers them.
pub const PERMISSIONS: [&str; 4] = ["read", "write", "delete", "grant"];

/// What `POST /storage/upload-archive` answers with.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct ArchiveUpload {
    /// Whether whatever consumes the volume should be restarted to see the new
    /// contents. The box answers true unconditionally, so this is advice rather
    /// than a measurement.
    #[serde(default)]
    pub needs_restart: bool,
    #[serde(default)]
    pub message: String,
}

/// The compression formats the box will produce, in the order the UI offers
/// them. `tar.gz` is the box's own default.
pub const ARCHIVE_FORMATS: [&str; 3] = ["tar.gz", "tar.bz2", "tar.xz"];

/// Whether a filename is an archive the box will unpack.
///
/// The server picks the decompressor from the filename it is sent, so a name it
/// cannot classify is a 400 after the whole file has been uploaded. Checking
/// first turns a wasted gigabyte into an immediate message.
pub fn is_supported_archive(filename: &str) -> bool {
    let lower = filename.to_ascii_lowercase();
    [
        ".tar.gz", ".tgz", ".tar.bz2", ".tbz2", ".tar.xz", ".txz", ".tar",
    ]
    .iter()
    .any(|ext| lower.ends_with(ext))
}

impl Client {
    /// Lists every partition with its published names and live state.
    ///
    /// Answers an empty list when object storage is not configured, which is a
    /// deployment choice rather than a failure — the UI says so instead of
    /// showing an error.
    ///
    /// Calls `GET /gfeh`.
    pub async fn partitions(&self) -> Result<Vec<Partition>> {
        self.get_json("/gfeh").await
    }

    /// Calls `GET /gfeh/principals`.
    pub async fn principals(&self, network: &str) -> Result<Vec<Principal>> {
        self.get_json(&format!("/gfeh/principals?network={}", enc(network)))
            .await
    }

    /// Projects a Town OS account into a partition.
    ///
    /// The ceiling follows the account: an administrator becomes a gfeh
    /// superuser, anyone else gets read-write and no grants — deliberately
    /// useless until somebody grants them something.
    ///
    /// Calls `POST /gfeh/principals/add`.
    pub async fn add_principal(&self, network: &str, principal: &str) -> Result<Principal> {
        self.post_json(
            "/gfeh/principals/add",
            &serde_json::json!({ "network": network, "principal": principal }),
        )
        .await
    }

    /// Removes a principal, and with it every grant derived from it.
    ///
    /// Calls `POST /gfeh/principals/remove`.
    pub async fn remove_principal(&self, network: &str, principal: &str) -> Result<()> {
        self.post_empty(
            "/gfeh/principals/remove",
            &serde_json::json!({ "network": network, "principal": principal }),
        )
        .await
    }

    /// Lists what one principal holds. The principal is required — gfehd's own
    /// handler has no default, so an absent one is an error rather than
    /// "every grant".
    ///
    /// Calls `GET /gfeh/grants`.
    pub async fn grants(&self, network: &str, principal: &str) -> Result<Vec<Grant>> {
        self.get_json(&format!(
            "/gfeh/grants?network={}&principal={}",
            enc(network),
            enc(principal)
        ))
        .await
    }

    /// Grants a principal authority over a subtree.
    ///
    /// The answer carries the rights **as stored**, which is what gfeh clamped
    /// them to rather than what was asked for. Callers must show that, not the
    /// request: an administrator has to be able to see a grant was narrowed, or
    /// they will believe they gave access nobody has.
    ///
    /// Calls `POST /gfeh/grants/add`.
    pub async fn add_grant(
        &self,
        network: &str,
        principal: &str,
        path: &str,
        perm: &[String],
        inheritable: bool,
    ) -> Result<Grant> {
        self.post_json(
            "/gfeh/grants/add",
            &serde_json::json!({
                "network": network,
                "principal": principal,
                "path": path,
                "perm": perm,
                "inheritable": inheritable,
            }),
        )
        .await
    }

    /// Calls `POST /gfeh/grants/revoke`.
    pub async fn revoke_grant(&self, network: &str, id: i64) -> Result<()> {
        self.post_empty(
            "/gfeh/grants/revoke",
            &serde_json::json!({ "network": network, "id": id }),
        )
        .await
    }

    /// Calls `GET /gfeh/exposures`.
    pub async fn exposures(&self, network: &str) -> Result<Vec<Exposure>> {
        self.get_json(&format!("/gfeh/exposures?network={}", enc(network)))
            .await
    }

    /// Withdraws a published link, after which it stops resolving.
    ///
    /// Calls `POST /gfeh/exposures/withdraw`.
    pub async fn withdraw_exposure(&self, network: &str, token: &str) -> Result<()> {
        self.post_empty(
            "/gfeh/exposures/withdraw",
            &serde_json::json!({ "network": network, "token": token }),
        )
        .await
    }

    // --- btrfs volumes ---

    /// Lists subvolumes. `state` filters to `user`, `installed` or
    /// `uninstalled`; `None` spans all three.
    ///
    /// Calls `POST /storage`.
    pub async fn filesystems(
        &self,
        prefix: &str,
        state: Option<&str>,
        limit: u32,
        offset: u32,
        search: &str,
    ) -> Result<FilesystemPage> {
        let mut body = serde_json::json!({
            "name": prefix,
            "limit": limit,
            "offset": offset,
            "sort_by": "name",
            "sort_order": "asc",
        });
        if let Some(state) = state.filter(|s| !s.is_empty()) {
            body["state"] = serde_json::Value::String(state.into());
        }
        if !search.is_empty() {
            body["search"] = serde_json::Value::String(search.into());
        }
        self.post_json("/storage", &body).await
    }

    /// Calls `POST /storage/create`.
    pub async fn create_filesystem(&self, fs: &Filesystem) -> Result<()> {
        self.post_empty("/storage/create", fs).await
    }

    /// Changes a volume's name or quota.
    ///
    /// Renaming works only for user volumes; a package volume (one under
    /// `installed/` or `uninstalled/`) must keep its name, and the server
    /// refuses the call if `fs.name` differs from `name`.
    ///
    /// Calls `POST /storage/modify`.
    pub async fn modify_filesystem(&self, name: &str, fs: &Filesystem) -> Result<()> {
        self.post_empty(
            "/storage/modify",
            &serde_json::json!({ "name": name, "filesystem": fs }),
        )
        .await
    }

    /// Calls `POST /storage/remove`.
    pub async fn remove_filesystem(&self, name: &str) -> Result<()> {
        self.post_empty("/storage/remove", &serde_json::json!({ "name": name }))
            .await
    }

    // --- Archives ---
    //
    // How a bulk of files gets into or out of a volume. Both are admin-only, and
    // both refuse a `gfeh/` volume: an object-storage partition's contents are
    // gfehd's to write, and unpacking a tar over them behind its back would
    // leave its index describing objects that are no longer there.

    /// Unpacks an archive into a volume.
    ///
    /// The file is streamed from disk rather than read into memory — these run to
    /// a gigabyte by default — and its **name matters**: the box picks the
    /// decompressor from the extension, so [`is_supported_archive`] is worth
    /// checking before spending the upload.
    ///
    /// `subpath` extracts into a subdirectory of the volume instead of its root.
    /// `stop_service` names a systemd unit to stop for the duration, which is how
    /// you replace files something is holding open; the box restarts it after.
    ///
    /// Calls `POST /storage/upload-archive` (admin).
    pub async fn upload_archive(
        &self,
        subvolume: &str,
        archive: &Path,
        subpath: &str,
        stop_service: &str,
    ) -> Result<ArchiveUpload> {
        // Part::file supplies the filename, the length and a streaming body. The
        // length is the part that matters beyond convenience: it gives the
        // request a Content-Length, which is what the box checks against its
        // size limit before reading a byte.
        let part = reqwest::multipart::Part::file(archive)
            .await
            .map_err(|source| Error::Io {
                path: archive.display().to_string(),
                source,
            })?;

        let mut form = reqwest::multipart::Form::new()
            .text("subvolume", subvolume.to_owned())
            .part("archive", part);
        if !subpath.is_empty() {
            form = form.text("subpath", subpath.to_owned());
        }
        if !stop_service.is_empty() {
            form = form.text("stop_service", stop_service.to_owned());
        }

        const PATH: &str = "/storage/upload-archive";
        // Deliberately not through `post_json`: the multipart boundary has to be
        // the one reqwest generated for this form, so the body cannot be a
        // serialized value.
        let req = self
            .request(reqwest::Method::POST, PATH)
            .multipart(form);
        let resp = self.send("POST", PATH, req).await?;
        Self::decode(PATH, resp).await
    }

    /// Writes a compressed archive of a volume to `destination`.
    ///
    /// `paths` confines the archive to those entries, relative to the volume
    /// root; empty takes everything. `format` is one of [`ARCHIVE_FORMATS`], or
    /// empty for the box's default.
    ///
    /// The body is written to disk as it arrives, so this holds no more than one
    /// chunk in memory however large the volume is. A failure part way through
    /// leaves a partial file behind, which the caller should remove — an archive
    /// that stops in the middle is not a smaller archive.
    ///
    /// Calls `POST /storage/download-archive` (admin).
    pub async fn download_archive(
        &self,
        subvolume: &str,
        paths: &[String],
        format: &str,
        destination: &Path,
    ) -> Result<u64> {
        use tokio::io::AsyncWriteExt as _;

        let mut body = serde_json::json!({ "subvolume": subvolume });
        if !paths.is_empty() {
            body["paths"] = serde_json::json!(paths);
        }
        if !format.is_empty() {
            body["format"] = serde_json::Value::String(format.to_owned());
        }

        const PATH: &str = "/storage/download-archive";
        let req = self.request(reqwest::Method::POST, PATH).json(&body);
        let mut resp = self.send("POST", PATH, req).await?;

        let io_error = |source: std::io::Error| Error::Io {
            path: destination.display().to_string(),
            source,
        };
        let mut file = tokio::fs::File::create(destination).await.map_err(io_error)?;
        let mut written = 0u64;
        while let Some(chunk) = resp.chunk().await? {
            file.write_all(&chunk).await.map_err(io_error)?;
            written += chunk.len() as u64;
        }
        file.flush().await.map_err(io_error)?;
        Ok(written)
    }
}

fn enc(value: &str) -> String {
    let mut out = String::with_capacity(value.len());
    for byte in value.bytes() {
        match byte {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
                out.push(byte as char)
            }
            other => out.push_str(&format!("%{other:02X}")),
        }
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn default_ports_are_left_off_the_url() {
        let https = PartitionName {
            view: "public".into(),
            fqdn: "files.home.town".into(),
            port: 443,
            http: false,
        };
        assert_eq!(https.url(), "https://files.home.town");

        let http = PartitionName {
            view: "public".into(),
            fqdn: "files.home.town".into(),
            port: 80,
            http: true,
        };
        assert_eq!(http.url(), "http://files.home.town");
    }

    #[test]
    fn nonstandard_ports_are_kept() {
        let name = PartitionName {
            view: "admin".into(),
            fqdn: "files.home.town".into(),
            port: 8443,
            http: false,
        };
        assert_eq!(name.url(), "https://files.home.town:8443");
    }

    #[test]
    fn archive_names_the_box_can_unpack_are_recognised() {
        for name in [
            "backup.tar.gz",
            "BACKUP.TAR.GZ",
            "backup.tgz",
            "backup.tar.bz2",
            "backup.tbz2",
            "backup.tar.xz",
            "backup.txz",
            "backup.tar",
        ] {
            assert!(is_supported_archive(name), "{name} should be accepted");
        }
    }

    #[test]
    fn names_the_box_would_refuse_are_caught_before_the_upload() {
        for name in ["backup.zip", "backup.7z", "backup", "backup.gz", "tar.gz.txt"] {
            assert!(!is_supported_archive(name), "{name} should be refused");
        }
    }

    #[test]
    fn unset_port_falls_back_to_the_scheme_default() {
        let name = PartitionName {
            view: "public".into(),
            fqdn: "files.home.town".into(),
            port: 0,
            http: true,
        };
        assert_eq!(name.url(), "http://files.home.town");
    }
}