When the App Restarts

OmniGet's queue is useful only if a crash does not erase the user's decisions. This chapter focuses on the difference between preserving queue intent and preserving completed bytes: how append-only records replay live work, how sampled progress and .part files divide the recovery problem, and what still has to be re-resolved after restart. Readers should finish able to judge recovery as a lifecycle with limits, not as a promise that every interrupted download resumes from an identical external state.

A process can stop at the worst possible moment: after the user has queued a batch, while one item is active, or halfway through a record write. The recovery design is meant for precisely these ordinary interruptions, not only dramatic hardware failures. A single file that is rewritten from scratch can be made atomic against truncation, yet still lose the interval between writes. OmniGet's write-ahead-log approach addresses a different problem: make each important transition durable enough that replay can reconstruct what was still alive when the process ended.

Intent and bytes need different forms of recovery

The queue records user intent at enqueue time. That intent includes the URL, title, platform, output directory, quality and mode choices, format information, referer where relevant, and the item's position. The record is not the media itself. It is the information needed to know what the user asked OmniGet to do and how the queue was arranged before execution began.

The transfer path has a separate recovery object: the .part file. It contains bytes that have arrived but have not yet passed the final validation and rename step. A partial file can help the downloader resume when the source supports ranges, but it cannot tell the queue whether the user wanted a different quality, whether the item was scheduled, or whether the process had already marked the job as cancelled. The log and the partial file answer different questions, and recovery is reliable only when neither is asked to replace the other.

This distinction prevents a common misunderstanding about “resume.” Resuming is not one operation. The queue must recover the intent and options; the downloader must inspect the partial bytes and the current remote resource; the source must still accept the request; and the resulting body must still pass validation. A crash can preserve the first two while the last two have changed outside the computer.

An append-only lifecycle

The write-ahead log records transitions as individual JSON lines: an item is enqueued, started, updated with sampled progress, completed, failed, cancelled, or removed. Replay reads the log in order and keeps a live representation for each item. Terminal records remove an item from the live set. The remaining items are sorted by their original queue position rather than by the order in which later progress records happened to arrive.

That ordering is part of the user's intent. Suppose item three started before item one because its information was ready first. If the application restarts, the queue should not silently become a history of whichever job emitted the most recent event.