R2D1 / 문서

Filesystem DocumentStore

FileSystemDocumentStore는 애플리케이션이 제공한 executor에서 blocking filesystem operation을 실행하는 framework-neutral DocumentStore입니다. canonical document는 로컬 파일에 보관됩니다.

의존성과 생성

root directory와 blocking I/O용 executor를 전달합니다. adapter는 executor를 만들거나 닫지 않으므로 사용이 끝난 뒤 caller가 중지해야 합니다.

implementation("dev.nexcraft:r2d1-filesystem:<version>")

생성 예시

ExecutorService filesystemExecutor = Executors.newFixedThreadPool(4);
FileSystemDocumentStore documents =
    new FileSystemDocumentStore(
        Path.of("/var/lib/my-app/r2d1"), filesystemExecutor);

디스크 layout

collection 이름과 document identifier는 UTF-8 path segment로 encode됩니다. list는 canonical .json 파일만 document로 인식합니다.

temporary file, orphan temporary file, symlink, unrelated file은 document가 아닙니다.
canonical file이 없으면 get은 DocumentNotFoundException을 반환합니다.
없는 파일을 delete하는 것은 idempotent합니다.

<root>/<encoded-collection>/<encoded-document-id>.json

Atomic replacement

put은 collection directory 안의 고유 temporary file에 전체 bytes를 쓰고 닫은 다음 ATOMIC_MOVE + REPLACE_EXISTING으로 publish합니다. provider가 atomic replace를 지원하지 않으면 StorageException.Operation으로 실패하며 delete-then-move로 fallback하지 않습니다.

process crash 뒤 orphan temporary file이 남을 수 있지만 logical visibility는 바뀌지 않습니다. startup 때 자동 제거하지 않습니다.

Durability와 concurrency 한계

atomic visibility는 fsync나 power-loss durability 보장이 아닙니다. directory와 file metadata를 stable storage로 force하지 않습니다.

동시 put에는 lost-update 방지, JVM lock, distributed lock, version history, MVCC, CAS, ETag가 제공되지 않습니다.

DocumentStore.put 뒤 IndexStore.upsert, DocumentStore.delete 뒤 IndexStore.delete 순서를 따르며, 두 번째 단계 실패 의미는 Consistency 문서와 같습니다.