Roll back one part of a channel to a checkpoint.
Use it when the user asks to restore a channel's database or files to
an earlier point. State the channel, the checkpoint, and the mode to
the user, and call this tool only after the user confirms them.
A checkpoint is a row of ``list_channel_snapshots``. ``part`` picks
what the restore rewinds.
``database`` starts a restore of the channel's Postgres database and
returns at once. The restore runs in the background: it reads the
snapshot from its backup, loads it into a new database, and then
switches the channel to that database. A restore can take up to an hour; for databases under 10 GB it typically takes minutes. Tell the user
this before you start.
``during_restore`` chooses what the app can do while the restore runs:
- ``read_only``, the default: the app stays online and reads its
database, and every database write fails until the restore ends.
- ``maintenance``: the app's addresses show a maintenance page, and
every database write fails until the restore ends. xhostd's own page
answers HTTP 503, so an uptime monitor reports the app as down
during the restore.
- ``live``: the app keeps reading and writing its database, with no
page, and the switch to the restored database discards every write
made during the restore.
In every mode, a write made while the restore still waits to start
is discarded at the switch. The result's ``notice`` states the chosen
mode's effect: relay it to the user.
**The user's own maintenance page.** A static channel can serve the
page in place of xhostd's, with its own pages, images, and styles:
1. Create a static app (``create_app`` with ``template="static"``),
push the page's files, and deploy it. It must belong to the same
owner as the restored app.
2. Start the restore with ``during_restore="maintenance"``, and name
that channel with ``maintenance_app`` and ``maintenance_channel``.
The app's addresses then serve the static channel, which answers with
its own status codes: 200 for its pages and 404 for a path it lacks.
If the static channel stops or is deleted during the restore, xhostd's
own page replaces it within a minute. Don't redeploy the page channel
while a restore runs: for up to a minute after the redeploy, requests
to the app's addresses fail. A ``maintenance`` restore changes what the
app's public addresses serve, so the tool is marked open-world.
Read progress with ``get_restore_status(restore_id)``, or give the
user ``console_url``, the project's Database page. While the restore
is active, a deploy of the channel answers ``restore_in_flight`` (HTTP
409). A failed restore leaves the database unchanged, and
``get_restore_status`` then reports its ``error_code`` and a
``message`` to relay. The call refuses at once, and changes nothing,
with:
- ``restore_in_flight`` (HTTP 409): a restore of the channel is
already active. The message names its id.
- ``snapshot_out_of_window`` (HTTP 409): permanent. Pick a newer
checkpoint.
- ``snapshot_not_found`` or ``snapshot_host_gone`` (HTTP 404):
permanent.
- ``maintenance_channel_not_found``, ``maintenance_channel_not_static``,
or ``maintenance_channel_not_deployed`` (HTTP 400): the page channel
belongs to another owner, is not a static app, or is not deployed.
``files`` rewinds every object in the channel's blob store to its
state at the checkpoint. The route takes the channel name as
``confirm_channel_name`` to confirm the destructive change; this
tool passes the channel name you give, so confirm the channel with
the user first. It refuses with
``no_aligned_blob_snapshot`` (HTTP 409) when the checkpoint has
no files leg. Pick a row whose ``aligned_blob`` flag is true.
For both parts, on the ``prod`` channel this is a PROTECTED
ACTION: it answers 403 ``protected_action`` to an agent
credential until the app owner turns agent access on in the
console. ``files`` refuses with ``channel_busy`` (HTTP 409) if any
deploy on the channel is queued or running. ``database`` cancels
every deploy and rewind still queued for the channel, and
``cancelled_deploys`` lists their ids: tell the user, and deploy
again once the restore ends. A deploy that already runs finishes
first, and the restore waits for it.
Returns ``{restore_id, status, during_restore, notice,
cancelled_deploys, console_url}`` for ``database``, or the updated
channel blob-store status for ``files``.
Reference: https://docs.xhostd.com/mcp-tools#restore_channel_snapshot