Define how Pravda represents capture outcomes and returns a previous usable snapshot when a refresh fails.
Zavod should be able to request a fresh capture while remaining operational when a source is temporarily unavailable. If the refresh fails, Pravda may return the latest usable snapshot within a caller-specified maximum age. Zavod can parse that evidence and emit a warning instead of failing the crawler.
State model
Separate the page-facing state from the underlying failure cause.
Page states:
live: capture completed and passed validation.blocked: access was denied or challenged.gone: the source returned a permanent absence response.down: the source could not be reached.partial: some evidence was captured, but the result did not satisfy validation.
Failure causes should remain machine-readable, for example DNS failure, timeout, HTTP error, invalid content, browser error, or storage error.
Retrieval behavior
Support a capture operation with an optional maximum stale age:
- Attempt a fresh capture.
- Return it if it is usable.
- If it is unusable, find the latest usable snapshot within
max_stale_age.
- Return the stale snapshot together with the failed fresh attempt and
stale: true.
- Fail if no acceptable snapshot exists.
A stale snapshot must retain its original capture time and identity. The failed refresh attempt must also be stored.
Questions
- Which HTTP statuses map to
gone, blocked, and down?
- Is usability determined by Pravda alone or by caller-supplied validation?
- Should
partial snapshots ever qualify for stale fallback?
- Is stale retrieval part of
POST /snapshots or a separate operation?
- Should
max_stale_age be required whenever fallback is enabled?
Acceptance criteria
- Snapshot states and failure causes are defined.
- Usable-snapshot criteria are explicit.
- Fresh, stale-fallback, and no-fallback response shapes are specified.
- Failed refresh attempts remain inspectable.
- Stale responses expose snapshot age and the failed refresh outcome.
- Tests cover fresh success, failed refresh with fallback, expired fallback, and no usable history.
Define how Pravda represents capture outcomes and returns a previous usable snapshot when a refresh fails.
Zavod should be able to request a fresh capture while remaining operational when a source is temporarily unavailable. If the refresh fails, Pravda may return the latest usable snapshot within a caller-specified maximum age. Zavod can parse that evidence and emit a warning instead of failing the crawler.
State model
Separate the page-facing state from the underlying failure cause.
Page states:
live: capture completed and passed validation.blocked: access was denied or challenged.gone: the source returned a permanent absence response.down: the source could not be reached.partial: some evidence was captured, but the result did not satisfy validation.Failure causes should remain machine-readable, for example DNS failure, timeout, HTTP error, invalid content, browser error, or storage error.
Retrieval behavior
Support a capture operation with an optional maximum stale age:
max_stale_age.stale: true.A stale snapshot must retain its original capture time and identity. The failed refresh attempt must also be stored.
Questions
gone,blocked, anddown?partialsnapshots ever qualify for stale fallback?POST /snapshotsor a separate operation?max_stale_agebe required whenever fallback is enabled?Acceptance criteria