Skip to main content

Metadata

Metadata is an owned, immutable description of a storage entry. It does not borrow from a response, lister, reader, or operation, so callers may retain it for any lifetime. Clones may share immutable storage internally. Consuming one clone through Metadata::into_builder and building a modified value does not change any other clone.

Construction and access​

Callers construct metadata with MetadataBuilder::file(content_length), MetadataBuilder::dir(), or MetadataBuilder::unknown(), then finish it with MetadataBuilder::build. Existing metadata can be consumed with Metadata::into_builder; set_file(content_length), set_dir(), and set_unknown() change its mode before rebuilding it.

User metadata is exposed through a borrowed UserMetadata view. The view supports lookup, length checks, and iteration without requiring a HashMap allocation. An absent user-metadata map and an explicitly supplied empty map remain distinguishable.

Rust metadata and finalized operation arguments use compact blocks whose encoded size, including indexes, must not exceed u16::MAX bytes. Construction panics when a block exceeds this bound. Services and callers should enforce their own smaller protocol limits before reaching this representation boundary.

Content length​

Every file Metadata contains the complete object length by construction. MetadataBuilder::file(0) represents an empty file. Directory and unknown metadata report zero.

Raw services and intermediate layers use Unknown while either the entry mode or its full length is unavailable. They promote that value to FILE only at a boundary that owns an authoritative length:

  • stat and read-response parsers construct FILE only after obtaining the complete object length from the service response.
  • list completion stats unknown entries, resolves their mode, and promotes files with the stat result's length.
  • write completion uses the number of bytes written for replacements. Append adapters use the final object offset instead of the number of appended bytes.
  • copy completion uses a service result length, the source-length hint, the source length discovered by a segmented copier, or successful copy progress. It does not issue a target stat and fails when none of these sources can provide an authoritative length.

Delete markers that do not carry an object length use a content length of zero.

Operation boundary​

Public operation options are mutable logical construction values. Before OpenDAL freezes them into raw Op* arguments, it resolves logical conditions such as if_not_changed against the composed service capability. Raw arguments contain only the primitive conditions that a service must execute and do not retain the source Metadata.

Historical decisions​