Scala と AWS SDK で Cloudflare R2 にファイルをエクスポート
AWS SDK for Java v2 を使い、Scala アプリケーションで処理済みのローカルファイルを非公開の Cloudflare R2 バケットにエクスポートします。この例では、同期、非同期、FS2 ストリーミング、並列アップロードの各モードを備えたひとつのコマンドラインプログラムと、保存されたバイト列を確認する方法を紹介します。
Cloudflare R2 を選ぶ理由は?
R2 の S3 互換 API により、Scala コードから Java SDK のリクエスト署名と HTTP クライアントを利用できます。この例では、標準のアカウントエンドポイントで、管轄区域の制限がないバケットを対象にします。管轄区域を指定したバケットには、対応するエンドポイントが必要です。
Scala プロジェクトのセットアップ
この構成は、sbt 1.x を使う既存の Scala 2.13 アプリケーションを対象としています。検証済みの固定バージョンは、Scala 2.13.18、sbt 1.13.0、Cats Effect 3.7.1、FS2 3.14.0、AWS SDK 2.56.0 です。Scala 3 と sbt 2 への移行は別途検討する選択肢です。ここではバージョンを固定し、例を Scala 2.13 系のビルドに保ちます。
Bash、cURL、および保守されている OpenJDK 21 環境を用意し、java を PATH に配置してください。検証済みの JDK パッチバージョンは 21.0.12.1 です。利用する JDK ディストリビューターが提供する
21 系の最新セキュリティ更新を適用してください。Scala コンパイラーや sbt コマンドを別途インストールする必要はありません。書き込み可能なディレクトリで次のコマンドを実行して、新しいプロジェクトを作成してください。サブシェルを使うため、現在のディレクトリは変わりません。
(
set -eu
command -v java >/dev/null
command -v curl >/dev/null
java -version
mkdir r2-scala
cd r2-scala
mkdir -p project src/main/scala
curl -fsSLo sbt-launch.jar https://repo.maven.apache.org/maven2/org/scala-sbt/sbt-launch/1.13.0/sbt-launch-1.13.0.jar
)
r2-scala が存在するため作成に失敗した場合は、別の親ディレクトリを選んでください。ダウンロードに失敗した場合は、プロジェクトを残し、その中で cURL コマンドだけを再実行してください。次のファイルを r2-scala に保存してください。ランチャーのバージョン固定には project/build.properties を使います。
sbt.version=1.13.0
build.sbt を保存してください。
scalaVersion := "2.13.18"
libraryDependencies ++= Seq(
"software.amazon.awssdk" % "s3" % "2.56.0",
"software.amazon.awssdk" % "netty-nio-client" % "2.56.0",
"software.amazon.awssdk" % "apache-client" % "2.56.0",
"org.typelevel" %% "cats-effect" % "3.7.1",
"co.fs2" %% "fs2-io" % "3.14.0",
"co.fs2" %% "fs2-reactive-streams" % "3.14.0"
)
Compile / run / fork := true
AWS SDK クライアントの設定
バケットを作成し、そのバケットに範囲を限定した、オブジェクトの読み取りと書き込み権限を持つ
R2 S3 認証情報を作成してください。プログラムを実行する前に、プロセスの環境変数で R2_ACCOUNT_ID、R2_ACCESS_KEY_ID、R2_SECRET_ACCESS_KEY、R2_BUCKET を指定してください。シークレットマネージャーまたはターミナルの環境変数設定を使い、認証情報を
Scala ファイルやコマンド引数に記述しないでください。バケットは非公開のままとし、事前に作成しておく必要があります。
クライアントは、Cloudflare の Java 設定に従い、リージョン auto、パス形式のアドレス指定、チャンクエンコーディングの無効化を使用します。WHEN_REQUIRED は、SDK の任意のリクエストチェックサムを無効にします。プログラムでは、同期 HTTP に Apache、非同期 HTTP に Netty を選択し、Cats Effect の Resource で各クライアントを閉じます。
基本的な同期アップロード
単純なブロッキング PUT には sync を選んでください。Cats Effect のブロッキングプール上で RequestBody.fromFile を通じてファイルを読み取ります。キャンセル時は、ブロッキング呼び出しが戻るかタイムアウトするまで待機します。基になる Future のキャンセルが必要な場合は、async または fs2 を選んでください。
Cats Effect による非同期アップロード
次の完全なプログラムを src/main/scala/R2Upload.scala として保存してください。async は SDK のファイルボディを使い、fs2 は Reactive Streams のパブリッシャーを提供します。どちらも Cats Effect の CompletableFuture ブリッジを介して待機します。このブリッジは、ファイバーがキャンセルされると Future のキャンセルを要求します。
import cats.effect.{ExitCode, IO, IOApp, Resource}
import cats.effect.implicits._
import cats.syntax.all._
import fs2.interop.reactivestreams._
import fs2.io.file.{Files, Flags, Path}
import java.io.InputStream
import java.net.URI
import java.nio.ByteBuffer
import java.security.MessageDigest
import java.time.Duration
import java.util.Optional
import org.reactivestreams.Subscriber
import software.amazon.awssdk.auth.credentials.{AwsBasicCredentials, StaticCredentialsProvider}
import software.amazon.awssdk.core.async.AsyncRequestBody
import software.amazon.awssdk.core.checksums.RequestChecksumCalculation
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration
import software.amazon.awssdk.core.sync.RequestBody
import software.amazon.awssdk.http.apache.ApacheHttpClient
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient
import software.amazon.awssdk.regions.Region
import software.amazon.awssdk.retries.StandardRetryStrategy
import software.amazon.awssdk.services.s3.{S3AsyncClient, S3Client, S3Configuration}
import software.amazon.awssdk.services.s3.model.{GetObjectRequest, PutObjectRequest, PutObjectResponse, S3Exception}
object R2Upload extends IOApp {
final case class Config(endpoint: URI, accessKey: String, secretKey: String, bucket: String)
final case class Task(path: Path, key: String)
private val service = S3Configuration.builder()
.pathStyleAccessEnabled(true)
.chunkedEncodingEnabled(false)
.build()
private def overrides: ClientOverrideConfiguration =
ClientOverrideConfiguration.builder()
.apiCallTimeout(Duration.ofMinutes(2))
.apiCallAttemptTimeout(Duration.ofSeconds(45))
.retryStrategy(StandardRetryStrategy.builder().maxAttempts(3).build())
.build()
private def credentials(config: Config): StaticCredentialsProvider =
StaticCredentialsProvider.create(
AwsBasicCredentials.create(config.accessKey, config.secretKey)
)
def asyncClient(config: Config): Resource[IO, S3AsyncClient] =
Resource.fromAutoCloseable(IO.blocking {
S3AsyncClient.builder()
.httpClientBuilder(NettyNioAsyncHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(10))
.readTimeout(Duration.ofSeconds(30))
.writeTimeout(Duration.ofSeconds(30)))
.endpointOverride(config.endpoint)
.credentialsProvider(credentials(config))
.region(Region.of("auto"))
.serviceConfiguration(service)
.requestChecksumCalculation(RequestChecksumCalculation.WHEN_REQUIRED)
.overrideConfiguration(overrides)
.build()
})
def syncClient(config: Config): Resource[IO, S3Client] =
Resource.fromAutoCloseable(IO.blocking {
S3Client.builder()
.httpClientBuilder(ApacheHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(10))
.socketTimeout(Duration.ofSeconds(30)))
.endpointOverride(config.endpoint)
.credentialsProvider(credentials(config))
.region(Region.of("auto"))
.serviceConfiguration(service)
.requestChecksumCalculation(RequestChecksumCalculation.WHEN_REQUIRED)
.overrideConfiguration(overrides)
.build()
})
private def request(bucket: String, task: Task, size: Long): PutObjectRequest = {
require(size >= 0 && size <= 5L * 1024 * 1024 * 1024,
"Use multipart upload for files larger than 5 GiB")
PutObjectRequest.builder()
.bucket(bucket).key(task.key)
.contentType("application/octet-stream")
.contentLength(size)
.build()
}
def uploadSync(client: S3Client, bucket: String, task: Task): IO[PutObjectResponse] =
Files[IO].size(task.path).flatMap { size =>
IO.blocking(client.putObject(
request(bucket, task, size), RequestBody.fromFile(task.path.toNioPath)
))
}
def uploadAsync(client: S3AsyncClient, bucket: String, task: Task): IO[PutObjectResponse] =
Files[IO].size(task.path).flatMap { size =>
IO.fromCompletableFuture(IO {
client.putObject(request(bucket, task, size),
AsyncRequestBody.fromFile(task.path.toNioPath))
})
}
def uploadStream(client: S3AsyncClient, bucket: String, task: Task): IO[PutObjectResponse] =
Files[IO].size(task.path).flatMap { size =>
val buffers = Files[IO].readAll(task.path, 64 * 1024, Flags.Read)
.chunks.map(chunk => ByteBuffer.wrap(chunk.toArray))
buffers.toUnicastPublisher.use { publisher =>
val body = new AsyncRequestBody {
override def contentLength(): Optional[java.lang.Long] =
Optional.of(java.lang.Long.valueOf(size))
override def subscribe(subscriber: Subscriber[_ >: ByteBuffer]): Unit =
publisher.subscribe(subscriber)
}
IO.fromCompletableFuture(IO {
client.putObject(request(bucket, task, size), body)
})
}
}
def uploadMany(client: S3AsyncClient, bucket: String,
tasks: List[Task]): IO[List[PutObjectResponse]] =
tasks.parTraverseN(4)(task => uploadAsync(client, bucket, task))
private def digest(input: InputStream): Array[Byte] = {
val hash = MessageDigest.getInstance("SHA-256")
val buffer = new Array[Byte](64 * 1024)
var count = input.read(buffer)
while (count != -1) {
hash.update(buffer, 0, count)
count = input.read(buffer)
}
hash.digest()
}
def verify(client: S3Client, bucket: String, task: Task): IO[Unit] = {
val local = Resource.fromAutoCloseable(IO.blocking(
java.nio.file.Files.newInputStream(task.path.toNioPath)))
val remote = Resource.fromAutoCloseable(IO.blocking(client.getObject(
GetObjectRequest.builder().bucket(bucket).key(task.key).build())))
(local, remote).tupled.use { case (source, stored) =>
IO.blocking {
require(MessageDigest.isEqual(digest(source), digest(stored)), "Stored bytes differ")
}
}
}
override def run(args: List[String]): IO[ExitCode] = {
val operation = IO {
require(args.length >= 3 && args.length % 2 == 1,
"Usage: R2Upload sync|async|fs2|parallel|verify file key [file key ...]")
val mode = args.head
require(Set("sync", "async", "fs2", "parallel", "verify").contains(mode), "Unknown mode")
require(mode == "parallel" || args.length == 3, "Only parallel accepts multiple files")
val account = sys.env("R2_ACCOUNT_ID")
require(account.matches("[a-fA-F0-9]{32}"), "Invalid R2 account ID")
val config = Config(
URI.create(s"https://$account.r2.cloudflarestorage.com"),
sys.env("R2_ACCESS_KEY_ID"), sys.env("R2_SECRET_ACCESS_KEY"), sys.env("R2_BUCKET")
)
val tasks = args.tail.grouped(2).map(pair => Task(Path(pair.head), pair(1))).toList
require(tasks.forall(task =>
task.path.toString.matches("[A-Za-z0-9_./-]+") &&
task.key.matches("[A-Za-z0-9_./-]+") && !task.key.startsWith("-")),
"Use ASCII paths and keys containing only letters, digits, _, ., /, and -")
require(tasks.map(_.key).distinct.size == tasks.size, "Use distinct destination keys")
(mode, config, tasks)
}.flatMap { case (mode, config, tasks) =>
val upload = if (mode == "verify")
syncClient(config).use(client => verify(client, config.bucket, tasks.head))
else if (mode == "sync")
syncClient(config).use(client => uploadSync(client, config.bucket, tasks.head).void)
else
asyncClient(config).use { client =>
mode match {
case "fs2" => uploadStream(client, config.bucket, tasks.head).void
case "parallel" => uploadMany(client, config.bucket, tasks).void
case _ => uploadAsync(client, config.bucket, tasks.head).void
}
}
upload *> IO.println(if (mode == "verify") "Stored bytes match." else "Upload completed.")
}
operation.as(ExitCode.Success).handleErrorWith {
case error: S3Exception =>
IO.println(s"Upload failed (${error.getClass.getSimpleName}, HTTP ${error.statusCode()}).").as(ExitCode.Error)
case error =>
IO.println(s"Upload failed (${error.getClass.getSimpleName}). Check arguments, environment, file access, and network.")
.as(ExitCode.Error)
}
}
}
r2-scala でターミナルを開いてください。次のコマンドは、小さな入力ファイルを作成し、プログラムをコンパイルしてアップロードします。初回のコンパイルでは依存関係をダウンロードします。このランチャーのファイル引数とキー引数に使えるのは、ASCII の英字、数字、_、.、/、- のみです。ハイフンで始まるローカル名の前には ./ を付けてください。保存先キーは - で始めることができず、バッチ内で一意にする必要があります。すべての試行が終わるまで、ソースファイルを変更しないでください。
(
set -eu
printf 'Hello, R2!\n' > hello.txt
java -Dsbt.server.autostart=false -jar sbt-launch.jar compile
java -Dsbt.server.autostart=false -jar sbt-launch.jar "runMain R2Upload async ./hello.txt uploads/hello.txt"
)
ほかの単一ファイルモードを使うには、async を
sync または fs2 に置き換えてください。PUT が成功すると、入力が空の場合も含め、同じキーの既存オブジェクトが置き換わります。以前のオブジェクトを残す必要がある場合は、新しいキーを使ってください。
成功後、非公開オブジェクトを読み戻し、ローカルと保存先の内容全体の SHA-256 ハッシュを比較してください。
java -Dsbt.server.autostart=false -jar sbt-launch.jar "runMain R2Upload verify ./hello.txt uploads/hello.txt"
検証プログラムは、両方のハッシュが一致した場合にのみ Stored bytes match. を出力します。不一致または読み取り失敗の場合は、ゼロ以外のステータスを返します。PUT の完了だけで確認できるのは、サービスが受け付けたことまでです。重要な原本を削除する前に比較を実行してください。検証時にもソースが変更されていない必要があります。
レスポンスとエラーの処理
Upload completed. は、選択したすべてのアップロードとクライアントスコープが終了した後にのみ表示されます。サービスエラーでは、ゼロ以外の終了コードと HTTP ステータスを返します。ローカル設定、ファイル、ネットワークのエラーでも、認証情報や SDK の生のレスポンスを出力せずに、ゼロ以外の終了コードを返します。
キャンセルされたアップロードは、正常完了にはなりません。キャンセルやレスポンスの消失があっても、保存先に確定済みのオブジェクトが残る場合があります。再試行する前に確認してください。このプログラムは、失敗時にオブジェクトをロールバックしたり、リモートデータを削除したりしません。
指数バックオフによる再試行ロジック
SDK の標準再試行戦略は、再試行可能な障害に対処し、PUT ごとに最大三回試行します。API 呼び出しのタイムアウトは再試行を含めて二分、各試行のタイムアウトは 45 秒です。接続確立の上限は 10 秒です。これらはリクエストの制限であり、並列バッチ全体に二分の期限を設けるものではありません。トランスポートの読み取り制限は 30 秒で、各試行のタイムアウトより短くなっています。Netty には 30 秒の書き込み制限もあります。
転送が遅いと、ファイルサイズの上限未満でもタイムアウトする場合があります。保存先を確認してから、接続に合わせて制限を調整し、変更していないファイルを再試行してください。無制限の再試行ループは追加しないでください。FS2 パブリッシャーは、新しいサブスクリプションに対してファイルストリームを再実行できるため、変更されず、再読み取り可能なソースが必要です。
複数ファイルの並列アップロード
parallel モードは、最大四つのアップロードエフェクトを同時に実行します。ひとつが失敗すると、ほかのエフェクトをキャンセルし、失敗ステータスを返します。完了済みのオブジェクトは残ります。バッチはトランザクションではありません。report.pdf という名前のふたつ目のローカルファイルを作成してから、次を実行してください。
java -Dsbt.server.autostart=false -jar sbt-launch.jar "runMain R2Upload parallel ./hello.txt uploads/hello.txt ./report.pdf uploads/report.pdf"
この上限の対象は実行中のアップロードであり、メモリ内の引数リストや、Netty と SDK 内のすべてのバッファーではありません。ひとつのファイルを並列パートに分割することもありません。
fs2 による大容量ファイルのストリーミング
fs2 は 64 KiB のチャンクを読み取り、下流からの要求に応じて
ByteBuffer 要素として提供します。パブリッシャーのリソースは、完了、失敗、キャンセルに至るまで開いたままです。これにより、ファイル全体をバイト配列に読み込むことを避けられますが、JVM や HTTP クライアントの総メモリ使用量に固定の上限を設けるものではありません。
すべてのアップロードモードは単一の PUT を使い、5 GiB を超えるファイルはリクエスト送信前に拒否します。ストリーミングによってマルチパートアップロードや再開機能が追加されるわけではありません。より大きなファイルや再開可能なパートには、R2 マルチパートアップロードを使ってください。
セキュリティのベストプラクティス
バケットに範囲を限定した認証情報を使い、保存先キーは意図を持って選んでください。このサーバー側の Scala プログラムには、ブラウザーの CORS 設定も公開バケット URL も必要ありません。ユーザーから提供されたファイルは、アプリケーションが配信する場所へエクスポートする前に検証を完了してください。
よくあるエラーと対処法
| 結果 | 次の確認事項 |
|---|---|
| HTTP エラー | アカウントエンドポイント、バケット名、トークンのオブジェクト権限を確認してください。ステータスだけでは、どの設定が誤っているかは特定できません。 |
| ローカルエラー | 四つの環境変数すべて、引数の制限、ファイルの読み取り可否、5 GiB の上限を確認してください。 |
| タイムアウトまたは接続エラー | 接続状況とリクエスト制限を確認し、再試行の前に保存先を調べてください。 |
| 並列バッチの一部失敗 | 要求したキーをそれぞれ確認してください。コマンド全体が失敗しても、成功したほかのオブジェクトは残ります。 |
まとめ
通常のエクスポートには SDK のファイルボディを使い、既存のストリームパイプラインからバイト列を供給する必要がある場合は FS2 を使ってください。Transloadit の処理ジョブに続けてエクスポートする場合は、このプログラムを実行する代わりに、🤖 /cloudflare/store Robot で結果を R2 に書き込めます。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
