Skip to main content

objectstore_types/
metadata.rs

1//! Per-object metadata types and HTTP header serialization.
2//!
3//! This module defines [`Metadata`], the per-object metadata structure that
4//! travels through the entire system: clients set it via HTTP headers, the
5//! server parses and validates it, the service passes it to backends, and
6//! backends persist it alongside the stored object.
7//!
8//! The module also defines further types used in metadata.
9//!
10//! # Serialization
11//!
12//! Metadata has two serialization formats:
13//!
14//! - **HTTP headers** — used by the public API. [`Metadata::from_headers`] and
15//!   [`Metadata::to_headers`] handle this conversion for public fields only.
16//! - **JSON** — used internally by backends for storage. JSON serialization
17//!   includes additional internal fields that are skipped in the header
18//!   representation.
19//!
20//! # HTTP header prefixes
21//!
22//! Headers use three prefix conventions:
23//!
24//! - Standard HTTP headers where applicable (`Content-Type`, `Content-Encoding`)
25//! - `x-sn-*` for objectstore-specific fields (e.g. `x-sn-expiration`)
26//! - `x-snme-` for custom user metadata (e.g. `x-snme-build_id`)
27//!
28//! Backends that store metadata as object metadata (like GCS) layer their own
29//! prefix on top, so `x-sn-expiration` becomes `x-goog-meta-x-sn-expiration`.
30//! The [`Metadata::from_headers`] and [`Metadata::to_headers`] methods accept
31//! a `prefix` parameter for this purpose.
32//!
33//! # Escaping free-form values
34//!
35//! [`Metadata`] always holds logical strings: [`filename`](Metadata::filename),
36//! [`origin`](Metadata::origin), and [`custom`](Metadata::custom) values may
37//! contain arbitrary Unicode.
38//!
39//! Over the wire, metadata travels in HTTP headers, which have no charset. In
40//! practice anything outside visible ASCII is either rejected outright or
41//! silently reinterpreted.
42//!
43//! The fields are therefore percent-encoded in headers, via
44//! [`headers::encode_header_value`] and [`headers::decode_header_value`].
45//! Encoding is a property of the *transport*, never of the stored value:
46//! anything reading [`Metadata`] sees the logical string.
47
48use std::borrow::Cow;
49use std::collections::BTreeMap;
50use std::fmt;
51use std::num::ParseIntError;
52use std::str::FromStr;
53use std::time::{Duration, SystemTime};
54
55use http::header::{self, HeaderMap, HeaderName};
56use humantime::{format_duration, format_rfc3339_micros, parse_duration, parse_rfc3339};
57use serde::{Deserialize, Serialize};
58
59use crate::headers;
60
61/// The custom HTTP header that contains the serialized [`ExpirationPolicy`].
62pub const HEADER_EXPIRATION: &str = "x-sn-expiration";
63/// The custom HTTP header that contains the object creation time.
64pub const HEADER_TIME_CREATED: &str = "x-sn-time-created";
65/// The custom HTTP header that contains the object expiration time.
66pub const HEADER_TIME_EXPIRES: &str = "x-sn-time-expires";
67/// The custom HTTP header that contains the origin of the object.
68pub const HEADER_ORIGIN: &str = "x-sn-origin";
69/// The custom HTTP header that contains the filename of the object.
70pub const HEADER_FILENAME: &str = "x-sn-filename";
71/// The custom HTTP header that contains the size of the stored object in bytes.
72pub const HEADER_SIZE: &str = "x-sn-size";
73/// The prefix for custom HTTP headers containing custom per-object metadata.
74pub const HEADER_META_PREFIX: &str = "x-snme-";
75
76/// The default content type for objects without a known content type.
77pub const DEFAULT_CONTENT_TYPE: &str = "application/octet-stream";
78
79/// Upper bound on the TTI debounce window.
80///
81/// The debounce window for TTI bumps is `min(tti / 4, MAX_TTI_DEBOUNCE)`. For
82/// TTI values above 4 days the debounce stays at 24 hours (the historical
83/// constant); shorter TTI values get a proportionally smaller window so that
84/// bumps are not silently suppressed.
85const MAX_TTI_DEBOUNCE: Duration = Duration::from_hours(24);
86
87/// Errors that can happen dealing with metadata
88#[derive(Debug, thiserror::Error)]
89pub enum Error {
90    /// Any problems dealing with http headers, essentially converting to/from [`str`].
91    #[error("error dealing with http headers")]
92    Header(#[from] Option<http::Error>),
93    /// The value for the expiration policy is invalid.
94    #[error("invalid expiration policy value")]
95    Expiration(#[from] Option<humantime::DurationError>),
96    /// The compression algorithm is invalid.
97    #[error("invalid compression value")]
98    Compression,
99    /// The content type is invalid.
100    #[error("invalid content type")]
101    ContentType(#[from] mediatype::MediaTypeError),
102    /// The creation time is invalid.
103    #[error("invalid creation time")]
104    CreationTime(#[from] humantime::TimestampError),
105    /// The object size is not a valid byte count.
106    #[error("invalid object size")]
107    Size(#[from] ParseIntError),
108    /// A free-form header value did not decode into a logical string.
109    #[error("invalid metadata header value")]
110    Encoding(#[from] crate::headers::DecodeError),
111    /// An internal consistency invariant on the metadata was violated.
112    #[error("invariant violation: {0}")]
113    Invariant(&'static str),
114}
115impl From<header::InvalidHeaderValue> for Error {
116    fn from(err: header::InvalidHeaderValue) -> Self {
117        Self::Header(Some(err.into()))
118    }
119}
120impl From<header::InvalidHeaderName> for Error {
121    fn from(err: header::InvalidHeaderName) -> Self {
122        Self::Header(Some(err.into()))
123    }
124}
125impl From<header::ToStrError> for Error {
126    fn from(_err: header::ToStrError) -> Self {
127        // the error happens when converting a header value back to a `str`
128        Self::Header(None)
129    }
130}
131
132/// The per-object expiration policy.
133///
134/// Controls automatic object cleanup. The policy is set by the client at upload
135/// time via the [`x-sn-expiration`](HEADER_EXPIRATION) header and persisted with
136/// the object.
137///
138/// | Variant      | Wire format | Behavior                                     |
139/// |--------------|-------------|----------------------------------------------|
140/// | `Manual`     | `manual`    | No automatic expiration (default)            |
141/// | `TimeToLive` | `ttl:30s`   | Expires after a fixed duration from creation |
142/// | `TimeToIdle` | `tti:1h`    | Expires after a duration of no access        |
143///
144/// Durations use [humantime](https://docs.rs/humantime) format (e.g. `30s`,
145/// `5m`, `1h`, `7d`).
146///
147/// **Important:** `Manual` is the default and must remain so — persisted objects
148/// without an explicit policy are deserialized as `Manual`.
149#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
150pub enum ExpirationPolicy {
151    /// Manual expiration, meaning no automatic cleanup.
152    // IMPORTANT: Do not change the default, we rely on this for persisted objects.
153    #[default]
154    Manual,
155    /// Time to live, with expiration after the specified duration.
156    TimeToLive(Duration),
157    /// Time to idle, with expiration once the object has not been accessed within the specified duration.
158    TimeToIdle(Duration),
159}
160impl ExpirationPolicy {
161    /// Returns the duration after which the object expires.
162    pub fn expires_in(&self) -> Option<Duration> {
163        match self {
164            ExpirationPolicy::Manual => None,
165            ExpirationPolicy::TimeToLive(duration) => Some(*duration),
166            ExpirationPolicy::TimeToIdle(duration) => Some(*duration),
167        }
168    }
169
170    /// Returns `true` if this policy indicates time-based expiry.
171    pub fn is_timeout(&self) -> bool {
172        match self {
173            ExpirationPolicy::TimeToLive(_) => true,
174            ExpirationPolicy::TimeToIdle(_) => true,
175            ExpirationPolicy::Manual => false,
176        }
177    }
178
179    /// Returns `true` if this policy is `Manual`.
180    pub fn is_manual(&self) -> bool {
181        *self == ExpirationPolicy::Manual
182    }
183
184    /// Checks whether a TTI deadline needs bumping given the current expiry and access time.
185    ///
186    /// Returns `Some(new_expire_at)` when the current deadline is stale enough
187    /// to justify a write, `None` otherwise. The debounce window scales with the
188    /// TTI duration so short-TTI objects get bumped more frequently.
189    pub fn check_tti_bump(
190        &self,
191        time_expires: Option<SystemTime>,
192        access_time: SystemTime,
193    ) -> Option<SystemTime> {
194        let ExpirationPolicy::TimeToIdle(tti) = *self else {
195            return None;
196        };
197
198        let new_expire_at = access_time + tti;
199        let debounce = (tti / 4).min(MAX_TTI_DEBOUNCE);
200        match time_expires {
201            Some(ts) if ts < new_expire_at - debounce => Some(new_expire_at),
202            _ => None,
203        }
204    }
205}
206impl fmt::Display for ExpirationPolicy {
207    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
208        match self {
209            ExpirationPolicy::TimeToLive(duration) => {
210                write!(f, "ttl:{}", format_duration(*duration))
211            }
212            ExpirationPolicy::TimeToIdle(duration) => {
213                write!(f, "tti:{}", format_duration(*duration))
214            }
215            ExpirationPolicy::Manual => f.write_str("manual"),
216        }
217    }
218}
219impl FromStr for ExpirationPolicy {
220    type Err = Error;
221
222    fn from_str(s: &str) -> Result<Self, Self::Err> {
223        if s == "manual" {
224            return Ok(ExpirationPolicy::Manual);
225        }
226        if let Some(duration) = s.strip_prefix("ttl:") {
227            return Ok(ExpirationPolicy::TimeToLive(parse_duration(duration)?));
228        }
229        if let Some(duration) = s.strip_prefix("tti:") {
230            return Ok(ExpirationPolicy::TimeToIdle(parse_duration(duration)?));
231        }
232        Err(Error::Expiration(None))
233    }
234}
235
236/// The compression algorithm applied to an object's payload.
237///
238/// Transmitted via the standard `Content-Encoding` HTTP header. Currently only
239/// Zstandard (`zstd`) is supported.
240#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
241pub enum Compression {
242    /// Compressed using `zstd`.
243    Zstd,
244    // /// Compressed using `gzip`.
245    // Gzip,
246    // /// Compressed using `lz4`.
247    // Lz4,
248}
249
250impl Compression {
251    /// Returns a string representation of the compression algorithm.
252    pub fn as_str(&self) -> &str {
253        match self {
254            Compression::Zstd => "zstd",
255            // Compression::Gzip => "gzip",
256            // Compression::Lz4 => "lz4",
257        }
258    }
259}
260
261impl fmt::Display for Compression {
262    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
263        f.write_str(self.as_str())
264    }
265}
266
267impl FromStr for Compression {
268    type Err = Error;
269
270    fn from_str(s: &str) -> Result<Self, Self::Err> {
271        match s {
272            "zstd" => Ok(Compression::Zstd),
273            // "gzip" => Compression::Gzip,
274            // "lz4" => Compression::Lz4,
275            _ => Err(Error::Compression),
276        }
277    }
278}
279
280/// Per-object metadata.
281///
282/// Includes first-class fields (expiration, compression, timestamps, etc.) and
283/// arbitrary user-provided key-value metadata. See the [module-level
284/// documentation](self) for the HTTP header mapping conventions.
285#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
286#[serde(default)]
287pub struct Metadata {
288    /// The expiration policy of the object (header: `x-sn-expiration`).
289    ///
290    /// Skipped during serialization when set to [`ExpirationPolicy::Manual`].
291    #[serde(skip_serializing_if = "ExpirationPolicy::is_manual")]
292    pub expiration_policy: ExpirationPolicy,
293
294    /// The creation/last replacement time of the object (header: `x-sn-time-created`).
295    ///
296    /// Set by the server every time an object is put, i.e. when objects are first
297    /// created and when existing objects are overwritten.
298    #[serde(skip_serializing_if = "Option::is_none")]
299    pub time_created: Option<SystemTime>,
300
301    /// The resolved expiration timestamp (header: `x-sn-time-expires`).
302    ///
303    /// Derived from the [`expiration_policy`](Self::expiration_policy). When using
304    /// a time-to-idle policy, this reflects the expiration timestamp present
305    /// *prior to* the current access to the object.
306    #[serde(skip_serializing_if = "Option::is_none")]
307    pub time_expires: Option<SystemTime>,
308
309    /// IANA media type of the object (header: `Content-Type`).
310    ///
311    /// Defaults to [`DEFAULT_CONTENT_TYPE`] (`application/octet-stream`).
312    pub content_type: Cow<'static, str>,
313
314    /// The compression algorithm used for this object (header: `Content-Encoding`).
315    #[serde(skip_serializing_if = "Option::is_none")]
316    pub compression: Option<Compression>,
317
318    /// The origin of the object (header: `x-sn-origin`).
319    ///
320    /// Typically the IP address of the original source. This is an optional but
321    /// encouraged field that tracks where the payload was originally obtained
322    /// from (e.g. the IP of a Sentry SDK or CLI).
323    #[serde(skip_serializing_if = "Option::is_none")]
324    pub origin: Option<String>,
325
326    /// An optional filename associated with this object (header: `x-sn-filename`).
327    ///
328    /// When present, the server includes a `Content-Disposition: attachment; filename="<filename>"`
329    /// header in GET responses, prompting browsers and download tools to save the file
330    /// under this name. Non-ASCII filenames additionally get an RFC 8187 `filename*` parameter.
331    ///
332    /// This is a logical string and may contain arbitrary Unicode; it is escaped only on the
333    /// wire (see [the module docs](self#escaping-free-form-values)).
334    #[serde(skip_serializing_if = "Option::is_none")]
335    pub filename: Option<String>,
336
337    /// Size of the stored data in bytes, if known (header: `x-sn-size`).
338    ///
339    /// Read-only. This is the size of the complete object, even when only a range of it is
340    /// being returned. It describes the stored bytes, so for a compressed object it is the
341    /// compressed size.
342    #[serde(skip_serializing_if = "Option::is_none")]
343    pub size: Option<usize>,
344
345    /// Arbitrary user-provided key-value metadata (header prefix: `x-snme-`).
346    ///
347    /// Each entry is transmitted as `x-snme-{key}: {value}`.
348    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
349    pub custom: BTreeMap<String, String>,
350}
351
352impl Metadata {
353    /// Parses the metadata headers accepted from writing endpoints.
354    ///
355    /// Unlike [`from_headers`](Self::from_headers), this skips parsing read-only attributes so
356    /// clients cannot set them via headers.
357    ///
358    /// This materializes the following attributes:
359    /// - [`time_created`](Self::time_created)
360    /// - [`time_expires`](Self::time_expires)
361    ///
362    /// A prefix can also be provided which is stripped from custom non-standard headers.
363    pub fn from_insert_headers(headers: &HeaderMap, prefix: &str) -> Result<Self, Error> {
364        let mut metadata = Self::parse_headers(headers, prefix, true)?;
365
366        let now = SystemTime::now();
367        metadata.time_created = Some(now);
368        metadata.time_expires = metadata.expiration_policy.expires_in().map(|ttl| now + ttl);
369
370        Ok(metadata)
371    }
372
373    /// Validates internal consistency of the metadata.
374    ///
375    /// A time-based [`expiration_policy`](Self::expiration_policy) must carry a resolved
376    /// [`time_expires`](Self::time_expires); backends rely on this to persist a concrete
377    /// expiration.
378    pub fn validate(&self) -> Result<(), Error> {
379        if self.expiration_policy.is_timeout() && self.time_expires.is_none() {
380            return Err(Error::Invariant(
381                "expiration policy requires a resolved expiration time",
382            ));
383        }
384        Ok(())
385    }
386
387    /// Checks whether this object's TTI deadline needs bumping.
388    ///
389    /// See [`ExpirationPolicy::check_tti_bump`] for details.
390    pub fn check_tti_bump(&self, access_time: SystemTime) -> Option<SystemTime> {
391        self.expiration_policy
392            .check_tti_bump(self.time_expires, access_time)
393    }
394
395    /// Extracts public API metadata from the given [`HeaderMap`].
396    ///
397    /// A prefix can be also be provided which is being stripped from custom non-standard headers.
398    pub fn from_headers(headers: &HeaderMap, prefix: &str) -> Result<Self, Error> {
399        Self::parse_headers(headers, prefix, false)
400    }
401
402    /// Parses metadata from the given [`HeaderMap`].
403    ///
404    /// When `skip_read_only` is set, read-only attributes are not parsed off the headers, so a
405    /// malformed client-supplied value cannot fail the parse. A prefix can also be provided which
406    /// is stripped from custom non-standard headers.
407    fn parse_headers(
408        headers: &HeaderMap,
409        prefix: &str,
410        skip_read_only: bool,
411    ) -> Result<Self, Error> {
412        let mut metadata = Metadata::default();
413
414        for (name, value) in headers {
415            match *name {
416                // standard HTTP headers
417                header::CONTENT_TYPE => {
418                    let content_type = value.to_str()?;
419                    validate_content_type(content_type)?;
420                    metadata.content_type = content_type.to_owned().into();
421                }
422                header::CONTENT_ENCODING => {
423                    let compression = value.to_str()?;
424                    metadata.compression = Some(Compression::from_str(compression)?);
425                }
426                _ => {
427                    let Some(name) = name.as_str().strip_prefix(prefix) else {
428                        continue;
429                    };
430
431                    match name {
432                        // Objectstore first-class metadata
433                        HEADER_EXPIRATION => {
434                            let expiration_policy = value.to_str()?;
435                            metadata.expiration_policy =
436                                ExpirationPolicy::from_str(expiration_policy)?;
437                        }
438                        HEADER_TIME_CREATED if !skip_read_only => {
439                            let timestamp = value.to_str()?;
440                            let time = parse_rfc3339(timestamp)?;
441                            metadata.time_created = Some(time);
442                        }
443                        HEADER_TIME_EXPIRES if !skip_read_only => {
444                            let timestamp = value.to_str()?;
445                            let time = parse_rfc3339(timestamp)?;
446                            metadata.time_expires = Some(time);
447                        }
448                        HEADER_ORIGIN => {
449                            metadata.origin = Some(headers::decode_header_value(value)?);
450                        }
451                        HEADER_FILENAME => {
452                            metadata.filename = Some(headers::decode_header_value(value)?);
453                        }
454                        HEADER_SIZE if !skip_read_only => {
455                            let size = value.to_str()?;
456                            metadata.size = Some(size.parse()?);
457                        }
458                        _ => {
459                            // customer-provided metadata
460                            if let Some(name) = name.strip_prefix(HEADER_META_PREFIX) {
461                                let value = headers::decode_header_value(value)?;
462                                metadata.custom.insert(name.into(), value);
463                            }
464                        }
465                    }
466                }
467            }
468        }
469
470        Ok(metadata)
471    }
472
473    /// Turns the metadata into a [`HeaderMap`] for the public API.
474    ///
475    /// It will prefix any non-standard headers with the given `prefix`. GCS-specific headers are
476    /// not emitted; backends handle those separately.
477    pub fn to_headers(&self, prefix: &str) -> Result<HeaderMap, Error> {
478        let Self {
479            content_type,
480            compression,
481            origin,
482            filename,
483            expiration_policy,
484            time_created,
485            time_expires,
486            size,
487            custom,
488        } = self;
489
490        let mut headers = HeaderMap::new();
491
492        // standard headers
493        headers.append(header::CONTENT_TYPE, content_type.parse()?);
494        if let Some(compression) = compression {
495            headers.append(header::CONTENT_ENCODING, compression.as_str().parse()?);
496        }
497
498        // Objectstore first-class metadata
499        if *expiration_policy != ExpirationPolicy::Manual {
500            let name = HeaderName::try_from(format!("{prefix}{HEADER_EXPIRATION}"))?;
501            headers.append(name, expiration_policy.to_string().parse()?);
502        }
503        if let Some(time) = time_created {
504            let name = HeaderName::try_from(format!("{prefix}{HEADER_TIME_CREATED}"))?;
505            let timestamp = format_rfc3339_micros(*time);
506            headers.append(name, timestamp.to_string().parse()?);
507        }
508        if let Some(time) = time_expires {
509            let name = HeaderName::try_from(format!("{prefix}{HEADER_TIME_EXPIRES}"))?;
510            let timestamp = format_rfc3339_micros(*time);
511            headers.append(name, timestamp.to_string().parse()?);
512        }
513        if let Some(origin) = origin {
514            let name = HeaderName::try_from(format!("{prefix}{HEADER_ORIGIN}"))?;
515            headers.append(name, headers::encode_header_value(origin));
516        }
517        if let Some(filename) = filename {
518            let name = HeaderName::try_from(format!("{prefix}{HEADER_FILENAME}"))?;
519            headers.append(name, headers::encode_header_value(filename));
520        }
521        if let Some(size) = size {
522            let name = HeaderName::try_from(format!("{prefix}{HEADER_SIZE}"))?;
523            headers.append(name, size.to_string().parse()?);
524        }
525
526        // customer-provided metadata
527        for (key, value) in custom {
528            let name = HeaderName::try_from(format!("{prefix}{HEADER_META_PREFIX}{key}"))?;
529            headers.append(name, headers::encode_header_value(value));
530        }
531
532        Ok(headers)
533    }
534}
535
536/// Validates that `content_type` is a valid [IANA Media
537/// Type](https://www.iana.org/assignments/media-types/media-types.xhtml).
538fn validate_content_type(content_type: &str) -> Result<(), Error> {
539    mediatype::MediaType::parse(content_type)?;
540    Ok(())
541}
542
543impl Default for Metadata {
544    fn default() -> Self {
545        Self {
546            expiration_policy: ExpirationPolicy::Manual,
547            time_created: None,
548            time_expires: None,
549            content_type: DEFAULT_CONTENT_TYPE.into(),
550            compression: None,
551            origin: None,
552            filename: None,
553            size: None,
554            custom: BTreeMap::new(),
555        }
556    }
557}
558
559#[cfg(test)]
560mod tests {
561    use super::*;
562
563    #[test]
564    fn from_headers_with_origin() {
565        let mut headers = HeaderMap::new();
566        headers.insert("content-type", "text/plain".parse().unwrap());
567        headers.insert(HEADER_ORIGIN, "203.0.113.42".parse().unwrap());
568
569        let metadata = Metadata::from_headers(&headers, "").unwrap();
570        assert_eq!(metadata.origin.as_deref(), Some("203.0.113.42"));
571        assert_eq!(metadata.content_type, "text/plain");
572    }
573
574    #[test]
575    fn from_headers_without_origin() {
576        let mut headers = HeaderMap::new();
577        headers.insert("content-type", "text/plain".parse().unwrap());
578
579        let metadata = Metadata::from_headers(&headers, "").unwrap();
580        assert!(metadata.origin.is_none());
581    }
582
583    #[test]
584    fn to_headers_with_origin() {
585        let metadata = Metadata {
586            origin: Some("203.0.113.42".into()),
587            ..Default::default()
588        };
589
590        let headers = metadata.to_headers("").unwrap();
591        assert_eq!(headers.get(HEADER_ORIGIN).unwrap(), "203.0.113.42");
592    }
593
594    #[test]
595    fn to_headers_without_origin() {
596        let metadata = Metadata::default();
597        let headers = metadata.to_headers("").unwrap();
598        assert!(headers.get(HEADER_ORIGIN).is_none());
599    }
600
601    #[test]
602    fn origin_header_roundtrip() {
603        let metadata = Metadata {
604            origin: Some("203.0.113.42".into()),
605            ..Default::default()
606        };
607
608        let headers = metadata.to_headers("").unwrap();
609        let roundtripped = Metadata::from_headers(&headers, "").unwrap();
610        assert_eq!(roundtripped.origin, metadata.origin);
611    }
612
613    #[test]
614    fn from_headers_with_filename() {
615        let mut headers = HeaderMap::new();
616        headers.insert(HEADER_FILENAME, "report.pdf".parse().unwrap());
617
618        let metadata = Metadata::from_headers(&headers, "").unwrap();
619        assert_eq!(metadata.filename.as_deref(), Some("report.pdf"));
620    }
621
622    #[test]
623    fn from_headers_without_filename() {
624        let headers = HeaderMap::new();
625        let metadata = Metadata::from_headers(&headers, "").unwrap();
626        assert!(metadata.filename.is_none());
627    }
628
629    #[test]
630    fn to_headers_with_filename() {
631        let metadata = Metadata {
632            filename: Some("report.pdf".into()),
633            ..Default::default()
634        };
635
636        let headers = metadata.to_headers("").unwrap();
637        assert_eq!(headers.get(HEADER_FILENAME).unwrap(), "report.pdf");
638    }
639
640    #[test]
641    fn to_headers_without_filename() {
642        let metadata = Metadata::default();
643        let headers = metadata.to_headers("").unwrap();
644        assert!(headers.get(HEADER_FILENAME).is_none());
645    }
646
647    #[test]
648    fn filename_header_roundtrip() {
649        let metadata = Metadata {
650            filename: Some("report.pdf".into()),
651            ..Default::default()
652        };
653
654        let headers = metadata.to_headers("").unwrap();
655        let roundtripped = Metadata::from_headers(&headers, "").unwrap();
656        assert_eq!(roundtripped.filename, metadata.filename);
657    }
658
659    /// Every free-form field is escaped on the way out and decoded on the way back in.
660    ///
661    /// The escaping itself is covered in [`crate::headers`]; this only pins down that each of the
662    /// three fields that needs it actually goes through it, in both directions.
663    #[test]
664    fn free_form_values_are_escaped_on_the_wire() {
665        let metadata = Metadata {
666            origin: Some("Ünknown-源".into()),
667            filename: Some("réport-📄.pdf".into()),
668            custom: BTreeMap::from([("release".to_owned(), "100% vérsion-🚀".to_owned())]),
669            ..Default::default()
670        };
671
672        let headers = metadata.to_headers("").unwrap();
673        assert_eq!(
674            headers.get(HEADER_ORIGIN).unwrap(),
675            "%C3%9Cnknown-%E6%BA%90"
676        );
677        assert_eq!(
678            headers.get(HEADER_FILENAME).unwrap(),
679            "r%C3%A9port-%F0%9F%93%84.pdf",
680        );
681        assert_eq!(
682            headers.get(format!("{HEADER_META_PREFIX}release")).unwrap(),
683            "100%25 v%C3%A9rsion-%F0%9F%9A%80",
684        );
685
686        let roundtripped = Metadata::from_headers(&headers, "").unwrap();
687        assert_eq!(roundtripped.origin, metadata.origin);
688        assert_eq!(roundtripped.filename, metadata.filename);
689        assert_eq!(roundtripped.custom, metadata.custom);
690    }
691
692    #[test]
693    fn from_headers_content_type_and_encoding() {
694        let mut headers = HeaderMap::new();
695        headers.insert("content-type", "application/json".parse().unwrap());
696        headers.insert("content-encoding", "zstd".parse().unwrap());
697
698        let metadata = Metadata::from_headers(&headers, "").unwrap();
699        assert_eq!(metadata.content_type, "application/json");
700        assert_eq!(metadata.compression, Some(Compression::Zstd));
701    }
702
703    #[test]
704    fn from_headers_expiration_policy() {
705        let mut headers = HeaderMap::new();
706        headers.insert(HEADER_EXPIRATION, "ttl:30s".parse().unwrap());
707
708        let metadata = Metadata::from_headers(&headers, "").unwrap();
709        assert_eq!(
710            metadata.expiration_policy,
711            ExpirationPolicy::TimeToLive(Duration::from_secs(30))
712        );
713    }
714
715    #[test]
716    fn from_headers_timestamps() {
717        let mut headers = HeaderMap::new();
718        headers.insert(
719            HEADER_TIME_CREATED,
720            "2024-01-15T12:00:00.000000Z".parse().unwrap(),
721        );
722        headers.insert(
723            HEADER_TIME_EXPIRES,
724            "2024-01-16T12:00:00.000000Z".parse().unwrap(),
725        );
726
727        let metadata = Metadata::from_headers(&headers, "").unwrap();
728        assert!(metadata.time_created.is_some());
729        assert!(metadata.time_expires.is_some());
730    }
731
732    #[test]
733    fn from_insert_headers_ignores_read_only_fields() {
734        // Read-only and output attributes must never be taken from an untrusted
735        // client request, even if the client supplies the headers.
736        let forged_created = "2024-01-15T12:00:00.000000Z";
737        let mut headers = HeaderMap::new();
738        headers.insert("content-type", "text/plain".parse().unwrap());
739        headers.insert(HEADER_TIME_CREATED, forged_created.parse().unwrap());
740        headers.insert(
741            HEADER_TIME_EXPIRES,
742            "2024-01-16T12:00:00.000000Z".parse().unwrap(),
743        );
744
745        let metadata = Metadata::from_insert_headers(&headers, "").unwrap();
746        // `time_created` is stamped by the server, not the client's forged value.
747        let created = metadata.time_created.unwrap();
748        assert_ne!(created, parse_rfc3339(forged_created).unwrap());
749        assert!(metadata.time_expires.is_none());
750        assert!(metadata.size.is_none());
751        // Client-settable fields are still parsed.
752        assert_eq!(metadata.content_type, "text/plain");
753    }
754
755    #[test]
756    fn from_insert_headers_ignores_malformed_read_only_fields() {
757        // A malformed read-only header must not fail the write: it is skipped, not parsed.
758        let mut headers = HeaderMap::new();
759        headers.insert(HEADER_TIME_CREATED, "not-a-timestamp".parse().unwrap());
760        headers.insert(HEADER_TIME_EXPIRES, "not-a-timestamp".parse().unwrap());
761
762        let metadata = Metadata::from_insert_headers(&headers, "").unwrap();
763        assert!(metadata.time_created.is_some());
764        assert!(metadata.time_expires.is_none());
765    }
766
767    #[test]
768    fn from_insert_headers_resolves_time_expires_for_ttl() {
769        let mut headers = HeaderMap::new();
770        headers.insert(HEADER_EXPIRATION, "ttl:30s".parse().unwrap());
771
772        let metadata = Metadata::from_insert_headers(&headers, "").unwrap();
773        let created = metadata.time_created.unwrap();
774        let expires = metadata.time_expires.unwrap();
775        // Both timestamps derive from the same `now`, so the expiry is exact.
776        assert_eq!(expires, created + Duration::from_secs(30));
777    }
778
779    #[test]
780    fn from_insert_headers_resolves_time_expires_for_tti() {
781        let mut headers = HeaderMap::new();
782        headers.insert(HEADER_EXPIRATION, "tti:1h".parse().unwrap());
783
784        let metadata = Metadata::from_insert_headers(&headers, "").unwrap();
785        let created = metadata.time_created.unwrap();
786        let expires = metadata.time_expires.unwrap();
787        assert_eq!(expires, created + Duration::from_hours(1));
788    }
789
790    #[test]
791    fn from_insert_headers_manual_leaves_time_expires_none() {
792        let headers = HeaderMap::new();
793        let metadata = Metadata::from_insert_headers(&headers, "").unwrap();
794        assert_eq!(metadata.expiration_policy, ExpirationPolicy::Manual);
795        assert!(metadata.time_expires.is_none());
796    }
797
798    #[test]
799    fn validate_accepts_resolved_timeout() {
800        let metadata = Metadata {
801            expiration_policy: ExpirationPolicy::TimeToLive(Duration::from_secs(30)),
802            time_expires: Some(SystemTime::now() + Duration::from_secs(30)),
803            ..Default::default()
804        };
805        assert!(metadata.validate().is_ok());
806    }
807
808    #[test]
809    fn validate_accepts_manual_without_expiry() {
810        let metadata = Metadata::default();
811        assert!(metadata.validate().is_ok());
812    }
813
814    #[test]
815    fn validate_rejects_timeout_without_expiry() {
816        let metadata = Metadata {
817            expiration_policy: ExpirationPolicy::TimeToIdle(Duration::from_hours(1)),
818            time_expires: None,
819            ..Default::default()
820        };
821        assert!(matches!(metadata.validate(), Err(Error::Invariant(_))));
822    }
823
824    #[test]
825    fn from_headers_custom_metadata_with_prefix() {
826        let mut headers = HeaderMap::new();
827        // Simulate a backend that prefixes headers, e.g. "x-goog-meta-"
828        let prefix = "x-goog-meta-";
829        let expiration_header: HeaderName = format!("{prefix}{HEADER_EXPIRATION}").parse().unwrap();
830        headers.insert(expiration_header, "tti:1h".parse().unwrap());
831
832        let custom_header: HeaderName = format!("{prefix}{HEADER_META_PREFIX}my-key")
833            .parse()
834            .unwrap();
835        headers.insert(custom_header, "my-value".parse().unwrap());
836
837        let metadata = Metadata::from_headers(&headers, prefix).unwrap();
838        assert_eq!(
839            metadata.expiration_policy,
840            ExpirationPolicy::TimeToIdle(Duration::from_hours(1))
841        );
842        assert_eq!(metadata.custom.get("my-key").unwrap(), "my-value");
843    }
844
845    #[test]
846    fn from_headers_invalid_content_type() {
847        let mut headers = HeaderMap::new();
848        headers.insert("content-type", "not a valid media type!".parse().unwrap());
849
850        let err = Metadata::from_headers(&headers, "").unwrap_err();
851        assert!(matches!(err, Error::ContentType(_)));
852    }
853
854    #[test]
855    fn from_headers_invalid_compression() {
856        let mut headers = HeaderMap::new();
857        headers.insert("content-encoding", "brotli".parse().unwrap());
858
859        let err = Metadata::from_headers(&headers, "").unwrap_err();
860        assert!(matches!(err, Error::Compression));
861    }
862
863    #[test]
864    fn from_headers_invalid_expiration() {
865        let mut headers = HeaderMap::new();
866        headers.insert(HEADER_EXPIRATION, "garbage".parse().unwrap());
867
868        let err = Metadata::from_headers(&headers, "").unwrap_err();
869        assert!(matches!(err, Error::Expiration(_)));
870    }
871
872    #[test]
873    fn from_headers_invalid_timestamp() {
874        let mut headers = HeaderMap::new();
875        headers.insert(HEADER_TIME_CREATED, "not-a-timestamp".parse().unwrap());
876
877        let err = Metadata::from_headers(&headers, "").unwrap_err();
878        assert!(matches!(err, Error::CreationTime(_)));
879    }
880
881    #[test]
882    fn to_headers_all_fields() {
883        let metadata = Metadata {
884            expiration_policy: ExpirationPolicy::TimeToLive(Duration::from_mins(1)),
885            time_created: Some(SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000)),
886            time_expires: Some(SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_060)),
887            content_type: "text/html".into(),
888            compression: Some(Compression::Zstd),
889            origin: Some("10.0.0.1".into()),
890            filename: Some("report.pdf".into()),
891            size: None,
892            custom: BTreeMap::from([("foo".into(), "bar".into())]),
893        };
894
895        let headers = metadata.to_headers("pfx-").unwrap();
896        let map: BTreeMap<_, _> = headers
897            .iter()
898            .map(|(k, v)| (k.as_str(), v.to_str().unwrap()))
899            .collect();
900
901        insta::assert_debug_snapshot!(map, @r#"
902        {
903            "content-encoding": "zstd",
904            "content-type": "text/html",
905            "pfx-x-sn-expiration": "ttl:1m",
906            "pfx-x-sn-filename": "report.pdf",
907            "pfx-x-sn-origin": "10.0.0.1",
908            "pfx-x-sn-time-created": "2023-11-14T22:13:20.000000Z",
909            "pfx-x-sn-time-expires": "2023-11-14T22:14:20.000000Z",
910            "pfx-x-snme-foo": "bar",
911        }
912        "#);
913    }
914
915    #[test]
916    fn full_roundtrip_all_fields() {
917        let prefix = "x-test-";
918        let metadata = Metadata {
919            expiration_policy: ExpirationPolicy::TimeToIdle(Duration::from_hours(2)),
920            time_created: Some(SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000)),
921            time_expires: Some(SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_007_200)),
922            content_type: "image/png".into(),
923            compression: Some(Compression::Zstd),
924            origin: Some("192.168.1.1".into()),
925            filename: Some("image.png".into()),
926            size: None,
927            custom: BTreeMap::from([
928                ("key1".into(), "value1".into()),
929                ("key2".into(), "value2".into()),
930            ]),
931        };
932
933        let headers = metadata.to_headers(prefix).unwrap();
934        let roundtripped = Metadata::from_headers(&headers, prefix).unwrap();
935
936        assert_eq!(roundtripped.expiration_policy, metadata.expiration_policy);
937        assert_eq!(roundtripped.content_type, metadata.content_type);
938        assert_eq!(roundtripped.compression, metadata.compression);
939        assert_eq!(roundtripped.origin, metadata.origin);
940        assert_eq!(roundtripped.filename, metadata.filename);
941        assert_eq!(roundtripped.time_created, metadata.time_created);
942        assert_eq!(roundtripped.time_expires, metadata.time_expires);
943        assert_eq!(roundtripped.custom, metadata.custom);
944    }
945
946    #[test]
947    fn from_headers_empty() {
948        let headers = HeaderMap::new();
949        let metadata = Metadata::from_headers(&headers, "x-goog-meta-").unwrap();
950        assert_eq!(metadata, Metadata::default());
951    }
952
953    #[test]
954    fn from_headers_invalid_time_expires() {
955        let mut headers = HeaderMap::new();
956        let name: HeaderName = format!("x-goog-meta-{HEADER_TIME_EXPIRES}")
957            .parse()
958            .unwrap();
959        headers.insert(name, "not-a-timestamp".parse().unwrap());
960
961        // NOTE: This produces InvalidCreationTime even for time_expires because
962        // both fields share the same humantime::TimestampError #[from] conversion.
963        assert!(Metadata::from_headers(&headers, "x-goog-meta-").is_err());
964    }
965
966    #[test]
967    fn serde_roundtrip_default() {
968        let metadata = Metadata::default();
969        let json = serde_json::to_string(&metadata).unwrap();
970        let deserialized: Metadata = serde_json::from_str(&json).unwrap();
971        assert_eq!(deserialized, metadata);
972    }
973
974    #[test]
975    fn serde_roundtrip_all_fields() {
976        let metadata = Metadata {
977            expiration_policy: ExpirationPolicy::TimeToIdle(Duration::from_hours(1)),
978            time_created: Some(SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000)),
979            time_expires: Some(SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_003_600)),
980            content_type: "application/json".into(),
981            compression: Some(Compression::Zstd),
982            origin: Some("10.0.0.1".into()),
983            filename: Some("data.json".into()),
984            size: Some(1024),
985            custom: BTreeMap::from([("key".into(), "value".into())]),
986        };
987
988        let json = serde_json::to_string(&metadata).unwrap();
989        let deserialized: Metadata = serde_json::from_str(&json).unwrap();
990        assert_eq!(deserialized, metadata);
991    }
992
993    #[test]
994    fn size_roundtrips_through_headers() {
995        let metadata = Metadata {
996            size: Some(42),
997            ..Default::default()
998        };
999
1000        let headers = metadata.to_headers("").unwrap();
1001        assert_eq!(headers.get(HEADER_SIZE).unwrap(), "42");
1002        assert_eq!(Metadata::from_headers(&headers, "").unwrap().size, Some(42));
1003    }
1004
1005    #[test]
1006    fn size_is_prefixed_in_headers() {
1007        let metadata = Metadata {
1008            size: Some(42),
1009            ..Default::default()
1010        };
1011
1012        let headers = metadata.to_headers("x-goog-meta-").unwrap();
1013        assert_eq!(headers.get("x-goog-meta-x-sn-size").unwrap(), "42");
1014    }
1015
1016    #[test]
1017    fn from_insert_headers_ignores_size() {
1018        // Size is materialized by the server; a client-supplied value must never be trusted.
1019        let mut headers = HeaderMap::new();
1020        headers.insert(HEADER_SIZE, "9999".parse().unwrap());
1021
1022        let metadata = Metadata::from_insert_headers(&headers, "").unwrap();
1023        assert!(metadata.size.is_none());
1024    }
1025
1026    #[test]
1027    fn from_headers_rejects_malformed_size() {
1028        let mut headers = HeaderMap::new();
1029        headers.insert(HEADER_SIZE, "not-a-number".parse().unwrap());
1030
1031        assert!(matches!(
1032            Metadata::from_headers(&headers, ""),
1033            Err(Error::Size(_))
1034        ));
1035    }
1036
1037    #[test]
1038    fn default_metadata() {
1039        let metadata = Metadata::default();
1040        assert_eq!(metadata.content_type, DEFAULT_CONTENT_TYPE);
1041        assert_eq!(metadata.expiration_policy, ExpirationPolicy::Manual);
1042        assert!(metadata.compression.is_none());
1043        assert!(metadata.origin.is_none());
1044        assert!(metadata.filename.is_none());
1045        assert!(metadata.time_created.is_none());
1046        assert!(metadata.time_expires.is_none());
1047        assert!(metadata.size.is_none());
1048        assert!(metadata.custom.is_empty());
1049    }
1050
1051    #[test]
1052    fn expiration_display_roundtrip() {
1053        let cases = [
1054            ExpirationPolicy::Manual,
1055            ExpirationPolicy::TimeToLive(Duration::from_secs(30)),
1056            ExpirationPolicy::TimeToIdle(Duration::from_hours(1)),
1057        ];
1058
1059        for policy in cases {
1060            let displayed = policy.to_string();
1061            let parsed: ExpirationPolicy = displayed.parse().unwrap();
1062            assert_eq!(parsed, policy);
1063        }
1064    }
1065
1066    #[test]
1067    fn expiration_parse_invalid() {
1068        assert!(ExpirationPolicy::from_str("garbage").is_err());
1069        assert!(ExpirationPolicy::from_str("ttl:").is_err());
1070        assert!(ExpirationPolicy::from_str("").is_err());
1071    }
1072
1073    #[test]
1074    fn expiration_policy_helpers() {
1075        assert_eq!(ExpirationPolicy::Manual.expires_in(), None);
1076        assert!(ExpirationPolicy::Manual.is_manual());
1077        assert!(!ExpirationPolicy::Manual.is_timeout());
1078
1079        let ttl = ExpirationPolicy::TimeToLive(Duration::from_mins(1));
1080        assert_eq!(ttl.expires_in(), Some(Duration::from_mins(1)));
1081        assert!(ttl.is_timeout());
1082        assert!(!ttl.is_manual());
1083
1084        let tti = ExpirationPolicy::TimeToIdle(Duration::from_mins(2));
1085        assert_eq!(tti.expires_in(), Some(Duration::from_mins(2)));
1086        assert!(tti.is_timeout());
1087        assert!(!tti.is_manual());
1088    }
1089
1090    #[test]
1091    fn compression_display_roundtrip() {
1092        let displayed = Compression::Zstd.to_string();
1093        assert_eq!(displayed, "zstd");
1094        let parsed: Compression = displayed.parse().unwrap();
1095        assert_eq!(parsed, Compression::Zstd);
1096    }
1097
1098    #[test]
1099    fn compression_parse_invalid() {
1100        assert!(Compression::from_str("gzip").is_err());
1101        assert!(Compression::from_str("").is_err());
1102    }
1103
1104    #[test]
1105    fn check_tti_bump_returns_none_for_manual() {
1106        let metadata = Metadata::default();
1107        assert!(metadata.check_tti_bump(SystemTime::now()).is_none());
1108    }
1109
1110    #[test]
1111    fn check_tti_bump_returns_none_for_ttl() {
1112        let now = SystemTime::now();
1113        let metadata = Metadata {
1114            expiration_policy: ExpirationPolicy::TimeToLive(Duration::from_hours(1)),
1115            time_expires: Some(now + Duration::from_hours(1)),
1116            ..Default::default()
1117        };
1118        assert!(metadata.check_tti_bump(now).is_none());
1119    }
1120
1121    #[test]
1122    fn check_tti_bump_returns_none_when_fresh() {
1123        let now = SystemTime::now();
1124        let tti = Duration::from_hours(2 * 24);
1125        let metadata = Metadata {
1126            expiration_policy: ExpirationPolicy::TimeToIdle(tti),
1127            time_expires: Some(now + tti),
1128            ..Default::default()
1129        };
1130        assert!(metadata.check_tti_bump(now).is_none());
1131    }
1132
1133    #[test]
1134    fn check_tti_bump_returns_new_deadline_when_stale() {
1135        let now = SystemTime::now();
1136        let tti = Duration::from_hours(2 * 24);
1137        let debounce = tti / 4;
1138        let stale_deadline = now + tti - debounce - Duration::from_mins(1);
1139        let metadata = Metadata {
1140            expiration_policy: ExpirationPolicy::TimeToIdle(tti),
1141            time_expires: Some(stale_deadline),
1142            ..Default::default()
1143        };
1144        let new_deadline = metadata.check_tti_bump(now).unwrap();
1145        assert_eq!(new_deadline, now + tti);
1146    }
1147
1148    #[test]
1149    fn check_tti_bump_short_tti_triggers_bump() {
1150        let now = SystemTime::now();
1151        let tti = Duration::from_hours(2);
1152        let debounce = tti / 4;
1153        let stale_deadline = now + tti - debounce - Duration::from_mins(1);
1154        let metadata = Metadata {
1155            expiration_policy: ExpirationPolicy::TimeToIdle(tti),
1156            time_expires: Some(stale_deadline),
1157            ..Default::default()
1158        };
1159        let new_deadline = metadata.check_tti_bump(now).unwrap();
1160        assert_eq!(new_deadline, now + tti);
1161    }
1162
1163    #[test]
1164    fn check_tti_bump_debounce_caps_at_24h() {
1165        let now = SystemTime::now();
1166        let tti = Duration::from_hours(30 * 24);
1167        let capped_debounce = Duration::from_hours(24);
1168        let stale_deadline = now + tti - capped_debounce - Duration::from_mins(1);
1169        let metadata = Metadata {
1170            expiration_policy: ExpirationPolicy::TimeToIdle(tti),
1171            time_expires: Some(stale_deadline),
1172            ..Default::default()
1173        };
1174        assert!(metadata.check_tti_bump(now).is_some());
1175
1176        let fresh_deadline = now + tti - capped_debounce + Duration::from_mins(1);
1177        let metadata = Metadata {
1178            time_expires: Some(fresh_deadline),
1179            ..metadata
1180        };
1181        assert!(metadata.check_tti_bump(now).is_none());
1182    }
1183
1184    #[test]
1185    fn check_tti_bump_returns_none_when_time_expires_missing() {
1186        let metadata = Metadata {
1187            expiration_policy: ExpirationPolicy::TimeToIdle(Duration::from_hours(1)),
1188            time_expires: None,
1189            ..Default::default()
1190        };
1191        assert!(metadata.check_tti_bump(SystemTime::now()).is_none());
1192    }
1193}