Web Worker とローカル受信サーバーによるファイルアップロード
Web Worker を使うと、ページのメインスレッドとは別にファイルを処理し、メッセージでアップロードの進捗を通知できます。この例では、単一の専用ワーカーを実行可能なローカル受信サーバーに接続します。ファイルを選択してチャンクを順次送信し、受信サーバーが実際に受け入れたファイルをダウンロードします。
ワーカーに任せる処理の選択
通常の非同期アップロードにはワーカーは不要です。パイプラインでファイルの解析や変換も必要な場合に使用します。ワーカーはリクエストを送信できますが、ページの DOM は更新できません。代わりに、ページがワーカーのメッセージを描画します。Web Workers の使用方法を参照してください。
ここでは、小さなファイルのハッシュ計算を処理の一例として使います。Web Crypto 自体が非同期のため、この例はワーカーによるアップロードの高速化や総メモリ使用量の削減を主張するものではありません。複数ファイルのキュー処理とストリームの逐次読み取りは、別のワーカープールとストリームのチュートリアルで扱います。このページでは、単一のファイルと単一のワーカーに限定します。
Node.js 24.15.0 またはそれより新しい保守対象リリース、Yarn 4 を備えた Corepack、Bash、およびモジュールワーカー、Web Crypto、AbortSignal.timeout() に対応するブラウザーを使用してください。完全なサンプルは、Linux 上の Node.js 24.15.0 および 26.8.1 と
Chromium 145 でテスト済みです。2026年10月2日時点で Node 24 は LTS、Node 26 は Current です。Node のリリース一覧から最新のパッチを選んでください。Corepack がない場合は、先に Yarn のインストール手順に従ってください。
ローカルプロジェクトとページの作成
次のコードを Bash に貼り付けてください。既存のディレクトリは使用せず、専用のロックファイルで Yarn プロジェクトを分離し、インストールに失敗した場合は元のディレクトリに戻ります。失敗後も新しいデモ用ディレクトリが残る場合があります。内容を確認し、別の新しい名前を選んでから再試行してください。以降のファイルはすべて
worker-upload-demo 内に配置します。
if (
mkdir worker-upload-demo &&
cd worker-upload-demo &&
printf '%s\n' '{"name":"worker-upload-demo","private":true,"type":"module","packageManager":"yarn@4.12.0"}' > package.json &&
printf '%s\n' 'nodeLinker: node-modules' 'enableGlobalCache: false' 'globalFolder: .yarn/global' 'npmRegistryServer: https://registry.npmjs.org' > .yarnrc.yml &&
touch yarn.lock &&
mkdir src &&
corepack yarn add --dev --exact vite@8.3.1 typescript@6.0.3 @types/node@26.6.3
); then
cd worker-upload-demo
else
printf '%s\n' 'Setup failed; inspect the new directory before retrying.' >&2
false
fi
これを index.html として保存してください。受信サーバーは、ビルド済みページとアップロード用ルートを同じループバックオリジンから配信します。このファイルを直接開くのではなく、表示された HTTP URL を開いてください。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Dedicated worker upload</title>
</head>
<body>
<main>
<h1>Dedicated worker upload</h1>
<label for="fileInput">File to upload, up to 16 MiB</label>
<input type="file" id="fileInput" />
<button type="button" id="uploadBtn">Upload</button>
<button type="button" id="cancelBtn" disabled>Cancel</button>
<label id="progressLabel" for="uploadProgress">Upload progress</label>
<progress id="uploadProgress" aria-labelledby="progressLabel" value="0" max="100"></progress>
<p id="status" role="status">Choose a file.</p>
<output id="checksum" aria-label="Receiver SHA-256"></output>
<p><a id="download" hidden download="received.bin">Download received file</a></p>
</main>
<script type="module" src="/src/main.ts"></script>
</body>
</html>
メッセージ契約の定義とチェック
src/worker-types.ts を保存してください。完了メッセージには受信サーバーのチェックサムとダウンロード URL が含まれるため、ページに確認可能な結果を表示できます。
export interface WorkerMessage {
file: File
}
export type WorkerResponse =
| { type: 'processed' }
| { type: 'progress'; percent: number }
| { type: 'confirming' }
| { type: 'complete'; sha256: string; url: string }
| { type: 'error'; message: string }
ページ用に tsconfig.json を保存してください。
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "Bundler",
"target": "ES2022",
"lib": ["ES2022", "DOM", "DOM.Iterable"],
"types": [],
"strict": true,
"verbatimModuleSyntax": true,
"allowImportingTsExtensions": true,
"noEmit": true
},
"include": ["src/main.ts", "src/worker-types.ts"]
}
tsconfig.worker.json を保存してください。ワーカーを個別にチェックすることで、DOM とワーカーのグローバル定義の混在を避けます。Vite がモジュールワーカーをビルドし、TypeScript がその型をチェックします。
{
"extends": "./tsconfig.json",
"compilerOptions": { "lib": ["ES2022", "WebWorker"] },
"include": ["src/upload.worker.ts", "src/worker-types.ts"]
}
Node の受信サーバー用に tsconfig.server.json を保存してください。
{
"extends": "./tsconfig.json",
"compilerOptions": {
"module": "NodeNext",
"moduleResolution": "NodeNext",
"lib": ["ES2022"],
"types": ["node"]
},
"include": ["server.mts"]
}
ワーカーからチャンクを順次送信
src/upload.worker.ts を保存してください。5 MiB 以下のファイルは送信前にハッシュを計算します。それより大きいファイルでは、ファイル全体のハッシュ計算を省略します。各リクエストは生の Blob を送信し、HTTP 応答による確認を待ってから次のオフセットに進みます。空のファイルではチャンクのリクエストは不要ですが、確定処理は必要です。
xhr.upload が転送の進捗を通知します。これらのイベントは、サーバーが受け入れたことを確認するものではありません。すべてのバイトがブラウザーから送出済みでも、最後のリクエストが成功するまでは進捗バーは 100% 未満にとどまります。
import type { WorkerMessage, WorkerResponse } from './worker-types.ts'
declare const self: DedicatedWorkerGlobalScope
const CHUNK_SIZE = 5 * 1024 * 1024
const MAX_FILE_SIZE = 16 * 1024 * 1024
function send(message: WorkerResponse): void {
self.postMessage(message)
}
function uploadChunk(chunk: Blob, url: string, onProgress: (ratio: number) => void): Promise<void> {
return new Promise((resolve, reject) => {
const xhr = new XMLHttpRequest()
xhr.upload.onprogress = (event) => {
if (event.lengthComputable) onProgress(event.loaded / event.total)
}
xhr.open('PUT', url)
xhr.timeout = 60_000
xhr.setRequestHeader('Content-Type', 'application/octet-stream')
xhr.onload = () => {
if (xhr.status >= 200 && xhr.status < 300) resolve()
else reject(new Error('Chunk rejected'))
}
xhr.onerror = () => reject(new Error('Upload network error'))
xhr.ontimeout = () => reject(new Error('Upload timed out'))
xhr.onabort = () => reject(new Error('Upload canceled'))
xhr.send(chunk)
})
}
async function run({ file }: WorkerMessage): Promise<void> {
if (file.size > MAX_FILE_SIZE) throw new Error('File exceeds the demo limit')
let expectedHash: string | undefined
if (file.size <= CHUNK_SIZE) {
const digest = await crypto.subtle.digest('SHA-256', await file.arrayBuffer())
expectedHash = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
send({ type: 'processed' })
}
const created = await fetch(`/uploads?size=${file.size}`, {
method: 'POST', signal: AbortSignal.timeout(60_000),
})
if (!created.ok) throw new Error('Could not create upload')
const entry: unknown = await created.json()
if (!entry || typeof entry !== 'object' || !('id' in entry)
|| typeof entry.id !== 'string' || !/^[0-9a-f-]{36}$/.test(entry.id)) {
throw new Error('Invalid upload ID')
}
const url = `/uploads/${entry.id}`
for (let start = 0; start < file.size; start += CHUNK_SIZE) {
const chunk = file.slice(start, start + CHUNK_SIZE)
await uploadChunk(chunk, `${url}?offset=${start}`, (ratio) => {
const percent = (start + ratio * chunk.size) / file.size * 100
send({ type: 'progress', percent: Math.min(99, percent) })
})
}
send({ type: 'confirming' })
const completed = await fetch(`${url}/complete`, {
method: 'POST', signal: AbortSignal.timeout(60_000),
})
if (!completed.ok) throw new Error('Finalization failed')
const result: unknown = await completed.json()
if (!result || typeof result !== 'object' || !('sha256' in result) || !('size' in result)
|| typeof result.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(result.sha256)
|| result.size !== file.size || (expectedHash !== undefined && result.sha256 !== expectedHash)) {
throw new Error('Invalid completion acknowledgment')
}
send({ type: 'complete', sha256: result.sha256, url })
}
self.onmessage = (event: MessageEvent<WorkerMessage>) => {
run(event.data).catch(() => send({ type: 'error', message: 'Upload failed. Please try again.' }))
}
進捗の描画とワーカーの解放
src/main.ts を保存してください。選択された
File は一度だけ取得し、コントロールを無効にしてアップロードの重複実行を防ぎます。すべての終了経路でワーカーを終了します。同一性チェックにより、すでにキャンセルされたワーカーからのキュー内のメッセージも無視します。
import type { WorkerMessage, WorkerResponse } from './worker-types.ts'
const fileInput = document.getElementById('fileInput')
const uploadBtn = document.getElementById('uploadBtn')
const cancelBtn = document.getElementById('cancelBtn')
const uploadProgress = document.getElementById('uploadProgress')
const statusElement = document.getElementById('status')
const checksum = document.getElementById('checksum')
const download = document.getElementById('download')
if (!(fileInput instanceof HTMLInputElement) || !(uploadBtn instanceof HTMLButtonElement)
|| !(cancelBtn instanceof HTMLButtonElement) || !(uploadProgress instanceof HTMLProgressElement)
|| !(statusElement instanceof HTMLElement) || !(checksum instanceof HTMLOutputElement)
|| !(download instanceof HTMLAnchorElement)) {
throw new Error('Missing upload controls')
}
let worker: Worker | null = null
const finish = (message: string): void => {
worker?.terminate()
worker = null
uploadBtn.disabled = false
fileInput.disabled = false
cancelBtn.disabled = true
statusElement.textContent = message
}
uploadBtn.addEventListener('click', () => {
if (worker !== null) return
const file = fileInput.files?.[0]
uploadProgress.value = 0
checksum.value = ''
download.hidden = true
download.removeAttribute('href')
if (!file) {
statusElement.textContent = 'Please select a file.'
return
}
if (file.size > 16 * 1024 * 1024) {
statusElement.textContent = 'Choose a file of at most 16 MiB.'
return
}
uploadBtn.disabled = true
fileInput.disabled = true
cancelBtn.disabled = false
statusElement.textContent = 'Preparing upload.'
try {
const current = new Worker(new URL('./upload.worker.ts', import.meta.url), { type: 'module' })
worker = current
current.onmessage = (event: MessageEvent<WorkerResponse>) => {
if (worker !== current) return
const response = event.data
switch (response.type) {
case 'processed':
statusElement.textContent = 'File hashed. Uploading.'
break
case 'progress':
uploadProgress.value = response.percent
statusElement.textContent = `Uploading: ${Math.round(response.percent)}%`
break
case 'confirming':
statusElement.textContent = 'Confirming upload.'
break
case 'complete':
checksum.value = response.sha256
download.href = response.url
download.hidden = false
uploadProgress.value = 100
finish('Upload complete.')
break
case 'error':
finish(response.message)
break
}
}
current.onerror = (event) => {
if (worker !== current) return
event.preventDefault()
finish('The upload worker failed. Please try again.')
}
current.onmessageerror = () => {
if (worker === current) finish('Could not read the upload worker response.')
}
current.postMessage({ file } satisfies WorkerMessage)
} catch {
finish('Could not start the upload worker.')
}
})
cancelBtn.addEventListener('click', () => finish('Upload canceled.'))
window.addEventListener('pagehide', () => finish('Upload stopped.'))
対応するローカル受信サーバーの実行
server.mts を保存してください。Node はネイティブの TypeScript 型除去でこの ES モジュールを実行します。受信サーバーは生成した ID のファイルを作成し、次に期待するオフセットでチャンクを受け入れます。完了時の長さを検証し、SHA-256 を計算した後にのみダウンロードを公開します。各チャンクのペイロードは 5 MiB に制限し、チャンクをディスクに追記します。チェックサムの計算時には、保存したファイルをストリームで読み取ります。
これはファイルサイズを 16 MiB に制限した、localhost 用の学習用プロトコルです。認証、再試行、再開、有効期限、ディスク全体のクォータはありません。ファイルは
received/ に残ります。再起動すると、メモリ内のアップロード登録情報とダウンロード URL は失われます。デモを停止した後、不要になったファイルをそのディレクトリから削除してください。クライアントのファイル名を保存先パスとして使うことはありません。
import type { IncomingMessage, ServerResponse } from 'node:http'
import { createHash, randomUUID } from 'node:crypto'
import { createReadStream } from 'node:fs'
import { appendFile, mkdir, readFile, stat, writeFile } from 'node:fs/promises'
import { createServer } from 'node:http'
import { parseArgs } from 'node:util'
const CHUNK_SIZE = 5 * 1024 * 1024
const MAX_FILE_SIZE = 16 * 1024 * 1024
const receivedRoot = new URL('./received/', import.meta.url)
interface Upload {
path: URL
size: number
received: number
complete: boolean
busy: boolean
}
const uploads = new Map<string, Upload>()
function reply(response: ServerResponse, status: number, value: unknown): void {
response.writeHead(status, { 'Content-Type': 'application/json' })
response.end(JSON.stringify(value))
}
async function readBody(request: IncomingMessage, limit: number): Promise<Buffer> {
const parts: Buffer[] = []
let length = 0
for await (const part of request) {
if (!(part instanceof Buffer)) throw new Error('Unexpected request body')
length += part.length
if (length > limit) throw new Error('Request body exceeds its limit')
parts.push(part)
}
return Buffer.concat(parts, length)
}
async function handle(request: IncomingMessage, response: ServerResponse): Promise<void> {
const url = new URL(request.url ?? '/', 'http://localhost')
if (request.method === 'GET' && (url.pathname === '/' || /^\/assets\/[\w.-]+\.(js|css)$/.test(url.pathname))) {
const path = url.pathname === '/' ? '/index.html' : url.pathname
const data = await readFile(new URL(`./dist${path}`, import.meta.url))
response.writeHead(200, {
'Content-Type': path.endsWith('.html') ? 'text/html' : path.endsWith('.css') ? 'text/css' : 'text/javascript',
})
response.end(data)
return
}
if (request.method === 'POST' && url.pathname === '/uploads') {
const sizeText = url.searchParams.get('size')
const size = sizeText !== null && /^\d+$/.test(sizeText) ? Number(sizeText) : NaN
if (!Number.isSafeInteger(size) || size < 0 || size > MAX_FILE_SIZE) {
reply(response, 400, { error: 'Invalid file size' })
return
}
await readBody(request, 0)
const id = randomUUID()
const path = new URL(`${id}.bin`, receivedRoot)
await writeFile(path, Buffer.alloc(0), { flag: 'wx' })
uploads.set(id, { path, size, received: 0, complete: false, busy: false })
reply(response, 201, { id })
return
}
const match = /^\/uploads\/([0-9a-f-]{36})(\/complete)?$/.exec(url.pathname)
const upload = match?.[1] !== undefined ? uploads.get(match[1]) : undefined
if (!upload) {
reply(response, 404, { error: 'Upload not found' })
return
}
if (request.method === 'GET' && !match?.[2] && upload.complete) {
response.writeHead(200, { 'Content-Type': 'application/octet-stream' })
createReadStream(upload.path).on('error', () => response.destroy()).pipe(response)
return
}
if (upload.busy || upload.complete) {
reply(response, 409, { error: 'Upload is busy or already complete' })
return
}
upload.busy = true
try {
if (request.method === 'PUT' && !match?.[2]) {
const offsetText = url.searchParams.get('offset')
const offset = offsetText !== null && /^\d+$/.test(offsetText) ? Number(offsetText) : NaN
const expected = Math.min(CHUNK_SIZE, upload.size - upload.received)
if (offset !== upload.received || expected <= 0) {
reply(response, 409, { error: 'Unexpected chunk offset' })
return
}
const data = await readBody(request, expected)
if (data.length !== expected) {
reply(response, 400, { error: 'Unexpected chunk length' })
return
}
await appendFile(upload.path, data)
upload.received += data.length
reply(response, 204, null)
return
}
if (request.method === 'POST' && match?.[2] === '/complete') {
await readBody(request, 0)
if (upload.received !== upload.size || (await stat(upload.path)).size !== upload.size) {
reply(response, 409, { error: 'Upload is incomplete' })
return
}
const hash = createHash('sha256')
for await (const part of createReadStream(upload.path)) hash.update(part)
upload.complete = true
reply(response, 200, { size: upload.size, sha256: hash.digest('hex') })
return
}
reply(response, 405, { error: 'Method not allowed' })
} finally {
upload.busy = false
}
}
async function main(): Promise<void> {
const { values } = parseArgs({ options: { port: { type: 'string', default: '0' } } })
const port = Number(values.port)
if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Invalid port')
await readFile(new URL('./dist/index.html', import.meta.url))
await mkdir(receivedRoot, { recursive: true })
const server = createServer((request, response) => {
handle(request, response).catch(() => {
if (!response.headersSent) reply(response, 500, { error: 'Request failed' })
else response.destroy()
})
})
server.requestTimeout = 60_000
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 listening address')
console.log(`Open http://127.0.0.1:${address.port}`)
}
main().catch((error: unknown) => {
console.error(error instanceof Error ? error.message : 'Receiver startup failed')
process.exitCode = 1
})
デモのディレクトリで次のブロックを貼り付け、三つの環境すべてをチェックし、ページとワーカーをビルドして受信サーバーを実行してください。&& の連結により、ビルドに失敗した際に古いビルドが起動されるのを防ぎます。ポートにゼロを指定すると、OS に空きポートを要求します。受信サーバーが表示した URL を開いてください。停止するには、このターミナルで Ctrl+C を押してください。固定ポートを選ぶには、--port 0 を、たとえば
--port 8000 に置き換えます。使用中のポートでは起動に失敗します。
corepack yarn tsc --project tsconfig.json &&
corepack yarn tsc --project tsconfig.worker.json &&
corepack yarn tsc --project tsconfig.server.json &&
corepack yarn vite build &&
node server.mts --port 0
小さなファイルを選び、Upload をクリックしてください。Upload complete. が表示されたら、Download received file を使い、ダウンロードしたバイト列を元のファイルと比較してください。表示される SHA-256 は受信サーバー上のファイルのものです。クライアント側のハッシュとも比較するのは、小さなファイルを扱う分岐だけです。完了が確認するのは、このローカルアップロード契約の成立であり、マルウェアスキャンや別の処理パイプラインを通過したことではありません。
5 MiB より大きいファイルを試して、複数のリクエストと短い最終チャンクの動作を確認してください。アップロード中に Cancel をクリックし、別のアップロードを開始してください。キャンセルすると、ワーカーとそのクライアント側の処理が停止します。受け入れ済みのバイトは受信サーバーに残る場合があり、サーバーがすでに受け入れた確定処理は、その応答をキャンセルしても取り消せません。新しく試行すると新しい ID が作成されます。ファイルをチャンクに分割しても、このプロトコルで転送を再開できるようにはなりません。
再開可能な転送には、Uppy の Tus プラグインが、対応する tus サーバーとともに tus プロトコルを使用します。これは、このデモとは異なるサーバー契約です。
