Struct trillium_caching_headers::EntityTag
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 1 | ETag 2 | Strong Comparison | Weak Comparison |
|---|---|---|---|
W/"1" | W/"1" | no match | match |
W/"1" | W/"2" | no match | no match |
W/"1" | "1" | no match | match |
"1" | "1" | match | match |
Fields§
§weak: boolWeakness indicator for the tag
Implementations§
§impl EntityTag
impl EntityTag
pub fn new(weak: bool, tag: &str) -> EntityTag
pub fn new(weak: bool, tag: &str) -> EntityTag
Constructs a new EntityTag, asserting that it doesn’t overflow and valid ASCII string.
Assertions are performed in debug mode only.
pub fn strong(tag: &str) -> EntityTag
pub fn strong(tag: &str) -> EntityTag
Constructs a new strong EntityTag, using the same checks as new.
pub fn checked_new(weak: bool, tag: &str) -> Result<EntityTag, ParseError>
pub fn checked_new(weak: bool, tag: &str) -> Result<EntityTag, ParseError>
Constructs a new EntityTag, verifying it’s size and whether it includes ASCII.
pub fn checked_weak(tag: &str) -> Result<EntityTag, ParseError>
pub fn checked_weak(tag: &str) -> Result<EntityTag, ParseError>
Constructs a new weak EntityTag, using the same checks as checked_new.
pub fn checked_strong(tag: &str) -> Result<EntityTag, ParseError>
pub fn checked_strong(tag: &str) -> Result<EntityTag, ParseError>
Constructs a new strong EntityTag, using the same checks as checked_new.
pub fn from_file_meta(metadata: &Metadata) -> EntityTag
pub fn from_file_meta(metadata: &Metadata) -> EntityTag
pub const fn const_from_data(bytes: &[u8]) -> EntityTag
pub const fn const_from_data(bytes: &[u8]) -> EntityTag
pub fn strong_eq(&self, other: &EntityTag) -> bool
pub fn strong_eq(&self, other: &EntityTag) -> bool
For strong comparison two entity-tags are equivalent if both are not weak and their opaque-tags match character-by-character.