Skip to content

Commit 60a2fe0

Browse files
tipabutipabu
committed
Use separate headers for versioned_writes' stack and history modes
Now, instead of saying X-Versions-Location: <container> X-Versions-Mode: history clients should just say X-History-Location: <container> Since we've never had a release featuring a user-settable X-Versions-Mode header, support may be dropped and that is now ignored. Change-Id: Icfd0f481d4e40dd5375c737190aea7ee8dbc3bf9
1 parent b4c1517 commit 60a2fe0

File tree

5 files changed

+275
-287
lines changed

5 files changed

+275
-287
lines changed

‎api-ref/source/parameters.yaml‎

Lines changed: 35 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -621,6 +621,27 @@ X-Fresh-Metadata:
621621
in: header
622622
required: false
623623
type: boolean
624+
X-History-Location:
625+
description: |
626+
The URL-encoded UTF-8 representation of the container that stores
627+
previous versions of objects. If neither this nor ``X-Versions-Location``
628+
is set, versioning is disabled for this container. ``X-History-Location``
629+
and ``X-Versions-Location`` cannot both be set at the same time. For more
630+
information about object versioning, see `Object versioning
631+
<http://docs.openstack.org/ developer/swift/api/object_versioning.html>`_.
632+
in: header
633+
required: false
634+
type: string
635+
X-History-Location_resp:
636+
description: |
637+
If present, this container has versioning enabled and the value
638+
is the UTF-8 encoded name of another container.
639+
For more information about object versioning,
640+
see `Object versioning <http://docs.openstack.org/developer/
641+
swift/api/object_versioning.html>`_.
642+
in: header
643+
required: false
644+
type: string
624645
X-Newest:
625646
description: |
626647
If set to true , Object Storage queries all
@@ -683,9 +704,17 @@ X-Remove-Container-name:
683704
in: header
684705
required: false
685706
type: string
707+
X-Remove-History-Location:
708+
description: |
709+
Set to any value to disable versioning. Note that this disables version
710+
that was set via ``X-Versions-Location`` as well.
711+
in: header
712+
required: false
713+
type: string
686714
X-Remove-Versions-Location:
687715
description: |
688-
Set to any value to disable versioning.
716+
Set to any value to disable versioning. Note that this disables version
717+
that was set via ``X-History-Location`` as well.
689718
in: header
690719
required: false
691720
type: string
@@ -756,10 +785,11 @@ X-Trans-Id-Extra:
756785
X-Versions-Location:
757786
description: |
758787
The URL-encoded UTF-8 representation of the container that stores
759-
previous versions of objects. If not set, versioning is disabled
760-
for this container. For more information about object versioning,
761-
see `Object versioning <http://docs.openstack.org/developer/
762-
swift/api/object_versioning.html>`_.
788+
previous versions of objects. If neither this nor ``X-History-Location``
789+
is set, versioning is disabled for this container. ``X-Versions-Location``
790+
and ``X-History-Location`` cannot both be set at the same time. For more
791+
information about object versioning, see `Object versioning
792+
<http://docs.openstack.org/ developer/swift/api/object_versioning.html>`_.
763793
in: header
764794
required: false
765795
type: string
@@ -773,26 +803,6 @@ X-Versions-Location_resp:
773803
in: header
774804
required: false
775805
type: string
776-
X-Versions-Mode:
777-
description: |
778-
The versioning mode for this container. The value must be either
779-
``stack`` or ``history``. If not set, ``stack`` mode will be used.
780-
This setting has no impact unless ``X-Versions-Location`` is set
781-
for the container. For more information about object versioning,
782-
see `Object versioning <http://docs.openstack.org/developer/
783-
swift/api/object_versioning.html>`_.
784-
in: header
785-
required: false
786-
type: string
787-
X-Versions-Mode_resp:
788-
description: |
789-
If set, this is the versioning mode for this container. The value is either
790-
``stack`` or ``history``. For more information about object versioning,
791-
see `Object versioning <http://docs.openstack.org/developer/
792-
swift/api/object_versioning.html>`_.
793-
in: header
794-
required: false
795-
type: string
796806

797807
# variables in path
798808
account:

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ Response Parameters
8383
- X-Container-Sync-Key: X-Container-Sync-Key_resp
8484
- X-Container-Sync-To: X-Container-Sync-To_resp
8585
- X-Versions-Location: X-Versions-Location_resp
86-
- X-Versions-Mode: X-Versions-Mode_resp
86+
- X-History-Location: X-History-Location_resp
8787
- X-Timestamp: X-Timestamp
8888
- X-Trans-Id: X-Trans-Id
8989
- Content_Type: Content-Type_listing_resp
@@ -197,7 +197,7 @@ Request
197197
- X-Container-Sync-To: X-Container-Sync-To
198198
- X-Container-Sync-Key: X-Container-Sync-Key
199199
- X-Versions-Location: X-Versions-Location
200-
- X-Versions-Mode: X-Versions-Mode
200+
- X-History-Location: X-History-Location
201201
- X-Container-Meta-name: X-Container-Meta-name_req
202202
- X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
203203
- X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
@@ -331,8 +331,9 @@ Request
331331
- X-Container-Sync-To: X-Container-Sync-To
332332
- X-Container-Sync-Key: X-Container-Sync-Key
333333
- X-Versions-Location: X-Versions-Location
334-
- X-Versions-Mode: X-Versions-Mode
334+
- X-History-Location: X-History-Location
335335
- X-Remove-Versions-Location: X-Remove-Versions-Location
336+
- X-Remove-History-Location: X-Remove-History-Location
336337
- X-Container-Meta-name: X-Container-Meta-name_req
337338
- X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
338339
- X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
@@ -436,7 +437,7 @@ Response Parameters
436437
- X-Trans-Id: X-Trans-Id
437438
- Content-Type: Content-Type_cud_resp
438439
- X-Versions-Location: X-Versions-Location_resp
439-
- X-Versions-Mode: X-Versions-Mode_resp
440+
- X-History-Location: X-History-Location_resp
440441
- X-Storage-Policy: X-Storage-Policy
441442

442443

‎doc/source/api/object_versioning.rst‎

Lines changed: 30 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -20,30 +20,37 @@ To allow object versioning within a cluster, the cloud provider should add the
2020
``allow_versioned_writes`` option to ``true`` in the
2121
``[filter:versioned_writes]`` section of the proxy-server configuration file.
2222

23-
The ``X-Versions-Location`` header defines the
24-
container that holds the non-current versions of your objects. You
25-
must UTF-8-encode and then URL-encode the container name before you
26-
include it in the ``X-Versions-Location`` header. This header enables
27-
object versioning for all objects in the container. With a comparable
28-
``archive`` container in place, changes to objects in the ``current``
29-
container automatically create non-current versions in the ``archive``
30-
container.
31-
32-
The ``X-Versions-Mode`` header defines the behavior of ``DELETE`` requests to
33-
objects in the versioned container. In the default ``stack`` mode, deleting an
34-
object will restore the most-recent version from the ``archive`` container,
35-
overwriting the curent version. Alternatively you may specify ``history``
36-
mode, where deleting an object will copy the current version to the
37-
``archive`` then remove it from the ``current`` container.
38-
39-
Example Using ``stack`` Mode
40-
----------------------------
23+
To enable object versioning for a container, you must specify an "archive
24+
container" that will retain non-current versions via either the
25+
``X-Versions-Location`` or ``X-History-Location`` header. These two headers
26+
enable two distinct modes of operation. Either mode may be used within a
27+
cluster, but only one mode may be active for any given container. You must
28+
UTF-8-encode and then URL-encode the container name before you include it in
29+
the header.
30+
31+
For both modes, **PUT** requests will archive any pre-existing objects before
32+
writing new data, and **GET** requests will serve the current version. **COPY**
33+
requests behave like a **GET** followed by a **PUT**; that is, if the copy
34+
*source* is in a versioned container then the current version will be copied,
35+
and if the copy *destination* is in a versioned container then any pre-existing
36+
object will be archived before writing new data.
37+
38+
If object versioning was enabled using ``X-History-Location``, then object
39+
**DELETE** requests will copy the current version to the archive container then
40+
remove it from the versioned container.
41+
42+
If object versioning was enabled using ``X-Versions-Location``, then object
43+
**DELETE** requests will restore the most-recent version from the archive
44+
container, overwriting the curent version.
45+
46+
Example Using ``X-Versions-Location``
47+
-------------------------------------
4148

4249
#. Create the ``current`` container:
4350

4451
.. code::
4552
46-
# 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"
53+
# curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive"
4754
4855
.. code::
4956
@@ -169,14 +176,14 @@ Example Using ``stack`` Mode
169176
on it. If want to completely remove an object and you have five
170177
versions of it, you must **DELETE** it five times.
171178

172-
Example Using ``history`` Mode
173-
------------------------------
179+
Example Using ``X-History-Location``
180+
------------------------------------
174181

175182
#. Create the ``current`` container:
176183

177184
.. code::
178185
179-
# 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"
186+
# curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-History-Location: archive"
180187
181188
.. code::
182189
@@ -266,7 +273,7 @@ Example Using ``history`` Mode
266273
#. Issue a **DELETE** request to a versioned object to copy the
267274
current version of the object to the archive container then delete it from
268275
the current container. Subsequent **GET** requests to the object in the
269-
current container will return 404 Not Found.
276+
current container will return ``404 Not Found``.
270277

271278
.. code::
272279

0 commit comments

Comments
 (0)