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 しません。

プロセスのクラッシュで orphan temporary file が残ることがありますが logical visibility は変わらず、起動時にも自動削除しません。

Durability と concurrency の限界

atomic visibility は fsync や power-loss durability の保証ではありません。adapter は directory と file metadata を stable storage に force しません。

同時 put に対する lost-update prevention、JVM lock、distributed lock、version history、MVCC、CAS、ETag は提供しません。

順序は DocumentStore.put の後に IndexStore.upsert、DocumentStore.delete の後に IndexStore.delete です。2段目の失敗は Consistency 文書の意味になります。