R2D1 / 文档

R2 DocumentStore

R2DocumentStore 是使用 Cloudflare R2 作为 authoritative DocumentStore 的实现。完整 document bytes 保存在 R2，indexed query 的 projection 保存在所选 IndexStore。

依赖与创建

R2 adapter 包含在 dev.nexcraft:r2d1 中。配置 constructor 会验证 HTTPS origin、credential、bucket 和 region。四参数形式使用 signing region auto。

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

R2Config

下面的值是 placeholder。请将 access key 和 secret 放在 source control 之外的 secret configuration 中。

R2Config config =
    new R2Config(
        URI.create("https://<account-id>.r2.cloudflarestorage.com"),
        accessKeyId,
        secretAccessKey,
        bucketName);

R2DocumentStore documents = new R2DocumentStore(config);

异步客户端所有权

new R2DocumentStore(R2Config) 会创建并拥有 asynchronous client。关闭 store 会关闭该 client。

如果应用已经拥有 S3AsyncClient，请使用第二个 constructor。此时关闭 R2DocumentStore 不会关闭 caller-owned client。

adapter 不会额外创建 R2D1 executor、scheduler、virtual thread、retry policy 或 timeout policy。

操作与失败

R2 write 成功后 index update 失败时，collection facade 报告 PersistenceException.PartialFailure。

put 将 serialized bytes 写入 encoded collection/document key。
get 将 missing object 映射为 DocumentNotFoundException。
delete 在 object 已不存在时仍是 idempotent。
list 使用 bounded S3-compatible pagination 和 adapter-owned opaque cursor。

Endpoint 与 credential

endpoint 必须是没有 path、query、fragment 或 user information 的 HTTPS origin。R2Config.toString() 会隐藏 endpoint、bucket、access key 和 secret。