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