Merge "Use separate headers for versioned_writes' stack and history modes"

Author: Jenkins

api-ref/source/parameters.yaml

@@ -666,6 +666,27 @@ X-Fresh-Metadata:
   in: header
   required: false
   type: boolean
+X-History-Location:
+  description: |
+    The URL-encoded UTF-8 representation of the container that stores
+    previous versions of objects. If neither this nor ``X-Versions-Location``
+    is set, versioning is disabled for this container. ``X-History-Location``
+    and ``X-Versions-Location`` cannot both be set at the same time. For more
+    information about object versioning, see `Object versioning
+    <http://docs.openstack.org/ developer/swift/api/object_versioning.html>`_.
+  in: header
+  required: false
+  type: string
+X-History-Location_resp:
+  description: |
+    If present, this container has versioning enabled and the value
+    is the UTF-8 encoded name of another container.
+    For more information about object versioning,
+    see `Object versioning <http://docs.openstack.org/developer/
+    swift/api/object_versioning.html>`_.
+  in: header
+  required: false
+  type: string
 X-Newest:
   description: |
     If set to true , Object Storage queries all
@@ -728,9 +749,17 @@ X-Remove-Container-name:
   in: header
   required: false
   type: string
+X-Remove-History-Location:
+  description: |
+    Set to any value to disable versioning. Note that this disables version
+    that was set via ``X-Versions-Location`` as well.
+  in: header
+  required: false
+  type: string
 X-Remove-Versions-Location:
   description: |
-    Set to any value to disable versioning.
+    Set to any value to disable versioning. Note that this disables version
+    that was set via ``X-History-Location`` as well.
   in: header
   required: false
   type: string
@@ -801,10 +830,11 @@ X-Trans-Id-Extra:
 X-Versions-Location:
   description: |
     The URL-encoded UTF-8 representation of the container that stores
-    previous versions of objects. If not set, versioning is disabled
-    for this container. For more information about object versioning,
-    see `Object versioning <http://docs.openstack.org/developer/
-    swift/api/object_versioning.html>`_.
+    previous versions of objects. If neither this nor ``X-History-Location``
+    is set, versioning is disabled for this container. ``X-Versions-Location``
+    and ``X-History-Location`` cannot both be set at the same time. For more
+    information about object versioning, see `Object versioning
+    <http://docs.openstack.org/ developer/swift/api/object_versioning.html>`_.
   in: header
   required: false
   type: string
@@ -818,26 +848,6 @@ X-Versions-Location_resp:
   in: header
   required: false
   type: string
-X-Versions-Mode:
-  description: |
-    The versioning mode for this container. The value must be either
-    ``stack`` or ``history``. If not set, ``stack`` mode will be used.
-    This setting has no impact unless ``X-Versions-Location`` is set
-    for the container. For more information about object versioning,
-    see `Object versioning <http://docs.openstack.org/developer/
-    swift/api/object_versioning.html>`_.
-  in: header
-  required: false
-  type: string
-X-Versions-Mode_resp:
-  description: |
-    If set, this is the versioning mode for this container. The value is either
-    ``stack`` or ``history``. For more information about object versioning,
-    see `Object versioning <http://docs.openstack.org/developer/
-    swift/api/object_versioning.html>`_.
-  in: header
-  required: false
-  type: string
 
 # variables in path
 account:

api-ref/source/storage-container-services.inc

@@ -85,7 +85,7 @@ Response Parameters
    - X-Container-Sync-Key: X-Container-Sync-Key_resp
    - X-Container-Sync-To: X-Container-Sync-To_resp
    - X-Versions-Location: X-Versions-Location_resp
-   - X-Versions-Mode: X-Versions-Mode_resp
+   - X-History-Location: X-History-Location_resp
    - X-Timestamp: X-Timestamp
    - X-Trans-Id: X-Trans-Id
    - Content_Type: Content-Type_listing_resp
@@ -199,7 +199,7 @@ Request
    - X-Container-Sync-To: X-Container-Sync-To
    - X-Container-Sync-Key: X-Container-Sync-Key
    - X-Versions-Location: X-Versions-Location
-   - X-Versions-Mode: X-Versions-Mode
+   - X-History-Location: X-History-Location
    - X-Container-Meta-name: X-Container-Meta-name_req
    - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
    - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
@@ -335,8 +335,9 @@ Request
    - X-Container-Sync-To: X-Container-Sync-To
    - X-Container-Sync-Key: X-Container-Sync-Key
    - X-Versions-Location: X-Versions-Location
-   - X-Versions-Mode: X-Versions-Mode
+   - X-History-Location: X-History-Location
    - X-Remove-Versions-Location: X-Remove-Versions-Location
+   - X-Remove-History-Location: X-Remove-History-Location
    - X-Container-Meta-name: X-Container-Meta-name_req
    - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
    - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
@@ -440,7 +441,7 @@ Response Parameters
    - X-Trans-Id: X-Trans-Id
    - Content-Type: Content-Type_cud_resp
    - X-Versions-Location: X-Versions-Location_resp
-   - X-Versions-Mode: X-Versions-Mode_resp
+   - X-History-Location: X-History-Location_resp
    - X-Storage-Policy: X-Storage-Policy
 
 

doc/source/api/object_versioning.rst

@@ -20,30 +20,37 @@ To allow object versioning within a cluster, the cloud provider should add the
 ``allow_versioned_writes`` option to ``true`` in the
 ``[filter:versioned_writes]`` section of the proxy-server configuration file.
 
-The ``X-Versions-Location`` header defines the
-container that holds the non-current versions of your objects. You
-must UTF-8-encode and then URL-encode the container name before you
-include it in the ``X-Versions-Location`` header. This header enables
-object versioning for all objects in the container. With a comparable
-``archive`` container in place, changes to objects in the ``current``
-container automatically create non-current versions in the ``archive``
-container.
-
-The ``X-Versions-Mode`` header defines the behavior of ``DELETE`` requests to
-objects in the versioned container. In the default ``stack`` mode, deleting an
-object will restore the most-recent version from the ``archive`` container,
-overwriting the curent version. Alternatively you may specify ``history``
-mode, where deleting an object will copy the current version to the
-``archive`` then remove it from the ``current`` container.
-
-Example Using ``stack`` Mode
-----------------------------
+To enable object versioning for a container, you must specify an "archive
+container" that will retain non-current versions via either the
+``X-Versions-Location`` or ``X-History-Location`` header. These two headers
+enable two distinct modes of operation. Either mode may be used within a
+cluster, but only one mode may be active for any given container. You must
+UTF-8-encode and then URL-encode the container name before you include it in
+the header.
+
+For both modes, **PUT** requests will archive any pre-existing objects before
+writing new data, and **GET** requests will serve the current version. **COPY**
+requests behave like a **GET** followed by a **PUT**; that is, if the copy
+*source* is in a versioned container then the current version will be copied,
+and if the copy *destination* is in a versioned container then any pre-existing
+object will be archived before writing new data.
+
+If object versioning was enabled using ``X-History-Location``, then object
+**DELETE** requests will copy the current version to the archive container then
+remove it from the versioned container.
+
+If object versioning was enabled using ``X-Versions-Location``, then object
+**DELETE** requests will restore the most-recent version from the archive
+container, overwriting the curent version.
+
+Example Using ``X-Versions-Location``
+-------------------------------------
 
 #.   Create the ``current`` container:
 
    .. code::
 
-       # curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive" -H "X-Versions-Mode: stack"
+       # curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive"
 
    .. code::
 
@@ -169,14 +176,14 @@ Example Using ``stack`` Mode
    on it. If want to completely remove an object and you have five
    versions of it, you must **DELETE** it five times.
 
-Example Using ``history`` Mode
-------------------------------
+Example Using ``X-History-Location``
+------------------------------------
 
 #.   Create the ``current`` container:
 
    .. code::
 
-       # curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive" -H "X-Versions-Mode: history"
+       # curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-History-Location: archive"
 
    .. code::
 
@@ -266,7 +273,7 @@ Example Using ``history`` Mode
 #. Issue a **DELETE** request to a versioned object to copy the
    current version of the object to the archive container then delete it from
    the current container. Subsequent **GET** requests to the object in the
-   current container will return 404 Not Found.
+   current container will return ``404 Not Found``.
 
    .. code::