大容量PDFを守る再開可能アップロード(tus.io)完全ガイド
大容量のPDFを顧客からアップロードしてもらう機能を作るとき、必ずといっていいほど壁にぶつかります。PHPのupload_max_filesizeを超えてエラー、Nginxのclient_max_body_sizeでブロック、モバイル回線が不安定で接続が切れたら最初からやり直し——という光景は、PDF処理を扱う開発者であれば一度は経験しているはずです。
この記事では、FUNBREW PDFのtus.ioプロトコル対応の再開可能アップロード機能を使って、これらの問題を根本から解決する方法を解説します。curl・JavaScript SDK・tus-js-clientの実装コードと合わせて、本番運用での注意点まで網羅します。
大容量アップロードの何が問題か
通常のマルチパートファイルアップロード(multipart/form-data)は、ファイル全体を1リクエストで送信する設計です。この設計には以下の問題があります。
| 問題 | 症状 |
|---|---|
| サーバーサイドのサイズ制限 | Nginxはclient_max_body_size(既定1MB)超過で413エラー、PHPはupload_max_filesize(既定2MB)を超えたファイルを受け取らない |
| タイムアウト | 大容量ファイルのアップロード中にプロキシタイムアウトが発生 |
| ネットワーク断 | Wi-Fi切断・スマホ圏外で中断 → 最初からやり直し |
| 進捗表示の困難 | アップロード全体の進捗をUIに正確に反映しにくい |
特にモバイルユーザーや法人向けの書類提出ワークフローでは、数十MB〜数百MBのPDFを扱うケースが増えています。「圏外に入っただけでやり直し」はユーザーエクスペリエンスとして致命的です。
tusプロトコルとは
tus.ioはHTTPの上に作られた再開可能なファイルアップロードのためのオープンプロトコルです。仕様はバージョン1.0.0として公開されています。
tus の核心はシンプルで、チャンク(分割)+ オフセット管理の2つです。
POSTでアップロードを予約し、サーバーからアップロードキーを受け取るPATCHでチャンクを分割して送信する(どこまで受信済みかUpload-Offsetで管理)- 中断後は
HEADでオフセットを確認し、中断ポイントから再開する
1リクエストで送るのは1チャンクだけなので、チャンクを経路上の上限(Nginxのclient_max_body_sizeなど)より小さくすれば、ファイル全体の大きさはこれらの上限に縛られません。またPATCHの本文はファイルそのもの(application/offset+octet-stream)で、multipart/form-dataのファイル添付ではないため、PHPのupload_max_filesizeの対象外です。ファイル全体の上限はサーバーがOPTIONSのTus-Max-Sizeで示します。
FUNBREW PDF APIでのtus実装
エンドポイント一覧
FUNBREW PDF APIはtusプロトコル v1.0.0 に準拠したエンドポイントを提供しています。
| Method | Path | 役割 |
|---|---|---|
OPTIONS |
/api/pdf/uploads |
サーバー capability・対応バージョンの確認 |
POST |
/api/pdf/uploads |
アップロード予約 → Locationヘッダでuploadキーを発行 |
HEAD |
/api/pdf/uploads/{key} |
Upload-Offsetを取得(再開ポイント確認) |
PATCH |
/api/pdf/uploads/{key} |
チャンクの書き込み |
DELETE |
/api/pdf/uploads/{key} |
アップロードの中断・破棄 |
認証: 既存のPDF APIキーをそのまま使えます(X-API-Keyヘッダ。Authorization: Bearerでも可)。アップロード用のエンドポイントにはレート制限がかからず、プランの機能制限もありません(制限がかかるのは、アップロードしたファイルを渡すmerge・compressなどの処理API側です)。
ファイルサイズの上限: 既定の設定では1ファイル5GBまでです。実際の値はOPTIONSレスポンスのTus-Max-Sizeヘッダで確認できます。
主要ヘッダ
| ヘッダ | 方向 | 説明 |
|---|---|---|
Tus-Resumable: 1.0.0 |
リクエスト | tusプロトコルバージョン(仕様上OPTIONS以外で必須。違う版を送ると412) |
Upload-Length |
POSTリクエスト | ファイルの総バイト数 |
Upload-Offset |
PATCHリクエスト / HEADレスポンス | チャンクの開始位置(受信済みバイト数)。サーバーの値と食い違うと409 |
Upload-Metadata |
POSTリクエスト | キー base64値をカンマ区切りで並べたメタデータ。filename(またはname)が無いと400 |
Upload-Expires |
POST・PATCHレスポンス | 未完了のアップロードが破棄される期限 |
Content-Type: application/offset+octet-stream |
PATCHリクエスト | チャンク送信時は必須 |
実装例
1. curlで生プロトコルを確認する
tusのプロトコルを理解するには、curlで手動実行するのが最も確実です。
export KEY="sk-your-api-key"
export BASE="https://pdf.funbrew.cloud"
export FILE="large-document.pdf"
FILE_SIZE=$(wc -c < "$FILE" | tr -d ' ')
# Upload-Metadata の値は base64。echo だと改行まで符号化されるので printf を使う
FILE_NAME_B64=$(printf '%s' "$(basename "$FILE")" | base64 | tr -d '\n')
# ステップ1: アップロードを予約する(POST)
LOCATION=$(curl -s -D - -o /dev/null -X POST "$BASE/api/pdf/uploads" \
-H "X-API-Key: $KEY" \
-H "Tus-Resumable: 1.0.0" \
-H "Upload-Length: $FILE_SIZE" \
-H "Upload-Metadata: filename $FILE_NAME_B64,filetype $(printf '%s' application/pdf | base64)" \
| grep -i "^location:" | tr -d '\r' | awk '{print $2}')
echo "Upload URL: $LOCATION"
# → https://pdf.funbrew.cloud/api/pdf/uploads/<UUID>
# ステップ2: チャンクを送信する(PATCH)
# ここでは全データを1チャンクで送る例。経路上のプロキシにボディサイズの上限があるなら、
# それより小さいチャンクに分けて、返ってきた Upload-Offset から次を送る
curl -i -X PATCH "$LOCATION" \
-H "X-API-Key: $KEY" \
-H "Tus-Resumable: 1.0.0" \
-H "Upload-Offset: 0" \
-H "Content-Type: application/offset+octet-stream" \
--data-binary @"$FILE"
# → 204 No Content, Upload-Offset: <total_bytes>
# ステップ3: 中断した場合は現在のオフセットを確認する(HEAD)
# curl で HEAD を送るときは -X HEAD ではなく -I を使う
curl -I "$LOCATION" \
-H "X-API-Key: $KEY" \
-H "Tus-Resumable: 1.0.0"
# → 200 OK
# Upload-Offset: <bytes_received>
# Upload-Length: <total_bytes>
Upload-Offsetの値から中断ポイントがわかるので、次回のPATCHはそのオフセットから送信します。Locationの末尾のUUIDがアップロードキーで、後で処理APIに渡します。
2. @funbrew/pdf-client SDK
FUNBREW PDFのブラウザ向けJavaScript SDK(npmには未公開で、https://pdf.funbrew.cloud/sdk/から配信)を使うと、tus-js-clientの細かい設定を意識せずに再開可能アップロードが実装できます。
APIキーの扱いに注意: ダッシュボードで発行するAPIキーは全権限を持ちます。公開ページのブラウザにキーを埋め込むと誰でも読めるので、社内ツールなど利用者を限定できる画面でだけ使うか、自社バックエンドを経由させてください。
<!-- CDN経由(バンドラー不要) -->
<script src="https://pdf.funbrew.cloud/sdk/pdf-client.umd.js"></script>
import { PdfClient } from 'https://pdf.funbrew.cloud/sdk/pdf-client.esm.js';
const client = new PdfClient({
baseUrl: 'https://pdf.funbrew.cloud',
apiKey: 'sk-your-api-key',
});
// ファイルアップロード(再開可能・retryDelays の間隔で自動リトライ)
const result = await client.uploadFile(file, {
chunkSize: 5 * 1024 * 1024, // 5MB チャンク(SDKの既定値)
onProgress: (sent, total) => {
const pct = ((sent / total) * 100).toFixed(1);
progressBar.style.width = `${pct}%`;
label.textContent = `${pct}%`;
},
});
console.log(result.key); // → アップロードキー(UUID)
// そのままPDF処理に使用できる
const compressed = await client.compress({
upload_id: result.key,
quality: 'medium',
});
console.log(compressed.download_url); // 取得には APIキー(download スコープ)が要る
TypeScript型定義は https://pdf.funbrew.cloud/sdk/types/index.d.ts から取得できます。
3. tus-js-clientでの実装
より詳細な制御が必要な場合は、tus公式クライアントを直接使用します。
npm install tus-js-client
import * as tus from 'tus-js-client';
interface UploadOptions {
file: File;
apiKey: string;
onProgress?: (percentage: number) => void;
onSuccess?: (uploadUrl: string) => void;
onError?: (error: Error) => void;
}
function startResumableUpload({
file,
apiKey,
onProgress,
onSuccess,
onError,
}: UploadOptions): tus.Upload {
const upload = new tus.Upload(file, {
endpoint: 'https://pdf.funbrew.cloud/api/pdf/uploads',
headers: { 'X-API-Key': apiKey },
// チャンクサイズ: 経路上のプロキシの上限より小さく(ここではSDKと同じ5MB)
chunkSize: 5 * 1024 * 1024,
// リトライまでの待ち時間(ミリ秒)。配列の長さが最大試行回数
retryDelays: [0, 1000, 3000, 5000, 10000],
// filename はサーバーで必須(無いと POST が 400)
metadata: {
filename: file.name,
filetype: file.type,
},
onProgress: (bytesUploaded, bytesTotal) => {
const pct = (bytesUploaded / bytesTotal) * 100;
onProgress?.(pct);
},
onSuccess: () => {
// upload.url に完了済みアップロードのURLが入る
// 末尾のUUIDがアップロードキー
onSuccess?.(upload.url ?? '');
},
onError: (error) => {
onError?.(error as Error);
},
});
// 前回の中断箇所を確認して再開
// ブラウザではアップロードURLがファイルのフィンガープリントとともに Web Storage に保存される
upload.findPreviousUploads().then((previousUploads) => {
if (previousUploads.length > 0) {
upload.resumeFromPreviousUpload(previousUploads[0]);
}
upload.start();
});
return upload;
}
// キャンセル
// upload.abort();
findPreviousUploads() / resumeFromPreviousUpload() を使うと、ページをリロードした後でも同じファイルを選び直せば中断箇所から再開できます(未完了のアップロードはUpload-Expiresの期限までサーバーに残ります)。
中断・再開のフロー
実際のネットワーク断でどう動くかを図示します。
クライアント サーバー
| |
|-- POST /api/pdf/uploads -----→| アップロード予約
|←-- 201, Location: /..../abc --| uploadキー発行
| |
|-- PATCH (offset=0, 5MB) ----→ | チャンク1送信
|←-- 204, Upload-Offset: 5MB --|
| |
|-- PATCH (offset=5MB, 5MB) --→ | チャンク2送信
~~~ ネットワーク断 ~~~
| |
| (復旧後) |
|-- HEAD /..../abc -----------→ | オフセット確認
|←-- 200, Upload-Offset: 8MB --| 8MBまで受信済みと判明
| |
|-- PATCH (offset=8MB, ...) --→ | 8MB地点から再開
|←-- 204, Upload-Offset: 全量--| 完了
図の数値は一例です。サーバーは受信済みのバイト数(Upload-Offset)を記録しており、クライアントがHEADで問い合わせることでどこから再開すればよいかが正確にわかります。
並列アップロード(Concatenation extension)
大容量ファイルを並列に送りたい場合は、tusのConcatenation拡張が使えます。ファイルをN個の部分アップロード(partial)に分けて並列に送り、最後に連結(final)を作るとサーバー側で1つのファイルにまとまります。
tus-js-clientではparallelUploadsを指定します。このときmetadataは連結後のアップロードにしか付かず、部分アップロードにはmetadataForPartialUploadsの値が付きます。FUNBREW PDFのサーバーはPOSTのたびにfilenameを要求するので、metadataForPartialUploadsにもfilenameを入れてください(入れないと部分アップロードのPOSTが400になります)。
// tus-js-clientでの並列アップロード
const upload = new tus.Upload(file, {
endpoint: 'https://pdf.funbrew.cloud/api/pdf/uploads',
parallelUploads: 4, // 4つの部分アップロードに分けて並列送信
headers: { 'X-API-Key': apiKey },
metadata: { filename: file.name, filetype: file.type },
// 部分アップロードにも filename を付ける(サーバーで必須)
metadataForPartialUploads: { filename: file.name },
onSuccess: () => {
// upload.url の末尾が連結後の最終アップロードキー
console.log(upload.url?.split('/').pop());
},
});
upload.start();
JS SDKのuploadFile()にもparallelUploadsオプションがありますが、SDKは部分アップロードにfilenameを付けないため、並列アップロードには上のようにtus-js-clientを直接使ってください。
注意: サーバーがS3直流しモード(s3-multipart)で動いている場合、Concatenationは使えずUpload-Concat付きのPOSTに400が返ります。400が返ったら並列をやめて1本で送ってください。
Webhookでアップロード完了を受け取る
アップロード完了をサーバー側からプッシュ通知で受け取りたい場合は、Webhookイベントを設定できます。
ダッシュボードのWebhook画面では選べないイベントなので、Webhook管理API(POST /api/webhooks。manageスコープのキーが必要で、SaaS版・Webhook機能のあるプランのみ)でeventsに指定して登録します。
curl -X POST https://pdf.funbrew.cloud/api/webhooks \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/webhooks/funbrew", "events": ["tus.upload.completed", "tus.upload.aborted"]}'
# レスポンスの data.secret が署名検証用のシークレット(このときだけ返る)
アップロードが完了すると、次のようなペイロードが届きます。
{
"event": "tus.upload.completed",
"timestamp": "2026-06-04T09:00:00.000000Z",
"data": {
"upload_key": "3f1c2a9e-8b7d-4e6f-9a01-2b3c4d5e6f70",
"original_filename": "quarterly-report.pdf",
"size": 15728640,
"storage": "local",
"s3_key": null,
"content_type": "application/pdf"
}
}
| イベント | 発火タイミング |
|---|---|
tus.upload.completed |
アップロードが最終チャンクまで完了した瞬間 |
tus.upload.aborted |
DELETE受信時、または期限切れの未完了アップロードがGCで掃除されたとき |
content_typeはアップロード時にUpload-Metadataのfiletypeを送ったときだけ入ります(無ければnull)。既存のpdf.generated系Webhookと同じ署名・リトライ・配信記録の仕組みが使えます。Webhookの詳細はPDF API Webhook連携ガイドを参照してください。
アップロード後の処理
完了したアップロードのキー(LocationヘッダのUUID末尾部分)は、そのまま各PDF処理エンドポイントに渡せます。
# アップロード → 直接マージ
curl -X POST https://pdf.funbrew.cloud/api/pdf/merge \
-H "X-API-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{
"upload_ids": ["3f1c2a9e-8b7d-4e6f-9a01-2b3c4d5e6f70", "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"],
"expiration_hours": 24
}'
# アップロード → 圧縮
curl -X POST https://pdf.funbrew.cloud/api/pdf/compress \
-H "X-API-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{"upload_id": "3f1c2a9e-8b7d-4e6f-9a01-2b3c4d5e6f70", "quality": "medium"}'
対応エンドポイントはmerge(upload_ids。filenamesと合わせて2〜50件)・compress・extract-text・to-image(upload_id。filenameとはどちらか一方)です。これらはSaaS版のみで、プランで使える機能に含まれていないと403、generateスコープのキーが必要です(現在の Free・Pro・Business はいずれも使えます)。完了していない・見つからない・他社のアップロードを渡すと422が返ります。
これらのエンドポイントは処理が終わってから結果を返す同期APIで、X-Job-Idヘッダを返し、GET /api/pdf/jobs/{jobId}/eventsでSSE進捗が購読できます(SSEについては別途SSE進捗ストリーミングガイドで解説します)。
本番運用の注意点
チャンクサイズの選択
1チャンク=1リクエストなので、チャンクは経路上のプロキシのボディサイズ上限より小さくする必要があります。SDKの既定は5MBです。チャンクを小さくすると切断時に送り直す量が減りますが、リクエスト数が増えます。利用者の回線に合わせて、retryDelaysと合わせて調整してください(tus-js-client単体の既定はchunkSize: Infinity=1リクエストで全体を送る設定です)。
GC(中断アップロードの掃除)
アップロードの状態は期限(既定で約1日。Upload-Expiresヘッダで分かる)付きで保存され、期限を過ぎたものは毎日03:25(日本時間)に動く掃除コマンドが削除します。完了済みのアップロードも期限を過ぎると消えます。
アップロード後はできるだけ早く(遅くとも期限内に)PDF処理エンドポイントに渡してください。
認証とアクセス制御
- アップロードキーは作成した会社のみがアクセスできます(他社のキーへのHEAD・PATCH・DELETEは404)。Open版(シングルテナント)では会社の区分けはありません
- キーはUUIDで推測不可能ですが、APIキーの管理は本番運用ガイドに従って適切に行ってください
Nginx設定
自社のNginxを経由してtusのリクエストをFUNBREW PDFへ中継する場合は、中継側の設定を確認してください(Nginxのclient_max_body_sizeの既定は1MBで、超えると413になります)。
# /etc/nginx/conf.d/pdf-api.conf(自社サーバーで中継する場合の例)
location /api/pdf/uploads {
client_max_body_size 0; # 0 でボディサイズの検査をしない(チャンクの大きさはクライアントで決める)
proxy_request_buffering off; # 受け取ったそばから上流へ送る(一時ファイルに溜めない)
proxy_send_timeout 3600s; # 上流への送信が途切れたとみなすまでの時間
proxy_read_timeout 3600s; # 上流からの応答を待つ時間
proxy_pass https://pdf.funbrew.cloud;
}
中継するとLocationヘッダのURLはFUNBREW PDFのものになる点に注意してください。
まとめ
tus.ioプロトコルを使った再開可能アップロードは、大容量PDFの扱いを根本から変えます。
- チャンクを上限より小さくすれば、
upload_max_filesizeやclient_max_body_sizeにファイル全体の大きさが縛られない - ネットワーク断が起きてもオフセット地点から再開できる
- チャンク単位の進捗表示がUIに組み込みやすい
- アップロード完了後はそのままPDF処理APIに連携できる
FUNBREW PDFの既定の設定では1ファイル5GBまでアップロードできます。SDKプレイグラウンドでアップロード→圧縮の流れを、プレイグラウンドでPDF生成を試せます。大容量ファイルを扱うユースケースについてはユースケース一覧も参照してください。
実装の詳細は@funbrew/pdf-client SDKの記事でさらに詳しく解説しています。
関連記事
- PDF API本番運用ガイド2026年版 — レート制限・監視・コスト管理
- PDF API Webhook連携ガイド — Webhookイベントの設定と活用
- SSEによるPDF処理進捗ストリーミングガイド — リアルタイム進捗表示