JavaScript でブラウザーから Google Storage に分割アップロード
大容量ファイルを Node.js 経由で中継せず、ブラウザーから非公開の Google Cloud Storage(GCS)バケットへ直接送信します。サーバーは単一の所有者を認証して再開可能なアップロードセッションを開始します。ブラウザーはアラインメント要件に沿ったチャンクを送信し、中断後は再開位置を GCS に問い合わせます。この例では、同じページを開いたままでの一時停止と再開に加え、完了後の独立したバイト検証も行います。
チャンク分割アップロードを使う理由は?
接続が切れると、ブラウザーが確認できた量より多くのバイトが保存されている場合があります。GCS の再開可能なプロトコルでは、追加のデータを送信する前に、受け付け済みの位置を問い合わせられます。これらのリクエストは単一のオブジェクトを構築するため、結合や削除が必要な個別のチャンクオブジェクトはありません。
Google Cloud Storage の設定
Linux または macOS の Bash、最新の Node.js 24 LTS リリース、Corepack、既存の非公開バケットを使用します。以下のパッケージ設定では Yarn 4.18.1 と Google Auth Library 11.3.0 を固定します。テスト済みの LTS バージョンは Node.js 24.22.0 です。同じメジャーバージョン内で、メンテナンスされているセキュリティ更新を引き続き適用してください。
サーバーにはバケットの storage.objects.create が必要です。新規作成のみを行うこの例では、バケットをスコープとする
roles/storage.objectCreator ロールでこの権限を付与できます。後述のバイト検証には storage.objects.get も必要で、roles/storage.objectViewer で付与できます。Google のアップロードに必要な権限を参照してください。これらの権限を持つ既存の Application Default Credentials(ADC)を使用します。ADC が未設定の場合は、Google Cloud CLI をインストールし、サーバーを起動する前に
gcloud auth application-default login を実行してください。ログインに成功しただけでは、バケットへのアクセス権は得られません。
新しい gcs-upload プロジェクトを作成する場所のディレクトリで、以下を貼り付けてください。既存のディレクトリは拒否され、シェルの作業ディレクトリは変わりません。プロジェクト専用の Yarn 設定とロックファイルが作成されます。
(
set -eu
command -v node >/dev/null || { printf 'Install Node.js first.\n' >&2; exit 1; }
command -v corepack >/dev/null || { printf 'Install Corepack first.\n' >&2; exit 1; }
mkdir gcs-upload
cd gcs-upload
printf '%s\n' '{"name":"gcs-upload","private":true,"type":"module","packageManager":"yarn@4.18.1","dependencies":{"google-auth-library":"11.3.0"}}' > package.json
printf '%s\n' 'nodeLinker: node-modules' 'ignorePath: true' 'enableGlobalCache: false' > .yarnrc.yml
: > yarn.lock
corepack yarn@4.18.1 install
)
インストールに失敗した場合は、作成されたファイルを残したまま
(cd gcs-upload && corepack yarn@4.18.1 install) を再実行してください。成功したら、gcs-upload でターミナルを開き、以下の四つのファイルを保存します。
JSON API はバケットの CORS ルールとは独立して CORS を処理します。サーバーはセッション作成時にページの正確なオリジンを指定します。その後、ブラウザーがチャンクのリクエストにそのオリジンを追加します。CORS はブラウザーによるレスポンスの読み取りを許可し、アップロードトークンはセッションを作成できる人を制御します。
バックエンド:認証付きアップロードセッションの作成
以下を server.mjs として保存してください。設定したトークンは、このローカルツールの単一の所有者を識別します。すべてのセッションでこのトークンが必要です。サーバーは
uploads/owner/ 内で予測不能なオブジェクト名を選びます。クライアントは、バケット名、保存先パス、削除対象のオブジェクト名を指定できません。ifGenerationMatch=0 の事前条件によって、既存のオブジェクトの上書きも防ぎます。
import { createHash, randomUUID, timingSafeEqual } from 'node:crypto'
import { readFile } from 'node:fs/promises'
import { createServer } from 'node:http'
import { GoogleAuth } from 'google-auth-library'
const ORIGIN = 'http://127.0.0.1:8080'
const MAX_SIZE = 10 * 1024 ** 3
const assets = new Map([
['/', ['index.html', 'text/html; charset=utf-8']],
['/upload.mjs', ['upload.mjs', 'text/javascript; charset=utf-8']],
['/app.mjs', ['app.mjs', 'text/javascript; charset=utf-8']],
])
export function createUploadServer({ auth, bucket, token }) {
if (!bucket || !token || token.length < 32) throw new Error('Set BUCKET and a 32-character token')
const digest = (value) => createHash('sha256').update(value).digest()
const expected = digest(`Bearer ${token}`)
return createServer((req, res) => {
res.setHeader('Cache-Control', 'no-store')
res.setHeader('Referrer-Policy', 'no-referrer')
const reply = (status, body) => {
res.writeHead(status, { 'Content-Type': 'application/json' })
res.end(JSON.stringify(body))
}
async function handle() {
const asset = assets.get(req.url)
if (req.method === 'GET' && asset) {
const body = await readFile(new URL(asset[0], import.meta.url))
res.writeHead(200, { 'Content-Type': asset[1] })
res.end(body)
return
}
if (req.method !== 'POST' || req.url !== '/sessions') return reply(404, { error: 'Not found' })
if (!timingSafeEqual(expected, digest(req.headers.authorization ?? ''))) {
return reply(401, { error: 'Invalid upload token' })
}
if (req.headers.origin !== ORIGIN) return reply(403, { error: 'Invalid origin' })
const chunks = []
let bytes = 0
for await (const chunk of req) {
bytes += chunk.length
if (bytes > 1024) return reply(413, { error: 'Request too large' })
chunks.push(chunk)
}
let input
try {
input = JSON.parse(Buffer.concat(chunks, bytes).toString('utf8'))
} catch {
return reply(400, { error: 'Invalid JSON' })
}
const size = input?.size
if (!Number.isSafeInteger(size) || size < 1 || size > MAX_SIZE) {
return reply(400, { error: 'Choose a nonempty file of at most 10 GiB' })
}
const name = `uploads/owner/${randomUUID()}`
const url = new URL(`https://storage.googleapis.com/upload/storage/v1/b/${encodeURIComponent(bucket)}/o`)
url.search = new URLSearchParams({ uploadType: 'resumable', name, ifGenerationMatch: '0' })
const client = await auth.getClient()
const response = await client.request({
url: url.href,
method: 'POST',
headers: { Origin: ORIGIN, 'X-Upload-Content-Length': String(size) },
data: { contentType: 'application/octet-stream' },
timeout: 30_000,
retry: false,
})
const sessionUrl = response.headers.get('location')
if (!sessionUrl || new URL(sessionUrl).origin !== 'https://storage.googleapis.com') {
throw new Error('Invalid session response')
}
reply(201, { sessionUrl, name })
}
handle().catch(() => reply(502, { error: 'Could not create upload session' }))
})
}
if (import.meta.main) {
const auth = new GoogleAuth({ scopes: ['https://www.googleapis.com/auth/devstorage.read_write'] })
const server = createUploadServer({ auth, bucket: process.env.BUCKET, token: process.env.UPLOAD_TOKEN })
server.on('error', () => {
console.error('Could not start upload server. Check whether port 8080 is already in use.')
process.exitCode = 1
})
server.listen(8080, '127.0.0.1', () => console.log(`Open ${ORIGIN}`))
}
Google Auth Library は Google の認証情報をサーバー上に保持します。返されるセッション URL 自体がベアラー認証情報です。この URL を持つ人は誰でも、その単一の保存先にアップロードできます。これは有効期間が 15 分の署名付き URL ではありません。GCS の再開可能なセッションは一週間で有効期限が切れます。セッション URL をログや共有ストレージに残さないでください。
フロントエンド:最小限のチャンク分割アップローダー
以下を upload.mjs として保存してください。チャンクサイズの 8 MiB は、GCS が要求する 256 KiB アラインメントの倍数です。最後のチャンクはそれより小さくても構いません。308 レスポンスはアップロードが未完了であることを示すため、コードでは通常の HTTP エラー判定より先に処理します。リクエスト全体が GCS に受け付けられたと仮定せず、確認済みのバイト範囲を読み取ります。再開可能なアップロードプロトコルを参照してください。
const CHUNK_SIZE = 8 * 1024 * 1024
export async function uploadFileWithChunks(file, sessionUrl, { signal, onProgress = () => {} } = {}) {
if (file.size < 1 || file.size > 10 * 1024 ** 3) throw new Error('Invalid file size')
let offset = 0
let probe = true
let failures = 0
while (true) {
signal?.throwIfAborted()
const end = Math.min(offset + CHUNK_SIZE, file.size)
let response
try {
response = await fetch(sessionUrl, {
method: 'PUT',
credentials: 'omit',
signal,
headers: {
'Content-Range': probe ? `bytes */${file.size}` : `bytes ${offset}-${end - 1}/${file.size}`,
},
body: probe ? new Blob([]) : file.slice(offset, end),
})
} catch (error) {
signal?.throwIfAborted()
if (++failures > 5) throw error
await backoff(failures, signal)
probe = true
continue
}
await response.body?.cancel()
if (response.status === 200 || response.status === 201) {
onProgress(100)
return
}
if (response.status === 429 || response.status >= 500) {
if (++failures > 5) throw new Error('Upload retries exhausted')
await backoff(failures, signal)
probe = true
continue
}
if (response.status !== 308) throw new Error(`Upload failed (HTTP ${response.status})`)
const range = response.headers.get('range')
const match = range === null ? null : /^bytes=0-(\d+)$/.exec(range)
if (range !== null && !match) throw new Error('Invalid acknowledged range')
const next = match ? Number(match[1]) + 1 : 0
if (!Number.isSafeInteger(next) || next < offset || next >= file.size || (!probe && next > end)) {
throw new Error('Invalid acknowledged position')
}
if (!probe && next === offset) {
if (++failures > 5) throw new Error('Upload made no progress')
await backoff(failures, signal)
probe = true
continue
}
if (next > offset) failures = 0
offset = next
onProgress((offset / file.size) * 100)
probe = false
}
}
function backoff(attempt, signal) {
signal?.throwIfAborted()
return new Promise((resolve, reject) => {
const abort = () => {
clearTimeout(timer)
signal.removeEventListener('abort', abort)
reject(signal.reason)
}
const timer = setTimeout(() => {
signal?.removeEventListener('abort', abort)
resolve()
}, 500 * 2 ** (attempt - 1))
signal?.addEventListener('abort', abort, { once: true })
})
}
指数バックオフによる再試行
ネットワークエラー、レート制限、サーバーエラーが発生すると、進捗の更新の間に最大五回再試行します。各再試行では、まず空の PUT で保存済みの位置を問い合わせます。一時停止すると、実行中のリクエストと再試行の待機の両方を中断します。権限エラー、セッションの期限切れ、不正な範囲が発生した場合は、無限に繰り返さずアップロードを停止します。最後のレスポンスが失われた場合でも、次の状態確認で、再アップロードせずに完了を確認できる場合があります。
ページを index.html として保存します。
<!doctype html>
<html lang="en">
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Resumable GCS upload</title>
<label>Upload token <input id="token" type="password" autocomplete="off" /></label>
<label>File <input id="file" type="file" /></label>
<button id="upload">Upload / resume</button>
<button id="pause" disabled>Pause</button>
<progress id="progress" max="100" value="0" aria-label="Upload progress"></progress>
<p id="status" role="status">Choose a file.</p>
<script type="module" src="/app.mjs"></script>
</html>
操作用のコードを app.mjs として保存します。
import { uploadFileWithChunks } from './upload.mjs'
const fileInput = document.getElementById('file')
const tokenInput = document.getElementById('token')
const upload = document.getElementById('upload')
const pause = document.getElementById('pause')
const progress = document.getElementById('progress')
const status = document.getElementById('status')
let session
let controller
fileInput.addEventListener('change', () => {
session = undefined
progress.value = 0
})
pause.addEventListener('click', () => controller?.abort())
upload.addEventListener('click', async () => {
const file = fileInput.files[0]
if (!file) return
controller = new AbortController()
upload.disabled = fileInput.disabled = tokenInput.disabled = true
pause.disabled = false
status.textContent = 'Uploading…'
try {
if (!session) {
const response = await fetch('/sessions', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${tokenInput.value}` },
body: JSON.stringify({ size: file.size }),
signal: controller.signal,
})
if (!response.ok) throw new Error(`Session failed (HTTP ${response.status})`)
session = await response.json()
}
await uploadFileWithChunks(file, session.sessionUrl, {
signal: controller.signal,
onProgress: (value) => { progress.value = value },
})
status.textContent = `Uploaded to ${session.name}`
session = undefined
} catch {
status.textContent = controller.signal.aborted
? 'Paused. Click Upload / resume to continue.'
: 'Upload failed. Retry, or reselect the file to start a new session.'
} finally {
upload.disabled = fileInput.disabled = tokenInput.disabled = false
pause.disabled = true
}
})
バケットのプレースホルダーを置き換え、gcs-upload からサーバーを起動します。入力が表示されないプロンプトで、パスワードマネージャーから 32 文字以上のランダムなシークレットを貼り付けます。http://127.0.0.1:8080 を開き、Upload token にそのシークレットを入力して、空ではない 10 GiB 以下のファイルを選び、Upload / resume をクリックします。Pause で一時停止し、同じアップロードボタンで再開します。アップロード中はファイルを変更しないでください。終了したら Ctrl+C でサーバーを停止します。
(
export BUCKET='your-existing-private-bucket'
read -r -s -p 'Upload token: ' UPLOAD_TOKEN &&
printf '\n' &&
export UPLOAD_TOKEN &&
node server.mjs
)
保存されたバイトの検証
GCS が完了を確認すると、ページに
Uploaded to と、その後にオブジェクト名が表示されます。後続の処理でオブジェクトを使用する前に、選択したローカルファイルとバイトを比較してください。同じプロジェクト内に、以下を verify.mjs として保存します。メタデータを確認してダウンロード対象をその正確な世代に固定し、ファイル全体をメモリーに保持せず、両方のファイルをストリーミングで SHA-256 に通します。
import { createHash } from 'node:crypto'
import { createReadStream } from 'node:fs'
import { stat } from 'node:fs/promises'
import { GoogleAuth } from 'google-auth-library'
const [file, name, secondsText = '7200', ...extra] = process.argv.slice(2)
const seconds = Number(secondsText)
if (!file || !name || !process.env.BUCKET || extra.length ||
!Number.isSafeInteger(seconds) || seconds < 1 || seconds > 86400) {
console.error('Usage: BUCKET=your-bucket node verify.mjs FILE OBJECT_NAME [SECONDS: 1–86400]')
process.exit(1)
}
let phase = 'local-file'
// A process deadline also covers ADC refresh, which has its own HTTP transport.
const deadline = setTimeout(() => {
console.error(`Verification deadline exceeded during ${phase}. Retry with a larger SECONDS value.`)
process.exit(124)
}, seconds * 1000)
try {
const info = await stat(file)
if (!info.isFile() || info.size < 1 || info.size > 10 * 1024 ** 3) {
throw new Error('Choose a nonempty regular file of at most 10 GiB')
}
async function hash(stream) {
const digest = createHash('sha256')
let bytes = 0
for await (const chunk of stream) {
bytes += chunk.length
digest.update(chunk)
}
return { bytes, sha256: digest.digest('hex') }
}
const local = await hash(createReadStream(file))
phase = 'credentials'
const auth = new GoogleAuth({ scopes: ['https://www.googleapis.com/auth/devstorage.read_only'] })
const client = await auth.getClient()
await client.getAccessToken()
phase = 'metadata'
const url = new URL(`https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(process.env.BUCKET)}/o/${encodeURIComponent(name)}`)
const metadata = await client.request({ url: url.href, retry: false, timeout: 0 })
const object = metadata.data
if (object.name !== name || !/^[1-9]\d*$/.test(object.generation) ||
Number(object.size) !== local.bytes) throw new Error('Object metadata does not match the local file')
url.search = new URLSearchParams({ alt: 'media', generation: object.generation })
phase = 'download'
const response = await client.request({ url: url.href, responseType: 'stream', retry: false, timeout: 0 })
const stored = await hash(response.data)
phase = 'integrity'
if (stored.bytes !== local.bytes || stored.sha256 !== local.sha256) {
throw new Error('Stored bytes do not match the local file')
}
console.log(`Verified ${stored.bytes} bytes (generation ${object.generation}).`)
} catch (error) {
const status = Number.isInteger(error?.response?.status) ? error.response.status : null
const data = error?.response?.data
const oauthError = ['invalid_grant', 'invalid_client', 'unauthorized_client'].includes(data?.error)
? data.error : null
const oauthSubtype = data?.error_subtype === 'invalid_rapt' ? 'invalid_rapt' : null
console.error(JSON.stringify({ error: 'verification-failed', phase, status, oauthError, oauthSubtype }))
console.error(`Verification failed during ${phase}. Check ADC and bucket access for credentials/metadata errors; check the selected file and object for an integrity error.`)
process.exitCode = 1
} finally {
clearTimeout(deadline)
}
別のターミナルを開き、gcs-upload から実行します。ファイルパスを置き換え、ページから完全なオブジェクト名をコピーしてください。
BUCKET='your-existing-private-bucket' node verify.mjs './large-file.bin' 'uploads/owner/your-object-id' 7200
10 GiB 以下のファイルでは、検証全体の既定の制限時間は 7,200 秒(二時間)です。これには、ローカルでのハッシュ計算、認証情報の取得と OAuth の更新、メタデータの取得、ダウンロード全体が含まれます。接続に応じて異なる制限時間が必要な場合は、SECONDS を 1 から 86,400 に設定してください。10 GiB のダウンロードだけでも、二時間以内に収めるには約 12 Mbit/s が必要です。ここでは SDK による追加のボディ全体のタイムアウトはありません。制限時間に達すると、プロセスはステータス 124 で終了し、検証済みの結果は出力しません。アクセスエラーを別途調査したうえで、制限時間を延ばして再実行してください。制限時間を延ばしても、不正な認証情報やバイトの不一致は解決しません。検証ツールは保存済みのオブジェクトを読み取るだけで、再アップロードや変更は行いません。
再読み込み後も進捗を保持するには
ファイルとセッションは、このページのメモリー内に保持されます。一時停止しても両方が保持されますが、再読み込みや別のファイルの選択では、新しいセッションが始まります。未完了のセッションは、完成したオブジェクトを公開することなく期限切れになります。この例では、再読み込み後にセッションを復元しません。
複数ユーザー向けのアプリケーションでは、認証に基づくサーバー側のセッション所有権管理と、再選択したファイルの内容が同一であることを検証する仕組みが必要です。名前、サイズ、保存済みの進捗率だけでは不十分です。
セキュリティとパフォーマンスのベストプラクティス
トークンは、信頼できる単一の所有者を識別します。サーバーのバインド先はループバックのままにしてください。この例には、複数ユーザー向けのログインシステムやクォータは含まれません。セッション URL はアップロード用の認証情報なので、ログ、ブラウザーストレージ、共有するスクリーンショットに残さないでください。Google の認証情報は Node.js 内に保持されます。
ブラウザーは 8 MiB のチャンクを一度に一つ送信し、受領確認後にのみ進捗を報告します。一時停止すると現在のリクエストと再試行の待機を中断しますが、一時停止した時点ですでに一部のバイトが保存されている場合があります。次の試行では、GCS に受け付け済みのオフセットを問い合わせます。空のファイルと 10 GiB を超えるファイルは拒否されます。セッションを継続できないエラーが発生した場合は、ファイルを再選択して最初からやり直す必要があります。新規作成のみを許可する事前条件により、保存先の名前が衝突しても既存のオブジェクトは置き換えられません。
より充実したファイル選択インターフェースについては、Uppyを参照してください。組み込む際には、アプリケーションに適したアップロード用の転送手段も必要です。
