mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-11-12 20:15:10 +00:00
Deployed 16ae73e with MkDocs version: 1.6.1
This commit is contained in:
@@ -2536,14 +2536,21 @@
|
||||
</span></code></pre></div>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Polling cadence</p>
|
||||
<p>A few seconds between polls is plenty. The server writes progress updates roughly twice a second internally, but there is no push/streaming channel; you read the current snapshot each time you ask.</p>
|
||||
<p>A few seconds between polls is plenty. The server updates a job's progress roughly twice a second internally, and each poll reads the current snapshot.</p>
|
||||
</div>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Or let the server push the updates</p>
|
||||
<p><code>GET /api/download/jobs/{job_id}/events</code> streams the same job record as Server-Sent Events, and closes the stream when the job ends. It removes the polling loop above. See <a href="../endpoints/#get-apidownloadjobsjob_idevents">Endpoints</a>.</p>
|
||||
<div class="language-bash highlight"><pre><span></span><code><span id="__span-21-1"><a id="__codelineno-21-1" name="__codelineno-21-1" href="#__codelineno-21-1"></a>curl<span class="w"> </span>-N<span class="w"> </span><span class="s2">"</span><span class="nv">$BASE</span><span class="s2">/api/download/jobs/</span><span class="nv">$JOB</span><span class="s2">/events"</span><span class="w"> </span><span class="se">\</span>
|
||||
</span><span id="__span-21-2"><a id="__codelineno-21-2" name="__codelineno-21-2" href="#__codelineno-21-2"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-Secret-Key: </span><span class="nv">$SECRET</span><span class="s2">"</span>
|
||||
</span></code></pre></div>
|
||||
</div>
|
||||
<p>If a job ends in <code>failed</code>, the full record includes <code>error_message</code>, <code>error_code</code>, and (when the server was started with <code>--debug-api</code>) <code>error_traceback</code> and <code>worker_stderr</code> to help you diagnose it. Sensitive values in these fields are scrubbed before they are returned.</p>
|
||||
<hr />
|
||||
<h2 id="step-7-clean-up">Step 7: Clean up<a class="headerlink" href="#step-7-clean-up" title="Permanent link">¶</a></h2>
|
||||
<p>Once you have collected the output you can remove the finished job. <code>DELETE</code> on a job has two behaviors depending on its state:</p>
|
||||
<div class="language-shell highlight"><pre><span></span><code><span id="__span-21-1"><a id="__codelineno-21-1" name="__codelineno-21-1" href="#__codelineno-21-1"></a>curl<span class="w"> </span>-X<span class="w"> </span>DELETE<span class="w"> </span><span class="s2">"</span><span class="nv">$BASE</span><span class="s2">/api/download/jobs/</span><span class="nv">$JOB</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
</span><span id="__span-21-2"><a id="__codelineno-21-2" name="__codelineno-21-2" href="#__codelineno-21-2"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-Secret-Key: </span><span class="nv">$SECRET</span><span class="s2">"</span>
|
||||
<div class="language-shell highlight"><pre><span></span><code><span id="__span-22-1"><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a>curl<span class="w"> </span>-X<span class="w"> </span>DELETE<span class="w"> </span><span class="s2">"</span><span class="nv">$BASE</span><span class="s2">/api/download/jobs/</span><span class="nv">$JOB</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
</span><span id="__span-22-2"><a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-Secret-Key: </span><span class="nv">$SECRET</span><span class="s2">"</span>
|
||||
</span></code></pre></div>
|
||||
<ul>
|
||||
<li>If the job is <strong>terminal</strong> (completed/failed/cancelled) it is removed from the manager and you get <strong><code>204 No Content</code></strong> with an empty body.</li>
|
||||
@@ -2554,10 +2561,10 @@
|
||||
<p>A <code>204</code> response has no body. This applies to terminal-job removal here and to deleting history entries; check the status code before attempting to decode JSON.</p>
|
||||
</div>
|
||||
<p>To clear every finished job at once instead of one at a time:</p>
|
||||
<div class="language-shell highlight"><pre><span></span><code><span id="__span-22-1"><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a>curl<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$BASE</span><span class="s2">/api/download/jobs/clear-finished"</span><span class="w"> </span><span class="se">\</span>
|
||||
</span><span id="__span-22-2"><a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-Secret-Key: </span><span class="nv">$SECRET</span><span class="s2">"</span>
|
||||
<div class="language-shell highlight"><pre><span></span><code><span id="__span-23-1"><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a>curl<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$BASE</span><span class="s2">/api/download/jobs/clear-finished"</span><span class="w"> </span><span class="se">\</span>
|
||||
</span><span id="__span-23-2"><a id="__codelineno-23-2" name="__codelineno-23-2" href="#__codelineno-23-2"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-Secret-Key: </span><span class="nv">$SECRET</span><span class="s2">"</span>
|
||||
</span></code></pre></div>
|
||||
<div class="language-json highlight"><span class="filename">200 OK</span><pre><span></span><code><span id="__span-23-1"><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">"removed"</span><span class="p">:</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="p">}</span>
|
||||
<div class="language-json highlight"><span class="filename">200 OK</span><pre><span></span><code><span id="__span-24-1"><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">"removed"</span><span class="p">:</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
<hr />
|
||||
<h2 id="managing-the-queue">Managing the queue<a class="headerlink" href="#managing-the-queue" title="Permanent link">¶</a></h2>
|
||||
@@ -2604,24 +2611,24 @@
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Listing supports query parameters for filtering by <code>status</code> or <code>service</code>, sorting via <code>sort_by</code> (<code>created_time</code>, <code>started_time</code>, <code>completed_time</code>, <code>progress</code>, <code>status</code>, <code>service</code>) and <code>sort_order</code> (<code>asc</code> / <code>desc</code>), and requesting full per-job detail with <code>full=true</code>:</p>
|
||||
<div class="language-shell highlight"><pre><span></span><code><span id="__span-24-1"><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a>curl<span class="w"> </span><span class="s2">"</span><span class="nv">$BASE</span><span class="s2">/api/download/jobs?status=downloading&sort_by=progress&sort_order=desc"</span><span class="w"> </span><span class="se">\</span>
|
||||
</span><span id="__span-24-2"><a id="__codelineno-24-2" name="__codelineno-24-2" href="#__codelineno-24-2"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-Secret-Key: </span><span class="nv">$SECRET</span><span class="s2">"</span>
|
||||
<div class="language-shell highlight"><pre><span></span><code><span id="__span-25-1"><a id="__codelineno-25-1" name="__codelineno-25-1" href="#__codelineno-25-1"></a>curl<span class="w"> </span><span class="s2">"</span><span class="nv">$BASE</span><span class="s2">/api/download/jobs?status=downloading&sort_by=progress&sort_order=desc"</span><span class="w"> </span><span class="se">\</span>
|
||||
</span><span id="__span-25-2"><a id="__codelineno-25-2" name="__codelineno-25-2" href="#__codelineno-25-2"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-Secret-Key: </span><span class="nv">$SECRET</span><span class="s2">"</span>
|
||||
</span></code></pre></div>
|
||||
<div class="language-json highlight"><span class="filename">200 OK</span><pre><span></span><code><span id="__span-25-1"><a id="__codelineno-25-1" name="__codelineno-25-1" href="#__codelineno-25-1"></a><span class="p">{</span>
|
||||
</span><span id="__span-25-2"><a id="__codelineno-25-2" name="__codelineno-25-2" href="#__codelineno-25-2"></a><span class="w"> </span><span class="nt">"jobs"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
</span><span id="__span-25-3"><a id="__codelineno-25-3" name="__codelineno-25-3" href="#__codelineno-25-3"></a><span class="w"> </span><span class="p">{</span>
|
||||
</span><span id="__span-25-4"><a id="__codelineno-25-4" name="__codelineno-25-4" href="#__codelineno-25-4"></a><span class="w"> </span><span class="nt">"job_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3f9c1e0a-8d2b-4e6f-9a1c-77b0f2a1c4d5"</span><span class="p">,</span>
|
||||
</span><span id="__span-25-5"><a id="__codelineno-25-5" name="__codelineno-25-5" href="#__codelineno-25-5"></a><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"downloading"</span><span class="p">,</span>
|
||||
</span><span id="__span-25-6"><a id="__codelineno-25-6" name="__codelineno-25-6" href="#__codelineno-25-6"></a><span class="w"> </span><span class="nt">"service"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EXAMPLE"</span><span class="p">,</span>
|
||||
</span><span id="__span-25-7"><a id="__codelineno-25-7" name="__codelineno-25-7" href="#__codelineno-25-7"></a><span class="w"> </span><span class="nt">"title_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"12345"</span><span class="p">,</span>
|
||||
</span><span id="__span-25-8"><a id="__codelineno-25-8" name="__codelineno-25-8" href="#__codelineno-25-8"></a><span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Example Show S01E01"</span><span class="p">,</span>
|
||||
</span><span id="__span-25-9"><a id="__codelineno-25-9" name="__codelineno-25-9" href="#__codelineno-25-9"></a><span class="w"> </span><span class="nt">"progress"</span><span class="p">:</span><span class="w"> </span><span class="mf">42.7</span><span class="p">,</span>
|
||||
</span><span id="__span-25-10"><a id="__codelineno-25-10" name="__codelineno-25-10" href="#__codelineno-25-10"></a><span class="w"> </span><span class="nt">"phase"</span><span class="p">:</span><span class="w"> </span><span class="s2">"downloading"</span><span class="p">,</span>
|
||||
</span><span id="__span-25-11"><a id="__codelineno-25-11" name="__codelineno-25-11" href="#__codelineno-25-11"></a><span class="w"> </span><span class="nt">"completed_tracks"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
||||
</span><span id="__span-25-12"><a id="__codelineno-25-12" name="__codelineno-25-12" href="#__codelineno-25-12"></a><span class="w"> </span><span class="nt">"total_tracks"</span><span class="p">:</span><span class="w"> </span><span class="mi">3</span>
|
||||
</span><span id="__span-25-13"><a id="__codelineno-25-13" name="__codelineno-25-13" href="#__codelineno-25-13"></a><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-25-14"><a id="__codelineno-25-14" name="__codelineno-25-14" href="#__codelineno-25-14"></a><span class="w"> </span><span class="p">]</span>
|
||||
</span><span id="__span-25-15"><a id="__codelineno-25-15" name="__codelineno-25-15" href="#__codelineno-25-15"></a><span class="p">}</span>
|
||||
<div class="language-json highlight"><span class="filename">200 OK</span><pre><span></span><code><span id="__span-26-1"><a id="__codelineno-26-1" name="__codelineno-26-1" href="#__codelineno-26-1"></a><span class="p">{</span>
|
||||
</span><span id="__span-26-2"><a id="__codelineno-26-2" name="__codelineno-26-2" href="#__codelineno-26-2"></a><span class="w"> </span><span class="nt">"jobs"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
</span><span id="__span-26-3"><a id="__codelineno-26-3" name="__codelineno-26-3" href="#__codelineno-26-3"></a><span class="w"> </span><span class="p">{</span>
|
||||
</span><span id="__span-26-4"><a id="__codelineno-26-4" name="__codelineno-26-4" href="#__codelineno-26-4"></a><span class="w"> </span><span class="nt">"job_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3f9c1e0a-8d2b-4e6f-9a1c-77b0f2a1c4d5"</span><span class="p">,</span>
|
||||
</span><span id="__span-26-5"><a id="__codelineno-26-5" name="__codelineno-26-5" href="#__codelineno-26-5"></a><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"downloading"</span><span class="p">,</span>
|
||||
</span><span id="__span-26-6"><a id="__codelineno-26-6" name="__codelineno-26-6" href="#__codelineno-26-6"></a><span class="w"> </span><span class="nt">"service"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EXAMPLE"</span><span class="p">,</span>
|
||||
</span><span id="__span-26-7"><a id="__codelineno-26-7" name="__codelineno-26-7" href="#__codelineno-26-7"></a><span class="w"> </span><span class="nt">"title_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"12345"</span><span class="p">,</span>
|
||||
</span><span id="__span-26-8"><a id="__codelineno-26-8" name="__codelineno-26-8" href="#__codelineno-26-8"></a><span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Example Show S01E01"</span><span class="p">,</span>
|
||||
</span><span id="__span-26-9"><a id="__codelineno-26-9" name="__codelineno-26-9" href="#__codelineno-26-9"></a><span class="w"> </span><span class="nt">"progress"</span><span class="p">:</span><span class="w"> </span><span class="mf">42.7</span><span class="p">,</span>
|
||||
</span><span id="__span-26-10"><a id="__codelineno-26-10" name="__codelineno-26-10" href="#__codelineno-26-10"></a><span class="w"> </span><span class="nt">"phase"</span><span class="p">:</span><span class="w"> </span><span class="s2">"downloading"</span><span class="p">,</span>
|
||||
</span><span id="__span-26-11"><a id="__codelineno-26-11" name="__codelineno-26-11" href="#__codelineno-26-11"></a><span class="w"> </span><span class="nt">"completed_tracks"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
||||
</span><span id="__span-26-12"><a id="__codelineno-26-12" name="__codelineno-26-12" href="#__codelineno-26-12"></a><span class="w"> </span><span class="nt">"total_tracks"</span><span class="p">:</span><span class="w"> </span><span class="mi">3</span>
|
||||
</span><span id="__span-26-13"><a id="__codelineno-26-13" name="__codelineno-26-13" href="#__codelineno-26-13"></a><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-26-14"><a id="__codelineno-26-14" name="__codelineno-26-14" href="#__codelineno-26-14"></a><span class="w"> </span><span class="p">]</span>
|
||||
</span><span id="__span-26-15"><a id="__codelineno-26-15" name="__codelineno-26-15" href="#__codelineno-26-15"></a><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
<p>Retrying reuses the original job's service, title, and parameters to enqueue a brand new job (returning <code>202</code> with a fresh <code>job_id</code>); it only works on terminal jobs and returns <code>409 CONFLICT</code> otherwise. Prioritizing only works on jobs still in the <code>queued</code> state.</p>
|
||||
<hr />
|
||||
@@ -2638,13 +2645,13 @@
|
||||
<hr />
|
||||
<h2 id="error-handling">Error handling<a class="headerlink" href="#error-handling" title="Permanent link">¶</a></h2>
|
||||
<p>Apart from the auth middleware's short form, every error the API returns uses a single structured envelope:</p>
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-26-1"><a id="__codelineno-26-1" name="__codelineno-26-1" href="#__codelineno-26-1"></a><span class="p">{</span>
|
||||
</span><span id="__span-26-2"><a id="__codelineno-26-2" name="__codelineno-26-2" href="#__codelineno-26-2"></a><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"error"</span><span class="p">,</span>
|
||||
</span><span id="__span-26-3"><a id="__codelineno-26-3" name="__codelineno-26-3" href="#__codelineno-26-3"></a><span class="w"> </span><span class="nt">"error_code"</span><span class="p">:</span><span class="w"> </span><span class="s2">"INVALID_PARAMETERS"</span><span class="p">,</span>
|
||||
</span><span id="__span-26-4"><a id="__codelineno-26-4" name="__codelineno-26-4" href="#__codelineno-26-4"></a><span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Human-readable description"</span><span class="p">,</span>
|
||||
</span><span id="__span-26-5"><a id="__codelineno-26-5" name="__codelineno-26-5" href="#__codelineno-26-5"></a><span class="w"> </span><span class="nt">"timestamp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-07-03T12:00:00Z"</span><span class="p">,</span>
|
||||
</span><span id="__span-26-6"><a id="__codelineno-26-6" name="__codelineno-26-6" href="#__codelineno-26-6"></a><span class="w"> </span><span class="nt">"details"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-26-7"><a id="__codelineno-26-7" name="__codelineno-26-7" href="#__codelineno-26-7"></a><span class="p">}</span>
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-27-1"><a id="__codelineno-27-1" name="__codelineno-27-1" href="#__codelineno-27-1"></a><span class="p">{</span>
|
||||
</span><span id="__span-27-2"><a id="__codelineno-27-2" name="__codelineno-27-2" href="#__codelineno-27-2"></a><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"error"</span><span class="p">,</span>
|
||||
</span><span id="__span-27-3"><a id="__codelineno-27-3" name="__codelineno-27-3" href="#__codelineno-27-3"></a><span class="w"> </span><span class="nt">"error_code"</span><span class="p">:</span><span class="w"> </span><span class="s2">"INVALID_PARAMETERS"</span><span class="p">,</span>
|
||||
</span><span id="__span-27-4"><a id="__codelineno-27-4" name="__codelineno-27-4" href="#__codelineno-27-4"></a><span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Human-readable description"</span><span class="p">,</span>
|
||||
</span><span id="__span-27-5"><a id="__codelineno-27-5" name="__codelineno-27-5" href="#__codelineno-27-5"></a><span class="w"> </span><span class="nt">"timestamp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-07-03T12:00:00Z"</span><span class="p">,</span>
|
||||
</span><span id="__span-27-6"><a id="__codelineno-27-6" name="__codelineno-27-6" href="#__codelineno-27-6"></a><span class="w"> </span><span class="nt">"details"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-27-7"><a id="__codelineno-27-7" name="__codelineno-27-7" href="#__codelineno-27-7"></a><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
<p><code>details</code> appears only when there is something to add, <code>retryable: true</code> appears only for transient failures, and a <code>debug_info</code> block (exception type and traceback) is included only when the server runs with <code>--debug-api</code>.</p>
|
||||
<p>The <code>error_code</code> maps to an HTTP status. The ones you will meet most often:</p>
|
||||
|
||||
Reference in New Issue
Block a user