Struct etag::EntityTag

source ·
pub struct EntityTag {
    pub weak: bool,
    /* private fields */
}
Expand description

An entity tag, defined in RFC7232

The ETag HTTP response header is an identifier for a specific version of a resource. It allows caches to be more efficient, and saves bandwidth, as a web server does not need to send a full response if the content has not changed. On the other side, if the content has changed, etags are useful to help prevent simultaneous updates of a resource from overwriting each other (“mid-air collisions”).

If the resource at a given URL changes, a new Etag value must be generated. Etags are therefore similar to fingerprints and might also be used for tracking purposes by some servers. A comparison of them allows to quickly determine whether two representations of a resource are the same, but they might also be set to persist indefinitely by a tracking server.

Size limit

In order to avoid allocation, ETag size is limited to 62 characters, which should be sufficient for any hashing mechanism.

Format W/"<etag_value>"

  • ‘W/’ (case-sensitive) indicates that a weak validator is used. Weak validators are easy to generate but are far less useful for comparisons. Strong validators are ideal for comparisons but can be very difficult to generate efficiently. Weak Etag values of two representations of the same resources might be semantically equivalent, but not byte-for-byte identical.

  • “<etag_value>” Entity tags uniquely representing the requested resources. They are a string of ASCII characters placed between double quotes (Like “675af34563dc-tr34”). The method by which ETag values are generated is not specified. Oftentimes, a hash of the content, a hash of the last modification timestamp, or just a revision number is used. For example, MDN uses a hash of hexadecimal digits of the wiki content.

Comparison

To check if two entity tags are equivalent in an application always use the strong_eq or weak_eq methods based on the context of the Tag. Only use == to check if two tags are identical.

The example below shows the results for a set of entity-tag pairs and both the weak and strong comparison function results:

ETag 1ETag 2Strong ComparisonWeak Comparison
W/"1"W/"1"no matchmatch
W/"1"W/"2"no matchno match
W/"1""1"no matchmatch
"1""1"matchmatch

Fields§

§weak: bool

Weakness indicator for the tag

Implementations§

Constructs a new EntityTag, asserting that it doesn’t overflow and valid ASCII string.

Assertions are performed in debug mode only.

Examples found in repository?
src/lib.rs (line 104)
103
104
105
106
107
108
109
110
111
    pub fn weak(tag: &str) -> Self {
        Self::new(true, tag)
    }

    #[inline]
    /// Constructs a new strong EntityTag, using the same checks as `new`.
    pub fn strong(tag: &str) -> Self {
        Self::new(false, tag)
    }

Constructs a new weak EntityTag, using the same checks as new.

Constructs a new strong EntityTag, using the same checks as new.

Constructs a new EntityTag, verifying it’s size and whether it includes ASCII.

Examples found in repository?
src/lib.rs (line 133)
132
133
134
135
136
137
138
139
140
    pub fn checked_weak(tag: &str) -> Result<Self, ParseError> {
        Self::checked_new(true, tag)
    }

    #[inline]
    /// Constructs a new strong EntityTag, using the same checks as `checked_new`.
    pub fn checked_strong(tag: &str) -> Result<Self, ParseError> {
        Self::checked_new(false, tag)
    }

Constructs a new weak EntityTag, using the same checks as checked_new.

Examples found in repository?
src/lib.rs (line 321)
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
    fn from_str(text: &str) -> Result<EntityTag, ParseError> {
        let len = text.len();
        let slice = &text[..];

        if !slice.ends_with('"') || len < 2 {
            return Err(ParseError::InvalidFormat);
        }

        if slice.starts_with('"') {
            let slice = &slice[1..len-1];
            EntityTag::checked_strong(slice)
        } else if len >= 4 && slice.starts_with("W/\"") {
            let slice = &slice[3..len-1];
            EntityTag::checked_weak(slice)
        } else {
            Err(ParseError::InvalidFormat)
        }
    }

Constructs a new strong EntityTag, using the same checks as checked_new.

Examples found in repository?
src/lib.rs (line 318)
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
    fn from_str(text: &str) -> Result<EntityTag, ParseError> {
        let len = text.len();
        let slice = &text[..];

        if !slice.ends_with('"') || len < 2 {
            return Err(ParseError::InvalidFormat);
        }

        if slice.starts_with('"') {
            let slice = &slice[1..len-1];
            EntityTag::checked_strong(slice)
        } else if len >= 4 && slice.starts_with("W/\"") {
            let slice = &slice[3..len-1];
            EntityTag::checked_weak(slice)
        } else {
            Err(ParseError::InvalidFormat)
        }
    }

Creates weak EntityTag from file metadata using modified time and len.

Format:

[modified-]<len>

Creates strong EntityTag by hashing provided bytes.

Format:

<len>-<hash>

Creates strong EntityTag by hashing provided bytes.

Format:

<len>-<hash>

Get the tag.

For strong comparison two entity-tags are equivalent if both are not weak and their opaque-tags match character-by-character.

Examples found in repository?
src/lib.rs (line 263)
262
263
264
    pub fn strong_ne(&self, other: &EntityTag) -> bool {
        !self.strong_eq(other)
    }

For weak comparison two entity-tags are equivalent if their opaque-tags match character-by-character, regardless of either or both being tagged as “weak”.

Examples found in repository?
src/lib.rs (line 268)
267
268
269
    pub fn weak_ne(&self, other: &EntityTag) -> bool {
        !self.weak_eq(other)
    }

The inverse of EntityTag.strong_eq().

The inverse of EntityTag.weak_eq().

Trait Implementations§

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Formats the value using the given formatter. Read more
The associated error which can be returned from parsing.
Parses a string s to return a value of this type. Read more
This method tests for self and other values to be equal, and is used by ==.
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
Converts the given value to a String. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.