문제: 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개가 번역 전과 같음).
202 lines
13 KiB
Markdown
202 lines
13 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가 익명으로 거부됐다.
|
|
|
|
use case가 아닌 것은 어떤 transport도 부르지 않는 것이다. `CleanupService`와 `FileReconciliationService`는
|
|
호출자 신원이 없는 백그라운드 worker가 돌린다. 상태를 바꾸는 use case는 scheduler가 가질 수 없는 권한을
|
|
선언해야 한다. `FileserverUseCaseContractDeviationTest`가 그 목록을 고정한다.
|
|
|
|
`FileserverErrorCode`의 HTTP 상태 어휘는 애플리케이션 계층에 남는다. 이 절이 예전에 든 이유 그대로다:
|
|
servlet transport와 Nginx 위임 경로가 같은 실패에 다른 상태로 답하면 안 된다.
|