문제: 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개가 번역 전과 같음).
74 lines
3.7 KiB
Markdown
74 lines
3.7 KiB
Markdown
# 저장소 인증
|
|
|
|
## 인증이 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를 다시 쓰는 저장소도 이것을 상속한다.
|