Symlink implementation.

Add a symbolic link ("symlink") object support to Swift. This
object will reference another object. GET and HEAD
requests for a symlink object will operate on the referenced object.
DELETE and PUT requests for a symlink object will operate on the
symlink object, not the referenced object, and will delete or
overwrite it, respectively.
POST requests are *not* forwarded to the referenced object and should
be sent directly. POST requests sent to a symlink object will
result in a 307 Error.

Historical information on symlink design can be found here:
https://github.com/openstack/swift-specs/blob/master/specs/in_progress/symlinks.rst.
https://etherpad.openstack.org/p/swift_symlinks

Co-Authored-By: Thiago da Silva <thiago@redhat.com>
Co-Authored-By: Janie Richling <jrichli@us.ibm.com>
Co-Authored-By: Kazuhiro MIYAHARA <miyahara.kazuhiro@lab.ntt.co.jp>
Co-Authored-By: Kota Tsuyuzaki <tsuyuzaki.kota@lab.ntt.co.jp>

Change-Id: I838ed71bacb3e33916db8dd42c7880d5bb9f8e18
Signed-off-by: Thiago da Silva <thiago@redhat.com>

3 files changed, 91 insertions, 3 deletions

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index c8dc8ae7d..8ab65f58e 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -164,7 +164,7 @@ ETag_obj_req:
     manifest objects, this value is the MD5 checksum of the
     concatenated string of ETag values for each of the segments in
     the manifest. You are strongly recommended to compute
-    the MD5 checksum value and include it in the request. This 
+    the MD5 checksum value and include it in the request. This
     enables the Object Storage API to check the integrity of the
     upload. The value is not quoted.
   in: header
@@ -850,6 +850,44 @@ X-Storage-Policy:
   in: header
   required: false
   type: string
+X-Symlink-Target:
+  description: |
+    Set to specify that this is a symlink object.
+    The value is the relative path of the target object in the
+    format <container>/<object>.  The target object does not need to
+    exist at the time of symlink creation.
+    You must UTF-8-encode and then URL-encode the names of the
+    container and object before you include them in this header.
+  in: header
+  required: false
+  type: string
+X-Symlink-Target-Account:
+  description: |
+    Set to specify that this is a cross-account symlink to
+    an object in the account specified in the value.
+    The ``X-Symlink-Target`` must also be set for this to
+    be effective.
+    You must UTF-8-encode and then URL-encode the account name
+    before you include it in this header.
+  in: header
+  required: false
+  type: string
+X-Symlink-Target-Account_resp:
+  description: |
+    If present, and ``X-Symlink-Target`` is present, then
+    this is a cross-account symlink to
+    an object in the account specified in the value.
+  in: header
+  required: false
+  type: string
+X-Symlink-Target_resp:
+  description: |
+    If present, this is a symlink object.
+    The value is the relative path of the target object in the
+    format <container>/<object>.
+  in: header
+  required: false
+  type: string
 X-Timestamp:
   description: |
     The date and time in `UNIX Epoch time stamp
@@ -1092,6 +1130,23 @@ swiftinfo_sig:
   in: query
   required: false
   type: string
+symlink:
+  description: |
+    If you include the ``symlink=get`` query parameter
+    and the object is a symlink, then the response will include
+    data and metadata from the symlink itself rather than from the target.
+  in: query
+  required: false
+  type: string
+symlink_copy:
+  description: |
+    If you include the ``symlink=get`` query parameter
+    and the object is a symlink, the target object
+    contents are not copied. Instead, the symlink is copied to
+    create a new symlink to the same target.
+  in: query
+  required: false
+  type: string
 temp_url_expires:
   description: |
     The date and time in `UNIX Epoch time stamp
@@ -1180,5 +1235,12 @@ name_in_container_get:
   in: body
   required: true
   type: string
+symlink_path:
+  description: |
+    This field exists only when the object is symlink.
+    This is the target path of the symlink object.
+  in: body
+  required: true
+  type: string
 
 
diff --git a/api-ref/source/storage-container-services.inc b/api-ref/source/storage-container-services.inc
index a66f85fe4..a1351275a 100644
--- a/api-ref/source/storage-container-services.inc
+++ b/api-ref/source/storage-container-services.inc
@@ -96,6 +96,7 @@ Response Parameters
    - content_type: content_type
    - bytes: bytes_in_container_get
    - name: name_in_container_get
+   - symlink_path: symlink_path
 
 
 Response Example format=json
diff --git a/api-ref/source/storage-object-services.inc b/api-ref/source/storage-object-services.inc
index bb6833e31..4c2b45b38 100644
--- a/api-ref/source/storage-object-services.inc
+++ b/api-ref/source/storage-object-services.inc
@@ -111,6 +111,7 @@ Request
    - temp_url_expires: temp_url_expires
    - filename: filename
    - multipart-manifest: multipart-manifest_get
+   - symlink: symlink
    - Range: Range
    - If-Match: If-Match
    - If-None-Match: If-None-Match-get-request
@@ -139,7 +140,8 @@ Response Parameters
    - X-Openstack-Request-Id: X-Openstack-Request-Id
    - Date: Date
    - X-Static-Large-Object: X-Static-Large-Object
-
+   - X-Symlink-Target: X-Symlink-Target_resp
+   - X-Symlink-Target-Account: X-Symlink-Target-Account_resp
 
 
 Response Example
@@ -263,6 +265,8 @@ Request
    - X-Object-Meta-name: X-Object-Meta-name
    - If-None-Match: If-None-Match-put-request
    - X-Trans-Id-Extra: X-Trans-Id-Extra
+   - X-Symlink-Target: X-Symlink-Target
+   - X-Symlink-Target-Account: X-Symlink-Target-Account
 
 
 Response Parameters
@@ -321,6 +325,12 @@ The new object contains the same manifest as the original.
 The segment objects are not copied. Instead, both the original
 and new manifest objects share the same set of segment objects.
 
+To copy a symlink either with a COPY or a PUT with the
+``X-Copy-From`` request, include the ``symlink=get`` query string.
+The new symlink will have the same target as the original.
+The target object is not copied. Instead, both the original
+and new symlinks point to the same target object.
+
 All metadata is
 preserved during the object copy. If you specify metadata on the
 request to copy the object, either PUT or COPY , the metadata
@@ -396,6 +406,7 @@ Request
    - container: container
    - object: object
    - multipart-manifest: multipart-manifest_copy
+   - symlink: symlink_copy
    - X-Auth-Token: X-Auth-Token
    - X-Service-Token: X-Service-Token
    - Destination: Destination
@@ -445,6 +456,9 @@ manifest=delete`` query parameter. This operation deletes the
 segment objects and, if all deletions succeed, this operation
 deletes the manifest object.
 
+A DELETE request made to a symlink path will delete the symlink
+rather than the target object.
+
 An alternative to using the DELETE operation is to use
 the POST operation with the ``bulk-delete`` query parameter.
 
@@ -570,6 +584,7 @@ Request
    - temp_url_expires: temp_url_expires
    - filename: filename
    - multipart-manifest: multipart-manifest_head
+   - symlink: symlink
    - X-Newest: X-Newest
    - If-Match: If-Match
    - If-None-Match: If-None-Match-get-request
@@ -597,7 +612,8 @@ Response Parameters
    - Date: Date
    - X-Static-Large-Object: X-Static-Large-Object
    - Content-Type: Content-Type_obj_resp
-
+   - X-Symlink-Target: X-Symlink-Target_resp
+   - X-Symlink-Target-Account: X-Symlink-Target-Account_resp
 
 
 Response Example
@@ -659,6 +675,15 @@ body. There are alternate uses of the POST operation as follows:
   can be used to upload an archive (tar file). The archive is then extracted
   to create objects.
 
+A POST request must not include X-Symlink-Target header. If it does then a
+400 status code is returned and the object metadata is not modified.
+
+When a POST request is sent to a symlink, the metadata will be applied to the
+symlink, but the request will result in a ``307 Temporary Redirect`` response
+to the client. The POST is never redirected to the target object, thus a
+GET/HEAD request to the symlink without ``symlink=get`` will not return the
+metadata that was sent as part of the POST request.
+
 Example requests and responses:
 
 - Create object metadata: