Files
clean-architecture-backend-…/docs/fileserver/design-deviations.md
T
DongHyeonka 2d274a6842
pr / done (pull_request) Canceled after 0s
refactor(application)!: 시스템 쓰기와 운영자 연산을 유스케이스 계약 안으로 옮긴다
시스템이 부르는 쓰기가 유스케이스 계약 밖에 있다. 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을 던진다.
2026-11-13 16:37:03 +09:00

209 lines
14 KiB
Markdown

# 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](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가 익명으로 거부됐다.
백그라운드 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 위임 경로가 같은 실패에 다른 상태로 답하면 안 된다.