tus-java-client で Java のファイルアップロードを再開
アップロードリクエストが失敗しても、ファイル全体を再送する必要はありません。このチュートリアルでは、tus-java-client でバイナリファイルをアップロードし、意図的なサーバー障害から復旧して、保存されたバイト列を検証します。クライアントとサーバーをローカルで実行し、サーバーに保存されたオフセットから再試行が始まることを確認します。
tus-java-client のセットアップ
以下のコマンドは、Bash、OpenJDK 21.0.12.1、Maven 3.9.16、Node.js 24.22.1、Corepack、Yarn 4.12.0 を使用する Linux 環境を対象としています。これらはテスト済みのツールバージョンです。Node はローカルのテストサーバーを実行します。既存の tus エンドポイントに接続する場合、Java アプリケーションに Node は不要です。
既存のアプリケーションの外にプロジェクトを作成します。空のロックファイルで Yarn の独立したプロジェクト境界を定め、ローカル設定でサーバーの依存関係に node_modules を選択します。このブロックの実行後もターミナルのディレクトリは元のままで、java-tus-demo ディレクトリがすでに存在する場合は処理を拒否します。
(
mkdir java-tus-demo &&
cd java-tus-demo &&
mkdir -p src/main/java &&
touch yarn.lock &&
printf 'nodeLinker: node-modules\n' > .yarnrc.yml
)
エディターで java-tus-demo を開き、二つのターミナルで作業ディレクトリとして使用します。ルートに、以下の完全な pom.xml を保存します。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>example</groupId>
<artifactId>java-tus-demo</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.release>21</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>io.tus.java.client</groupId>
<artifactId>tus-java-client</artifactId>
<version>0.5.1</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.14.1</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.9.0</version>
</plugin>
</plugins>
</build>
</project>
ローカル tus サーバーの起動
POM と同じディレクトリに package.json を保存します。
{
"name": "java-tus-demo",
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"dependencies": {
"@tus/file-store": "2.1.1",
"@tus/server": "2.4.5"
}
}
以下を server.ts として保存します。公式の Node tus サーバーとディスクストアを使用します。障害スイッチは、開始オフセットが 1 MiB に達したアップロードリクエストを一度だけ拒否します。それ以前のバイト列はディスクに残ります。初回の実行では有効のままにしておきます。
import { createServer } from 'node:http'
import { FileStore } from '@tus/file-store'
import { Server } from '@tus/server'
const port = Number(process.argv[2] ?? '1080')
if (!Number.isInteger(port) || port < 0 || port > 65535) {
throw new Error('Port must be an integer from 0 to 65535')
}
const tus = new Server({
path: '/files',
datastore: new FileStore({ directory: './uploads' }),
})
let failOnce = true
const http = createServer((request, response) => {
// Java's HttpURLConnection uses this override when it cannot send PATCH.
if (request.method === 'POST' && request.headers['x-http-method-override'] === 'PATCH') {
request.method = 'PATCH'
}
response.on('finish', () => {
console.log(`${request.method} ${request.url} -> ${response.statusCode}, request offset=${request.headers['upload-offset'] ?? '-'}`)
})
if (failOnce && request.method === 'PATCH' && Number(request.headers['upload-offset']) >= 1048576) {
failOnce = false
request.resume()
response.writeHead(503, { 'Tus-Resumable': '1.0.0' })
response.end('Deliberate interruption')
return
}
void tus.handle(request, response).catch((error: unknown) => {
console.error(error)
response.destroy()
})
})
http.on('error', (error) => {
console.error(`Server failed: ${error.message}`)
process.exitCode = 1
})
http.listen(port, '127.0.0.1', () => {
const address = http.address()
if (address && typeof address !== 'string') {
console.log(`Listening at http://127.0.0.1:${address.port}/files`)
}
})
テストした Java トランスポートでは、このオーバーライドが必要です。0.5.1 のアップローダーは
POST にフォールバックし、X-HTTP-Method-Override: PATCH を使用します。このリクエストを通常の作成リクエストとして転送すると、アップロードが失敗します。
最初のターミナルでサーバーの依存関係をインストールし、起動します。
corepack yarn install && corepack yarn node server.ts 1080
待ち受け URL が表示されるまで待ちます。ポート 1080 が使用中の場合は、このコマンドと後述の Java コマンドで別のポートを指定します。サーバーはループバックのみにバインドし、認証はありません。ローカルでのみ使用してください。これは学習用のテスト環境であり、デプロイ用の設定ではありません。終了したら Ctrl+C で停止します。
基本的な使い方
以下の完全なクラスを src/main/java/TusUploaderExample.java として保存します。
import io.tus.java.client.ProtocolException;
import io.tus.java.client.TusClient;
import io.tus.java.client.TusExecutor;
import io.tus.java.client.TusUpload;
import io.tus.java.client.TusUploader;
import io.tus.java.client.TusURLMemoryStore;
import java.io.File;
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL;
import java.util.ArrayList;
import java.util.List;
public class TusUploaderExample {
public static void main(String[] args) {
try {
run(args);
} catch (Exception error) {
System.err.println("Upload failed: " + error.getMessage());
System.exit(1);
}
}
private static void run(String[] args) throws Exception {
if (args.length != 2) {
throw new IllegalArgumentException("Usage: TusUploaderExample ENDPOINT FILE");
}
File file = new File(args[1]);
if (!file.isFile() || !file.canRead()) {
throw new IOException("Input must be a readable regular file: " + file);
}
List<HttpURLConnection> connections = new ArrayList<>();
TusClient client = new TusClient() {
@Override
public void prepareConnection(HttpURLConnection connection) {
super.prepareConnection(connection);
connection.setReadTimeout(5000);
connections.add(connection);
}
};
client.setConnectTimeout(5000);
client.setUploadCreationURL(URI.create(args[0]).toURL());
client.enableResuming(new TusURLMemoryStore());
TusExecutor executor = new TusExecutor() {
private int attempt = 0;
@Override
protected void makeAttempt() throws IOException, ProtocolException {
System.out.println("Attempt " + ++attempt);
TusUpload upload = new TusUpload(file);
URL completedUrl;
// Close the file even if creation, resuming, or finish() fails.
try (var input = upload.getInputStream()) {
TusUploader uploader = client.resumeOrCreateUpload(upload);
uploader.setChunkSize(64 * 1024);
uploader.setRequestPayloadSize(1024 * 1024);
System.out.println("Starting at byte " + uploader.getOffset());
try {
while (uploader.uploadChunk() != -1) {
// The server response is checked when the request finishes.
}
} finally {
uploader.finish();
}
completedUrl = uploader.getUploadURL();
} finally {
for (HttpURLConnection connection : connections) {
connection.disconnect();
}
connections.clear();
}
System.out.println("Completed: " + completedUrl);
}
};
executor.setDelays(new int[] {500, 1000});
if (!executor.makeAttempts()) {
throw new IOException("Upload interrupted while waiting to retry");
}
}
}
各試行で同じファイルを開き直し、一つのクライアントと URL ストアを共有します。resumeOrCreateUpload() は初回の試行でアップロードを作成し、再試行時には HEAD でサーバーのオフセットを取得します。転送中は元のファイルを変更しないでください。ライブラリのファイルフィンガープリントにはパスと長さが含まれますが、コンテンツハッシュは含まれません。
二つのサイズ設定は役割が異なります。64 KiB のチャンクはクライアントのコピーバッファーで、1 MiB のペイロード設定は各 HTTP アップロードリクエストの上限です。中断を確認しやすいよう、意図的にリクエストを小さくしています。スループット向上のための推奨値ではありません。
二つ目のターミナルで、リクエスト二つ分より少し大きいバイナリサンプルを作成します。このコマンドは、既存の sample.bin の上書きを拒否します。
corepack yarn node -e "require('node:fs').writeFileSync('sample.bin', require('node:crypto').randomBytes(2 * 1024 * 1024 + 4099), {flag: 'wx'})"
コンパイルし、実行時の依存関係をコピーして、クラスを実行します。&& により、ビルド失敗時に古いクラスが実行されるのを防ぎます。ここでのクラスパス区切り文字は Linux 用です。
mvn -q compile dependency:copy-dependencies &&
java -cp 'target/classes:target/dependency/*' TusUploaderExample http://127.0.0.1:1080/files sample.bin
応用機能
再試行の証拠の確認
サーバーを新たに起動した場合、Java の出力は次のようになるはずです。
Attempt 1
Starting at byte 0
Attempt 2
Starting at byte 1048576
Completed: http://127.0.0.1:1080/files/<upload-id>
サーバーのターミナルで、オフセット 0 から始まる成功したアップロードリクエスト、503 が意図的に発生した位置
1048576、その後の HEAD を確認します。Java の再試行の開始バイト位置は、その HEAD レスポンスから取得します。残りの成功したリクエストは 1048576 と
2097152 から始まります。これは tus のオフセットプロトコルに従った動作です。サーバーがクライアントに再開位置を伝えるため、最初の MiB を再送する必要はありません。
以下の UPLOAD_ID を、完了した URL の最後のパスセグメントに置き換えます。二つ目のターミナルで、実際に保存されたファイルを比較します。
cmp sample.bin uploads/UPLOAD_ID && printf 'Files match\n'
完了メッセージは、サーバーが転送を確認したことを意味します。cmp は、それとは別にディスク上のバイト列を検証します。不一致またはファイルの欠落があると、ゼロ以外の終了ステータスで報告します。
中断後に保持されるもの
TusURLMemoryStore は、この Java プロセスの実行中にのみアップロード URL を保持します。シミュレーションした障害では、このプロセスは実行を続けます。Ctrl+C で Java を停止して再起動すると、新しいアップロードが作成されます。この例には、プロセス再起動後の復旧は実装していません。その機能の組み込みには、永続化された
TusURLStoreと、信頼できるファイル識別ポリシーが必要です。
サーバーは停止後も uploads/ にファイルを保持します。Java を再実行すると、サーバー上にランダムな名前の新しいファイルが作成され、以前のアップロードはそのまま残ります。不要になったローカルのテストファイルは削除してください。一度限りの障害を再び発生させるにはサーバーを再起動します。無効にするには failOnce を false に設定します。
ベストプラクティス
この例では、初回の呼び出しと、500 ms 後、1,000 ms 後の二回の再試行を合わせ、最大三回試行します。この上限は
TusExecutor.setDelays()によるものです。接続と読み取りのタイムアウトは個々の待機時間を制限するもので、アップロード全体の期限ではありません。
空のファイルも有効で、進捗率を計算せずに完了します。ファイルが存在しない場合は、サーバーに接続する前に失敗します。サーバーが利用できない状態が続くと、Java は再試行を使い切った後に失敗を表示し、ゼロ以外のステータスで終了します。再試行できないプロトコルエラーでは、より早く失敗する場合があります。スクリプトでは、その終了ステータスを確認してください。進捗のオフセットだけでは完了を判断できません。finish() が最後のレスポンスを拒否する可能性がまだあるためです。
プラットフォームの互換性
このチュートリアルは、Linux 上のデスクトップ Java プロセスを対象としています。Java ライブラリは Android にも対応していますが、このプログラムは Android のライフサイクルイベントやバックグラウンドスケジューリングを処理しません。Android への組み込みについては、tus-android-clientを出発点にしてください。
