Skip to content

Commit

Permalink
Handle 5xx responses with empty bodies, and implement exponential bac…
Browse files Browse the repository at this point in the history 
…koff
  • Loading branch information
Nick Levine committed Sep 30, 2016
1 parent 64949b1 commit 1324a84
Show file tree
Hide file tree
Showing 6 changed files with 211 additions and 60 deletions.
91 changes: 86 additions & 5 deletions doc/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ <h2>Contents</h2>
<li> <a href='#dictionary'>The ZS3 Dictionary</a>
<ul>
<li> <a href='#credentials'>Credentials</a>
<li> <a href='#backoff'>Backoff</a>
<li> <a href='#bucket-ops'>Operations on Buckets</a>
<li> <a href='#querying-buckets'>Querying Buckets</a>
<li> <a href='#object-ops'>Operations on Objects</a>
Expand Down Expand Up @@ -377,7 +378,50 @@ <h2>Contents</h2>



<a name='bucket-ops'><h3>Operations on Buckets</h3></a>
<a name='backoff'><h3>Backoff</h3></a>

<p>
The response to some requests &mdash; a very small proportion
&mdash; will be an error internal to the AWS server. In these
circumstances an <cite>exponential backoff</cite>
policy is recommended.
</p>

<div class='item'>
<div class='type'><a name='*backoff*'>[Special variable]</a></div>
<div class='signature'>
<code class='name'>*backoff*</code>
</div>

<blockquote class='description'>
<p>
Used as the default value of <code>:backoff</code> when
submitting a request. The value should be a cons of two
numbers: how many times to try before giving up, and how long
to wait (in ms) before trying for the second time. Each
subsequent attempt will double that time.
</p>

<p>
The default value is <code>(3 . 100)</code>.
</p>

<p>
If a requst fails more times than permitted by
<code>*backoff*</code>, an error will be signalled:
</p>

<pre class="code">(ERROR #&lt;ZS3::INTERNAL-ERROR @ #x10008f1a8b2&gt;)</pre>

<p>
It is the application's responsibility to handle this.</p>
</blockquote>
</div>




<a name='bucket-ops'><h3>Operations on Buckets</h3></a>

<p>With ZS3, you can put, get, copy, and delete buckets. You can also
get information about the bucket.
Expand All @@ -387,7 +431,7 @@ <h2>Contents</h2>
<div class='signature'>
<code class='name'>all-buckets</code>
<span class='args'>
<code class='llkw'>&amp;key</code> <var>credentials</var>
<code class='llkw'>&amp;key</code> <var>credentials</var> <var>backoff</var>
</span>
<span class='result'>=> <var>bucket-vector</var></span>
</div>
Expand Down Expand Up @@ -442,6 +486,7 @@ <h2>Contents</h2>
<code class='llkw'>&amp;key</code>
<var>prefix</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>key-vector</var></span>
</div>
Expand Down Expand Up @@ -474,6 +519,7 @@ <h2>Contents</h2>
<var>bucket</var>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>boolean</var></span>
</div>
Expand All @@ -495,6 +541,7 @@ <h2>Contents</h2>
<var>public</var>
<var>location</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -547,7 +594,9 @@ <h2>Contents</h2>
<div class='signature'>
<code class='name'>delete-bucket</code>
<span class='args'>
<var>bucket</var> <code class='llkw'>&amp;key</code> <var>credentials</var>
<var>bucket</var> <code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand All @@ -566,7 +615,9 @@ <h2>Contents</h2>
<div class='signature'>
<code class='name'>bucket-location</code>
<span class='args'>
<var>bucket</var> <code class='llkw'>&amp;key</code> <var>credentials</var>
<var>bucket</var> <code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>location</var></span>
</div>
Expand Down Expand Up @@ -684,6 +735,7 @@ <h2>Contents</h2>
<code class='llkw'>&amp;body</code>
<var>days</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -719,6 +771,7 @@ <h2>Contents</h2>
<var>key</var>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>status-string</var></span>
</div>
Expand Down Expand Up @@ -753,6 +806,7 @@ <h2>Contents</h2>
<var>max-keys</var>
<var>delimiter</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>response</var></span>
</div>
Expand Down Expand Up @@ -1094,6 +1148,7 @@ <h2>Contents</h2>
<var>when-etag-matches</var> <var>unless-etag-matches</var> <br>
<var>if-exists</var> <var>string-external-format</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>object</var></span>
</div>
Expand Down Expand Up @@ -1164,6 +1219,7 @@ <h2>Contents</h2>
<var>when-modified-since</var> <var>unless-modified-since</var>
<var>when-etag-matches</var> <var>unless-etag-matches</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>vector</var></span>
</div>
Expand Down Expand Up @@ -1192,6 +1248,7 @@ <h2>Contents</h2>
<var>when-etag-matches</var>
<var>unless-etag-matches</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>string</var></span>
</div>
Expand Down Expand Up @@ -1221,6 +1278,7 @@ <h2>Contents</h2>
<var>when-etag-matches</var>
<var>unless-etag-matches</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>pathname</var></span>
</div>
Expand Down Expand Up @@ -1256,6 +1314,7 @@ <h2>Contents</h2>
<var>expires</var>
<var>storage-class</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -1337,6 +1396,7 @@ <h2>Contents</h2>
<var>expires</var>
<var>storage-class</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -1373,6 +1433,7 @@ <h2>Contents</h2>
<var>expires</var>
<var>storage-class</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -1406,6 +1467,7 @@ <h2>Contents</h2>
<var>expires</var>
<var>storage-class</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -1447,6 +1509,7 @@ <h2>Contents</h2>
<var>expires</var>
<var>storage-class</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -1495,6 +1558,7 @@ <h2>Contents</h2>
<var>metadata</var> <var>public</var> <var>precondition-errors</var>
<var>storage-class</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -1544,6 +1608,7 @@ <h2>Contents</h2>
<var>key</var>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand All @@ -1567,6 +1632,7 @@ <h2>Contents</h2>
<var>keys</var>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>deleted-count</var>, <var>errors</var></span>
</div>
Expand All @@ -1588,6 +1654,7 @@ <h2>Contents</h2>
<var>bucket</var>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>count</var></span>
</div>
Expand All @@ -1608,6 +1675,7 @@ <h2>Contents</h2>
<var>key</var>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>metadata-alist</var></span>
</div>
Expand Down Expand Up @@ -1637,6 +1705,7 @@ <h2>Contents</h2>
<var>storage-class</var>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -1684,6 +1753,7 @@ <h2>Contents</h2>
<var>bucket</var>
<var>key</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>owner</var>, <var>grants</var></span>
</div>
Expand All @@ -1705,6 +1775,7 @@ <h2>Contents</h2>
<var>bucket</var>
<var>key</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -1856,6 +1927,7 @@ <h2>Contents</h2>
<span class='args'>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>acl-person</var></span>
</div>
Expand All @@ -1879,6 +1951,7 @@ <h2>Contents</h2>
<var>bucket</var>
<var>key</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand All @@ -1899,6 +1972,7 @@ <h2>Contents</h2>
<var>bucket</var>
<var>key</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand Down Expand Up @@ -1931,6 +2005,7 @@ <h2>Contents</h2>
<var>bucket</var>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand All @@ -1950,6 +2025,7 @@ <h2>Contents</h2>
<var>bucket</var>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand All @@ -1973,6 +2049,7 @@ <h2>Contents</h2>
<code class='llkw'>&amp;key</code>
<var>target-grants</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand All @@ -1999,7 +2076,9 @@ <h2>Contents</h2>
<div class='signature'>
<code class='name'>disable-logging</code>
<span class='args'>
<var>bucket</var> <code class='llkw'>&amp;key</code> <var>credentials</var>
<var>bucket</var> <code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> |</span>
</div>
Expand All @@ -2018,6 +2097,7 @@ <h2>Contents</h2>
<var>bucket</var>
<code class='llkw'>&amp;key</code>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>target-bucket</var>,
<var>target-prefix</var>,
Expand Down Expand Up @@ -2150,6 +2230,7 @@ <h2>Contents</h2>
<var>key</var>
<var>parameters</var>
<var>credentials</var>
<var>backoff</var>
</span>
<span class='result'>=> <var>headers-alist</var>,
<var>status-code</var>,
Expand Down
11 changes: 8 additions & 3 deletions errors.lisp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,14 +58,19 @@
(setf (message response) (bvalue :message bindings))
(setf (error-data response) (bvalue :data bindings))))

(defmethod specialized-initialize ((response amazon-error) (source null))
(setf (code response) "InternalError"
(message response) nil
(error-data response) nil))

(defmethod print-object ((response amazon-error) stream)
(print-unreadable-object (response stream :type t)
(prin1 (code response) stream)))

;;; Further specializing error messages/conditions

(defun report-request-error (condition stream)
(format stream "~A: ~A"
(format stream "~A~@[: ~A~]"
(code (request-error-response condition))
(message (request-error-response condition))))

Expand Down Expand Up @@ -134,7 +139,7 @@
:response response
:data (error-data response)
,@(mapcan #'slot-initializer slots))))))


;;; The specific errors

Expand Down Expand Up @@ -186,7 +191,7 @@
(report-request-error condition stream)
(format stream "~&For more information, see:~% ~A"
(linked-url condition)))))


(define-condition bucket-restrictions (linked)
()
Expand Down
Loading

0 comments on commit 1324a84

Please sign in to comment.