Skip to main content

fauna_api/
drive.rs

1use std::sync::Arc;
2
3use chrono::{DateTime, Utc};
4use futures_util::StreamExt;
5use reqwest::header::{CONTENT_LENGTH, CONTENT_TYPE};
6use serde::de::DeserializeOwned;
7use serde_json::{Value, json};
8
9use crate::authentification::{CredentialsOrApiKey, Profile};
10use crate::error::{Error, Result};
11use crate::http::{client, ok};
12
13const DIRECTORY: &str = "application/x-directory";
14
15/// Progress callback, called with a fraction from 0 to 1.
16pub type Progress = Arc<dyn Fn(f64) + Send + Sync>;
17
18#[derive(Clone)]
19pub struct File {
20    pub authorization: DriveAuthorization,
21
22    pub content_type: String,
23    pub content_length: u64,
24
25    pub access_date: DateTime<Utc>,
26    pub create_date: DateTime<Utc>,
27
28    name: String,
29    online: bool,
30
31    data: Option<Vec<u8>>,
32    preview_data: Option<Option<Vec<u8>>>,
33}
34
35impl std::fmt::Debug for File {
36    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
37        f.debug_struct("File")
38            .field("authorization", &self.authorization)
39            .field("name", &self.name)
40            .field("online", &self.online)
41            .field("content_type", &self.content_type)
42            .field("content_length", &self.content_length)
43            .finish_non_exhaustive()
44    }
45}
46
47fn authorization_header(authorization: &CredentialsOrApiKey) -> String {
48    match authorization {
49        CredentialsOrApiKey::Credentials(credentials) => format!("Token {}", credentials.token),
50        CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
51    }
52}
53
54fn status_error(status: u16) -> Error {
55    match status {
56        401 => Error::Message(format!("{status}: Unauthorized request.")),
57        403 => Error::Message(format!("{status}: Forbidden request.")),
58        _ => Error::Message(format!("{status}: Bad request.")),
59    }
60}
61
62impl File {
63    #[allow(clippy::too_many_arguments)]
64    fn new(
65        authorization: DriveAuthorization,
66        name: String,
67        online: bool,
68        content_type: String,
69        content_length: u64,
70        access_date: DateTime<Utc>,
71        create_date: DateTime<Utc>,
72        data: Option<Vec<u8>>,
73    ) -> Self {
74        File {
75            authorization,
76            name,
77            online,
78            content_type,
79            content_length,
80            access_date,
81            create_date,
82            data,
83            preview_data: None,
84        }
85    }
86
87    pub fn from_json(json: &Value, authorization: DriveAuthorization) -> File {
88        let now = Utc::now();
89        let date = |key: &str| crate::tickets::parse_date(&json[key]).unwrap_or(now);
90        let content_length = match &json["contentLength"] {
91            Value::String(length) => length.parse().unwrap_or(0),
92            length => length.as_f64().unwrap_or(0.0) as u64,
93        };
94        File::new(
95            authorization,
96            json["name"].as_str().unwrap_or_default().to_string(),
97            true,
98            json["contentType"]
99                .as_str()
100                .unwrap_or("application/octet-stream")
101                .to_string(),
102            content_length,
103            date("accessDate"),
104            date("createDate"),
105            None,
106        )
107    }
108
109    pub fn name(&self) -> &str {
110        &self.name
111    }
112
113    pub fn online(&self) -> bool {
114        self.online
115    }
116
117    fn is_directory(&self) -> bool {
118        self.content_type == DIRECTORY
119    }
120
121    /// Authorization plus either Path (+ Group) or Access-Code, with the
122    /// trailing slash directories need.
123    fn file_request(&self, request: reqwest::RequestBuilder) -> reqwest::RequestBuilder {
124        match &self.authorization {
125            DriveAuthorization::Path {
126                authorization,
127                path,
128                group,
129            } => {
130                let request = request
131                    .header("Authorization", authorization_header(authorization))
132                    .header(
133                        "Path",
134                        if self.is_directory() {
135                            format!("{path}/")
136                        } else {
137                            path.clone()
138                        },
139                    );
140                match group {
141                    Some(group) => request.header("Group", group),
142                    None => request,
143                }
144            }
145            DriveAuthorization::AccessCode {
146                authorization,
147                access_code,
148            } => request
149                .header("Authorization", authorization_header(authorization))
150                .header("Access-Code", access_code),
151            DriveAuthorization::Repository {
152                authorization,
153                group,
154                ..
155            } => repository_request(request, authorization, group),
156        }
157    }
158
159    /// GET a Drive route, or the repository file itself with `query` for repository files.
160    fn get(&self, route: &str, query: &str) -> reqwest::RequestBuilder {
161        let url = match &self.authorization {
162            DriveAuthorization::Repository {
163                repository, path, ..
164            } => format!("{}{query}", repository_url(*repository, path)),
165            _ => format!("{}{route}", crate::get_url()),
166        };
167        self.file_request(client().get(url))
168    }
169
170    pub async fn download(
171        &mut self,
172        revalidate: bool,
173        on_progress: Option<Progress>,
174    ) -> Result<Vec<u8>> {
175        if let Some(data) = &self.data
176            && !revalidate
177        {
178            return Ok(data.clone());
179        }
180
181        let response = self.get("/file/download", "?download=1").send().await?;
182
183        if !response.status().is_success() {
184            return Err(status_error(response.status().as_u16()));
185        }
186
187        let content_length = self.content_length;
188        let on_loaded = on_progress.clone().map(|progress| {
189            move |loaded: u64| {
190                if content_length > 0 {
191                    progress((loaded as f64 / content_length as f64).clamp(0.0, 1.0));
192                }
193            }
194        });
195        let buffer = parse_stream(response, on_loaded).await?;
196        if let Some(progress) = on_progress {
197            progress(1.0);
198        }
199
200        let data = buffer.into_iter().next().unwrap_or_default();
201        self.data = Some(data.clone());
202        Ok(data)
203    }
204
205    // Fetch a server-generated preview image (image/webp) for this file, or
206    // None when the file type has no meaningful preview. Cached per file.
207    pub async fn preview(&mut self, revalidate: bool) -> Result<Option<Vec<u8>>> {
208        if let Some(preview) = &self.preview_data
209            && !revalidate
210        {
211            return Ok(preview.clone());
212        }
213
214        let response = self.get("/file/preview", "?preview=1").send().await?;
215
216        if response.status().as_u16() == 204 {
217            self.preview_data = Some(None);
218            return Ok(None);
219        }
220
221        if !response.status().is_success() {
222            let status = response.status().as_u16();
223            if status == 401 || status == 403 {
224                return Err(status_error(status));
225            }
226            // Soft-fail (incl. 429): cache miss so this File does not hammer.
227            self.preview_data = Some(None);
228            return Ok(None);
229        }
230
231        let buffer = parse_stream(response, None::<fn(u64)>).await?;
232        let data = buffer.into_iter().next().unwrap_or_default();
233        self.preview_data = Some(Some(data.clone()));
234        Ok(Some(data))
235    }
236
237    pub async fn upload(&mut self, on_progress: Option<Progress>) -> Result<()> {
238        let request = match &self.authorization {
239            DriveAuthorization::AccessCode { .. } => {
240                return Err(Error::Message("401: Unauthorized request.".to_string()));
241            }
242            DriveAuthorization::Path {
243                authorization,
244                path,
245                group,
246            } => {
247                let request = client()
248                    .post(format!("{}/file/upload", crate::get_url()))
249                    .header("Authorization", authorization_header(authorization))
250                    .header(
251                        "Path",
252                        if self.is_directory() {
253                            format!("{path}/")
254                        } else {
255                            path.clone()
256                        },
257                    );
258                match group {
259                    Some(group) => request.header("Group", group),
260                    None => request,
261                }
262            }
263            DriveAuthorization::Repository {
264                authorization,
265                repository,
266                path,
267                group,
268            } => repository_request(
269                client().post(repository_url(*repository, path)),
270                authorization,
271                group,
272            ),
273        };
274
275        let body: Vec<u8> = if self.is_directory() {
276            b"Folder".to_vec()
277        } else {
278            match &self.data {
279                Some(data) => data.clone(),
280                None => return Err(Error::Message("400: No data to upload.".to_string())),
281            }
282        };
283
284        let total = body.len();
285        let content_type = if self.content_type.is_empty() {
286            "application/octet-stream".to_string()
287        } else {
288            self.content_type.clone()
289        };
290        let response = request
291            .header(CONTENT_TYPE, content_type)
292            .header(CONTENT_LENGTH, total)
293            .body(crate::http::progress_body(body, on_progress.clone()))
294            .send()
295            .await
296            .map_err(|_| Error::Message("Failed to upload file.".to_string()))?;
297
298        if let Some(progress) = on_progress {
299            progress(1.0);
300        }
301
302        if response.status().is_success() {
303            self.online = true;
304            return Ok(());
305        }
306        Err(status_error(response.status().as_u16()))
307    }
308
309    pub async fn copy(&self, path: &str) -> Result<()> {
310        if matches!(self.authorization, DriveAuthorization::AccessCode { .. }) {
311            return Err(Error::Message("401: Unauthorized request.".to_string()));
312        }
313        if matches!(self.authorization, DriveAuthorization::Repository { .. }) {
314            return Err(Error::Message(
315                "403: Not available for repository files.".to_string(),
316            ));
317        }
318
319        let response = self
320            .file_request(client().post(format!("{}/file/copy", crate::get_url())))
321            .json(&json!({ "copyPath": path }))
322            .send()
323            .await?;
324        ok(response).await?;
325        Ok(())
326    }
327
328    pub async fn text(&mut self) -> Result<String> {
329        Ok(String::from_utf8_lossy(&self.download(false, None).await?).into_owned())
330    }
331
332    pub async fn json<T: DeserializeOwned>(&mut self) -> Result<T> {
333        Ok(serde_json::from_str(&self.text().await?)?)
334    }
335
336    pub async fn remove(&mut self) -> Result<()> {
337        let (authorization, path, group) = match &self.authorization {
338            DriveAuthorization::Path {
339                authorization,
340                path,
341                group,
342            } => (authorization, path, group),
343            DriveAuthorization::AccessCode { .. } => {
344                return Err(Error::Message("401: Unauthorized request.".to_string()));
345            }
346            DriveAuthorization::Repository { .. } => {
347                return Err(Error::Message(
348                    "403: Not available for repository files.".to_string(),
349                ));
350            }
351        };
352        let path = if self.is_directory() {
353            format!("{path}/")
354        } else {
355            path.clone()
356        };
357        remove(authorization, &path, group.as_deref()).await?;
358        self.data = None;
359        self.online = false;
360        Ok(())
361    }
362
363    pub async fn generate_access_code(&self, expiration: Option<u64>) -> Result<String> {
364        if matches!(self.authorization, DriveAuthorization::AccessCode { .. }) {
365            return Err(Error::Message("401: Unauthorized request.".to_string()));
366        }
367        if matches!(self.authorization, DriveAuthorization::Repository { .. }) {
368            return Err(Error::Message(
369                "403: Not available for repository files.".to_string(),
370            ));
371        }
372        let response = self
373            .file_request(client().post(format!("{}/file/access-code", crate::get_url())))
374            .json(&json!({ "expiration": expiration }))
375            .send()
376            .await?;
377        Ok(ok(response).await?.text().await?)
378    }
379
380    pub async fn owner(&self) -> Result<Profile> {
381        if matches!(self.authorization, DriveAuthorization::Repository { .. }) {
382            return Err(Error::Message(
383                "403: Not available for repository files.".to_string(),
384            ));
385        }
386        let response = correct_header(
387            &self.authorization,
388            client().get(format!("{}/file/owner", crate::get_url())),
389        )
390        .send()
391        .await?;
392        Ok(ok(response).await?.json().await?)
393    }
394}
395
396#[derive(Debug, Clone)]
397pub enum DriveAuthorization {
398    Path {
399        authorization: CredentialsOrApiKey,
400        path: String,
401        group: Option<String>,
402    },
403    AccessCode {
404        authorization: CredentialsOrApiKey,
405        access_code: String,
406    },
407    Repository {
408        authorization: CredentialsOrApiKey,
409        repository: u64,
410        path: String,
411        group: Option<String>,
412    },
413}
414
415/// A repository file's address on Termite: `/termite/repositories/{id}/files/{path}`.
416fn repository_url(repository: u64, path: &str) -> String {
417    let tail: String = path
418        .split('/')
419        .filter(|segment| !segment.is_empty())
420        .map(|segment| format!("/{}", crate::http::encode(segment)))
421        .collect();
422    format!(
423        "{}/termite/repositories/{repository}/files{tail}",
424        crate::termite::get_url()
425    )
426}
427
428fn repository_request(
429    request: reqwest::RequestBuilder,
430    authorization: &CredentialsOrApiKey,
431    group: &Option<String>,
432) -> reqwest::RequestBuilder {
433    let request = request.header("Authorization", authorization_header(authorization));
434    match group {
435        Some(group) => request.header("Group", group),
436        None => request,
437    }
438}
439
440/// `Partial<{ accessDate, createDate }>` in the TypeScript SDK.
441#[derive(Debug, Clone, Copy, Default)]
442pub struct FileDates {
443    pub access_date: Option<DateTime<Utc>>,
444    pub create_date: Option<DateTime<Utc>>,
445}
446
447/// The `meta` argument of `fromAccessCode`.
448#[derive(Debug, Clone, Default)]
449pub struct FileMeta {
450    pub name: String,
451    pub content_type: String,
452    pub content_length: Option<u64>,
453    pub access_date: Option<DateTime<Utc>>,
454    pub create_date: Option<DateTime<Utc>>,
455}
456
457fn correct_header(
458    authorization: &DriveAuthorization,
459    request: reqwest::RequestBuilder,
460) -> reqwest::RequestBuilder {
461    match authorization {
462        DriveAuthorization::Path {
463            authorization,
464            path,
465            group,
466        } => {
467            let request = request
468                .header("Authorization", authorization_header(authorization))
469                .header("Path", path);
470            match group {
471                Some(group) => request.header("Group", group),
472                None => request,
473            }
474        }
475        DriveAuthorization::AccessCode {
476            authorization,
477            access_code,
478        } => request
479            .header("Authorization", authorization_header(authorization))
480            .header("Access-Code", access_code),
481        DriveAuthorization::Repository {
482            authorization,
483            group,
484            ..
485        } => repository_request(request, authorization, group),
486    }
487}
488
489pub async fn list(
490    authorization: &CredentialsOrApiKey,
491    path: &str,
492    group: Option<&str>,
493) -> Result<Vec<String>> {
494    let request = client()
495        .get(format!("{}/file/list", crate::get_url()))
496        .header("Authorization", authorization_header(authorization))
497        .header("Path", path);
498    let request = match group {
499        Some(group) => request.header("Group", group),
500        None => request,
501    };
502    let response = request.send().await?;
503    Ok(ok(response).await?.json().await?)
504}
505
506/// Builds an in-memory file from bytes the caller already holds (the browser
507/// SDK takes a `File`). An empty `content_type` is inferred from the name.
508pub async fn wrap(
509    authorization: DriveAuthorization,
510    name: &str,
511    content_type: &str,
512    data: Vec<u8>,
513    options: FileDates,
514) -> Result<File> {
515    let now = Utc::now();
516    let content_type = if content_type.is_empty() {
517        mime_guess::from_path(name)
518            .first()
519            .map(|mime| mime.essence_str().to_string())
520            .unwrap_or_else(|| "application/octet-stream".to_string())
521    } else {
522        content_type.to_string()
523    };
524    Ok(File::new(
525        authorization,
526        name.to_string(),
527        false,
528        content_type,
529        data.len() as u64,
530        options.access_date.unwrap_or(now),
531        options.create_date.unwrap_or(now),
532        Some(data),
533    ))
534}
535
536/// Build an in-memory File from raw bytes (not yet uploaded). `path` is
537/// the Drive destination (e.g. `tmp/${uuid}-${name}`); the display name is the
538/// last path segment. The file is offline until an explicit `upload()`.
539pub fn from_bytes(
540    authorization: CredentialsOrApiKey,
541    path: &str,
542    content_type: &str,
543    data: Vec<u8>,
544    options: FileDates,
545) -> File {
546    let now = Utc::now();
547    let name = path
548        .rsplit('/')
549        .next()
550        .filter(|name| !name.is_empty())
551        .unwrap_or(path);
552    File::new(
553        DriveAuthorization::Path {
554            authorization,
555            path: path.to_string(),
556            group: None,
557        },
558        name.to_string(),
559        false,
560        content_type.to_string(),
561        data.len() as u64,
562        options.access_date.unwrap_or(now),
563        options.create_date.unwrap_or(now),
564        Some(data),
565    )
566}
567
568/// Build a streaming File addressed by a per-file access code. Bytes are
569/// pulled on demand via `download()` (the `Access-Code` path). Used to hydrate
570/// chat message FILE parts returned by the server (each carries its own code),
571/// so members stream file bytes uniformly without a host-drive path.
572pub fn from_access_code(
573    authorization: CredentialsOrApiKey,
574    access_code: &str,
575    meta: FileMeta,
576) -> File {
577    let now = Utc::now();
578    File::new(
579        DriveAuthorization::AccessCode {
580            authorization,
581            access_code: access_code.to_string(),
582        },
583        meta.name,
584        true,
585        meta.content_type,
586        meta.content_length.unwrap_or(0),
587        meta.access_date.unwrap_or(now),
588        meta.create_date.unwrap_or(now),
589        None,
590    )
591}
592
593pub async fn folder(authorization: DriveAuthorization, options: FileDates) -> Result<File> {
594    let path = match &authorization {
595        DriveAuthorization::Path { path, .. } | DriveAuthorization::Repository { path, .. } => path,
596        DriveAuthorization::AccessCode { .. } => {
597            return Err(Error::Message("401: Unauthorized request.".to_string()));
598        }
599    };
600
601    let normalized = path.replace('\\', "/");
602    let normalized = normalized.trim_end_matches('/');
603    let name = normalized
604        .rsplit('/')
605        .next()
606        .unwrap_or_default()
607        .to_string();
608
609    let now = Utc::now();
610    Ok(File::new(
611        authorization,
612        name,
613        false,
614        DIRECTORY.to_string(),
615        0,
616        options.access_date.unwrap_or(now),
617        options.create_date.unwrap_or(now),
618        None,
619    ))
620}
621
622pub async fn pull(authorization: DriveAuthorization) -> Result<File> {
623    let url = match &authorization {
624        DriveAuthorization::Repository {
625            repository, path, ..
626        } => repository_url(*repository, path),
627        _ => format!("{}/file/pull", crate::get_url()),
628    };
629    let response = correct_header(&authorization, client().get(url))
630        .send()
631        .await?;
632    let json: Value = ok(response).await?.json().await?;
633    Ok(File::from_json(&json, authorization))
634}
635
636pub async fn remove(
637    authorization: &CredentialsOrApiKey,
638    path: &str,
639    group: Option<&str>,
640) -> Result<bool> {
641    let request = client()
642        .delete(format!("{}/file", crate::get_url()))
643        .header("Authorization", authorization_header(authorization))
644        .header("Path", path);
645    let request = match group {
646        Some(group) => request.header("Group", group),
647        None => request,
648    };
649    let response = request.send().await?;
650    ok(response).await?;
651    Ok(true)
652}
653
654/// Split a Drive style response into its parts. With `Encoding-Size` above 1 the
655/// body is a `--BOUNDARY` separated multipart and this returns every part.
656pub async fn parse_stream(
657    response: reqwest::Response,
658    on_loaded: Option<impl Fn(u64)>,
659) -> Result<Vec<Vec<u8>>> {
660    let encoding_size = response
661        .headers()
662        .get("Encoding-Size")
663        .and_then(|value| value.to_str().ok())
664        .and_then(|value| value.trim().parse::<i64>().ok());
665
666    let mut buffer = Vec::new();
667    let mut loaded = 0u64;
668    let mut body = response.bytes_stream();
669    while let Some(chunk) = body.next().await {
670        let chunk = chunk?;
671        loaded += chunk.len() as u64;
672        buffer.extend_from_slice(&chunk);
673        if let Some(on_loaded) = &on_loaded {
674            on_loaded(loaded);
675        }
676    }
677
678    if encoding_size.is_none_or(|size| size <= 1) {
679        return Ok(vec![buffer]);
680    }
681
682    const BOUNDARY: &[u8] = b"--BOUNDARY";
683    let mut parts = Vec::new();
684    let mut current = 0;
685    while let Some(offset) = buffer[current..]
686        .windows(BOUNDARY.len())
687        .position(|window| window == BOUNDARY)
688    {
689        let index = current + offset;
690        if index > current {
691            parts.push(buffer[current..index].to_vec());
692        }
693        current = index + BOUNDARY.len();
694    }
695    if current < buffer.len() {
696        parts.push(buffer[current..].to_vec());
697    }
698    Ok(parts)
699}
700
701#[cfg(test)]
702mod tests {
703    use super::parse_stream;
704
705    fn response(encoding_size: Option<&str>, body: &'static [u8]) -> reqwest::Response {
706        let mut builder = http::Response::builder();
707        if let Some(size) = encoding_size {
708            builder = builder.header("Encoding-Size", size);
709        }
710        reqwest::Response::from(builder.body(body).unwrap())
711    }
712
713    #[tokio::test]
714    async fn single_part_bodies_come_back_whole() {
715        let parts = parse_stream(response(None, b"hello"), None::<fn(u64)>)
716            .await
717            .unwrap();
718        assert_eq!(parts, vec![b"hello".to_vec()]);
719    }
720
721    #[tokio::test]
722    async fn multi_part_bodies_split_on_the_boundary() {
723        let loaded = std::sync::Mutex::new(0);
724        let parts = parse_stream(
725            response(Some("2"), b"--BOUNDARYfirst--BOUNDARYsecond"),
726            Some(|bytes| *loaded.lock().unwrap() = bytes),
727        )
728        .await
729        .unwrap();
730        assert_eq!(parts, vec![b"first".to_vec(), b"second".to_vec()]);
731        assert_eq!(*loaded.lock().unwrap(), 31);
732    }
733}