グラフとチャートが表示されたデスクの2台のモニター
技術解説

マルチパートアップロードで壊れるZIP配信、4つの検証ゲートで防ぐ設計判断

目次を見る

大容量のゲームビルドや資産パッケージをオブジェクトストレージにアップロードする際、マルチパートアップロード(ファイルを複数の分割パートに分けて並行転送する仕組み)を使う場面は珍しくありません。ところが配布リンクを公開した直後に「ZIPが壊れている」という問い合わせが来るケースがあります。これはストレージサービス側の不具合ではなく、公開タイミングとアップロード完了判定の設計ミスであることが多い問題です。

この記事は、ゲーム配信基盤やアセットパイプラインを運用しているSRE・バックエンドエンジニアに向けた内容です。マルチパートアップロードを使う・使わないの判断、そして使う場合にどこまで検証ゲートを設けるべきかを整理しました。小規模チームで運用コストと信頼性のバランスを取りたい方の参考になれば幸いです。

どんな場面でこの判断が必要になるか

ゲームのエクスポート機能やビルド成果物の配布では、数百MBから数GB単位のZIPファイルを生成し、ストレージにアップロードしてからダウンロードリンクを発行します。

ファイルサイズが大きくなると、単一のPUTリクエストでは接続切断時に最初からやり直しになり非効率です。そこでパートごとに分割してアップロードし、最後に結合する方式が使われます。

ここで問題になるのが「どの時点でダウンロードリンクを公開してよいか」です。パートのアップロードが全て成功しても、結合処理(complete操作)が失敗すればオブジェクトは不完全なまま残ります。この境界を曖昧にすると、配信直後に壊れたファイルが利用者の手元に届くことになります。

判断軸1: アップロード完了と公開可否を同一視しないか

最初の判断軸は、アップロード完了判定の粒度です。

マルチパートアップロードには少なくとも4つの独立した段階があります。アップロード開始(create)、各パートの転送(upload)、パート結合の確定(complete)、そして実体確認(verify)です。

これらを1つの「成功」フラグにまとめてしまうと、どこかの段階で失敗しても検知できません。たとえばパートのアップロードが全て200を返しても、complete操作がタイムアウトした場合、オブジェクトは存在しないか不完全な状態になります。

この4段階をそれぞれ独立したゲートとして扱い、全てを通過しない限り通知を出さない設計にするかどうかが最初の分岐点です。

判断軸2: 完了後にHEAD検証を追加コストとして受け入れるか

次の判断軸は、complete操作の成功を信用するか、追加で検証するかです。

ストレージAPIのcomplete操作が200を返しても、それだけでオブジェクトが期待通りのバイト数で存在することの保証にはなりません。ネットワーク越しの整合性には遅延や一時的な不整合がつきものです。

確実性を高めるには、complete成功後にHEADリクエスト(オブジェクトのメタデータだけを取得する軽量なAPI呼び出し)を発行し、返ってきたバイト数をZIP生成ジョブが把握している期待値と突き合わせる方法があります。

この追加リクエストは数十ミリ秒のレイテンシとAPI呼び出し回数の増加というコストを伴います。配布頻度が低い(1日数件程度の)エクスポート機能であれば、このコストは無視できる水準です。

判断軸3: 失敗時のクリーンアップを自動化するか、ジョブに持たせるか

3つ目の判断軸は、失敗したマルチパートアップロードの後始末を誰が担うかです。

ZIP生成が途中で止まった場合、すでにアップロード済みのパートを放置すると、ストレージ上に未完結の断片が残り続けます。これを次回のリトライ時に「使い回せるかもしれない」と判断するロジックを書くのは危険です。

古いパート情報が新しいリトライに混入すると、パートの順序やハッシュ値の不整合が起き、結合時にエラーになるか、最悪の場合は中身が壊れたまま結合が成功してしまいます。

安全な設計は、失敗を検知した時点でそのアップロードを明示的にアボート(中断)し、リトライは新しいマルチパートアップロードIDから始めることです。クリーンアップの自動実行をストレージサービス側の仕組みに期待するか、アプリケーション側のジョブが責任を持つかは、利用するストレージのライフサイクルルール機能の有無で決まります。

判断軸4: ジョブIDとアップロードIDを分離するか

4つ目の判断軸は、アプリケーション内部のID設計です。

エクスポート機能には2種類の識別子が存在します。1つはアプリケーションが発行する「エクスポートジョブID」で、もう1つはストレージプロバイダが発行する「アップロードID」です。

アップロードIDをそのまま公開URLや通知メッセージに使い回すと、将来ストレージプロバイダを乗り換える際にアプリケーションコードの広範囲に影響が及びます。ジョブIDを恒久的な識別子とし、アップロードIDはアダプター層(ストレージとの接続部分を担う薄いインターフェース)の内部詳細として隠蔽する設計が、長期的な保守性に効いてきます。

選択肢の比較

小規模チームがマルチパートアップロードの検証をどこまで実装するかは、おおよそ3つの選択肢に分かれます。

アプローチ実装コスト壊れたZIP配布のリスク
complete成功を信じて即公開低い高い(不整合を検知できない)
complete後にHEAD検証を追加中程度低い(バイト数不一致を検知可能)
HEAD検証+失敗時アボート+ID分離やや高い最も低い(状態漏れと混線を防止)

実装コストの差は、HEADリクエストの追加とリトライ時のRetry-Afterヘッダー(レート制限時に再試行までの待機秒数を示すレスポンスヘッダー)対応、指数バックオフ(リトライ間隔を指数関数的に広げる手法)の実装程度です。大きな追加インフラは不要で、既存のアップロードコーディネーターに検証関数を1つ足すイメージに近いものです。

ケース別の推奨

配信頻度が低く、エクスポート機能がプロダクトの主要導線でないなら、HEAD検証の追加だけでもリスクは大きく下がります。既存のcomplete成功判定の後ろに検証ステップを挟む変更で済みます。

ゲームビルドの自動配布基盤のように、CI/CDパイプラインから日常的に大量のアップロードが走る環境なら、4ゲート全てを実装する価値があります。アボート処理とID分離まで含めることで、障害調査時にログから原因を追いやすくなります。

複数のストレージプロバイダを将来的に切り替える可能性がある、あるいはマルチクラウド構成を検討しているなら、ジョブIDとアップロードIDの分離は早期に着手すべき設計です。後からの分離はアダプター層の書き直しを伴います。

マルチパートアップロードの「成功」は、complete操作のHTTPステータスだけでなく、HEAD検証でバイト数が一致することまで含めて判定すべきです。

あえて見送るべき条件

ファイルサイズが数十MB程度で、単一PUTアップロードで十分完結する規模なら、マルチパートアップロードそのものを導入する必要はありません。複雑な状態管理を増やすだけで得るものが少ないためです。

また、配布頻度が極端に低く(月に数件程度)、手動での目視確認が運用に組み込まれているなら、4ゲート全ての自動化に投資するより、まず単純なHEAD検証だけを追加して様子を見る選択も妥当です。過剰な設計は保守コストを増やすだけになりかねません。

まとめ

マルチパートアップロードを使う配信基盤では、アップロード完了と公開可否を切り分けて考えることが出発点になります。

具体的な次の一歩としては、まず現状のアップロード処理でcomplete操作の成功のみで通知を出していないかをコードで確認してください。もし即時通知になっているなら、HEADリクエストでバイト数を突き合わせる検証ステップを1つ追加するところから始められます。

失敗時のアボート処理とジョブID/アップロードIDの分離は、配信頻度と将来のプロバイダ移行可能性を見ながら優先度を判断してください。小さな検証ゲート1つの追加が、問い合わせ対応の工数を大きく減らすことにつながります。

参考

Multipart Game Export Uploads: 4 Gates Against Corrupted ZIP Downloads

AI 駆動開発のご相談は forva AI へ。

まずはお気軽にどうぞ。