Clarify DownloadService client responsibilities after cancellation

DownloadService에서 다운로드를 취소한 뒤에도 이미 예약된 콜백이 전달될 수 있다는 점을 API 주석에 명시했습니다. 클라이언트가 자신의 다운로드 상태를 추적하고, 더 이상 유효하지 않은 콜백을 무시해야 한다는 책임을 서비스와 클라이언트 인터페이스 양쪽에 설명했습니다. 실행 코드의 동작은 변경하지 않았습니다.

문제 설명

CancelDownload()를 호출하더라도 이미 예약된 OnDownloadSucceeded()나 OnDownloadFailed() 콜백까지 전달되지 않는다고 보장할 수는 없습니다. 취소 요청과 콜백 실행 사이의 비동기 처리 때문에, 클라이언트는 취소한 다운로드의 콜백을 나중에 받을 수 있습니다.

기존 API 주석에는 실행 중인 다운로드를 중단한다는 설명만 있어, 취소 이후의 콜백을 누가 처리해야 하는지 분명하지 않았습니다. Background Fetch에 남아 있던 TODO도 서비스가 이 문제를 해결하면 클라이언트의 방어 코드를 DCHECK로 바꿀 수 있다는 방향으로 적혀 있었습니다.

선행 CL 8277215에서는 서비스가 대기 중인 콜백과 취소 상태를 추가로 추적하는 방법을 시도했습니다. 리뷰에서는 다운로드의 시작·취소를 결정하는 클라이언트가 자신의 상태를 기준으로 콜백을 걸러야 하며, Background Fetch가 이미 그렇게 동작한다는 점을 확인했습니다. 이후 서비스 구현 변경은 중단하고, TODO 정리와 API 문서 보완을 각각 별도 CL로 진행했습니다.

해결 내용

components/download/public/background_service/의 헤더 두 파일에서 주석만 변경했습니다.

background_download_service.h: CancelDownload()가 이후의 모든 Client 콜백을 차단한다고 보장하지 않는다는 설명을 추가했습니다. 이미 예약된 성공·실패 콜백을 예로 들고, 클라이언트가 자신의 상태에 맞지 않는 콜백을 무시해야 한다고 명시했습니다.
client.h: Client 인터페이스 설명에도 다운로드 상태를 직접 추적하고 취소 이후를 포함해 더 이상 유효하지 않은 콜백을 무시해야 한다고 적었습니다. 자세한 계약은 BackgroundDownloadService::CancelDownload()를 참조하도록 연결했습니다.

아래는 해당 API 선언과 추가된 계약을 한국어 주석으로 요약한 스니펫입니다. 함수 선언은 그대로이며, 새로운 처리 로직을 추가한 코드는 아닙니다.

// 취소하더라도 이미 예약된 성공·실패 콜백이 도착할 수 있습니다.
// 클라이언트는 자신의 다운로드 상태에 맞지 않는 콜백을 무시해야 합니다.
virtual void CancelDownload(const std::string& guid) = 0;

서비스 호출자와 Client 구현자가 각각 읽는 위치에 같은 책임을 명시해, 취소 이후의 콜백을 서비스가 모두 막아 준다는 오해를 줄였습니다.

검증 내용

이번 CL은 API 주석만 수정하므로 테스트 코드나 실행 로직 변경은 없습니다. 리뷰 요청에서도 주석만 변경한 작업임을 명시했습니다.

Gerrit 기록상 Xinghui Lu와 Shakti Sahu의 승인을 받았습니다. 2026년 10월 6일 첫 CQ 실행은 linux-chromeos-rel의 no-op 빌드 검사에서 실패했습니다. 10월 7일 CQ를 다시 실행한 뒤 리베이스된 Patch Set 2가 머지됐습니다. 이 문서 작성 과정에서 Chromium 빌드나 테스트를 별도로 실행하지는 않았습니다.

연관 CL과 이슈

CL 8277215 — 취소 시 대기 중인 완료 콜백 처리 시도 (abandoned): ControllerImpl에서 대기·취소 GUID를 추적하고 콜백 결과를 취소로 바꾸려던 접근입니다. 클라이언트가 콜백의 유효성을 판단해야 한다는 리뷰 의견에 따라 중단했습니다. 해당 리뷰에서 DownloadService 문서를 보완하자는 제안이 나왔으며, 현재 CL의 리뷰 요청에서도 이 논의를 참조합니다.
CL 8316987 — 오래된 Background Fetch 취소 TODO 제거 (merged): 같은 논의에서 이어진 정리 작업입니다. 기존 GUID 조회 방어 코드는 유지하고, 서비스가 취소된 다운로드의 콜백을 차단해야 한다고 암시하던 TODO 다섯 개를 제거했습니다. 이번 CL은 API 문서에서 그 책임을 명확히 하는 작업입니다.
Chromium 이슈 40546930: 위 세 CL이 참조하는 다운로드 취소와 콜백 처리 관련 이슈입니다.

배운 점

비동기 API의 취소는 이미 예약된 콜백까지 모두 사라진다는 의미가 아닐 수 있습니다. 취소의 보장 범위와 호출자가 처리해야 할 상황을 문서에 명시해야 합니다.
시작·취소 상태를 이미 알고 있는 클라이언트가 콜백의 유효성을 판단하면, 서비스에 중복 상태 관리 로직을 추가하지 않고도 책임을 분명하게 유지할 수 있습니다.
구현 변경이 필요 없다는 결론을 얻었더라도, 오해를 유발한 TODO와 API 설명을 함께 정리하면 같은 접근을 다시 시도하는 일을 줄일 수 있습니다.