ISO 8601 timestamps for tempurl

Client-side implementation for ISO 8601 timestamp
support of tempurl middleware. Please see

https://review.openstack.org/#/c/422679/

Change-Id: I76da28b48948475ec1bae5258e0b39a316553fb7

2 files changed, 52 insertions, 12 deletions

diff --git a/doc/manpages/swift.1 b/doc/manpages/swift.1
index bbf5280..1f288d6 100644
--- a/doc/manpages/swift.1
+++ b/doc/manpages/swift.1
@@ -130,14 +130,33 @@ programs, such as jq.
          capabilities \-\-json
 .RE
 
-\fBtempurl\fR [\fIcommand-option\fR] \fImethod\fR \fIseconds\fR \fIpath\fR \fIkey\fR
+\fBtempurl\fR [\fIcommand-option\fR] \fImethod\fR \fItime\fR \fIpath\fR \fIkey\fR
 .RS 4
 Generates a temporary URL allowing unauthenticated access to the Swift object
-at the given path, using the given HTTP method, for the given number of
-seconds, using the given TempURL key. With the optional \-\-prefix\-based option a
-prefix-based URL is generated. If optional \-\-absolute argument is
-provided, seconds is instead interpreted as a Unix timestamp at which the URL
-should expire. \fBExample\fR: tempurl GET $(date \-d "Jan 1 2016" +%s)
+at the given path, using the given HTTP method, for the given time,
+using the given TempURL key.
+
+The time can be specified either as an integer
+denoting the amount of seconds the temporary URL is valid, or as an ISO 8601
+timestamp in one of following formats:  Complete date: YYYY\-MM\-DD (eg 1997\-07\-16),
+complete date plus hours, minutes and seconds: YYYY\-MM\-DDThh:mm:ss
+(eg 1997\-07\-16T19:20:30) or complete date plus hours, minutes and seconds with
+UTC designator: YYYY\-MM\-DDThh:mm:ssZ (eg 1997\-07\-16T19:20:30Z). Be aware that
+if you do not use the latter format, the timestamp is generated using your locale
+timezone. If the first format is used, the time part used will equal to 00:00:00.
+
+With the \-\-prefix\-based option a
+prefix-based URL is generated.
+
+The option \-\-iso8601 provides ISO 8601 UTC timestamps
+instead of Unix timestamps inside the generated URL.
+
+If optional \-\-absolute argument is
+provided and the time argument is specified in seconds, the seconds are
+interpreted as a Unix timestamp at which the URL
+should expire.
+
+\fBExample\fR: tempurl GET $(date \-d "Jan 1 2016" +%s)
 /v1/AUTH_foo/bar_container/quux.md my_secret_tempurl_key \-\-absolute
 
 .RE
diff --git a/doc/source/cli.rst b/doc/source/cli.rst
index b107448..8d80d1b 100644
--- a/doc/source/cli.rst
+++ b/doc/source/cli.rst
@@ -228,18 +228,39 @@ Capabilities
 Tempurl
 -------
 
-    ``tempurl [command-options] [method] [seconds] [path] [key]``
+    ``tempurl [command-options] [method] [time] [path] [key]``
 
        Generates a temporary URL for a Swift object. ``method`` option sets an HTTP method to
-       allow for this temporary URL that is usually 'GET' or 'PUT'. ``seconds`` option sets
-       the amount of time in seconds the temporary URL will be valid for; or, if ``--absolute``
-       is passed, the Unix timestamp when the temporary URL will expire. ``path`` option sets
-       the full path to the Swift object. Example: ``/v1/AUTH_account/c/o``. ``key`` option is
+       allow for this temporary URL that is usually ``GET` or ``PUT``. ``time`` option sets
+       the amount of time the temporary URL will be valid for.
+       ``time`` can be specified as an integer, denoting the number of seconds
+       from now on until the URL shall be valid; or, if ``--absolute``
+       is passed, the Unix timestamp when the temporary URL will expire.
+       But beyond that, ``time`` can also be specified as an ISO 8601 timestamp
+       in one of following formats:
+
+        i) Complete date: YYYY-MM-DD (eg 1997-07-16)
+
+        ii) Complete date plus hours, minutes and seconds:
+           YYYY-MM-DDThh:mm:ss
+         (eg 1997-07-16T19:20:30)
+
+        iii) Complete date plus hours, minutes and seconds with UTC designator:
+            YYYY-MM-DDThh:mm:ssZ
+         (eg 1997-07-16T19:20:30Z)
+
+       Please be aware that if you don't provide the UTC designator (i.e., Z)
+       the timestamp is generated using your local timezone. If only a date is
+       specified, the time part used will equal to ``00:00:00``.
+
+       ``path`` option sets the full path to the Swift object.
+       Example: ``/v1/AUTH_account/c/o``. ``key`` option is
        the secret temporary URL key set on the Swift cluster. To set a key, run
        ``swift post -m "Temp-URL-Key: <your secret key>"``. To generate a prefix-based temporary
        URL use the ``--prefix-based`` option. This URL will contain the path to the prefix. Do not
        forget to append the desired objectname at the end of the path portion (and before the
-       query portion) before sharing the URL.
+       query portion) before sharing the URL. It is possible to use ISO 8601 UTC timestamps within the
+       URL by using the ``--iso8601`` option.
 
 Auth
 ----