Skip to main content

Module metadata

Module metadata 

Source
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_headers and Metadata::to_headers handle this conversion for public fields only.
  • JSON over the wire — an alternate representation in API request and response bodies: WriteMetadata for writes and ReadMetadata for 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§

InvalidContentType
A content type is not a valid IANA Media Type.
Metadata
Per-object metadata.
MetadataUpdate
An application-specific JSON request for updating object metadata.
ReadMetadata
Metadata of an existing object, as returned in JSON.
WriteMetadata
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
ExpirationPolicy
The per-object expiration policy.
ExpiryAnchor
The timestamp against which a relative expiry extension is resolved.
ExpiryExtension
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.