Skip to main content

townos_api/
storage.rs

1//! Object storage — `gfeh` — and the btrfs volumes beneath it.
2//!
3//! One partition per network. `gfehd`'s own administrative surface is a Unix
4//! socket that checks no credential, so nothing here talks to it: the control
5//! plane proxies every call and authenticates the caller the way it does
6//! everywhere else. That is why this client needs no second endpoint and no
7//! second credential.
8//!
9//! Reads need a session; writes need the `gfeh` grant (which an administrator
10//! holds implicitly). See [`crate::Account::holds`].
11
12use std::path::Path;
13
14use serde::Deserialize;
15
16use crate::{Client, Error, Filesystem, FilesystemPage, Result};
17
18/// A published name for a partition, and the port it answers on.
19#[derive(Debug, Clone, Deserialize)]
20pub struct PartitionName {
21    #[serde(default)]
22    pub view: String,
23    #[serde(default)]
24    pub fqdn: String,
25    #[serde(default)]
26    pub port: u16,
27    /// Whether the name is served over plain HTTP rather than HTTPS.
28    #[serde(default)]
29    pub http: bool,
30}
31
32impl PartitionName {
33    /// The URL this name is reachable at.
34    pub fn url(&self) -> String {
35        let scheme = if self.http { "http" } else { "https" };
36        let default_port = if self.http { 80 } else { 443 };
37        if self.port == 0 || self.port == default_port {
38            format!("{scheme}://{}", self.fqdn)
39        } else {
40            format!("{scheme}://{}:{}", self.fqdn, self.port)
41        }
42    }
43}
44
45/// One network's object storage partition.
46#[derive(Debug, Clone, Deserialize)]
47pub struct Partition {
48    #[serde(default)]
49    pub network: String,
50    #[serde(default)]
51    pub tld: String,
52    /// Bytes; 0 means unlimited.
53    #[serde(default)]
54    pub quota: u64,
55    #[serde(default)]
56    pub running: bool,
57    #[serde(default)]
58    pub names: Vec<PartitionName>,
59}
60
61/// A principal in a partition's ACL forest.
62#[derive(Debug, Clone, Deserialize)]
63pub struct Principal {
64    #[serde(default)]
65    pub name: String,
66    #[serde(default)]
67    pub parent: Option<String>,
68    /// The most this principal can ever hold, whatever it is granted.
69    #[serde(default)]
70    pub ceiling: Vec<String>,
71    /// Whether this corresponds to a Town OS account, as opposed to a
72    /// sub-principal created inside gfeh.
73    #[serde(default)]
74    pub account: bool,
75}
76
77/// Authority over a subtree of a partition.
78#[derive(Debug, Clone, Deserialize)]
79pub struct Grant {
80    #[serde(default)]
81    pub id: i64,
82    #[serde(default)]
83    pub principal: String,
84    /// Relative to the partition root.
85    #[serde(default)]
86    pub path: String,
87    #[serde(default)]
88    pub perm: Vec<String>,
89    /// Whether it extends beneath `path`.
90    #[serde(default)]
91    pub inheritable: bool,
92}
93
94/// A published link into a partition.
95#[derive(Debug, Clone, Deserialize)]
96pub struct Exposure {
97    #[serde(default)]
98    pub token: String,
99    #[serde(default)]
100    pub path: String,
101    #[serde(default)]
102    pub filename: Option<String>,
103    #[serde(default)]
104    pub enabled: bool,
105}
106
107/// The permissions a grant can carry, in the order the UI offers them.
108pub const PERMISSIONS: [&str; 4] = ["read", "write", "delete", "grant"];
109
110/// What `POST /storage/upload-archive` answers with.
111#[derive(Debug, Clone, Default, Deserialize)]
112pub struct ArchiveUpload {
113    /// Whether whatever consumes the volume should be restarted to see the new
114    /// contents. The box answers true unconditionally, so this is advice rather
115    /// than a measurement.
116    #[serde(default)]
117    pub needs_restart: bool,
118    #[serde(default)]
119    pub message: String,
120}
121
122/// The compression formats the box will produce, in the order the UI offers
123/// them. `tar.gz` is the box's own default.
124pub const ARCHIVE_FORMATS: [&str; 3] = ["tar.gz", "tar.bz2", "tar.xz"];
125
126/// Whether a filename is an archive the box will unpack.
127///
128/// The server picks the decompressor from the filename it is sent, so a name it
129/// cannot classify is a 400 after the whole file has been uploaded. Checking
130/// first turns a wasted gigabyte into an immediate message.
131pub fn is_supported_archive(filename: &str) -> bool {
132    let lower = filename.to_ascii_lowercase();
133    [
134        ".tar.gz", ".tgz", ".tar.bz2", ".tbz2", ".tar.xz", ".txz", ".tar",
135    ]
136    .iter()
137    .any(|ext| lower.ends_with(ext))
138}
139
140impl Client {
141    /// Lists every partition with its published names and live state.
142    ///
143    /// Answers an empty list when object storage is not configured, which is a
144    /// deployment choice rather than a failure — the UI says so instead of
145    /// showing an error.
146    ///
147    /// Calls `GET /gfeh`.
148    pub async fn partitions(&self) -> Result<Vec<Partition>> {
149        self.get_json("/gfeh").await
150    }
151
152    /// Calls `GET /gfeh/principals`.
153    pub async fn principals(&self, network: &str) -> Result<Vec<Principal>> {
154        self.get_json(&format!("/gfeh/principals?network={}", enc(network)))
155            .await
156    }
157
158    /// Projects a Town OS account into a partition.
159    ///
160    /// The ceiling follows the account: an administrator becomes a gfeh
161    /// superuser, anyone else gets read-write and no grants — deliberately
162    /// useless until somebody grants them something.
163    ///
164    /// Calls `POST /gfeh/principals/add`.
165    pub async fn add_principal(&self, network: &str, principal: &str) -> Result<Principal> {
166        self.post_json(
167            "/gfeh/principals/add",
168            &serde_json::json!({ "network": network, "principal": principal }),
169        )
170        .await
171    }
172
173    /// Removes a principal, and with it every grant derived from it.
174    ///
175    /// Calls `POST /gfeh/principals/remove`.
176    pub async fn remove_principal(&self, network: &str, principal: &str) -> Result<()> {
177        self.post_empty(
178            "/gfeh/principals/remove",
179            &serde_json::json!({ "network": network, "principal": principal }),
180        )
181        .await
182    }
183
184    /// Lists what one principal holds. The principal is required — gfehd's own
185    /// handler has no default, so an absent one is an error rather than
186    /// "every grant".
187    ///
188    /// Calls `GET /gfeh/grants`.
189    pub async fn grants(&self, network: &str, principal: &str) -> Result<Vec<Grant>> {
190        self.get_json(&format!(
191            "/gfeh/grants?network={}&principal={}",
192            enc(network),
193            enc(principal)
194        ))
195        .await
196    }
197
198    /// Grants a principal authority over a subtree.
199    ///
200    /// The answer carries the rights **as stored**, which is what gfeh clamped
201    /// them to rather than what was asked for. Callers must show that, not the
202    /// request: an administrator has to be able to see a grant was narrowed, or
203    /// they will believe they gave access nobody has.
204    ///
205    /// Calls `POST /gfeh/grants/add`.
206    pub async fn add_grant(
207        &self,
208        network: &str,
209        principal: &str,
210        path: &str,
211        perm: &[String],
212        inheritable: bool,
213    ) -> Result<Grant> {
214        self.post_json(
215            "/gfeh/grants/add",
216            &serde_json::json!({
217                "network": network,
218                "principal": principal,
219                "path": path,
220                "perm": perm,
221                "inheritable": inheritable,
222            }),
223        )
224        .await
225    }
226
227    /// Calls `POST /gfeh/grants/revoke`.
228    pub async fn revoke_grant(&self, network: &str, id: i64) -> Result<()> {
229        self.post_empty(
230            "/gfeh/grants/revoke",
231            &serde_json::json!({ "network": network, "id": id }),
232        )
233        .await
234    }
235
236    /// Calls `GET /gfeh/exposures`.
237    pub async fn exposures(&self, network: &str) -> Result<Vec<Exposure>> {
238        self.get_json(&format!("/gfeh/exposures?network={}", enc(network)))
239            .await
240    }
241
242    /// Withdraws a published link, after which it stops resolving.
243    ///
244    /// Calls `POST /gfeh/exposures/withdraw`.
245    pub async fn withdraw_exposure(&self, network: &str, token: &str) -> Result<()> {
246        self.post_empty(
247            "/gfeh/exposures/withdraw",
248            &serde_json::json!({ "network": network, "token": token }),
249        )
250        .await
251    }
252
253    // --- btrfs volumes ---
254
255    /// Lists subvolumes. `state` filters to `user`, `installed` or
256    /// `uninstalled`; `None` spans all three.
257    ///
258    /// Calls `POST /storage`.
259    pub async fn filesystems(
260        &self,
261        prefix: &str,
262        state: Option<&str>,
263        limit: u32,
264        offset: u32,
265        search: &str,
266    ) -> Result<FilesystemPage> {
267        let mut body = serde_json::json!({
268            "name": prefix,
269            "limit": limit,
270            "offset": offset,
271            "sort_by": "name",
272            "sort_order": "asc",
273        });
274        if let Some(state) = state.filter(|s| !s.is_empty()) {
275            body["state"] = serde_json::Value::String(state.into());
276        }
277        if !search.is_empty() {
278            body["search"] = serde_json::Value::String(search.into());
279        }
280        self.post_json("/storage", &body).await
281    }
282
283    /// Calls `POST /storage/create`.
284    pub async fn create_filesystem(&self, fs: &Filesystem) -> Result<()> {
285        self.post_empty("/storage/create", fs).await
286    }
287
288    /// Changes a volume's name or quota.
289    ///
290    /// Renaming works only for user volumes; a package volume (one under
291    /// `installed/` or `uninstalled/`) must keep its name, and the server
292    /// refuses the call if `fs.name` differs from `name`.
293    ///
294    /// Calls `POST /storage/modify`.
295    pub async fn modify_filesystem(&self, name: &str, fs: &Filesystem) -> Result<()> {
296        self.post_empty(
297            "/storage/modify",
298            &serde_json::json!({ "name": name, "filesystem": fs }),
299        )
300        .await
301    }
302
303    /// Calls `POST /storage/remove`.
304    pub async fn remove_filesystem(&self, name: &str) -> Result<()> {
305        self.post_empty("/storage/remove", &serde_json::json!({ "name": name }))
306            .await
307    }
308
309    // --- Archives ---
310    //
311    // How a bulk of files gets into or out of a volume. Both are admin-only, and
312    // both refuse a `gfeh/` volume: an object-storage partition's contents are
313    // gfehd's to write, and unpacking a tar over them behind its back would
314    // leave its index describing objects that are no longer there.
315
316    /// Unpacks an archive into a volume.
317    ///
318    /// The file is streamed from disk rather than read into memory — these run to
319    /// a gigabyte by default — and its **name matters**: the box picks the
320    /// decompressor from the extension, so [`is_supported_archive`] is worth
321    /// checking before spending the upload.
322    ///
323    /// `subpath` extracts into a subdirectory of the volume instead of its root.
324    /// `stop_service` names a systemd unit to stop for the duration, which is how
325    /// you replace files something is holding open; the box restarts it after.
326    ///
327    /// Calls `POST /storage/upload-archive` (admin).
328    pub async fn upload_archive(
329        &self,
330        subvolume: &str,
331        archive: &Path,
332        subpath: &str,
333        stop_service: &str,
334    ) -> Result<ArchiveUpload> {
335        // Part::file supplies the filename, the length and a streaming body. The
336        // length is the part that matters beyond convenience: it gives the
337        // request a Content-Length, which is what the box checks against its
338        // size limit before reading a byte.
339        let part = reqwest::multipart::Part::file(archive)
340            .await
341            .map_err(|source| Error::Io {
342                path: archive.display().to_string(),
343                source,
344            })?;
345
346        let mut form = reqwest::multipart::Form::new()
347            .text("subvolume", subvolume.to_owned())
348            .part("archive", part);
349        if !subpath.is_empty() {
350            form = form.text("subpath", subpath.to_owned());
351        }
352        if !stop_service.is_empty() {
353            form = form.text("stop_service", stop_service.to_owned());
354        }
355
356        const PATH: &str = "/storage/upload-archive";
357        // Deliberately not through `post_json`: the multipart boundary has to be
358        // the one reqwest generated for this form, so the body cannot be a
359        // serialized value.
360        let req = self
361            .request(reqwest::Method::POST, PATH)
362            .multipart(form);
363        let resp = self.send("POST", PATH, req).await?;
364        Self::decode(PATH, resp).await
365    }
366
367    /// Writes a compressed archive of a volume to `destination`.
368    ///
369    /// `paths` confines the archive to those entries, relative to the volume
370    /// root; empty takes everything. `format` is one of [`ARCHIVE_FORMATS`], or
371    /// empty for the box's default.
372    ///
373    /// The body is written to disk as it arrives, so this holds no more than one
374    /// chunk in memory however large the volume is. A failure part way through
375    /// leaves a partial file behind, which the caller should remove — an archive
376    /// that stops in the middle is not a smaller archive.
377    ///
378    /// Calls `POST /storage/download-archive` (admin).
379    pub async fn download_archive(
380        &self,
381        subvolume: &str,
382        paths: &[String],
383        format: &str,
384        destination: &Path,
385    ) -> Result<u64> {
386        use tokio::io::AsyncWriteExt as _;
387
388        let mut body = serde_json::json!({ "subvolume": subvolume });
389        if !paths.is_empty() {
390            body["paths"] = serde_json::json!(paths);
391        }
392        if !format.is_empty() {
393            body["format"] = serde_json::Value::String(format.to_owned());
394        }
395
396        const PATH: &str = "/storage/download-archive";
397        let req = self.request(reqwest::Method::POST, PATH).json(&body);
398        let mut resp = self.send("POST", PATH, req).await?;
399
400        let io_error = |source: std::io::Error| Error::Io {
401            path: destination.display().to_string(),
402            source,
403        };
404        let mut file = tokio::fs::File::create(destination).await.map_err(io_error)?;
405        let mut written = 0u64;
406        while let Some(chunk) = resp.chunk().await? {
407            file.write_all(&chunk).await.map_err(io_error)?;
408            written += chunk.len() as u64;
409        }
410        file.flush().await.map_err(io_error)?;
411        Ok(written)
412    }
413}
414
415fn enc(value: &str) -> String {
416    let mut out = String::with_capacity(value.len());
417    for byte in value.bytes() {
418        match byte {
419            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
420                out.push(byte as char)
421            }
422            other => out.push_str(&format!("%{other:02X}")),
423        }
424    }
425    out
426}
427
428#[cfg(test)]
429mod tests {
430    use super::*;
431
432    #[test]
433    fn default_ports_are_left_off_the_url() {
434        let https = PartitionName {
435            view: "public".into(),
436            fqdn: "files.home.town".into(),
437            port: 443,
438            http: false,
439        };
440        assert_eq!(https.url(), "https://files.home.town");
441
442        let http = PartitionName {
443            view: "public".into(),
444            fqdn: "files.home.town".into(),
445            port: 80,
446            http: true,
447        };
448        assert_eq!(http.url(), "http://files.home.town");
449    }
450
451    #[test]
452    fn nonstandard_ports_are_kept() {
453        let name = PartitionName {
454            view: "admin".into(),
455            fqdn: "files.home.town".into(),
456            port: 8443,
457            http: false,
458        };
459        assert_eq!(name.url(), "https://files.home.town:8443");
460    }
461
462    #[test]
463    fn archive_names_the_box_can_unpack_are_recognised() {
464        for name in [
465            "backup.tar.gz",
466            "BACKUP.TAR.GZ",
467            "backup.tgz",
468            "backup.tar.bz2",
469            "backup.tbz2",
470            "backup.tar.xz",
471            "backup.txz",
472            "backup.tar",
473        ] {
474            assert!(is_supported_archive(name), "{name} should be accepted");
475        }
476    }
477
478    #[test]
479    fn names_the_box_would_refuse_are_caught_before_the_upload() {
480        for name in ["backup.zip", "backup.7z", "backup", "backup.gz", "tar.gz.txt"] {
481            assert!(!is_supported_archive(name), "{name} should be refused");
482        }
483    }
484
485    #[test]
486    fn unset_port_falls_back_to_the_scheme_default() {
487        let name = PartitionName {
488            view: "public".into(),
489            fqdn: "files.home.town".into(),
490            port: 0,
491            http: true,
492        };
493        assert_eq!(name.url(), "http://files.home.town");
494    }
495}