Delete a snapshot

Deleting a link in an incremental chain does not lose the snapshots that depend on it — the daemon keeps what they need.

A snapshot held by two hosts at once — a move part way through handing its history over — is served from the copy on the host its computer now lives on. One that cannot be attributed that way, such as an orphan, answers 409 until the handover finishes; nothing is changed.

THE DELETION OUTLIVES THIS CALL. You get a 202 and the snapshot’s row the moment the deletion is accepted, not when it finishes — detaching those dependents, then removing the stored objects, takes time that scales with the chain and with how much is stored, which is longer than any HTTP request survives. Poll GET /snapshots?include=unfinished for the id and WAIT FOR THE ROW TO GO. Its absence there is the deletion having finished; there is no state that means "deleted". A bare GET /snapshots drops the row as soon as it reads deleting, which can be long before the deletion has finished, so absence from a bare listing says only that the snapshot can no longer be restored or cloned.

A ROW THAT STAYS SAYS WHICH OF TWO THINGS HAPPENED, by its state, and it is the opposite polarity to a failed capture, which leaves no row at all. Once the daemon has detached the dependents it records the deletion and marks the snapshot deleting, and that state is left out of a bare listing because a half-deleted snapshot is not one you can restore or clone. A deleting row finishes without you: one held up by a backup upload of this snapshot that is slow to stop reads deleting while it waits and finishes once the upload has stopped, and one that stalls after that is retried by the daemon itself. A row still in the state it had has not recorded the deletion. It may still be working: detaching its dependents, or waiting on a slow upload while backup storage also refuses the record, which it goes on trying to write. Or it failed before recording anything (a dependent that is itself being deleted, below, or backup storage refusing the record with no upload to wait on), and then nothing was destroyed and nothing retries it. A row that stays in its old state is therefore worth a second DELETE: it is refused with a 409 while another deletion of this snapshot holds it, and otherwise accepted as one more attempt, which does no harm if an earlier one is still waiting; a 202 does not say that the first one failed.

EVERYTHING THAT CAN REFUSE A DELETION OF THIS SNAPSHOT IS REFUSED HERE, before the 202: no such snapshot, a capture reading through it, a clone or a migration holding it, and a deletion of this snapshot already running. That last one is what a second DELETE gets for as long as the first is working, so it is an answer about progress rather than a fault. Each of those 409s ends by itself and carries reason: "contention".

ONE CONFLICT ARRIVES AFTER THE 202, and it is about a different snapshot: a dependent that is ITSELF being deleted cannot be detached, so deleting the link it hangs off fails once the work starts. Nothing is destroyed — the row stays exactly as it was, in its ordinary state rather than deleting — and the delete succeeds once the dependent’s own deletion has finished. Deleting a chain one link at a time, waiting for each row to go, never meets it.

Requires the member role or higher.