Return the download link for one part of a channel checkpoint.
Use it when the user wants a copy of a channel's database, files, or
code as of a checkpoint.
A checkpoint is a row of ``list_channel_snapshots``. ``part``
picks what to download:
- ``database``: the Postgres database as a ``.sqlc`` archive for
``pg_restore``. Any row serves. xhostd builds the archive on
demand from the WAL-G archive, so the download is slow.
- ``files``: the channel's object-storage files as they were at
the checkpoint, as a ``.tar.gz``. Pick a row whose
``aligned_blob`` flag is true.
- ``code``: the deployed code at the checkpoint's ``git_sha``, as
a ``.tar``. Any row serves.
This tool mints nothing and downloads nothing. It returns
``{part, download_url, console_url}``: ``download_url`` is the API
link, and ``console_url`` serves the same artifact to a browser signed
in to the console.
**Run the request with your own token.** Send the header
``Authorization: Bearer <your token>``, with the token from
``$XHOSTD_TOKEN``. If that variable is unset, ask the user to mint a
token on the console /tokens page and export it as ``XHOSTD_TOKEN``.
Never ask the user to paste a token, and never write a token value
into a command. On a failure, the response body holds the error
envelope ``{"error": {"code", "message"}}``. Without a shell, give the
user ``console_url`` to open in a browser signed in to the console.
Any HTTP client works. For example:
``printf 'Authorization: Bearer %s\n' "$XHOSTD_TOKEN" | curl -sS --fail-with-body --header @- -o <file> <url>``.
The example sends the header on curl's stdin, so the token stays off
the argv of every process, which any local user can read.
Errors arrive when you fetch the link, not from this tool:
- Every part: 403 ``download_disabled`` means the operator turned
this part off, which is permanent. 404 ``snapshot_not_found``
means no such checkpoint on this channel. 403 ``scope_denied``
means a narrowed ``$XHOSTD_TOKEN`` lacks the part's scope.
- ``database``: ``snapshot_out_of_window`` (409) and
``snapshot_host_gone`` (404) are permanent, so pick a newer
checkpoint. Retry ``snapshot_not_yet_archived`` (409) after
about 900 seconds, ``backup_storage_unreachable`` (503) after
about 300 seconds, and ``extraction_busy`` (409) after about 600
seconds. Retry ``extraction_failed`` and ``extraction_no_space``
(503) later.
- ``files``: ``no_aligned_blob_snapshot`` (409) means the
checkpoint has no files leg. Another 409 names a checkpoint
older than the retention window, or one above the download limit
on file count or bytes. For the second, read the files with an
S3 client and the key pair that
``get_credential_request(purpose="object_storage")`` describes.
``blob_unavailable`` (503) is transient.
- ``code``: ``snapshot_sha_unknown`` and ``snapshot_code_gone``
(404) are permanent.
Returns ``{part, download_url, console_url}``.
Reference: https://docs.xhostd.com/mcp-tools#get_snapshot_download_link