Expand description
Per-object metadata types and HTTP header serialization.
This module defines Metadata, the per-object metadata structure that
travels through the entire system: clients set it via HTTP headers, the
server parses and validates it, the service passes it to backends, and
backends persist it alongside the stored object.
MetadataUpdate is the separate JSON request contract for explicit
metadata updates. It is not a persisted metadata representation.
§Serialization
Metadata has three serialization formats:
- HTTP headers — used by the single-object public API.
Metadata::from_headersandMetadata::to_headershandle this conversion for public fields only. - JSON over the wire — an alternate representation in API request and response bodies:
WriteMetadatafor writes andReadMetadatafor reads. - JSON storage — used internally by backends, through the serde implementation of
Metadata. It includes additional internal fields that are skipped in the header representation, and differs from the wire format.
§HTTP header prefixes
Headers use three prefix conventions:
- Standard HTTP headers where applicable (
Content-Type,Content-Encoding) x-sn-*for objectstore-specific fields (e.g.x-sn-expiration)x-snme-for custom user metadata (e.g.x-snme-build_id)
Backends that store metadata as object metadata (like GCS) layer their own
prefix on top, so x-sn-expiration becomes x-goog-meta-x-sn-expiration.
The Metadata::from_headers and Metadata::to_headers methods accept
a prefix parameter for this purpose.
§Escaping free-form values
Metadata always holds logical strings: filename,
origin, and custom values may
contain arbitrary Unicode.
Over the wire, metadata travels in HTTP headers, which have no charset. In practice anything outside visible ASCII is either rejected outright or silently reinterpreted.
The fields are therefore percent-encoded in headers, via
headers::encode_header_value and headers::decode_header_value.
Encoding is a property of the transport, never of the stored value:
anything reading Metadata sees the logical string.
§Custom metadata keys
Custom metadata keys are restricted by normalize_custom_key and escaped in header names by
encode_custom_key and headers::decode_header_str_lossy; see those functions for the exact
rules.
The key rule applies to writes only: Metadata::from_insert_headers and the JSON request
paths reject invalid keys, while Metadata::from_headers and backend reads accept whatever
is stored, so objects written before the rule was explicit stay readable.
Structs§
- Invalid
Content Type - A content type is not a valid IANA Media Type.
- Metadata
- Per-object metadata.
- Metadata
Update - An application-specific JSON request for updating object metadata.
- Read
Metadata Metadataof an existing object, as returned in JSON.- Write
Metadata - The writable subset of
Metadata, as sent in JSON when inserting an object.
Enums§
- Compression
- The compression algorithm applied to an object’s payload.
- Error
- Errors that can happen dealing with metadata
- Expiration
Policy - The per-object expiration policy.
- Expiry
Anchor - The timestamp against which a relative expiry extension is resolved.
- Expiry
Extension - A requested minimum expiration deadline.
Constants§
- DEFAULT_
CONTENT_ TYPE - The default content type for objects without a known content type.
- HEADER_
EXPIRATION - The custom HTTP header that contains the serialized
ExpirationPolicy. - HEADER_
FILENAME - The custom HTTP header that contains the filename of the object.
- HEADER_
META_ PREFIX - The prefix for custom HTTP headers containing custom per-object metadata.
- HEADER_
ORIGIN - The custom HTTP header that contains the origin of the object.
- HEADER_
SIZE - The custom HTTP header that contains the size of the stored object in bytes.
- HEADER_
TIME_ CREATED - The custom HTTP header that contains the object creation time.
- HEADER_
TIME_ EXPIRES - The custom HTTP header that contains the object expiration time.
Functions§
- encode_
custom_ key - Encodes a custom metadata key for use in a header name after
x-snme-. - normalize_
custom_ key - Validates and normalizes a custom metadata key.