From cc2778004205d6a42d9a3f01bed8f21af0b482d2 Mon Sep 17 00:00:00 2001 From: Alistair Coles Date: Wed, 6 Mar 2024 10:59:24 +0000 Subject: [PATCH] docs: add discussion of content-type metadata Change-Id: I2aa13e2b23bda86c51ef6aaa69ea3fd0075bb9ad --- doc/source/development_middleware.rst | 59 ++++++++++++++++++++++++--- 1 file changed, 54 insertions(+), 5 deletions(-) diff --git a/doc/source/development_middleware.rst b/doc/source/development_middleware.rst index e885e87e7e..6ee1d099b9 100644 --- a/doc/source/development_middleware.rst +++ b/doc/source/development_middleware.rst @@ -263,9 +263,9 @@ metadata items stored with an object while leaving some items unchanged. .. _sysmeta: -^^^^^^^^^^^^^^^ -System Metadata -^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^ +System Metadata (Sysmeta) +^^^^^^^^^^^^^^^^^^^^^^^^^ System metadata takes the form of ``X--Sysmeta-: ``, where ```` depends on the resources type (i.e. Account, Container, @@ -303,11 +303,60 @@ individual items of user metadata is not supported. In cases where middleware needs to store its own metadata with a POST request, it may use Object Transient Sysmeta. + +^^^^^^^^^^^^^^^ +Object Metadata +^^^^^^^^^^^^^^^ + +Objects have other metadata in addition to the user metadata and system +metadata described above. + +****************** +Immutable Metadata +****************** + +Objects have several items of immutable metadata. Like system metadata, these +may only be set using PUT requests. However, they do not follow the general +``X-Object-Sysmeta-`` naming scheme and they are not automatically removed +from client responses. + +Object immutable metadata includes:: + + X-Timestamp + Content-Length + Etag + +``X-Timestamp`` and ``Content-Length`` metadata MUST be included in PUT +requests to object servers. ``Etag`` metadata is generated by object servers +when they handle a PUT request, but checked against any ``Etag`` header sent +with the PUT request. + +Object immutable metadata, along with ``Content-Type``, is the only object +metadata that is stored by container servers and returned in object listings. + +************ +Content-Type +************ + +Object ``Content-Type`` metadata is treated differently from immutable +metadata, system metadata and user metadata. + +``Content-Type`` MUST be included in PUT requests to object servers. Unlike +immutable metadata or system metadata, ``Content-Type`` is mutable and may be +included in POST requests to object servers. However, unlike object user +metadata, existing ``Content-Type`` metadata persists if a POST request does +not include new ``Content-Type`` metadata. This is because an object must have +``Content-Type`` metadata, which is also stored by container servers and +returned in object listings. + +``Content-Type`` is the only item of object metadata that is both mutable and +yet also persists when not specified in a POST request. + .. _transient_sysmeta: -^^^^^^^^^^^^^^^^^^^^^^^^ +************************ Object Transient-Sysmeta -^^^^^^^^^^^^^^^^^^^^^^^^ +************************ If middleware needs to store object metadata with a POST request it may do so using headers of the form ``X-Object-Transient-Sysmeta-: ``.