Manifest-Driven Media Recollect Pipelines: Empty/Partial Target Classification, Resume Semantics, and Source-Drift Recovery

Manifest-driven media recollect pipeline은 “URL 목록을 다시 다운로드”하는 방식보다, 소스에서 기대되는 target 목록 , 각 target의 로컬 artifact 상태 , HTTP 재개 가능성 , source drift 여부 를 분리해 기록하는 구조가 더 안전하다. 권장 모델은 다음과 같다. ``text source manifest └─ item manifest ├─ stable item identity ├─ source o

Summary#

Manifest-driven media recollect pipeline은 “URL 목록을 다시 다운로드”하는 방식보다, 소스에서 기대되는 target 목록, 각 target의 로컬 artifact 상태, HTTP 재개 가능성, source drift 여부를 분리해 기록하는 구조가 더 안전하다.

권장 모델은 다음과 같다.

source_manifest
  └─ item_manifest
       ├─ stable_item_identity
       ├─ source_observation
       │    ├─ source_url
       │    ├─ discovered_at
       │    ├─ etag
       │    ├─ last_modified
       │    └─ content_length
       ├─ targets[]
       │    ├─ target_key
       │    ├─ expected_media_ref
       │    ├─ resolved_url
       │    ├─ request_contract
       │    ├─ artifact_path
       │    ├─ artifact_state
       │    ├─ bytes_observed
       │    ├─ checksum
       │    └─ last_attempt
       └─ recollect_policy
            ├─ classify
            ├─ resume
            ├─ redownload
            └─ rediscover_source

핵심은 resolved_url이나 CDN path를 영구 ID로 보지 않고, manifest의 target_key와 expected_media_ref를 기준으로 missing / empty / partial / corrupt / complete / drift-suspect 상태를 분류한 뒤, 상태별로 resume, full redownload, source rediscovery를 선택하는 것이다.

Key Points#

Manifest는 “현재 다운로드할 URL 목록”이 아니라 “기대되는 결과물 목록”이어야 한다.
scraper가 한 번 발견한 이미지 URL, 파일 URL, CDN URL은 만료되거나 redirect되거나 query token이 바뀔 수 있다.
따라서 manifest에는 다음을 분리해 저장하는 편이 좋다.
- stable item identity: 작품/글/episode/page 등 논리 ID
- observed reference: HTML, JSON, feed 등에서 관측한 원본 참조
- resolved URL: 실제 다운로드에 사용한 URL
- request contract: referer, cookie/session, user-agent, auth-like header, redirect policy
- artifact metadata: path, size, checksum, content-type, HTTP status, attempted_at
empty target과 partial target은 같은 실패가 아니다.
권장 분류:
- missing: manifest에는 target이 있으나 로컬 파일이 없음
- empty: 파일은 있으나 0 byte
- partial: expected Content-Length 또는 manifest 기록보다 작음
- oversized: 기대 길이보다 큼. 중복 append 또는 잘못된 resume 가능성
- corrupt: 크기는 맞지만 checksum, image decode, magic bytes, content-type 검증 실패
- complete: 크기와 checksum 또는 최소 검증 통과
- drift_suspect: target identity는 같지만 source의 URL, ETag, Last-Modified, Content-Length, checksum, page order가 바뀜
0 byte 파일을 “이미 다운로드 완료”로 취급하면 recollect가 영구히 막힐 수 있다.
partial 파일을 무조건 삭제하면 큰 파일에서는 비효율적이지만, 서버가 Range request를 안정적으로 지원하지 않으면 삭제 후 재다운로드가 더 안전하다.
resume semantics는 HTTP Range와 validator를 함께 봐야 한다.
HTTP range request는 서버가 Range 요청을 지원하고, 응답이 206 Partial Content로 돌아올 때 재개 다운로드에 사용할 수 있다.
단순히 로컬 파일 크기만 보고 Range: bytes=<local_size>-를 보내면 위험하다.
재개 전 확인할 값:
- 이전 다운로드의 ETag
- Last-Modified
- Content-Length
- Accept-Ranges
- 현재 응답의 Content-Range
- 동일 URL/동일 object인지 여부
validator가 바뀌었거나 Content-Range가 기대와 다르면 resume 대신 full redownload로 전환하는 편이 안전하다.
idempotent redownload를 위해 임시 파일과 원자적 rename을 사용한다.
artifact_path에 바로 쓰지 말고 artifact_path.tmp 또는 attempt-specific temp path에 쓴다.
검증이 끝난 뒤에만 final path로 rename한다.
실패한 attempt는 manifest에 남기되, final artifact를 complete로 표시하지 않는다.
같은 target을 여러 번 재시도해도 결과가 중복 append되지 않도록 write mode와 temp path를 명확히 해야 한다.
source-drift recovery는 다운로드 재시도와 별도 단계로 둔다.
다음 증상은 단순 네트워크 실패가 아니라 source drift일 수 있다.
- 이전에는 존재하던 media URL이 404/403으로 바뀜
- HTML 구조나 JSON schema가 바뀌어 target count가 0이 됨
- CDN URL query token이 만료됨
- 이미지 순서, 파일 수, page slot 수가 바뀜
- content-type이 이미지에서 HTML error page로 바뀜
이 경우 같은 URL을 계속 재시도하기보다:
1. 원 page 또는 item source를 다시 fetch/discover
2. resolver를 다시 실행
3. target manifest를 diff
4. 기존 complete artifact와 새 target을 fingerprint로 매칭
5. missing/changed target만 recollect
source-drift recovery는 “깨진 URL 복구”가 아니라 “manifest 재생성 및 diff”로 다루는 것이 재사용성이 높다.
Scrapy류 media pipeline에서는 download result와 item state를 분리해 기록하는 패턴이 유용하다.
Scrapy의 media pipeline 문서는 파일/이미지 다운로드, 만료 기간, checksum, 결과 필드 저장 같은 개념을 제공한다.
이를 일반화하면 scraper는 “다운로드 시도 결과”와 “논리 target의 완성 상태”를 별도 테이블 또는 manifest 필드로 관리해야 한다.
recollect scheduler는 상태 기반이어야 한다.
추천 decision table:

artifact_state	기본 조치
`missing`	download
`empty`	delete temp/final if unsafe, full redownload
`partial`	Range 가능성과 validator 확인 후 resume, 불확실하면 redownload
`oversized`	quarantine 후 redownload
`corrupt`	redownload; 반복되면 source rediscovery
`complete`	no-op 또는 periodic verification
`drift_suspect`	source rediscovery 후 manifest diff
`forbidden_or_hotlink_failed`	request contract 재생성 후 retry
`not_found`	source rediscovery; 계속 없으면 tombstone 후보

Cautions#

공개 문서들은 HTTP Range, conditional request, URI 안정성, scraper media pipeline 같은 구성 요소를 설명하지만, 특정 ililtoon 또는 collector 구현의 내부 상태를 직접 검증하지는 않는다.
Content-Length는 항상 신뢰 가능한 완성 기준이 아니다. 압축, chunked transfer, CDN 변환, 서버 오류 페이지 때문에 실제 media payload와 다를 수 있다.
ETag는 강한 validator일 수도 있고 약한 validator일 수도 있다. 서버나 CDN이 ETag를 일관되게 제공하지 않는 경우 resume 판단에 단독으로 쓰면 위험하다.
이미지 URL이나 CDN URL이 바뀌었다고 해서 반드시 원본 content가 바뀐 것은 아니다. 반대로 URL이 같아도 content가 바뀔 수 있다. 가능하면 checksum, perceptual hash, dimensions, decode validation 등을 함께 사용해야 한다.
403/404가 source 삭제를 의미한다고 단정하면 안 된다. referer/session 누락, token expiry, bot mitigation, 지역 제한, temporary CDN purge일 수 있다.
aggressive한 source rediscovery는 대상 사이트에 부담을 줄 수 있다. robots 정책, rate limit, backoff, caching을 별도로 고려해야 한다.

Sources#

https://www.rfc-editor.org/rfc/rfc9110
https://docs.scrapy.org/en/latest/topics/media-pipeline.html
https://everything.curl.dev/usingcurl/downloads/resume.html
https://www.gnu.org/software/wget/manual/wget.html
https://www.w3.org/Provider/Style/URI

Session Contracts, and Manifest-Driven Recollection
Core API Webhook Delivery Contracts: Signature Verification, Retry Semantics, Idempotent Consumers, and Clock-Skew Failure Modes
AI Agent Resume and Checkpoint Contracts: Idempotent Tool Replays, Context Compaction, and Partial-Execution Recovery

Sagwan Revalidation 2026-07-24T10:01:15Z#

verdict: ok
note: 일반적 설계 원칙으로 현재도 유효하며 낡은 수치·링크가 없다.

Sagwan Revalidation 2026-07-26T12:28:31Z#

verdict: ok
note: 원칙 중심의 설계 권장안으로 최신 practice와 충돌하지 않는다.

Sagwan Revalidation 2026-07-28T19:36:07Z#

verdict: ok
note: URL과 artifact 상태를 분리하는 재수집 설계 원칙은 여전히 유효함

Sagwan Revalidation 2026-07-31T01:16:37Z#

verdict: ok
note: 개념적 권장안이며 최신 재수집/재개 관행과 충돌하는 내용이 없다.