refactor: Hono 기반 파일 API 및 자동 OpenAPI 문서 전환

[AlphaBs]

변경 내용

itty-router 기반 파일 서버를 Hono로 리팩토링하고 파일 라우트·서비스·R2 저장소·서명 로직을 분리했습니다. pnpm으로 전환하고, Hurl과 수동 Swagger 명세를 Vitest 및 자동 생성 OpenAPI/Scalar 문서로 대체했습니다. README는 한국어로 작성했습니다.

정상 MD5의 R2 저장 키, 인증 방식, 업로드 서명 규칙과 파일 HEAD의 메타데이터 조회는 유지합니다. 후속 결정으로 아래 외부 동작 변경을 포함합니다.

• 32자리 16진수 MD5 검증, 잘못된 단일·일괄 입력은 400
• Hono 기본 경로·쿼리 처리: 끝 슬래시 구분, 경로 파라미터 디코딩, 중복 쿼리의 첫 값 사용
• JSON Content-Type 통일, 잘못된 JSON은 400, 내부 오류는 일반화된 500
• 미지원 메서드는 404, 목록 HEAD는 GET 처리 후 본문 제거
• 저장된 캐시 정책이 없는 GET 다운로드에 1년 public immutable 캐시 적용
• 공개 /docs, /openapi.json 추가; HEAD 동작은 GET 설명에 포함

기존 비정상 키의 객체는 이동·삭제하지 않지만 새 입력 검증으로 접근이 거부될 수 있습니다. 같은 URL의 덮어쓰기와 메타데이터 변경은 캐시 만료 전까지 반영되지 않을 수 있습니다. 세부 계약은 docs/compatibility.md에 기록했습니다.

검증

• pnpm check: 타입 검사, 테스트 163개, 커버리지 100%, OpenAPI 검증 및 Worker dry-run 빌드 통과
• 운영 배포 완료: c336eee5-5d5f-4e01-8675-3f5cf7c26bd9
• 운영 파일 목록 200, 표본 파일 HEAD 200/본문 없음, GET 200 및 MD5 일치 확인
• GET의 Cache-Control: public, max-age=31536000, immutable 확인
• 기존 사용자 지정 도메인과 로그 설정을 Wrangler 설정에 반영

[AlphaBs]

코드 리뷰 완료 — main 대비 커밋 055d178 기준입니다.

검토 범위는 라우팅과 HEAD 처리, 인증·입력 검증 순서, R2 키 및 메타데이터, 업로드 서명, 캐시 기본값, OpenAPI/Scalar, CI와 배포 설정입니다. 현재 확인한 범위에서 합의된 동작 변경 외에 추가 수정을 요구할 결함은 발견하지 못했습니다.

• 파일 HEAD는 GET 핸들러에서 분기하여 R2.head()만 호출하며, 본문 없는 응답을 유지합니다.
• 보호된 요청은 인증 후 검증하고, 일괄 요청은 모든 해시를 검증한 뒤 R2에 접근합니다.
• 정상 MD5의 저장 키와 고정 시각의 서명 결과는 기존 계약 테스트로 검증합니다.
• 저장된 Cache-Control/Expires가 있으면 유지하고, 없는 GET 성공 응답에만 immutable 기본값을 적용합니다.
• 운영 필수 설정은 Secret으로 존재하며, 사용자 지정 도메인과 로그 설정이 Wrangler 설정에 반영돼 있습니다.

남은 검증 한계:

1. 실제 S3 PUT과 조건부 덮어쓰기 거부까지의 업로드 종단 간 검증은 수행하지 않았습니다. 현재 테스트는 생성된 서명·헤더와 로컬 R2 동작을 검증합니다.
2. 비정상 해시의 기존 객체가 운영에 존재하는지 전체 조사하지 않았습니다. 새 검증으로 접근이 차단될 수 있다는 점은 승인된 변경이며 PR에 명시돼 있습니다.
3. 같은 URL의 덮어쓰기·메타데이터 변경이 1년 캐시 동안 보이지 않을 수 있습니다. 이 역시 승인된 정책이며 결함으로 중복 지적하지 않습니다.

로컬 pnpm check(163개 테스트, 커버리지 100%, OpenAPI 및 빌드 검증)와 브랜치 CI가 통과했습니다. 운영 표본 파일의 목록·HEAD·GET·MD5·캐시 헤더도 확인했습니다.