Deno と WebSockets によるリアルタイムファイル処理
ブラウザーのボタンをクリックすると、Deno がマシン上のファイルのハッシュを計算し、バイト数と SHA-256 チェックサムを WebSocket 経由で返します。この例では、固定のファイル sample.txt のみを読み取り、最大 1 MiB まで受け付けます。ブラウザーはコマンドを送信して結果を受信するだけで、ファイルはアップロードしません。
この手順では、Linux 上の Deno 2.9.6 と Chromium を使用し、ターミナルのコマンドには Bash を使います。ランタイムが必要な場合は
Deno のインストールガイドを参照し、deno --version でバージョンを確認してください。インストールが必要なパッケージはありません。
Deno を使う理由は?
ここで使用する HTTP サーバー、WebSocket へのアップグレード、ファイル API、Web Crypto は Deno に備わっています。権限フラグを使い、アプリケーションに許可するのは、二つのファイルの読み取りと、一つのループバックアドレスおよびポートへのネットワークアクセスです。この例では、書き込み、サブプロセス、環境へのアクセスは必要ありません。
WebSocket サーバーの準備
任意のディレクトリで、次の内容を Bash に貼り付けてください。新しいプロジェクトと、abc を含む三バイトのファイルを作成します。末尾に改行は付きません。deno-checksum がすでに存在する場合は、上書きせずに作成が失敗します。括弧で囲んでいるため、ターミナルは親ディレクトリにとどまります。
(
mkdir deno-checksum &&
cd deno-checksum &&
printf 'abc' > sample.txt
)
次の内容を deno-checksum/server.ts として保存してください。/ でブラウザー用のページを配信し、/ws へのリクエストを
Deno の WebSocket APIでアップグレードします。処理を開始するのは、完全に一致するテキストコマンド hash だけです。どのメッセージからもファイルパスは指定できません。
const hostname = '127.0.0.1'
const port = 8000
const origin = `http://${hostname}:${port}`
const maxFileBytes = 1024 * 1024
const html = await Deno.readTextFile('./index.html')
let busy = false
class FileProblem extends Error {}
async function hashSample(): Promise<{ bytes: number; sha256: string }> {
using file = await Deno.open('./sample.txt', { read: true })
if (!(await file.stat()).isFile) {
throw new FileProblem('Use a regular file for sample.txt.')
}
// One extra byte distinguishes an exact-limit file from an oversized file.
const buffer = new Uint8Array(maxFileBytes + 1)
let bytes = 0
while (bytes < buffer.length) {
const count = await file.read(buffer.subarray(bytes))
if (count === null) break
bytes += count
}
if (bytes > maxFileBytes) {
throw new FileProblem('sample.txt exceeds 1 MiB.')
}
const digest = await crypto.subtle.digest('SHA-256', buffer.subarray(0, bytes))
const sha256 = Array.from(new Uint8Array(digest), (byte) =>
byte.toString(16).padStart(2, '0'),
).join('')
return { bytes, sha256 }
}
Deno.serve({ hostname, port, onListen: () => console.log(`Open ${origin}/`) }, (req) => {
const url = new URL(req.url)
if (req.method !== 'GET' || url.origin !== origin) {
return new Response('Not found', { status: 404 })
}
if (url.pathname === '/') {
return new Response(html, {
headers: { 'content-type': 'text/html; charset=utf-8' },
})
}
if (url.pathname !== '/ws') {
return new Response('Not found', { status: 404 })
}
if (req.headers.get('origin') !== origin) {
return new Response('Forbidden', { status: 403 })
}
if (req.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
return new Response('WebSocket required', { status: 426 })
}
const { socket, response } = Deno.upgradeWebSocket(req)
function send(message: object): void {
if (socket.readyState === WebSocket.OPEN) {
socket.send(JSON.stringify(message))
}
}
socket.addEventListener('message', async (event) => {
if (event.data !== 'hash') {
send({ type: 'error', message: 'Send the text command hash.' })
return
}
if (busy) {
send({ type: 'error', message: 'Server is busy. Try again.' })
return
}
busy = true
try {
send({ type: 'started' })
const result = await hashSample()
send({ type: 'result', ...result })
} catch (error) {
const message = error instanceof FileProblem
? error.message
: error instanceof Deno.errors.NotFound
? 'sample.txt was not found.'
: error instanceof Deno.errors.NotCapable || error instanceof Deno.errors.PermissionDenied
? 'Read permission for sample.txt was denied.'
: 'Could not hash sample.txt.'
send({ type: 'error', message })
} finally {
busy = false
}
})
return response
})
file.read() が返すバイト数は、要求した量より少ない場合があるため、EOF に達するかバッファーが満杯になるまでループを続けます。using は、失敗した場合も含め、関数を抜ける際にファイルを閉じます。sample.txt は通常のローカルファイルとして扱い、リクエスト中は変更しないでください。これはファイルシステムのスナップショットではありません。
ファイルが大きくなっても、読み取りバッファーの容量は最大 1 MiB と一バイトです。この上限が重要なのは、crypto.subtle.digest() が入力をストリーミングせず、メモリ上で受け取るためです。サーバー全体のメモリ使用量が 1 MiB に収まるという意味ではありません。
クライアントの実装
次の内容を deno-checksum/index.html として保存してください。ソケットが開くまではボタンを無効にし、リクエストの処理待ち中も無効のままにします。結果は以前の表示を置き換え、ディスクには何も保存しません。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="icon" href="data:," />
<title>Deno file checksum</title>
<style>
pre { white-space: pre-wrap; overflow-wrap: anywhere; }
</style>
</head>
<body>
<h1>Hash sample.txt</h1>
<button type="button" disabled>Hash file</button>
<p role="status">Connecting…</p>
<pre aria-label="Checksum result"></pre>
<script type="module">
const button = document.querySelector('button')
const status = document.querySelector('[role="status"]')
const result = document.querySelector('pre')
if (!(button instanceof HTMLButtonElement) || !status || !result) {
throw new Error('Missing page controls')
}
const socket = new WebSocket(`ws://${location.host}/ws`)
let pending = false
socket.addEventListener('open', () => {
status.textContent = 'Ready.'
button.disabled = false
})
button.addEventListener('click', () => {
if (pending || socket.readyState !== WebSocket.OPEN) return
pending = true
button.disabled = true
result.textContent = ''
status.textContent = 'Waiting for the server…'
socket.send('hash')
})
socket.addEventListener('message', (event) => {
const message = JSON.parse(event.data)
if (message.type === 'started') {
status.textContent = 'Hashing sample.txt…'
return
}
if (message.type === 'result') {
result.textContent = JSON.stringify(message, null, 2)
status.textContent = 'Done.'
} else if (message.type === 'error') {
status.textContent = message.message
}
pending = false
button.disabled = false
})
socket.addEventListener('error', () => {
status.textContent = 'Connection error. Check the server.'
button.disabled = true
})
socket.addEventListener('close', () => {
status.textContent = 'Disconnected. Reload to reconnect.'
button.disabled = true
pending = false
})
</script>
</body>
</html>
サーバーの起動
同じ親ディレクトリで、次を実行してください。
(
cd deno-checksum &&
deno run --no-config --no-prompt \
--allow-net=127.0.0.1:8000 \
--allow-read=./index.html,./sample.txt server.ts
)
--no-config は、上位プロジェクトの Deno 設定の継承を防ぎます。--no-prompt は、権限が不足している場合に、より広いアクセス権を求めずに失敗させます。読み取り権限の対象は、起動時に読み込むページと、リクエストごとに開くサンプルファイルです。ネットワークアクセスは 127.0.0.1:8000 に限定し、サーバーも明示的にそのアドレスにバインドします。
http://127.0.0.1:8000/ を開き、Hash fileを選択してください。HTML ファイルを直接開いたり、localhost を使用したりせず、必ず指定どおりのアドレスを使ってください。WebSocket ハンドシェイクでページのオリジンを確認するためです。ステータスが Done. になると、次の結果が表示されるはずです。
{
"type": "result",
"bytes": 3,
"sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
}
別のターミナルで親ディレクトリを開き、Linux の
sha256sum を使って同じバイト列を独立して検証してください。
sha256sum deno-checksum/sample.txt
最初のフィールドが sha256 と一致するはずです。値が異なる場合は、エディターが改行を追加した可能性があります。リクエストが完了してからファイルを変更し、Hash fileを再度選択すると、新しい内容のハッシュを計算できます。空のファイルやバイナリデータも扱えます。.txt という名前によってテキストのデコードが行われることはありません。終了したら Ctrl+C でサーバーを停止してください。
起動時にアドレスが使用中と報告された場合は、空いているポートを選び、const port と --allow-net のポートの両方を変更してから再試行してください。index.html がない場合は起動が停止します。一方、sample.txt がない場合は、ブラウザーに
sample.txt was not found.と表示されます。ファイルを復元して、もう一度クリックしてください。上限を超えるサイズのファイルでは、チェックサムを返さずに sample.txt exceeds 1 MiB. と表示されます。
WebSocket のライフサイクル
クライアントは、readyState が WebSocket.OPEN の間だけ送信します。サーバーは最初に started を送信し、次に result または error を送信します。処理が開始されたことは、ファイルの読み取り成功を示すものではありません。また、ステータスメッセージは進捗率の通知ではありません。
ハッシュ計算中にブラウザーが切断されても、上限のある処理は完了まで続きます。ソケットが開いていなければ、サーバーは応答を破棄します。finally ブロックは、後続のリクエストに備えて処理中フラグを解除します。再接続して新しいチェックサムを要求するには、ページを再読み込みしてください。自動再試行、ジョブ履歴、失われた結果の復元機能はありません。
セキュリティのベストプラクティス
このデモはローカルでのみ使用してください。ループバックへのバインドと、HTTP ホストおよび WebSocket オリジンの確認により、ブラウザーページからのアクセスを制限します。オリジンの確認は認証ではありません。ローカルのブラウザー以外のクライアントは、そのヘッダーを自ら送信できます。
1. 入力検証
このプロトコルは、hash と完全に一致するコマンドだけを受け付けます。JSON、パス、バイナリメッセージ、その他のテキストには、ファイルの読み取りを開始せずにエラーを返します。ファイル名はサーバーコードのみで決まります。ページに送信するエラーには、ファイルシステムのパスやスタックトレースではなく、固定のメッセージを使用します。
Deno の読み取り制限を確認するには、サーバーを停止し、読み取り権限から ,./sample.txt を削除してください。再起動してボタンをクリックすると、ページは読み込まれますが、リクエストに対して
Read permission for sample.txt was denied.と表示されます。先に進む前に権限を元に戻してください。ネットワーク権限を削除すると、サーバーはまったく待ち受けできなくなります。
2. レート制限
この例では、すべての接続を通じて、同時に実行できるハッシュ計算は一つだけです。その処理中に二つ目のリクエストを送ると、Server is busy. Try again.が返されます。ブラウザーも待機中はボタンを無効にするため、連続クリックで処理がキューに入ることはありません。
同時実行数の制限は、レート制限ではありません。クライアントはハッシュ計算の完了直後に次のリクエストを送信でき、サーバーは接続数も制限しません。公開サービスにする場合は、これらの確認に加えて、認証、認可、リクエスト数と接続数の制限が必要です。
3. メッセージサイズの制限
受け付けるコマンドはわずか四 ASCII バイトで、ファイルの内容がソケットを通ることはありません。ただし、他のコマンドを拒否するのはメッセージの到着後です。そのため、受信する WebSocket のバッファリング量は制限されません。WebSocket API にはバックプレッシャーがないため、ファイルの読み取り上限と処理中フラグだけでは、信頼できないトラフィックを扱うサーバーにはなりません。
WebSockets が必要かどうかの判断
チェックサムを一つ取得するだけなら、HTTP リクエストでも、接続管理の手間を抑えて同じ結果を返せます。WebSockets が役立つのは、すでに接続されているページが継続的にステータスメッセージや結果を必要とする場合です。この小さな例では、アップロード、任意のファイル選択、バックグラウンドジョブサービスを追加せずに、そのやり取りを示しています。
