openstack/swift
Code Issues Proposed changes

docs: add discussion of content-type metadata

Browse Source 
Change-Id: I2aa13e2b23bda86c51ef6aaa69ea3fd0075bb9ad
This commit is contained in:
Alistair Coles 2024-03-06 10:59:24 +00:00
parent 627448362a
commit cc27780042
1 changed files with 54 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
doc/source/development_middleware.rst
View File

@ -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-<type>-Sysmeta-<key>: <value>``,
where ``<type>`` 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-<key>`` 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-<key>: <value>``.