PDF 조작은 특히 페이지 순서를 다룰 때 복잡해질 수 있습니다. 최근 우리는 PDF 문서 구조와 페이지 인덱싱에 대한 중요한 통찰을 드러낸 흥미로운 디버깅 세션을 경험했습니다. 이 사례 연구는 겉보기에 간단한 “오프바이원” 오류가 PDF 사양에 대한 깊은 조사로 발전하여 문서 구조에 대한 근본적인 오해를 드러낸 과정을 보여줍니다.

문제

우리는 HotPDF Delphi 컴포넌트의 CopyPage라는 PDF 페이지 복사 유틸리티를 작업하고 있었습니다. 이 프로그램은 기본적으로 첫 번째 페이지를 복사해야 했지만, 대신 항상 두 번째 페이지를 복사하고 있었습니다. 언뜻 보기에는 간단한 인덱스 버그처럼 보였습니다 – 아마도 0 기반 대신 1 기반 인덱싱을 사용했거나 기본적인 산술 오류를 범했을 것입니다.

하지만 인덱싱 로직을 여러 번 확인하고 올바른 것을 확인한 후, 더 근본적인 무언가가 잘못되었다는 것을 깨달았습니다. 문제는 복사 로직 자체가 아니라 프로그램이 애초에 “페이지 1″이 무엇인지 해석하는 방식에 있었습니다.

증상

문제는 여러 가지 방식으로 나타났습니다:

1. 일관된 오프셋: 모든 페이지 요청이 한 위치씩 어긋나 있었습니다
2. 여러 문서에서 재현 가능: 문제가 여러 다른 PDF 파일에서 발생했습니다
3. 명백한 인덱스 오류 없음: 코드 로직이 표면적 검사에서는 올바르게 보였습니다
4. 이상한 페이지 순서: 모든 페이지를 복사할 때, 한 PDF의 페이지 순서는 2, 3, 1이었고, 다른 것은 2, 3, 4, 5, 6, 7, 8, 9, 10, 1이었습니다

이 마지막 증상이 돌파구로 이어지는 핵심 단서였습니다.

초기 조사

PDF 구조 분석

첫 번째 단계는 PDF 문서 구조를 조사하는 것이었습니다. 내부에서 무슨 일이 일어나고 있는지 이해하기 위해 여러 도구를 사용했습니다:

1. 수동 PDF 검사 – 원시 구조를 보기 위한 헥스 에디터 사용
2. 명령줄 도구 – qpdf –show-object 등을 사용하여 객체 정보 덤프
3. Python PDF 디버깅 스크립트 – 파싱 프로세스 추적

이러한 도구를 사용하여 소스 문서가 특정 페이지 트리 구조를 가지고 있음을 발견했습니다:
[crayon-6866b436cc48c383686877/]

이는 문서에 3개의 페이지가 포함되어 있지만 페이지 객체가 PDF 파일 내에서 순차적으로 배치되지 않았음을 보여주었습니다. Kids 배열이 논리적 페이지 순서를 정의했습니다:

• 페이지 1: 객체 20
• 페이지 2: 객체 1
• 페이지 3: 객체 4

첫 번째 단서

핵심 통찰은 객체 번호와 그들의 논리적 위치를 조사하는 것에서 나왔습니다. 주목할 점은:

• 객체 1이 Kids 배열의 두 번째에 나타남 (논리적 페이지 2)
• 객체 4가 Kids 배열의 세 번째에 나타남 (논리적 페이지 3)
• 객체 20이 Kids 배열의 첫 번째에 나타남 (논리적 페이지 1)

이는 파싱 코드가 Kids 배열의 순서를 따르는 대신 객체 번호나 파일 내 물리적 출현에 기반하여 내부 페이지 배열을 구축하는 경우, 페이지가 잘못된 순서가 될 것임을 의미했습니다.

가설 테스트

이 이론을 검증하기 위해 간단한 테스트를 만들었습니다:

1. 각 페이지를 개별적으로 추출하여 내용 확인
2. 추출된 페이지의 파일 크기 비교 (다른 페이지는 종종 다른 크기를 가짐)
3. 페이지별 마커 찾기 – 페이지 번호나 푸터 등

테스트 결과가 가설을 확인했습니다:

• 프로그램의 “페이지 1″에는 페이지 2에 있어야 할 내용이 있었습니다
• 프로그램의 “페이지 2″에는 페이지 3에 있어야 할 내용이 있었습니다
• 프로그램의 “페이지 3″에는 페이지 1에 있어야 할 내용이 있었습니다

이 순환 시프트 패턴이 페이지 배열이 올바르게 구축되지 않았다는 결정적인 증거였습니다.

근본 원인

파싱 로직 이해

핵심 문제는 PDF 파싱 코드가 Pages 트리 구조에서 정의된 논리적 순서가 아닌 PDF 파일 내 객체의 물리적 순서에 기반하여 내부 페이지 배열(PageArr)을 구축하고 있었다는 것입니다.

파싱 프로세스 중에 일어나고 있던 일은 다음과 같습니다:

[crayon-6866b436cc496256797191/]

이로 인해 다음과 같은 결과가 나왔습니다:

• PageArr[0]에는 객체 1이 포함되었습니다 (실제로는 논리적 페이지 2)
• PageArr[1]에는 객체 4가 포함되었습니다 (실제로는 논리적 페이지 3)
• PageArr[2]에는 객체 20이 포함되었습니다 (실제로는 논리적 페이지 1)

코드가 PageArr[0]을 사용하여 “페이지 1″을 복사하려고 할 때, 실제로는 잘못된 페이지를 복사하고 있었습니다.

두 가지 다른 순서

문제는 페이지를 순서화하는 두 가지 다른 방법을 혼동한 것에서 비롯되었습니다:

물리적 순서 (객체가 PDF 파일에 나타나는 방식):

[crayon-6866b436cc498422652132/]

논리적 순서 (Pages 트리의 Kids 배열에서 정의됨):

[crayon-6866b436cc49a947737756/]

파싱 코드는 물리적 순서를 사용하고 있었지만, 사용자는 논리적 순서를 기대하고 있었습니다.

왜 이런 일이 발생하는가

PDF 파일은 반드시 페이지가 순차적 순서로 작성되는 것은 아닙니다. 이는 여러 이유로 발생할 수 있습니다:

1. 증분 업데이트: 나중에 추가된 페이지가 더 높은 객체 번호를 받음
2. PDF 생성기: 다른 도구들이 객체를 다르게 조직할 수 있음
3. 최적화: 일부 도구는 압축이나 성능을 위해 객체를 재배치함
4. 편집 이력: 문서 변경이 객체 재번호를 야기할 수 있음

추가 복잡성: 다중 파싱 경로

우리의 HotPDF VCL 컴포넌트에는 두 가지 다른 파싱 경로가 있습니다:

1. 레거시 파싱: 오래된 PDF 1.3/1.4 형식에 사용
2. 모던 파싱: 객체 스트림과 새로운 기능을 가진 PDF (PDF 1.5/1.6/1.7)에 사용

버그는 두 경로 모두에서 수정되어야 했습니다. 이들은 다른 방식으로 페이지 배열을 구축하지만, 둘 다 Kids 배열에서 정의된 논리적 순서를 무시하고 있었습니다.

해결책

수정 설계

수정에는 PDF의 Pages 트리에서 정의된 논리적 순서와 일치하도록 내부 페이지 배열을 재구성하는 페이지 재정렬 기능의 구현이 필요했습니다. 이는 기존 기능을 깨뜨리지 않도록 신중하게 수행되어야 했습니다.

구현 전략

해결책에는 여러 핵심 구성 요소가 포함되었습니다:

[crayon-6866b436cc49c489672371/]

상세 구현

완전한 재정렬 기능은 다음과 같습니다:

[crayon-6866b436cc49d845235414/]

통합 지점

재정렬 기능은 두 파싱 경로 모두에서 적절한 시점에 호출되어야 했습니다:

1. 레거시 파싱 후: ListExtDictionary 완료 후 호출
2. 모던 파싱 후: 객체 스트림 처리 후 호출

[crayon-6866b436cc4a0985595695/]

오류 처리 및 엣지 케이스

구현에는 다양한 엣지 케이스에 대한 견고한 오류 처리가 포함되었습니다:

1. 루트 객체 부재: 문서 구조가 손상된 경우 우아한 폴백
2. 잘못된 페이지 참조: 깨진 참조를 건너뛰지만 처리 계속
3. 혼합 객체 타입: 재정렬 전에 객체가 실제로 페이지인지 확인
4. 빈 페이지 배열: 페이지가 없는 문서 처리
5. 예외 안전성: 크래시를 방지하기 위해 예외를 잡고 로그

도움이 된 디버깅 기법

1. 포괄적 로깅

모든 단계에서 상세한 디버그 출력을 추가하는 것이 중요했습니다. 다중 레벨 로그 시스템을 구현했습니다:

[crayon-6866b436cc4a2408881236/]

로깅을 통해 작업의 정확한 순서가 드러났고, 페이지 순서가 어디서 잘못되었는지 추적할 수 있었습니다.

2. PDF 구조 분석 도구

PDF 구조를 이해하기 위해 여러 외부 도구를 사용했습니다:

명령줄 도구:

[crayon-6866b436cc4a4958823665/]

데스크톱 PDF 분석 도구:

• PDF Explorer: PDF 구조의 시각적 트리 뷰
• PDF Debugger: PDF 파싱의 단계별 실행
• 헥스 에디터: 원시 바이트 레벨 분석

3. 테스트 파일 검증

체계적인 검증 프로세스를 만들었습니다:

[crayon-6866b436cc4a6025750190/]

4. 단계별 격리

문제를 격리된 구성 요소로 분해했습니다:

단계 1: PDF 파싱

• 문서가 올바르게 로드되는지 확인
• 객체 수와 타입 확인
• 페이지 트리 구조 검증

단계 2: 페이지 배열 구축

• 내부 배열에 추가되는 각 페이지 로그
• 페이지 객체 타입과 참조 확인
• 배열 인덱스 확인

단계 3: 페이지 복사

• 각 페이지를 개별적으로 복사 테스트
• 소스와 대상 페이지 내용 확인
• 복사 중 데이터 손상 확인

단계 4: 출력 검증

• 출력을 예상 결과와 비교
• 최종 문서에서 페이지 순서 검증
• 여러 PDF 뷰어에서 테스트

5. 바이너리 차이 분석

파일 크기 비교가 결정적이지 않을 때 바이너리 차이 도구를 사용했습니다:

[crayon-6866b436cc4a8250637339/]

이를 통해 어떤 바이트가 다른지 정확히 드러났고, 문제가 내용에 있는지 메타데이터에만 있는지 식별하는 데 도움이 되었습니다.

6. 참조 구현 비교

다른 PDF 라이브러리와의 동작도 비교했습니다:

[crayon-6866b436cc4a9387601788/]

이를 통해 비교할 “그라운드 트루스”를 얻었고, 실제로 어떤 페이지가 추출되어야 하는지 확인할 수 있었습니다.

7. 메모리 디버깅

문제가 배열 조작과 관련되어 있었기 때문에 메모리 디버깅 도구를 사용했습니다:

[crayon-6866b436cc4ab234453484/]

8. 버전 제어 고고학

파싱 코드가 어떻게 진화했는지 이해하기 위해 git을 사용했습니다:

[crayon-6866b436cc4ac562014200/]

이를 통해 객체 파싱을 최적화했지만 의도치 않게 페이지 순서를 깨뜨린 최근 리팩터링에서 버그가 도입되었음이 밝혀졌습니다.

배운 교훈

1. PDF 논리적 순서 대 물리적 순서

페이지가 PDF 파일에서 표시되어야 하는 순서와 같은 순서로 나타난다고 가정하지 마세요. 항상 Pages 트리 구조를 존중하세요.

2. 수정 타이밍

페이지 재정렬은 파싱 파이프라인의 적절한 순간 – 모든 페이지 객체가 식별된 후, 하지만 페이지 조작 전에 수행되어야 합니다.

3. 다중 PDF 파싱 경로

현대적인 PDF 파싱 라이브러리는 종종 여러 코드 경로(레거시 대 모던 파싱)를 가집니다. 수정이 모든 관련 경로에 적용되는지 확인하세요.

4. 철저한 테스트

페이지 순서 문제는 특정 문서 구조나 생성 도구에서만 나타날 수 있으므로 다양한 PDF 문서로 테스트하세요.

예방 전략

1. 적극적 PDF 구조 검증

PDF 파싱 중에 항상 페이지 순서를 검증하는 자동 확인을 구현하세요:

[crayon-6866b436cc4ae873945150/]

2. 포괄적 로깅 프레임워크

복잡한 문서 파싱을 위한 구조화된 로깅 시스템을 구현하세요:

[crayon-6866b436cc4b0347544918/]

3. 다양한 테스트 전략

엣지 케이스를 잡기 위해 다양한 소스의 PDF로 테스트하세요:

문서 소스:

• 오피스 애플리케이션 (Microsoft Office, LibreOffice)
• 웹 브라우저 (Chrome, Firefox PDF 내보내기)
• PDF 생성 도구 (Adobe Acrobat, PDFCreator)
• 프로그래밍 라이브러리 (losLab PDF 라이브러리, PyPDF2, PyMuPDF)
• OCR 텍스트 레이어가 있는 스캔 문서
• 오래된 도구로 생성된 레거시 PDF

테스트 카테고리:

[crayon-6866b436cc4b1842230137/]

4. PDF 사양의 깊은 이해

PDF 사양(ISO 32000)에서 공부해야 할 핵심 섹션:

• 섹션 7.7.5: 페이지 트리 구조
• 섹션 7.5: 간접 객체와 참조
• 섹션 7.4: 파일 구조와 조직
• 섹션 12: 대화형 기능 (고급 파싱용)

핵심 알고리즘의 참조 구현을 만드세요:

[crayon-6866b436cc4b3799321883/]

5. 자동 회귀 테스트

지속적 통합 테스트를 구현하세요:

[crayon-6866b436cc4b4533985049/]

고급 디버깅 기법

성능 프로파일링

큰 PDF는 파싱 로직의 성능 병목을 드러낼 수 있습니다:

[crayon-6866b436cc4b6308916924/]

메모리 사용량 분석

파싱 중 메모리 할당 패턴을 추적하세요:

[crayon-6866b436cc4b7122207946/]

크로스 플랫폼 검증

다른 플랫폼에서 동일한 PDF가 다르게 동작하는지 테스트하세요:

[crayon-6866b436cc4b8505209986/]

성능 개선

수정 후 측정된 성능 지표:

결론

이 디버깅 세션은 PDF 조작에서 몇 가지 중요한 통찰을 드러냈습니다:

기술적 통찰

• 논리적 순서 대 물리적 순서: PDF에서 가장 중요한 구별
• Pages 트리 구조: 항상 PDF 사양을 따라야 함
• 다중 파싱 경로: 모든 코드 경로에서 일관성 보장
• 견고한 오류 처리: 손상된 PDF에 대한 우아한 폴백

프로세스 통찰

• 체계적 디버깅: 가정을 테스트하고 증거를 수집
• 외부 도구: PDF 구조 분석을 위한 qpdf, cpdf 등 활용
• 참조 구현: 다른 라이브러리와 비교하여 검증
• 포괄적 로깅: 복잡한 파싱 프로세스 추적

프로젝트 관리 통찰

• 엣지 케이스 테스트: 다양한 PDF 소스로 테스트
• 회귀 방지: 자동 테스트 스위트 구현
• 문서화: 향후 참조를 위한 디버깅 프로세스 기록

궁극적으로, 이 경험은 PDF 조작 라이브러리를 개발할 때 표면적인 API 기능뿐만 아니라 기본 문서 구조를 깊이 이해하는 것의 중요성을 강조합니다. 겉보기에 간단한 “오프바이원” 오류가 PDF 사양의 핵심 개념에 대한 근본적인 오해를 드러낼 수 있습니다.

이 사례 연구가 유사한 PDF 관련 문제에 직면한 다른 개발자들에게 유용한 참고 자료가 되기를 바랍니다. 기억하세요: PDF 디버깅에서는 항상 사양을 신뢰하고, 가정을 테스트하며, 포괄적으로 로그를 남기세요.