# 저장소 인증 ## 인증이 volume마다인 이유 원자적 rename, 같은 파일 저장소 보장, symlink 거부는 「Kubernetes」나 「PVC」의 성질이 아니라 특정 mount 뒤의 특정 파일 시스템의 성질이다. CSI driver, StorageClass, 접근 모드, backend, mount 옵션 중 하나만 바꿔도 그중 무엇이든 달라질 수 있다. 다섯을 모두 적지 않은 인증은 다른 곳으로 옮길 수 없다. ## 인증하는 것 | 성질 | 중요한 이유 | |---|---| | staging과 content가 같은 파일 저장소 | 저장소를 넘는 rename은 복사라서 게시가 원자적이지 않게 된다. | | 원자적 rename | 게시 경로의 기본 전략이다. | | 원자적 생성(`O_EXCL`) | 게시를 조용한 덮어쓰기가 아니라 새로 만들기만 하게 한다. | | symlink 거부 | 바뀐 부모 폴더가 쓰기를 root 밖으로 돌리는 것을 막는다. | | 범위 읽기 | 다운로드 계약이 기댄다. | ## 인증 돌리기 이 repo는 인증 job 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 배포하는 쪽이 대상 volume을 저장 루트(`/var/lib/backend/files`)에 마운트한 일회성 pod에서 아래를 차례로 확인한다. 1. `staging`과 `content` 폴더를 만들고, `staging`의 파일을 `content`로 `mv`해 원자적 rename이 되는지 본다. 2. 두 폴더의 장치 번호(`stat -c %d`)가 같은지 본다. 다르면 rename이 복사가 된다. 3. `set -o noclobber` 상태에서 같은 파일을 두 번 만들어 `O_EXCL` 생성이 막히는지 본다. 4. 결과와 함께 묶음(Kubernetes 버전, CSI driver, StorageClass, 접근 모드, backend, mount 옵션)을 기록한다. 결과는 묶음 전체를 담은 기계가 읽는 형식으로 그 volume에 남긴다: ```json { "kubernetesVersion": "...", "csiDriver": "...", "storageClass": "...", "accessMode": "ReadWriteOnce", "backend": "ext2/ext3", "mountOptions": "rw,relatime", "atomicMove": true, "sameFileStore": true, "atomicCreate": true } ``` 2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다. ## 네트워크 파일 시스템 ```bash docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test ``` mount는 일부러 `hard`다. `soft` mount는 느린 서버를 짧게 끝난 쓰기로 바꾼다. 이 설계가 받아들이지 않는 바로 그 손상이다. ## 시작 때 강제 `FileserverStartupValidator`가 부팅 때 probe를 다시 돌리고, 필수 capability가 없으면 요청을 받지 않는다. 원자적 move를 증명하지 못하는 파일 시스템에 `ATOMIC_MOVE_REQUIRED`를 두면 조용히 기능을 줄이지 않고 닫힌 쪽으로 실패한다. ## 새 저장소 더하기 실행되는 계약 둘을 통과해야 한다. 글로 쓴 호환 주장은 받지 않는다. - `UploadStoragePortContract` — 애플리케이션 port의 계약이다. `application-fileserver` testFixtures에 있다 (`testImplementation testFixtures(project(':application-fileserver'))`). 애플리케이션의 `FakeUploadStorageGateway`도 이것을 상속한다. 그래서 use case 테스트와 실제 저장소가 같은 offset, chunk checksum, 크기 상한 규칙을 지킨다(0바이트로 선언한 업로드는 첫 바이트를 거부한다). - `ContentStoreContract` — 로컬 어댑터의 내부 `BlockingContentStore` SPI 계약이다. 이 어댑터의 테스트에 있다. 그 SPI는 일부러 어댑터 안에 둔다(리뷰 S1-#12: 애플리케이션은 그것을 부르지 않는다). 그래서 계약도 어댑터에 있다. 그 SPI를 다시 쓰는 저장소도 이것을 상속한다.