Files
clean-architecture-backend-…/docs/fileserver/design-deviations.md
DongHyeonka 6583cc2e02 docs(fileserver): 파일서버 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/fileserver 아래 살아 있는 문서 8개가 영어였다(language 예외). 번역하며
본 주장 중 지금 코드와 다른 것이 있었다.
- design-deviations.md: 지운 `FileStateMachine`·`FileserverStorageConfiguration`·
  content-store SPI 넷(`AsyncContentStore` 등)을 지금 있는 것처럼 적었다. 고정 테스트로
  없는 `SampleApplicationContextTest`·`LocalOrphanScanAdapterTest`·
  `FileserverRoundTripContractTest`를 댔다. JPA 저장소가 persistence-jpa에 있다고 했지만
  지금은 persistence-fileserver의 `FileserverJpaPersistenceConfig` 조건 하나 뒤에 있다.
  지운 reactive transport가 아직 스트리밍한다고 했다.
- security.md: 「익명 읽기를 켜면」이라고 했지만 설정 스위치가 없다
  (`FileserverSecurityConfiguration`이 늘 false로 만든다). 이름 `ContentDispositionFactory`는
  지금 `HttpContentDispositionFactory`다.
- upgrade-guide.md: batch 실패를 `results[].problem`으로, 결과 모름을 problem document로
  읽으라고 했다. 지금은 `results[].error`와 Envelope `error.details.ambiguous`다. 확인 명령이
  Fileserver 테스트가 없는 `:app-bootstrap:test --tests '*Fileserver*'`와 fileserver 코드가 없는
  `:application-core:check`·`:adapter:inbound:web:check`를 돌렸다.
- operations.md: 「NFS 결과 모름」 신호를 problem document로 적었다(지금은 Envelope).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 지원 등급
이름(Stable, Beta, Limited, Compatibility, Experimental)은 표와 테스트가 읽는 꼬리표라
원문으로 둔다(messaging 지원 매트릭스와 같다). configuration.md의 절 제목은 테스트가 읽는
「… — `key`」 꼴을 지킨다. 위 불일치는 코드에 맞춰 고쳤다.

테스트: FileserverDocumentationCoverageTest가 runbook 제목 일곱과 「Explicitly not
claimed」를 영어 문자열로 단언했다. 같은 계약(runbook마다 제목이 있고, 주장하지 않는 것을
따로 밝힌다)을 한국어 제목 `## 저장소 가득 참` 등과 `## 주장하지 않는 것`으로 단언한다.
제목 앞에 `## `를 붙여 본문 어딘가에 낱말만 있어도 통과하던 것을 제목으로 좁혔다.
metric 이름·CI job·endpoint·설정 key 단언은 그대로다.

버린 대안: runbook 제목을 영어로 남기기. 살아 있는 문서를 한국어로 쓴다는 소유자 결정과
맞지 않는다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0). 테스트의 단언을 같은 정규식으로
문서에 돌려 보았다(runbook 제목·job 존재·설정 key 44개가 번역 전과 같음).
2026-11-07 17:29:57 +09:00

13 KiB

Fileserver — 설계와 다른 곳

설계 명세와 구현 계획서는 고정된 문서다. 구현하다 보니 명세가 덜 정해졌거나 스스로 모순인 곳이 있었다. 그 해결은 명세를 고치지 않고 여기 적는다. 항목마다 그 결정을 고정하는 테스트를 적는다.

상태 기계와 계약에서 해결한 모순

1. 전이 표에 CREATED → FAILED edge가 없다

기록이 생긴 뒤 실패한 create는 FAILED로 끝나야 하는데, 표에 바로 가는 edge가 없다. 그래서 기록은 CREATED → UPLOADING → FAILED로 간다. 이것이 정직한 읽기이기도 하다. 업로드는 실패하기 전에 이미 허가됐다.

고정하는 테스트: ResumableUploadUseCasesTest(application-fileserver).

2. ContentKey의 글자 집합이 맨 앞 구분자를 허락한다

설계의 key 패턴 [a-z0-9/_-]{16,200}은 /etc/passwd/...에 맞는다. 값 타입에서 절대 경로를 거부하면 설계가 고정한 계약이 바뀐다. 그래서 더 엄격한 모양 검사는 §12.2 규칙 1에 따라 PhysicalPathResolver에 둔다. 식별자를 경로로 바꾸는 유일한 곳이다.

고정하는 테스트: PhysicalPathResolverTest.

3. VERIFYING → DELETING edge가 없다

검증 중인 파일을 지우는 합법적 전이가 없다. lifecycle 서비스는 edge를 지어내지 않고 409 FILE_NOT_READY로 거부한다. JPA markDeleting 문이 이미 강제하던 허용 상태 목록과 같다.

고정하는 테스트: FileLifecycleUseCasesTest.

4. If-Match는 ETag로 정해졌는데 lifecycle은 행 version을 기준으로 설계됐다

HTTP 계약은 entity tag를 보내고, metadata 저장소는 숫자 version으로 막는다. 서비스는 Optional<String> expectedEtag를 받아 기록의 strong validator와 비교한다. 그래서 client가 보낸 선행 조건이 곧 검사하는 선행 조건이다.

고정하는 테스트: FileLifecycleUseCasesTest.

5. 파일 이름 정책이 :를 남겼다

C:\Windows\system.ini가 C:Windowssystem.ini로 정리됐다. 드라이브가 붙은 이름이 표시 문자열과 헤더까지 살아남았다. :를 구조 문자 제거 집합에 넣었다.

고정하는 테스트: FileserverHardeningContractTest, AmbiguousFilesystemOperationDetectorTest.

설계가 암시하지만 정하지 않은 추가

6. fs_recovery_item

§10.2는 핵심 테이블 다섯을 나열하는데 그중 어느 것도 복구 큐를 담을 수 없다. 그런데 §29.3은 복구 큐를 요구한다. 맞춰 보기는 바이트와 metadata가 어긋나는 파일을 보고하는데, 그 목록을 메모리에 두면 재시작이 끊은 바로 그 경우를 잃는다. V2__fileserver_recovery_and_staging_cleanup.sql에서 더했다. 파일마다 열린 항목은 하나다. 그래서 같은 정리를 반복해도 로그가 쌓이지 않고 작업 목록이 갱신된다.

고정하는 테스트: PostgreSqlFileserverReclamationIntegrationTest.

7. fs_cleanup_item.upload_id

staging 객체는 파일이 아니라 업로드로 가리킨다. 이 열이 없으면 큐에 넣은 staging 정리가 이미 게시된 content만 가리킬 수 있어서, 취소·만료된 업로드는 아무도 찾지 못하는 바이트를 남겼다. 같은 마이그레이션에서 더했고, 항목이 대상 정확히 하나를 가리키는지 check 제약을 둔다.

고정하는 테스트: PostgreSqlFileserverReclamationIntegrationTest.

8. ContentReferenceLedgerPort와 StagingUploadLocatorPort

고아 scan은 어떤 기록이 아직 물리 객체를 가리키는지 물어야 하고, 맞춰 보기는 파일을 마지막으로 staging한 업로드로 되짚어야 한다. 설계에 적힌 그대로의 FileMetadataPort나 UploadSessionPort로는 어느 질문에도 답할 수 없다. 설계가 고정한 interface를 넓히지 않고, 둘 다 메서드 하나짜리 좁은 port로 만들었다.

고정하는 테스트: PostgreSqlFileserverReclamationIntegrationTest, LocalOrphanScanTest.

해석

9. 할당량 정산은 범위 안에서 FIFO다

예약 행과 그것을 잡은 업로드를 잇는 것이 없다. 그리고 설계는 upload session에 예약 id를 끼워 넣지 않고 TTL과 STALE_QUOTA_RESERVATION cleanup 유형으로 남은 것을 회수한다. 그래서 QuotaCommitPort는 그 파일의 namespace에서 가장 오래된 살아 있는 예약을 정산한다.

어느 행이 닫히는지는 할당량 판단을 바꾸지 않는다. 강제는 범위별로 예약·확정 바이트를 합하고 행 하나하나는 읽지 않는다. 크기가 다른 동시 업로드는 예약 합계를 잠깐 높거나 낮게 남길 수 있고, 각각 정산되면서 맞춰진다. 뒤에 살아 있는 예약이 없는 확정 사용량(TTL보다 오래 걸린 업로드)도 기록한다. 조용히 덜 세는 ledger는 잠깐 부정확한 ledger보다 나쁘다.

고정하는 테스트: PostgreSqlFileserverReclamationIntegrationTest.

10. Zero copy는 파일 넘기기가 아니라 channel 전송이다

계획서 Task 22는 로컬 파일에 zero copy를 요구한다. 그런데 §19는 Path가 저장소 어댑터를 떠나는 것을 금하고, 계획서 §5는 content store에 Path를 더하는 것을 금한다. WebFlux의 zero-copy API는 Path를 받으므로 그 길은 닫혀 있다.

servlet 경로는 다른 길을 쓴다. ZeroCopyDownloadPort는 transport에서 WritableByteChannel을 받고, 저장소 어댑터가 그 안으로 FileChannel.transferTo를 한다. 파일 시스템 개념이 저장소를 떠나지 않는 진짜 kernel 수준 전송이다. reactive transport는 2026-09-25에 지웠다(support-matrix.md).

zero copy는 관측 가능한 차이가 없는 최적화다. 저장소가 거절하면 응답은 스트리밍되고 바이트는 똑같다.

고정하는 테스트: LocalStorageGatewayContractTest, ZeroCopyEligibilityTest.

11. Fileserver JPA 저장소는 capability 스위치 뒤에 있다

metadata 저장소, session 저장소, 할당량 서비스, 큐, ledger, staging locator는 adapter:outbound:persistence-fileserver leaf에 있다. 그 leaf의 auto-configuration root FileserverJpaPersistenceConfig가 @ConditionalOnProperty(app.fileserver-platform.enabled) 하나로 entity 스캔, Spring Data repository, 저장소 bean을 모두 가린다.

이 관문이 없으면 persistence 모듈을 포함한 조립 루트는 Fileserver를 쓰지 않아도 이 bean들을 만들고, 그 bean마다 Fileserver 설정만 주는 협력 객체가 필요하다. 설계가 transport 면에 대해 말한 규칙을 persistence에 적용한 것이다: 의존성이 있다는 이유만으로 면이 나타나지 않는다.

예전의 FileStateMachine bean은 지웠다. 상태 전이 검사는 FileState.canTransitionTo가 한다 (docs/capability-status.md 「제거된 코드」).

고정하는 테스트: FileserverPersistenceActivationTest(스캔이 스위치 뒤에 있음), FileserverRuntimeAssemblyTest(capability를 켬), FileStateTransitionTest(전이 표).

12. Transaction 경계는 애플리케이션 서비스가 갖고, 일부러 좁다

설계는 transaction이 어디서 시작하는지 말하지 않는다. 저장소가 말한다. adapter:outbound:persistence-jpa는 repository 어댑터가 @Transactional 경계를 갖는 것을 금하고, application-core가 TransactionPort로 경계를 가진다. Fileserver도 이 규칙을 따른다. 여기 있는 Jpa* 저장소는 자기 @Transactional을 선언하지 않는다.

이 capability에 특별한 것은 경계가 얼마나 좁은가다. 경계 하나는 이어진 metadata 쓰기를 덮고 저장소 호출 앞에서 늘 멈춘다. DB transaction 안의 파일 시스템 작업은 바이트 전송 시간 내내 connection을 잡기 때문이다. 그래서 업로드 경로의 경계는 하나가 아니라 셋이다: lease 잡기, 바이트 전송, offset 확정.

여러 저장소가 함께 맞아야 하는 곳은 경계 하나를 같이 쓴다.

단위 경계 하나인 이유
할당량 예약 + 기록 insert + session 생성 insert가 실패한 뒤 남은 예약은 존재한 적 없는 파일의 용량을 잡는다
READY 전이 + 할당량 확정 예약이 확정으로 바뀌지 않은 완료 파일은 예약이 만료될 때까지 용량을 잡는다
markDeleting + cleanup 큐 넣기 닿을 수 없게 됐는데 회수할 항목이 큐에 없는 파일은 영영 수거되지 않는다
content 삭제 정산: 회수 + 기록 내리기 + 큐 항목 닫기 절반만 되면 이미 없는 content를 대상으로 항목이 재시도된다

이렇게 해도 저장소/metadata 이음매 자체는 원자적으로 만들 수 없다. 어떤 DB 경계도 못 한다. 그 이음매 때문에 결과를 모르는 완료 경로와 맞춰 보기가 있다. 남은 손으로 쓴 보상 하나(기록이 확정된 뒤 staging 생성이 실패한 경우)도 같은 이유로 있다.

고정하는 테스트: 애플리케이션 테스트는 경계를 그 자리에서 돌리며 세는 DirectTransactions를 쓴다. 실제 PostgreSQL에서 조립 전체는 FileserverCompositionIntegrationTest(app-bootstrap integrationTest)가 돈다. 예전에 이 경계를 실제 PostgreSQL에서 고정하던 FileserverRoundTripContractTest는 지금 없다.

구현하지 않은 것

AsyncContentStore, CapacityAwareContentStore, CopyCapableContentStore, DelegatedDownloadStore

application-fileserver에 구현 없이 선언돼 있던 선택 content-store SPI 넷이다. 구현도 호출도 없어서 지웠다 (docs/capability-status.md 「제거된 코드」). 각각 이 템플릿이 내놓지 않는 backend를 위한 확장 지점이었다.

  • AsyncContentStore — native client가 non-blocking인 backend용. 로컬 플랫폼은 blocking이다.
  • CapacityAwareContentStore — 용량은 로컬 플랫폼이 구현하는 StorageHealthPort와 StorageUsagePort로 보고한다.
  • CopyCapableContentStore — 서버 쪽 copy는 CopyContentPort가 한다. 로컬 플랫폼에는 스트리밍 copy보다 싼 방법이 없다.
  • DelegatedDownloadStore — 위임은 transport 경계에서 nginx X-Accel-Redirect 전략이 한다. 저장소가 끼어들 필요가 없다.

ContentStoreCapabilities가 실행 중인 저장소가 실제로 지원하는 것을 보고한다. 그래서 구현하지 않은 것을 쓸 수 있다고 광고하지 않는다.

저장소의 애플리케이션 계층 계약

5. Fileserver 연산은 use case다 (해결됨, 소유자 결정 32)

transport가 닿는 모든 연산은 application.fileserver.port.in의 메서드 하나짜리 port 뒤에 있는 CommandUseCase나 QueryUseCase다.

  • 업로드: create, append, status, cancel, finalize, 요청 하나짜리 업로드
  • 다운로드: describe, prepare, open, transfer
  • delete, copy, move
  • management plane 연산 여덟

구현(*ApplicationUseCase)마다 @UseCaseCapability를 선언한다. 그래서 transaction 방식, repository 접근, 외부 호출을 검사하는 ArchUnit 규칙이 이제 Fileserver를 다른 기능과 똑같이 본다.

쓰기를 막는 권한은 둘이고, 둘 다 남는다.

검사 위치 정하는 것
@RequiresPermission("file:…") use case의 proxy. web 어댑터의 method security가 강제한다 호출자의 role이 그 연산을 아예 허락하는지
FileAccessPolicyPort use case 안, 부수 효과 전 등급(read/write/admin), 그리고 호출자가 자기 tenant에서 그 파일의 소유자인지

권한은 file:read(describe, 다운로드, 업로드 상태), file:upload(create, append, finalize, cancel, 요청 하나짜리 업로드), file:delete, file:copy, file:move, file:admin(모든 management plane 연산)이다. security.yml은 이 권한을 fileserver 자신의 기본 등급 role인 ROLE_FILE_READ, ROLE_FILE_WRITE, ROLE_FILE_ADMIN에 준다. 그래서 등급을 가진 호출자는 그 권한도 가진다. 등급 role 이름을 바꾸거나 다른 role 이름으로 자기 FileAccessPolicyPort를 주는 배포는 app.authz.role-permissions에도 그 이름을 대응시킨다. security.access-policy: unenforced는 등급과 소유 검사만 풀고 권한 관문은 절대 풀지 않는다.

이어 올리기 전송은 전송 pool에서 돌고, method security는 호출한 스레드의 security context를 읽는다. 그래서 BlockingTransferExecutor가 요청의 context를 worker로 옮긴다(BlockingTransferExecutorSecurityContextTest). 이것이 없으면 인증한 append가 익명으로 거부됐다.

use case가 아닌 것은 어떤 transport도 부르지 않는 것이다. CleanupService와 FileReconciliationService는 호출자 신원이 없는 백그라운드 worker가 돌린다. 상태를 바꾸는 use case는 scheduler가 가질 수 없는 권한을 선언해야 한다. FileserverUseCaseContractDeviationTest가 그 목록을 고정한다.

FileserverErrorCode의 HTTP 상태 어휘는 애플리케이션 계층에 남는다. 이 절이 예전에 든 이유 그대로다: servlet transport와 Nginx 위임 경로가 같은 실패에 다른 상태로 답하면 안 된다.