Java で Rclone を使って Cloudflare R2 からファイルをインポート
Java の ProcessBuilder で rclone copy を実行し、rclone が正常終了した場合にのみ、ダウンロードしたディレクトリを公開します。以下の例では、Cloudflare R2 の非公開プレフィックスをインポートし、階層化されたファイル名を保持します。転送に失敗した場合や制限時間を超えた場合は、失敗を示す終了ステータスを返します。
バケットとツールの準備
この手順は、OpenJDK 21 と UTF-8 ロケールを使用する Linux アプリケーションを対象としています。OpenJDK 21.0.12.1 と rclone 1.75.2 でテストしました。JDK はメンテナンスされている更新版を使用してください。テストしたパッチ版が必須の最低バージョンというわけではありません。rclone は独立した実行可能ファイルで、インストールガイドから入手できます。Java の依存ライブラリやビルドツールは不要です。
ダウンロードするファイルを格納した既存の R2 バケットが必要です。インポート中は対象のプレフィックスを変更しないでください。変更中のバケットをコピーしても、ある時点のスナップショットにはなりません。それぞれ異なる Linux ファイルパスに対応するキーを使用してください。空のパスセグメント、. や .. のパスセグメント、ファイルとディレクトリの衝突、ファイルシステムで表現できない名前は使用できません。スペース、階層化されたパス、Unicode、ゼロバイトのファイルに対応しています。任意のオブジェクトキーが、有効なファイルシステムのパスになるとは限りません。
Java を起動するシェルで、必要な各実行可能ファイルを確認します。
command -v java >/dev/null &&
command -v javac >/dev/null &&
command -v rclone >/dev/null &&
java -version && javac -version && rclone version
以下のコマンドでは C.UTF-8 を選択するため、このロケールがインストールされている必要があります。所有権があり、書き込み可能なディレクトリで作業してください。ダウンロード先の親ディレクトリは既に存在し、ディレクトリ名のアトミックな変更に対応し、ダウンロード全体を格納できる空き容量が必要です。その親ディレクトリを排他的に制御し、インポーターは一度に一つだけ実行してください。
非公開 R2 リモートの設定
バケットを対象範囲とし、Object Read only 権限を持つ R2 トークンの Access Key ID と Secret Access Key を取得してください。この権限には、S3 互換 API によるオブジェクトの読み取りと一覧取得が含まれます。インポーターにリモートオブジェクトの作成や削除の権限は不要です。Cloudflare の R2 認証ガイドを参照してください。
テキストエディターで、以下を作業ディレクトリの r2-import.conf として保存します。三つのプレースホルダーを認証情報とアカウント ID に置き換えてください。このエンドポイントはデフォルトの管轄区域にあるバケット用です。該当する場合は、バケットの管轄区域に固有のエンドポイントを使用してください。
[cloudflare_r2]
type = s3
provider = Cloudflare
access_key_id = YOUR_ACCESS_KEY_ID
secret_access_key = YOUR_SECRET_ACCESS_KEY
endpoint = https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
region = auto
no_check_bucket = true
このファイルへのアクセスを制限します。
chmod 600 ./r2-import.conf
Java プログラムは --config でこのファイルを明示的に渡すため、rclone の通常の設定場所には依存しません。no_check_bucket は、オブジェクト権限を持つトークンに関する
Cloudflare の rclone 設定ガイドに従っています。このファイルをコミットしたり、認証情報をコマンドの引数に貼り付けたりしないでください。子プロセスが継承する RCLONE_* 変数は削除します。これにより、グローバルなドライランなどの設定によって、気付かないうちに別の処理として実行されることを防ぎます。
Java インポーターの保存
以下のファイル全体を RcloneImporter.java として保存します。引数は、rclone の実行可能ファイル、設定ファイル、リモートプレフィックス、新しいダウンロード先ディレクトリ、転送全体のタイムアウト(秒)です。任意の実行可能ファイルのパスやリモートをユーザーから受け付けるのではなく、信頼できるアプリケーション設定を渡してください。
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.Path;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.StandardCopyOption;
import java.nio.file.attribute.BasicFileAttributes;
import java.time.Duration;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicReference;
public class RcloneImporter {
private static final int DIAGNOSTIC_BYTES = 8192;
private static void runRclone(ProcessBuilder builder, Duration timeout)
throws IOException, InterruptedException {
Process process = builder.redirectErrorStream(true).start();
var diagnostics = new ByteArrayOutputStream();
var readFailure = new AtomicReference<IOException>();
Thread drain = Thread.ofVirtual().start(() -> {
try (var input = process.getInputStream()) {
byte[] buffer = new byte[4096];
int count;
while ((count = input.read(buffer)) != -1) {
int kept = Math.min(count, DIAGNOSTIC_BYTES - diagnostics.size());
if (kept > 0) diagnostics.write(buffer, 0, kept);
}
} catch (IOException error) {
readFailure.set(error);
}
});
try {
if (!process.waitFor(timeout.toMillis(), TimeUnit.MILLISECONDS)) {
throw new IOException("rclone timed out after " + timeout);
}
drain.join();
if (readFailure.get() != null) throw readFailure.get();
System.err.print(diagnostics.toString(StandardCharsets.UTF_8));
if (process.exitValue() != 0) {
throw new IOException("rclone exited with code " + process.exitValue());
}
} finally {
// Reap the direct rclone child before deleting anything it might still be writing.
process.destroyForcibly();
boolean interrupted = false;
while (process.isAlive() || drain.isAlive()) {
try {
process.waitFor();
drain.join();
} catch (InterruptedException error) {
interrupted = true;
}
}
if (interrupted) Thread.currentThread().interrupt();
}
}
private static void removeStaging(Path staging) throws IOException {
Files.walkFileTree(staging, new SimpleFileVisitor<Path>() {
@Override
public FileVisitResult visitFile(Path file, BasicFileAttributes attributes)
throws IOException {
Files.delete(file);
return FileVisitResult.CONTINUE;
}
@Override
public FileVisitResult postVisitDirectory(Path directory, IOException error)
throws IOException {
if (error != null) throw error;
Files.delete(directory);
return FileVisitResult.CONTINUE;
}
});
}
public static void importFiles(Path executable, Path config, String source, Path destination,
Duration timeout) throws IOException, InterruptedException {
if (!Files.isExecutable(executable) || !Files.isRegularFile(config)) {
throw new IOException("Check the rclone executable and configuration file");
}
if (!source.startsWith("cloudflare_r2:") || !source.endsWith("/")) {
throw new IllegalArgumentException("Use cloudflare_r2:bucket/prefix/ as the source");
}
if (timeout.isNegative() || timeout.isZero() || timeout.compareTo(Duration.ofDays(1)) > 0) {
throw new IllegalArgumentException("Timeout must be between 1 and 86400 seconds");
}
Path name = destination.getFileName();
if (name == null || name.toString().equals(".") || name.toString().equals("..")) {
throw new IllegalArgumentException("Choose a new destination directory name");
}
Path target = destination.toAbsolutePath();
if (Files.exists(target, LinkOption.NOFOLLOW_LINKS)) {
throw new IOException("Destination already exists; choose a new directory");
}
Path staging = Files.createTempDirectory(target.getParent(), ".r2-import-");
boolean published = false;
try {
ProcessBuilder builder = new ProcessBuilder(executable.toAbsolutePath().toString(),
"--config", config.toAbsolutePath().toString(), "copy",
"--", source, staging.toString());
builder.environment().keySet().removeIf(key -> key.startsWith("RCLONE_"));
runRclone(builder, timeout);
if (Thread.currentThread().isInterrupted()) throw new InterruptedException();
Files.move(staging, target, StandardCopyOption.ATOMIC_MOVE);
published = true;
} finally {
if (!published) removeStaging(staging);
}
}
public static void main(String[] args) {
if (args.length != 5) {
System.err.println("Usage: java RcloneImporter RCLONE CONFIG REMOTE DEST SECONDS");
System.exit(2);
}
try {
importFiles(Path.of(args[0]), Path.of(args[1]), args[2], Path.of(args[3]),
Duration.ofSeconds(Long.parseLong(args[4])));
System.out.println("Import complete: " + args[3]);
} catch (InterruptedException error) {
Thread.currentThread().interrupt();
System.err.println("Import interrupted; destination was not published");
System.exit(130);
} catch (IOException | IllegalArgumentException error) {
System.err.println("Import failed: " + error.getMessage());
System.exit(1);
}
}
}
子プロセスの両出力ストリームは、一つのパイプに送られます。別の仮想スレッドがそのパイプを読み取り続け、ターミナルでの診断用に先頭の 8 KiB だけを保持します。これにより、rclone の出力がパイプの容量を超えても、呼び出し元のスレッドで転送の制限時間を適用できます。サブプロセスの出力がブロックされるリスクについては、Java の
Process のドキュメントで説明されています。
ステージングディレクトリは、最終的なダウンロード先と同じ親ディレクトリ内に作成します。rclone が終了コードゼロで終了すると、Java はアトミックな移動を要求します。ファイルシステムが対応していない場合、インポートは失敗します。アトミックな移動は上書きを防ぐロックではありません。存在確認と別の書き込み処理が競合し得るため、この例では排他的なアクセスを必須としています。
コンパイルとプレフィックスのインポート
/absolute/path/to/rclone を先ほど確認した実行可能ファイルに置き換え、使用するバケットとプレフィックスを指定してください。パスを囲む引用符は残します。コンパイルに失敗したときに古いクラスファイルが起動されないよう、二つのコマンドをまとめて実行してください。
javac -proc:none -encoding UTF-8 RcloneImporter.java &&
LC_ALL=C.UTF-8 java -cp . RcloneImporter /absolute/path/to/rclone ./r2-import.conf \
'cloudflare_r2:my-data-bucket/source-files/' ./downloaded-files 600
成功すると、プログラムは Import complete: ./downloaded-files を出力し、終了コードゼロで終了します。source-files/reports/July résumé.txt のようなオブジェクトは downloaded-files/reports/July résumé.txt になります。copy はプレフィックスの内容をコピーし、source-files を追加のディレクトリとして作成しません。リモートのオブジェクトは削除しません。
600 秒の制限時間には rclone の再試行も含まれるため、低速な接続では、有効なファイルでも制限時間を超える場合があります。タイムアウト時は、直接の子プロセスである rclone を強制終了して終了を待ち、今回の実行用のステージングディレクトリを削除します。最終的なダウンロード先は作成されません。最大 86,400 秒までの、より長いタイムアウトを指定し、失敗したプロセスが終了してから同じダウンロード先で再試行してください。シンボリックリンクを含め、既存のダウンロード先は拒否されます。別のインポート結果を保存するには、新しい名前を使用してください。
インポート失敗時の診断
- 子プロセスの終了: 容量制限付きのターミナル診断出力を読み、選択した設定ファイル、トークンのバケット対象範囲、エンドポイント、外向きの HTTPS アクセスを確認してください。リクエストの失敗はエラーであり、空のダウンロードの成功ではありません。
- ファイルがない場合: 空のプレフィックスや存在しないプレフィックスは、空のディレクトリとして正常にコピーされる場合があります。使用する前にプレフィックスを確認し、結果を調べてください。終了コードゼロは、特定のオブジェクトが存在した証明にはなりません。必要な場合は、想定されるファイル一覧や公開元のチェックサムを別途保持してください。
- 割り込み:
importFilesを呼び出すアプリケーションは、待機中の Java スレッドに割り込めます。このメソッドは子プロセスを停止し、ステージング領域をクリーンアップしてからInterruptedExceptionを伝播します。割り込みフラグの復元は呼び出し元の責任です。これは JVM の強制終了とは異なります。 - 突然の終了: 電源断、
kill -9、JVM の終了により、.r2-import-*ディレクトリや孤立した子プロセスが残る場合があります。残っている子プロセスを停止してから、該当する実行のステージングディレクトリだけを削除してください。これらのディレクトリは未完了の作業領域であり、最終的なダウンロード先ではありません。ファイルシステムの権限や可用性が変わると、クリーンアップも失敗する場合があります。
インポートの実行場所の選択
この方法は、既に rclone を使用しており、処理前にローカルファイルが必要な Java サービスに適しています。ホスト型の Transloadit ワークフローにファイルを取り込む場合は、Cloudflare Import Robotと Java SDKを参照してください。
