1. LandOffer
  2. Blog
  3. All articles
  4. Design a Long-Running Export with Status, Retry, and Expiration

Product & Project Delivery

Design a Long-Running Export with Status, Retry, and Expiration

Define accepted work, operation state and file availability separately. Use a complete fictional export contract and locally checked reference model to clarify duplicate requests, cancellation races, retries and distinct expiration clocks.

9 min readLandOffer team

Treat a long-running export as a durable operation with its own identity, status and recovery actions. Acknowledging the request is different from finishing the file, and finishing the file is different from making a download link available. Define duplicate submission, cancellation, failure and each expiration clock before choosing the spinner or notification copy. Users should be able to return to the operation, recover its current status and avoid accidentally starting it again.

This LandOffer.ai guide develops an original fictional export contract and acceptance packet. Primary documentation was checked October 27, 2026. The service, records, timestamps and product decisions are invented. We executed a deterministic local reference model for selected state transitions and time boundaries. It does not test an API, browser, database concurrency, worker queue, storage service or production authorization system.

A clerk hands a small claim token to a colleague while a separate worker prepares a large folio at an archive workbench.

Separate accepted work, operation status and file access

RFC 9110's HTTP 202 semantics describe a request accepted for processing whose processing is incomplete. The eventual action is not guaranteed by that response. An export screen should therefore say that work was accepted, rather than claiming the file has been created.

Microsoft's asynchronous request-reply pattern describes acknowledging a request, exposing status and retrieving the eventual result separately. It discusses polling guidance, cancellation and duplicate-request keys. The pattern permits variants; a particular set of endpoint names or response codes is not automatically correct for every existing client.

For the fictional archive service below, the initial response uses 202 with an operation reference and status location. Successful status reads return a documented body containing execution and result availability. This contract keeps a completed operation visible even after its file expires. Its HTTP details need review against the actual service conventions before implementation.

A successful status fetch does not mean the export succeeded. A status endpoint can answer correctly that the operation failed. Likewise, losing the network connection does not establish that the worker stopped. Show an unavailable or stale view until status can be checked again.

Worked asset: a complete export state and copy contract

Fictional researcher Willa requests a CSV of approved collection descriptions from workspace Cedar. Engineer Ren defines the operation contract, designer Alba owns user actions and copy, and service owner Cato owns retention and recovery policy. Ren must obtain persistence and worker evidence; Alba must verify the rendered controls and stale-state behavior before release. No real archive or collection data is used.

Request X-41 identifies the workspace, requester, filters, selected fields, CSV schema v2 and a recorded data snapshot. The file represents that snapshot, not whatever the collection contains when somebody later downloads it. A newly requested export may contain different records. Size and completion time remain unknown until the service has enough evidence; the interface does not invent a percentage or delivery estimate.

The operation response includes its reference, execution state, creation and last-update timestamps, permitted actions, safe error information, and separate result/link expiration fields. “Last updated” describes the operation record, not a promise that all source data was updated then. A correlation reference helps support investigate without exposing signed URLs or internal exceptions.

Execution and availability Original user-facing copy Action and boundary
Queued / no result “Export X-41 is queued. You can leave this page and return from Export history.” Open the durable status record; offer cancellation under the contract
Running / no result “Preparing your CSV. Last update: November 18, 2026, 09:03 UTC.” Continue bounded status checks; show measured progress only if available
Cancel requested / no result “Cancellation requested. Waiting for the export worker to confirm.” Do not say canceled or offer a file while the request is unresolved
Canceled / no result “Export canceled. No download is available.” A new export requires an explicit new request; partial work is not published
Failed / no result “The export could not finish. Reference X-41. You can request another export.” Preserve the failure record; distinguish retryable failures from input/access problems
Succeeded / available “CSV ready. File available until November 19, 2026, 09:08 UTC.” Recheck access before issuing a short-lived download link
Succeeded / expired “This export's file has expired. Its operation record remains available.” Offer a new export with a new snapshot; do not imply link refresh restores deleted content

This model separates an execution outcome from result availability. “Expired” is a user-visible availability state, not a claim that yesterday's successful processing has become a failed job. The history can retain its original outcome while explaining why the file cannot be obtained now.

The example retains an operation record for seven days from acceptance, a completed file for 24 hours from completion, and each issued link for at most ten minutes. The duplicate-request mapping lasts 24 hours from acceptance. These are authored policy choices, not HTTP requirements or storage defaults. Display the applicable cutoff rather than leaving users to infer it from a generic “expires soon.”

Make retry name the thing being repeated

A request may reach the server even when its acknowledgment never reaches the browser. Disabling a button helps avoid some repeat clicks, but it does not resolve that lost-response ambiguity. The proposed service scopes a duplicate-request key to the authenticated requester and workspace and binds it to the request contents.

For the same key and identical contents within its 24-hour window, the design returns X-41 instead of queuing another export. Reusing the key with changed contents produces a documented conflict. This protection needs atomic server-side implementation and verification under competing requests; an in-memory example does not establish concurrent or distributed correctness. After the mapping expires, repeating an old submission may create another operation, so the client should recover the known status reference or ask for an explicit new export.

Retrying a failed status read repeats a read. Retrying a download requests the existing file through valid access. Requesting another export after failure or file expiry creates a new operation and snapshot. Name those actions separately in both the interface and support instructions.

Polling also needs a budget. In this design, the client follows the service's suggested next-check interval, backs off on transient read failures and stops polling a terminal operation. Closing the page stops that client's polling, not the export. Returning through history retrieves current status; it must not replay the original create request.

Define cancellation and completion as competing decisions

The cancellation button sends an intention, not a guarantee. Ren's proposed worker uses an atomic transition boundary: if cancellation is accepted before completion commits, the operation enters Cancel requested and cannot publish a result. The worker then confirms Canceled after its cleanup path. Temporary output cleanup is a separate operational obligation, not proof of cancellation from the UI alone.

If completion commits first, the cancel request reports that the file is already ready. The product does not pretend it stopped the completed work or silently delete a file another authorized client may be downloading. Any separate deletion feature needs its own policy and access checks.

Both outcomes need acceptance scenarios. Otherwise an optimistic interface may display Canceled while a background worker still publishes the file. A local transition model can expose a contradictory rule, but validating actual queue redelivery, persistence and race behavior needs implementation-level tests.

Two colleagues examine a finished archive packet beside a small clock and a separate paper token on a wooden counter.

Worked asset: completed cancellation, retry and expiration scenarios

The following packet specifies intended behavior for contract v1. The underlying records are synthetic. Its “model check” results describe only the local reference model executed for this article; the server and interface acceptance checks remain unperformed.

Case and concrete input Required outcome Evidence and unfinished boundary
A1: X-41 accepted November 18 at 09:00 UTC; its first response is lost; Willa resends the same key and contents at 09:01 Return X-41; one operation in the model Local key-map check passes; no HTTP response-loss or database concurrency test
A2: Same key at 09:02, but fields change from v2's description set to include another column Reject the key/content mismatch; retain X-41's original request Local mismatch rule passes; actual error payload and client rendering pending
A3: X-42 is Running; cancellation is recorded before completion Cancel requested, then Canceled; no published result Local sequence blocks publication after cancellation; worker cleanup and atomic persistence pending
A4: X-43 completes before a cancellation request Remain Succeeded/available; report too late to cancel Local terminal-state rule passes; real simultaneous-request behavior pending
A5: X-44 fails; Willa explicitly requests a replacement Preserve X-44 Failed; create distinct X-45 with a new key and snapshot Local identities remain separate; failure cause, retry policy and limits need service verification
A6: X-41 completes at 09:08; a link is issued at 09:10 and expires at 09:20 A new request at 09:21 cannot use that old link; access may be rechecked for a new link while the file remains Local clock rule passes; no signed URL, storage request or permission test
A7: At November 19, 09:08 UTC, X-41's 24-hour file retention ends Show Succeeded/expired; no fresh link for that result; offer a new export Local availability boundary passes; physical file removal and retention enforcement pending
A8: A client cannot fetch current status after seeing Running Show last-known state with stale/unavailable notice; do not infer Failed or replay create Authored interface requirement only; no browser/network test performed

The clocks have different anchors. X-41's duplicate mapping ends November 19 at 09:00, its file availability ends at 09:08, and the status record remains through November 25 at 09:00 UTC. The short link issued at 09:10 on November 18 ends ten minutes later, not a day later. The reference checks these exact boundaries, including equality at each cutoff.

Near file expiry, a newly issued link must not promise a full ten minutes if less file-retention time remains. This contract caps its nominal end at the earlier of issuance plus ten minutes and the file cutoff. Actual credentials or access revocation may stop access sooner. Keep those reasons distinguishable from “export failed.”

Keep download credentials and retention out of status shortcuts

Amazon S3's presigned-URL documentation explains that these links grant bearer access, have a configured lifetime and can become invalid earlier when their signing credentials expire or are revoked. It also distinguishes a transfer begun before expiry from a new request after expiry. Those are S3-specific documented behaviors, not tests of this proposed export service.

Use an authenticated application route to decide whether a current user may obtain a fresh link. Do not store bearer links in broadly visible history or treat knowledge of an operation reference as permission. A previously issued storage URL might remain usable until its own effective cutoff; application permission revocation does not automatically revoke every bearer credential. That exposure and any stronger revocation requirement need explicit security design.

The example intentionally does not promise that file expiry interrupts a transfer already in progress or erases downloaded copies. It requires a defined boundary for new downloads, scheduled result cleanup and retained status. Verify the chosen storage behavior, credential lifetime, caches and cleanup mechanism before displaying stronger guarantees.

For the next design review, bring the state/copy table, duplicate-key scope, cancellation race rule and clocked acceptance packet together. More workplace guides are available from LandOffer.ai. Ask the implementation owners to produce server, persistence, authorization and interface evidence against these same cases before calling the export ready. Keep A8 and the real-system boundaries open until that evidence exists.

Sources and Further Reading