R2 DocumentStore

R2DocumentStore is the authoritative document store backed by Cloudflare R2 through an AWS SDK v2 S3AsyncClient. It stores complete serialized documents; it does not filter document content.

Dependency and construction

The R2 adapter is part of dev.nexcraft:r2d1:

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

The configuration constructor validates an HTTPS origin, non-blank credentials, bucket, and region. The four-argument form uses the R2 signing region auto:

import dev.nexcraft.r2d1.r2.R2Config;
import dev.nexcraft.r2d1.r2.R2DocumentStore;
import java.net.URI;

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

R2DocumentStore documents = new R2DocumentStore(config);

The values in this example are placeholders. Keep access keys outside source control and supply them through the application’s secret configuration.

Client ownership

new R2DocumentStore(R2Config) creates and owns its asynchronous client. Closing the store closes that client. When the application already owns an S3AsyncClient, use the second constructor:

R2DocumentStore documents = new R2DocumentStore(applicationS3Client, bucketName);

Closing this store does not close the caller-owned client. The adapter does not create an R2D1 executor, scheduler, virtual thread, retry policy, or timeout policy.

Operations

The adapter implements the asynchronous DocumentStore SPI:

• put writes the serialized bytes to the encoded collection and document key;
• get reads one object and maps a missing object to DocumentNotFoundException;
• delete is idempotent when the object is already absent; and
• list uses bounded S3-compatible pagination and returns an adapter-owned opaque cursor.

The collection facade coordinates these stages with the IndexStore. A successful R2 write is the authoritative first stage of put; a failed following index update is reported as PersistenceException.PartialFailure.

Endpoint and credential handling

R2Config.toString() redacts endpoint, bucket, access key, and secret values. The adapter also avoids placing credentials in generated messages. The endpoint must be an HTTPS origin without a path, query, fragment, or user information.

For a complete collection setup, continue with Getting Started and choose an IndexStore.