loonfs_api/v0/
downloads.rs

1//! Download-grant shapes for the v0 HTTP API: what a client asks for when
2//! it wants a file's bytes straight from object storage, and the short-lived
3//! read capability it gets back.
4//!
5//! This is the read half of the direct transfer plane. The write half lives
6//! in [`super::uploads`], and the two share one access envelope
7//! ([`ObjectTransferAccess`]) because a client handles both the same way:
8//! send this method to this URL with these headers, before this instant.
9
10use super::ObjectTransferAccess;
11use crate::{AbsolutePath, ContentRef, NamespaceId, RevisionNo};
12use serde::{Deserialize, Serialize};
13
14/// What a client names when it asks to read a file directly.
15///
16/// A path and, optionally, the revision it wants — the same two things the
17/// proxied content read takes, so a caller switching transports changes
18/// nothing about what it is asking for.
19#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
20#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
21#[serde(deny_unknown_fields)]
22pub struct BeginDownloadRequest {
23    /// Absolute path of the file to read.
24    pub path: AbsolutePath,
25    /// Revision to read, or `None` for the path's current revision.
26    #[serde(default, skip_serializing_if = "Option::is_none")]
27    pub revision_no: Option<RevisionNo>,
28}
29
30impl BeginDownloadRequest {
31    /// Asks for the path's current revision.
32    pub fn for_path(path: AbsolutePath) -> Self {
33        Self {
34            path,
35            revision_no: None,
36        }
37    }
38
39    /// Asks for one prior revision of the path.
40    pub fn for_revision(path: AbsolutePath, revision_no: RevisionNo) -> Self {
41        Self {
42            path,
43            revision_no: Some(revision_no),
44        }
45    }
46}
47
48/// A short-lived capability to read one file's content object, plus
49/// everything the reader needs to check what arrives.
50///
51/// The raw object key is deliberately not here, exactly as it is not in a
52/// `direct_put` grant: a client learns a URL that expires, not an address it
53/// can revisit.
54///
55/// The grant names one immutable content object, so it does not go stale
56/// when the path moves on. A commit that replaces the file writes a new
57/// object and leaves this one alone; what the capability reads is what the
58/// requested revision held when the grant was issued, and the reference
59/// says which bytes those are.
60#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
61#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
62pub struct BeginDownloadResponse {
63    /// Namespace that was read.
64    pub namespace_id: NamespaceId,
65    /// Absolute path as rendered from stored display names.
66    pub absolute_path: AbsolutePath,
67    /// Revision the capability reads, resolved from the request.
68    pub revision_no: RevisionNo,
69    /// Identity, byte length, and checksum evidence for the object the
70    /// capability reads. A reader checks the bytes it receives against
71    /// `size_bytes`, and against `whole_file_sha256` when the reference
72    /// carries one — a direct-multipart object never will, because nobody
73    /// ever hashed it with SHA-256.
74    pub content_ref: ContentRef,
75    /// Short-lived read capability the client uses without learning the raw object key.
76    pub access: ObjectTransferAccess,
77}
78
79#[cfg(test)]
80mod tests {
81    use super::{BeginDownloadRequest, BeginDownloadResponse};
82    use crate::v0::ObjectTransferAccess;
83    use crate::{AbsolutePath, ContentId, ContentRef, NamespaceId, RevisionNo};
84    use std::collections::BTreeMap;
85
86    fn absolute_path() -> AbsolutePath {
87        AbsolutePath::parse("/docs/report.txt").expect("absolute path")
88    }
89
90    /// A download request names a path, never an object. Identity belongs
91    /// to the server on the way out exactly as it does on the way in.
92    #[test]
93    fn a_download_request_names_only_a_path_and_a_revision() {
94        let request: BeginDownloadRequest =
95            serde_json::from_str(r#"{"path":"/docs/report.txt"}"#).expect("decode request");
96        assert_eq!(request.path, absolute_path());
97        assert_eq!(request.revision_no, None);
98
99        let pinned: BeginDownloadRequest =
100            serde_json::from_str(r#"{"path":"/docs/report.txt","revision_no":3}"#)
101                .expect("decode pinned request");
102        assert_eq!(pinned.revision_no, Some(RevisionNo(3)));
103
104        assert!(
105            serde_json::from_str::<BeginDownloadRequest>(
106                r#"{"path":"/docs/report.txt","content_id":"con_0123456789abcdef0123456789abcdef"}"#
107            )
108            .is_err(),
109            "a client must not be able to name the content object"
110        );
111    }
112
113    #[test]
114    fn a_download_grant_exposes_only_presigned_access() {
115        let response = BeginDownloadResponse {
116            namespace_id: NamespaceId::parse("demo").expect("namespace id"),
117            absolute_path: absolute_path(),
118            revision_no: RevisionNo(7),
119            content_ref: ContentRef::blob_v1(ContentId::generate(), b"hello"),
120            access: ObjectTransferAccess::PresignedUrl {
121                method: "GET".to_owned(),
122                url: "https://bucket.example/object?X-Amz-Signature=abc".to_owned(),
123                headers: BTreeMap::new(),
124                expires_at_ms: 1,
125            },
126        };
127
128        let json = serde_json::to_string(&response).expect("serialize response");
129        assert!(json.contains(r#""kind":"presigned_url""#));
130        assert!(!json.contains("object_key"));
131    }
132}
loonfs_api/v0/downloads.rs

loonfs_api/v0/
downloads.rs
