시스템이 부르는 쓰기가 유스케이스 계약 밖에 있다. fileserver 정리·맞추기, 알림 claim·발송·lease 회복·맞추기·provider event replay는 capability도 트랜잭션 선언도 없는 서비스를 worker가 바로 부르고, 그 worker와 조립은 outbound adapter 안에 있다. 알림 운영자 연산 넷은 permission 없이 서비스 하나에 모여 있고 재시도 시각은 상수다. web stream bridge는 outbound가 구현한 replay 포트를 바로 읽는다. fileserver 관리 HTTP 기본값은 controller가 정한다. 고른 방법: 시스템 쓰기는 @SystemInvoked 유스케이스로 나누고 composition worker 설정이 new로 만든다(bean 아님). 알림 worker와 fileserver 정리 조립은 composition으로 옮기고, 맞추기의 재시도·포기 시점은 유스케이스가 정한다. 운영자 연산은 platform.admin의 유스케이스 클래스 넷과 notification-admin:* permission이다(port.in 인터페이스는 port.in과 admin의 cycle을 만들어 두지 않는다). replay 읽기는 조회 유스케이스 둘을 거치고 포트는 LiveEventReplayQueryPort로 이름을 바꾼다. 아키텍처 규칙 둘: 사용자 전송은 저장·id 포트를 쥐지 못하고, inbound는 application 서비스·coordinator를 interface로도 쥐지 못한다. 재시도 시각은 설정, 관리 기본값은 command 팩터리다. 재시도 시각의 규칙은 policy의 값 RetryTiming 하나가 갖고 설정은 그 값을 만든다. retry·routing 값들은 서버가 만드는 값이라 잘못된 값을 IllegalStateException으로 거절한다(manual 06). 모듈 기본값이 role notification-admin에 운영자 permission 넷을 준다(fileserver의 ROLE_FILE_ADMIN과 같다). 버린 대안: 서비스에 @UseCaseCapability만 달기(사용자와 시스템이 같은 진입점을 나눠 써서 권한 규칙이 막지 못한다), 운영자 서비스 삭제, 설정에서 policy를 만들어 버리며 검증하기(규칙이 바뀐 policy bean과 상관없이 남는다). 위험·한계: 공개 타입·생성자·bean 이름·아키텍처 규칙이 바뀐다. 파생 서비스가 할 일은 docs/upgrade/2026-11-round9-application.md 1~3·5·6행이다. claim·fence 커밋 위에 쌓았다. 검증: PR 본문의 desktop 결과. Refs: RR9-05-06, RR9-05-07, RR9-05-08, RR9-05-10, RR9-05-19 BREAKING CHANGE: NotificationAdminService·NotificationAdminApplicationService가 없어지고 운영자 연산은 platform.admin의 RedriveDeliveryUseCase 등이다(permission notification-admin:*). 알림 worker가 composition:notification-platform으로 옮기고 ReconciliationJobWorker·ProviderEventReplayWorker는 유스케이스가 됐다. MessagingReplayBridge 생성자가 조회 유스케이스를 받고 LiveEventReplayPort는 LiveEventReplayQueryPort다. 사용자 전송이 저장·id 포트나 application 서비스 interface를 쥐면 architectureTest가 실패한다. 운영자 요청 record 이름이 *Request로 바뀌고 DefaultNotificationRetryPolicy 생성자가 RetryTiming을 받는다. RetryBackoff·RetryBudget·RetryContext·RetryDecision.RetryAfter·RouteCandidate·RoutingContext·RoutingDecision·EligibilityResult가 잘못된 값에 IllegalStateException을 던진다.
14 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 경계에서 nginxX-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가 익명으로 거부됐다.
백그라운드 worker가 하는 쓰기도 use case다. 다만 사용자 것과 따로다. FileserverCleanupWorker는 호출자 신원이 없는
scheduler 스레드에서 돌므로 @SystemInvoked use case 둘(RunScheduledCleanupUseCase,
ReconcileRecoverableFilesUseCase)을 new로 만들어 쥔다. bean이 아니어서 transport가 닿지 못한다. 운영자가 같은
cleanup을 돌리는 길은 file:admin을 선언한 CleanupUploadsUseCase다(2026-11-13).
use case가 아닌 것은 그 use case들이 쥔 협력 객체다. CleanupService(DefaultCleanupService),
FileReconciliationService(DefaultFileReconciliationService), WriterLeaseCoordinator다. 이 서비스들은
composition:fileserver-platform이 bean으로 조립한다. 권한 검사 없이 쓰는 bean이라, inbound adapter가 interface로라도
쥐면 INBOUND_ADAPTERS_DEPEND_ON_PORTS_NOT_APPLICATION_SERVICES가 빌드를 실패시킨다(2026-11-13부터 interface와
coordinator도 본다). FileserverUseCaseContractDeviationTest가 그 목록을 고정한다.
FileserverErrorCode의 HTTP 상태 어휘는 애플리케이션 계층에 남는다. 이 절이 예전에 든 이유 그대로다:
servlet transport와 Nginx 위임 경로가 같은 실패에 다른 상태로 답하면 안 된다.