Web Workers とサイズ制限付きストリームによるファイルアップロード
アップロードパイプラインでページのメインスレッドとは別にファイルを処理するには、ワーカーを使います。この例では File を段階的に読み取り、ワーカーごとに一度に 1 MiB のチャンクを一つ送信し、受信側の最終確認を待ってからダウンロードリンクを表示します。二つのワーカーで別々のファイルを処理し、残りのファイルは件数を制限したキューで待機します。
従来のファイルアップロードの課題
通常の非同期アップロードでは、File を
FormData に直接追加できます。先に
FileReader で読み取る必要はありません。MDN の FormData の例を参照してください。ファイルの送信だけが必要なら、まずはこの方法を使ってください。ワーカーでネットワーク帯域幅が増えるわけではなく、このチュートリアルは速度や総メモリ使用量についての効果を主張するものではありません。
ここで扱う別の課題は、複数のファイルにわたる段階的な読み取りと受信確認の制御です。ワーカーの入門記事では基本的なメッセージを解説しています。チャンクの並列送信チュートリアルでは、一つのファイル内でリクエストを並行実行しますが、ここではファイルごとに順次実行します。
Web Workers とストリームの概要
Web Workers
ワーカーはファイルの処理やリクエストの実行はできますが、ページの DOM は更新できません。ページは構造化クローンで各 File を送信し、ワーカーからのメッセージを表示します。送信のためにファイルを
ArrayBuffer に読み込むことはありません。Web Workers の使用方法を参照してください。
JavaScript のストリーム
Blob.stream()は
File に継承され、バイトストリームを提供します。ワーカー内でも利用できます。その読み取り境界は、このアップロードプロトコルの境界とは一致しません。以下のジェネレーターは読み取り結果を 1 MiB のチャンクにまとめ、最後の短いチャンクはそのまま保持します。
アーキテクチャの概要
ページで受け付けるファイルは最大四つで、各ファイルは最大 8 MiB です。空のファイルも受け付けます。プールで実行するタスクは最大二つです。各ワーカーはアップロードを作成し、チャンクを読み取り、その multipart POST の受信確認を待ち、最後に受信側へアップロードの完了を要求します。進捗には受信確認済みのファイルバイト数を使い、転送中のバイト数は含めません。
受信側の実装も以下に示します。オフセットと長さを検証し、最大四つのファイルをメモリに保持して、完了したファイルをダウンロードできるようにします。アップロードは完了済みのものも含め、作成から 60 秒で期限切れになります。サーバーを停止すると、すべてのファイルが失われます。これはローカルのプロトコル実演用で、再試行、再読み込み後の復旧、永続ストレージはありません。
ローカルアップロードデモのセットアップ
このローカルの例には、Node.js 26.13.0、またはそれより新しい保守対象の Node.js 26 パッチ版と、モジュールワーカー、Blob.stream()、AbortSignal.timeout() に対応するブラウザーを使います。2026年11月7日に、Linux 上の Node.js 26.13.0 と Chromium 145 で一連の処理を再テストしました。この受信サーバーは localhost 用です。
以前のテストでは、10月21日のセキュリティ更新前の Node.js 26.8.1 を使用しました。Node 26 は 2026年10月1日時点では保守対象の Current リリースで、10月28日に LTS に移行しました。デプロイ用のランタイムを選ぶ際は、リリーススケジュールを確認してください。
Bash で新しいディレクトリを作成します。作成や移動に失敗した場合は作業を止め、別の名前を選んでからファイルを保存してください。依存関係のインストールや、親プロジェクトのビルド設定は不要です。
mkdir worker-stream-demo && cd worker-stream-demo
HTML を index.html として保存し、メインスレッド用の二つのブロックを表示順に main.ts に配置します。ワーカーと受信サーバーはそれぞれ
upload-worker.ts と server.mts として保存してください。受信サーバーはブラウザー用スクリプトを配信する際に TypeScript の型注釈を除去します。ブラウザーが .ts ソースを直接実行することはありません。
メインスレッド(main.js)
これを index.html として保存します。スクリプトは同じローカルオリジンから配信されます。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Worker stream uploads</title>
</head>
<body>
<main>
<h1>Worker stream uploads</h1>
<label for="file-input">Up to four files, each at most 8 MiB</label>
<input id="file-input" type="file" multiple />
<button id="upload-files" type="button">Upload files</button>
<button id="cancel-uploads" type="button" disabled>Cancel uploads</button>
<p id="status" role="status">Choose files.</p>
<ul id="results" aria-label="Upload results"></ul>
</main>
<script type="module" src="/main.js"></script>
</body>
</html>
main.ts の先頭に、このプールを配置します。完了したタスクを切り離してから UI を呼び出し、コールバックが例外を投げてもキューを進めます。ワーカースクリプトやメッセージのシリアライズに失敗した場合は、壊れたワーカーを再利用せず、プール全体をキャンセルします。
export type WorkerReply =
| { type: 'progress'; progress: number; message: string }
| { type: 'complete'; message: string; url: string }
| { type: 'error'; message: string }
type Callbacks = {
onProgress?: (progress: number, message: string) => void
onComplete?: (message: string, url: string) => void
onError?: (message: string) => void
}
type Task = { id: string; file: File }
class WorkerPool {
closed = false
workers: Worker[] = []
idleWorkers: Worker[] = []
taskQueue: Task[] = []
taskCallbacks = new Map<string, Callbacks>()
currentTasks = new Map<Worker, Task>()
constructor(script: string, size = 2) {
if (!Number.isInteger(size) || size < 1 || size > 2) throw new Error('Use one or two workers')
try {
for (let index = 0; index < size; index++) {
const worker = new Worker(script, { type: 'module' })
worker.onmessage = (event: MessageEvent<WorkerReply>) => this.handleWorkerMessage(worker, event.data)
worker.onerror = (event) => {
event.preventDefault()
this.terminate('An upload worker failed. Try again.')
}
worker.onmessageerror = () => this.terminate('An upload worker failed. Try again.')
this.workers.push(worker)
this.idleWorkers.push(worker)
}
} catch (error) {
this.terminate()
throw error
}
}
processFile(file: File, callbacks: Callbacks, id = crypto.randomUUID()): string {
if (this.closed) throw new Error('The upload pool is closed.')
if (this.taskCallbacks.size >= 4) throw new Error('The upload queue is full.')
const task = { id, file }
this.taskCallbacks.set(task.id, callbacks)
const worker = this.idleWorkers.pop()
if (worker) this.runTask(worker, task)
else this.taskQueue.push(task)
return task.id
}
runTask(worker: Worker, task: Task): void {
this.currentTasks.set(worker, task)
try {
worker.postMessage(task)
} catch {
this.terminate('An upload worker failed. Try again.')
}
}
handleWorkerMessage(worker: Worker, data: WorkerReply): void {
if (this.closed) return
const task = this.currentTasks.get(worker)
if (!task) return
const callbacks = this.taskCallbacks.get(task.id)
if (!callbacks) return
if (data.type === 'progress') {
callbacks.onProgress?.(data.progress, data.message)
return
}
this.currentTasks.delete(worker)
this.taskCallbacks.delete(task.id)
try {
if (data.type === 'complete') callbacks.onComplete?.(data.message, data.url)
else callbacks.onError?.(data.message)
} finally {
if (!this.closed) {
const next = this.taskQueue.shift()
if (next) this.runTask(worker, next)
else this.idleWorkers.push(worker)
}
}
}
terminate(message = 'Upload canceled.'): void {
if (this.closed) return
this.closed = true
for (const worker of this.workers) worker.terminate()
this.workers = []
this.idleWorkers = []
this.taskQueue = []
this.currentTasks.clear()
const callbacks = [...this.taskCallbacks.values()]
this.taskCallbacks.clear()
const errors: unknown[] = []
for (const callback of callbacks) {
try {
callback.onError?.(message)
} catch (error) {
errors.push(error)
}
}
if (errors.length > 0) throw new AggregateError(errors, 'Upload cancellation callbacks failed.')
}
}
このブロックを main.ts に追加します。バッチの実行中やクリーンアップ中は、ファイル選択と再送信を無効にします。各行は一つのファイルに対応するため、失敗を別のファイルの結果と取り違えることはありません。名前はテキストとして挿入し、HTML やストレージのパスとして解釈することはありません。
const input = document.getElementById('file-input')
const upload = document.getElementById('upload-files')
const cancel = document.getElementById('cancel-uploads')
const status = document.getElementById('status')
const results = document.getElementById('results')
if (!(input instanceof HTMLInputElement) || !(upload instanceof HTMLButtonElement) ||
!(cancel instanceof HTMLButtonElement) || !status || !results) throw new Error('Missing controls')
let pool: WorkerPool | null = null
let running = false
cancel.addEventListener('click', () => pool?.terminate())
window.addEventListener('pagehide', () => pool?.terminate())
input.addEventListener('change', () => {
if (!running) status.textContent = 'Ready to upload.'
})
upload.addEventListener('click', async () => {
if (running) return
const files = Array.from(input.files ?? [])
if (files.length < 1 || files.length > 4 || files.some((file) => file.size > 8 * 1024 * 1024)) {
status.textContent = 'Choose one to four files, each at most 8 MiB.'
return
}
running = true
input.disabled = upload.disabled = true
cancel.disabled = false
results.replaceChildren()
status.textContent = 'Uploading…'
const failedIds: string[] = []
let failures = 0
try {
const batchPool = new WorkerPool('/upload-worker.js')
pool = batchPool
const jobs = files.map((file) => new Promise<void>((resolve) => {
const id = crypto.randomUUID()
const row = document.createElement('li')
const name = document.createElement('p')
name.textContent = file.name
const progress = document.createElement('progress')
progress.max = 100
progress.value = 0
progress.setAttribute('aria-label', `Acknowledged bytes for ${file.name}`)
const message = document.createElement('p')
message.setAttribute('role', 'status')
message.textContent = 'Queued.'
row.append(name, progress, message)
results.append(row)
batchPool.processFile(file, {
onProgress(value, text) { progress.value = value; message.textContent = text },
onComplete(text, url) {
progress.value = 100
message.textContent = text
const link = document.createElement('a')
link.href = url
link.download = 'upload.bin'
link.textContent = `Download ${file.name}`
row.append(link)
resolve()
},
onError(text) {
failures++
failedIds.push(id)
message.textContent = text
resolve()
},
}, id)
}))
await Promise.all(jobs)
status.textContent = failures === 0 ? 'All uploads complete.' : 'Some uploads did not complete.'
} catch {
status.textContent = 'Could not start the upload workers. Try again.'
} finally {
pool?.terminate()
pool = null
let cleanupFailed = false
for (const id of failedIds) {
try {
const response = await fetch(`/uploads/${id}`, {
method: 'DELETE', headers: { 'X-Upload-Demo': '1' }, signal: AbortSignal.timeout(5000),
})
if (!response.ok) cleanupFailed = true
} catch { cleanupFailed = true }
}
if (cleanupFailed) status.textContent += ' Cleanup was not confirmed; uploads will expire.'
running = false
input.disabled = upload.disabled = false
cancel.disabled = true
}
})
ワーカーの実装(upload-worker.js)
これを upload-worker.ts として保存します。各 POST を待つことで、前のリクエストが保留中の間にジェネレーターが次のアプリケーションチャンクを生成するのを防ぎます。ただし、ブラウザー内部ではストリームの読み取り結果やリクエストデータがバッファリングされる場合があります。1 MiB というチャンクサイズは、ブラウザーの総メモリ使用量の上限ではありません。
import type { WorkerReply } from './main.js'
declare const self: DedicatedWorkerGlobalScope
const CHUNK_SIZE = 1024 * 1024
async function* readChunks(file: Blob): AsyncGenerator<Uint8Array<ArrayBuffer>> {
const reader = file.stream().getReader()
let buffer = new Uint8Array(CHUNK_SIZE)
let used = 0
let finished = false
try {
while (true) {
const { done, value } = await reader.read()
if (done) { finished = true; break }
let offset = 0
while (offset < value.length) {
const length = Math.min(CHUNK_SIZE - used, value.length - offset)
buffer.set(value.subarray(offset, offset + length), used)
used += length
offset += length
if (used === CHUNK_SIZE) {
yield buffer
buffer = new Uint8Array(CHUNK_SIZE)
used = 0
}
}
}
if (used > 0) yield buffer.subarray(0, used)
} finally {
if (!finished) await reader.cancel().catch(() => {})
reader.releaseLock()
}
}
function send(message: WorkerReply): void { self.postMessage(message) }
async function request(path: string, options: RequestInit): Promise<Response> {
const response = await fetch(path, {
...options, headers: { ...options.headers, 'X-Upload-Demo': '1' },
signal: AbortSignal.timeout(5000),
})
if (!response.ok) throw new Error('Upload request rejected')
return response
}
self.onmessage = async (event: MessageEvent<{ file: File; id: string }>) => {
const { file, id } = event.data
try {
if (!(file instanceof File) || file.size > 8 * CHUNK_SIZE) throw new Error('Invalid file')
await request(`/uploads/${id}`, { method: 'POST', headers: { 'Upload-Length': String(file.size) } })
send({ type: 'progress', progress: 0, message: 'Uploading…' })
let acknowledged = 0
for await (const chunk of readChunks(file)) {
const form = new FormData()
form.append('offset', String(acknowledged))
form.append('chunk', new Blob([chunk]), 'chunk.bin')
await request(`/uploads/${id}/chunks`, { method: 'POST', body: form })
acknowledged += chunk.length
send({ type: 'progress', progress: 100 * acknowledged / file.size,
message: `${acknowledged} / ${file.size} bytes acknowledged.` })
}
send({ type: 'progress', progress: 100, message: 'Confirming…' })
const response = await request(`/uploads/${id}/complete`, { method: 'POST' })
if (await response.text() !== String(file.size)) throw new Error('Unexpected acknowledgment')
send({ type: 'complete', message: 'Upload complete.', url: `/uploads/${id}/file` })
} catch {
send({ type: 'error', message: 'Upload failed. Try again.' })
}
}
ここでは ReadableStream のリクエストボディではなく、個別の multipart リクエストを使います。multipart の
Content-Type 境界はブラウザーに設定させてください。空のファイルはチャンクを送信しませんが、完了処理は必要です。
ワーカーでファイル全体を一度に読み取らない理由は?
ファイル全体に対する arrayBuffer() 呼び出しをワーカーに移しても、アプリケーションにはファイル全体のバッファが作成されます。この例の結合処理では、1 MiB のバッファと現在のストリーム読み取り結果を保持し、実行中の各タスクで受信確認を待つチャンクリクエストは一つだけです。Blob やネットワーク実装が追加のコピーを作る場合もあります。キュー内のタスクは、読み取り済みのバイト列ではなくファイルハンドルを保持します。
小さなワーカープールの構築
上記のプールにはワーカーが二つあり、保留中のタスクは最大四つです。これはスケジューリング上の制限であり、CPU 数に基づく推奨値ではありません。ワーカーを増やしても有効なスループットは増えず、処理、メモリ、リクエストのオーバーヘッドだけが増える場合があります。実際の処理工程と受信側に合わせて計測してください。
チャンクのローカル受信
これを server.mts として保存します。.mts 拡張子により、CommonJS プロジェクト内でも確実に ES モジュールモードで実行されます。stripTypeScriptTypes()は型注釈を除去しますが、スクリプトの型チェックは行いません。
import { readFile } from 'node:fs/promises'
import { createServer } from 'node:http'
import type { IncomingMessage, ServerResponse } from 'node:http'
import { stripTypeScriptTypes } from 'node:module'
const CHUNK_SIZE = 1024 * 1024
const MAX_BODY = CHUNK_SIZE + 4096
const TTL_MS = 60_000
type Upload = { bytes: Buffer; received: number; complete: boolean; expires: number }
const uploads = new Map<string, Upload>()
class HttpError extends Error {
status: number
constructor(status: number, message: string) { super(message); this.status = status }
}
function expire(): void {
for (const [id, upload] of uploads) {
if (upload.expires <= Date.now()) uploads.delete(id)
}
}
async function readBody(req: IncomingMessage, limit: number): Promise<Buffer> {
const bytes = Buffer.alloc(limit)
let length = 0
// Keep the connection long enough to report an oversize body.
for await (const part of req.iterator({ destroyOnReturn: false })) {
if (!Buffer.isBuffer(part)) throw new HttpError(400, 'Expected bytes')
if (length + part.length > limit) throw new HttpError(413, 'Body too large')
part.copy(bytes, length)
length += part.length
}
return bytes.subarray(0, length)
}
async function main(): Promise<void> {
const assets = new Map<string, string>([['/', await readFile(new URL('./index.html', import.meta.url), 'utf8')]])
for (const name of ['main', 'upload-worker']) {
assets.set(`/${name}.js`, stripTypeScriptTypes(await readFile(new URL(`./${name}.ts`, import.meta.url), 'utf8')))
}
const port = Number(process.argv[2] ?? 0)
if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Invalid port')
let origin = ''
let active = 0
async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
if (req.headers.host !== new URL(origin).host ||
(req.headers.origin !== undefined && req.headers.origin !== origin)) throw new HttpError(403, 'Use the printed local URL')
const method = req.method
if (method !== 'GET' && req.headers['x-upload-demo'] !== '1') throw new HttpError(403, 'Missing demo header')
const path = new URL(req.url ?? '/', origin).pathname
const isChunk = method === 'POST' && path.endsWith('/chunks')
const body = await readBody(req, isChunk ? MAX_BODY : 0)
// Parse before looking up an upload: pending work cannot retain a deleted session.
let chunk: Uint8Array | undefined
let offset: string | undefined
if (isChunk) {
const contentType = req.headers['content-type']
if (typeof contentType !== 'string' || !contentType.startsWith('multipart/form-data;')) throw new HttpError(400, 'Expected multipart data')
let form: FormData
try {
form = await new Request(origin, { method: 'POST', headers: { 'Content-Type': contentType }, body: new Uint8Array(body) }).formData()
} catch { throw new HttpError(400, 'Invalid multipart data') }
const value = form.get('chunk')
const position = form.get('offset')
if (!(value instanceof Blob) || value.size > CHUNK_SIZE || typeof position !== 'string' ||
!/^(0|[1-9]\d*)$/.test(position) || [...form.keys()].length !== 2) throw new HttpError(400, 'Invalid chunk fields')
chunk = new Uint8Array(await value.arrayBuffer())
offset = position
}
expire()
res.setHeader('Cache-Control', 'no-store')
res.setHeader('X-Content-Type-Options', 'nosniff')
const asset = assets.get(path)
if (method === 'GET' && asset !== undefined) {
res.setHeader('Content-Type', path === '/' ? 'text/html; charset=utf-8' : 'text/javascript')
res.end(asset)
return
}
const match = /^\/uploads\/([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})(?:\/(chunks|complete|file))?$/.exec(path)
if (!match) throw new HttpError(404, 'Unknown route')
const [, id, operation] = match
if (method === 'POST' && operation === undefined) {
const size = req.headers['upload-length']
if (typeof size !== 'string' || !/^(0|[1-9]\d*)$/.test(size) || Number(size) > 8 * CHUNK_SIZE) throw new HttpError(400, 'Expected a size from 0 to 8 MiB')
if (uploads.has(id)) throw new HttpError(409, 'Upload already exists')
if (uploads.size >= 4) throw new HttpError(503, 'Upload capacity reached')
uploads.set(id, { bytes: Buffer.alloc(Number(size)), received: 0, complete: false, expires: Date.now() + TTL_MS })
res.writeHead(201).end()
return
}
if (method === 'DELETE' && operation === undefined) {
uploads.delete(id)
res.writeHead(204).end()
return
}
const upload = uploads.get(id)
if (!upload) throw new HttpError(404, 'Upload missing or expired')
if (isChunk && operation === 'chunks') {
const expected = Math.min(CHUNK_SIZE, upload.bytes.length - upload.received)
if (!chunk || chunk.length === 0 || chunk.length !== expected || offset !== String(upload.received) || upload.complete) throw new HttpError(409, 'Unexpected chunk offset or length')
upload.bytes.set(chunk, upload.received)
upload.received += chunk.length
res.writeHead(204).end()
return
}
if (method === 'POST' && operation === 'complete') {
if (upload.received !== upload.bytes.length) throw new HttpError(409, 'Missing bytes')
upload.complete = true
res.end(String(upload.received))
return
}
if (method === 'GET' && operation === 'file') {
if (!upload.complete) throw new HttpError(409, 'Upload is not complete')
res.setHeader('Content-Type', 'application/octet-stream')
res.setHeader('Content-Disposition', 'attachment; filename="upload.bin"')
res.end(upload.bytes)
return
}
throw new HttpError(405, 'Unsupported operation')
}
const server = createServer({ requestTimeout: 10_000, headersTimeout: 10_000 }, (req, res) => {
if (active >= 6) { res.writeHead(503, { Connection: 'close' }).end('Too many requests'); return }
active++
let handled = false
let closed = false
const deadline = setTimeout(() => { req.destroy(); res.destroy() }, 10_000)
function release(): void {
if (handled && closed) { clearTimeout(deadline); active-- }
}
res.once('close', () => { closed = true; release() })
handle(req, res).catch((error: unknown) => {
const status = error instanceof HttpError ? error.status : 500
const message = error instanceof HttpError ? error.message : 'Request failed'
if (!res.destroyed) res.writeHead(status, { Connection: 'close' }).end(message)
}).finally(() => { handled = true; release() })
})
server.maxConnections = 16
await new Promise<void>((resolve, reject) => {
server.once('error', reject)
server.listen(port, '127.0.0.1', () => resolve())
})
const address = server.address()
if (!address || typeof address === 'string') throw new Error('Missing server address')
origin = `http://127.0.0.1:${address.port}`
setInterval(expire, 1000).unref()
process.once('SIGINT', () => {
server.close()
server.closeAllConnections()
})
console.log(`Open ${origin}`)
}
main().catch((error: unknown) => {
console.error(error instanceof Error ? error.message : 'Could not start the server')
process.exitCode = 1
})
登録された四つのファイルバッファは、合計で最大 32 MiB です。リクエスト解析には追加のバッファを使います。受け付ける各ボディの上限は、1 MiB に multipart のオーバーヘッド 4 KiB を加えたサイズで、末尾のデータも含みます。同時に動作するハンドラーは最大六つです。ダウンロードは削除や期限切れの後もファイルバッファを保持する場合があるため、処理とレスポンスのクローズが両方完了するまでハンドラーのスロットを使用し続けます。これらはアプリケーションの動作上の制限であり、プロセスの総メモリ使用量やガベージコレクションのタイミングを示すものではありません。
四つのファイルを保存したディレクトリで、次のコマンドをフォアグラウンドで実行します。
node server.mts
表示された http://127.0.0.1:PORT の URL を開きます。ファイルを選択して Upload files をクリックします。各行はチャンクの受信確認後に Confirming… になります。完了レスポンスが成功した場合にのみ、Upload complete. とダウンロードリンクが表示されます。リンクをクリックすると、受信したバイト列をブラウザーから upload.bin として保存できます。バイト数の一致は整合性チェックサムではありません。この例を検証する際は、ダウンロードしたファイルを元のファイルと比較してください。
Ctrl+C でサーバーを停止すると、接続が閉じられます。特定の空きポートを選ぶには、その番号を node server.mts に追加します。ポートが使用中、またはソースファイルがない場合は、準備完了の URL を表示せずエラーで終了します。
ブラウザーの互換性
サポート対象のブラウザーバージョンが Worker、Blob.stream()、AbortSignal.timeout() に対応しているか確認してください。この例では、スレッド間でストリームを転送しません。ブラウザーのリクエストタイムアウトは五秒のアクティブ時間を使い、中断されたワーカーでは一時停止する場合があります。受信側には別途十秒の期限があります。この手順では、ほかのブラウザーや OS は検証していません。
メモリ管理のベストプラクティス
ワーカーごとに転送中のアプリケーションチャンクを一つにし、ファイルハンドルのキューも小さく保ってください。リクエストが失敗すると、ジェネレーターは未完了のストリームをキャンセルし、リーダーのロックを解放します。ページはバッチ終了時、キャンセル時、および pagehide 時にすべてのワーカーを終了します。
バッチが保留中に Cancel uploads をクリックしてください。実行中およびキュー内の行は Upload canceled. になり、完了済みの行は結果を保持します。ページは失敗またはキャンセルされたアップロード ID の削除を試み、クリーンアップが決着するまでコントロールを無効に保ちます。作成レスポンスの喪失、ページのクローズ、削除の失敗により、期限切れまでバイト列が残る場合があります。ワーカーを終了しても、その
finally ブロックは実行されず、受信側がすでに受け付けたリクエストも取り消されません。
セキュリティと耐障害性
サーバーは 127.0.0.1 にバインドし、ホストとブラウザーのオリジンを検証して、変更操作にカスタムヘッダーを要求します。クロスオリジンアクセスの許可、ファイル名のパスとしての解釈、アップロードされたバイト列の実行可能な HTML としての配信は行いません。これらはローカルデモの境界であり、認証やコンテンツ検証ではありません。この受信サーバーを公開アップロードサービスとして公開しないでください。
デプロイするサービスには、認証、認可、ユーザーごとのクォータ、HTTPS、永続ストレージ、利用側に適した検証が必要です。このオフセットプロトコルは、重複したチャンクや順序の異なるチャンクを意図的に拒否します。再試行を追加するには冪等性の取り決めが必要です。再読み込み後に復旧するには、状態の永続化と受信側の状態との照合が必要です。
Web Workers のデバッグ
ブラウザーの開発者ツールで、ワーカーのリクエストとメッセージを調べてください。スクリプトの読み込みエラーはプールをキャンセルし、HTTP の失敗は対応する行に Upload failed. Try again. として表示されます。409 レスポンスは、オフセットの誤り、チャンク長の誤り、またはファイルの未完了を示します。503 は、完了済みのファイルも含めて四つのアップロードスロットがすべて使用中であることを意味する場合があります。期限切れを待ってから再試行してください。存在しない ID や期限切れの ID には 404 が返されます。
よくある落とし穴
- 受信確認済みのバイト数が 100% になった時点で完了とみなすこと。最後の POST はまだ失敗する可能性があります。
- キャンセルした処理が決着する前に入力を再度有効にすること。このページはクリーンアップの試行が終わるまで待機します。
- ストリームの読み取りサイズと HTTP チャンクサイズが一致すると思い込むこと。結合処理が短い端数を処理します。
- ワーカーを終了するとサーバーの状態も削除されると思い込むこと。期限切れの仕組みは引き続き必要です。
- キュー内のすべてのファイルを事前に読み取ること。段階的に処理する仕組みの意味がなくなります。
重要なポイント
空のファイルと 1 MiB を少し超えるバイナリファイルで試し、ダウンロードした各結果を入力と比較してください。重要なのは、実行中のタスク数を少なく保ちながら、段階的な読み取りからチャンクの受信確認、ファイルの完了確認までを一貫して扱うことです。本番環境で再開可能なアップロードを実現するには、tus などの保守されているプロトコルと、互換性のある受信サーバーを出発点にしてください。Uppy の tus プラグインは、保守されているブラウザークライアントを提供します。
