R2D1 / 文档

Filesystem DocumentStore

FileSystemDocumentStore 是 framework-neutral DocumentStore，在应用提供的 executor 上执行 blocking filesystem operation。canonical document 保存在本地文件中。

依赖与创建

传入 root directory 和用于 blocking I/O 的 executor。adapter 不会创建或关闭 executor，使用结束后由调用方停止它。

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

创建示例

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

磁盘布局

collection 名称和 document identifier 会编码为 UTF-8 path segment。list 只将 canonical .json 文件识别为 document。

temporary file、orphan temporary file、symlink 和 unrelated file 都不是 document。
没有 canonical file 时，get 返回 DocumentNotFoundException。
删除不存在的文件是 idempotent。

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

Atomic replacement

put 将完整 bytes 写入 collection directory 中的唯一 temporary file，关闭后使用 ATOMIC_MOVE + REPLACE_EXISTING 发布。如果 provider 不支持 atomic replace，则以 StorageException.Operation 失败，不会退化为 delete-then-move。

进程崩溃可能留下 orphan temporary file，但不会改变 logical visibility，启动时也不会自动清理。

Durability 与 concurrency 边界

atomic visibility 不是 fsync 或 power-loss durability 保证。adapter 不会将 directory 或 file metadata 强制写入稳定存储。

并发 put 不提供 lost-update prevention、JVM lock、distributed lock、version history、MVCC、CAS 或 ETag。

顺序是 DocumentStore.put 后 IndexStore.upsert、DocumentStore.delete 后 IndexStore.delete；第二阶段失败的语义见 Consistency 文档。