Node.js と tar-stream による CI ログアーカイブの作成
tar-stream を使い、完了した CI ログを到着順に tar アーカイブへ書き込みます。次の例では、アーカイブを一時ファイルにストリーミングし、すべてのエントリが完了した後にのみ
ci-logs.tar を公開します。ログの生成元でエラーが発生した場合も含め、既存の保存先は変更しません。
これは、文字列または Buffer として渡されたログを扱う、ローカルの Node.js ワークフローです。各ログはメモリに収まる必要がありますが、アーカイブ全体が収まる必要はありません。生成するのはディスク上の非圧縮の .tar ファイルであり、メモリ内のアーカイブや未完了のログのライブストリームではありません。
依存関係
Node.js 24.15.0 またはそれ以降の 24.x リリース、Yarn 4.12.0 を利用できる Corepack、Bash、および確認用の GNU tar を使用してください。この手順は Linux 上の Node.js 24.15.0 と GNU tar 1.35 でテストしています。ハードリンクに対応するローカルファイルシステムと、管理権限のある保存先ディレクトリを使用してください。ネットワークファイルシステムと Windows は、この手順のテスト対象外です。
サンプルプロジェクトを作成する親ディレクトリで、次の内容を Bash に貼り付けてください。サブシェルを使うため、現在のディレクトリは変わりません。また、途中で処理が失敗すると
&& がセットアップを停止します。node-tar-demo がすでに存在する場合は、既存のプロジェクトを削除せず、別の親ディレクトリを選んでください。
(
mkdir node-tar-demo &&
cd node-tar-demo &&
printf '%s\n' '{"private":true,"type":"module","packageManager":"yarn@4.12.0"}' > package.json &&
printf '%s\n' 'nodeLinker: node-modules' > .yarnrc.yml &&
touch yarn.lock &&
corepack yarn add --exact tar-stream@3.1.7
)
このプロジェクトでは ES modules を明示的に有効にし、node_modules の通常版を
node コマンド用にインストールします。専用のロックファイルにより、Yarn がこのプロジェクトを上位プロジェクトの一部として扱うのを防ぎます。Node はこれらの TypeScript ファイルをネイティブの型除去で実行します。型チェックは行いません。
エントリのストリーミングと完成したアーカイブの公開
次のモジュール全体を node-tar-demo/archive.ts として保存してください。生成元は AbortSignal を受け取り、完了したログをひとつずつ yield します。エントリを追加する前に pack ストリームの読み取りを開始し、各エントリのコールバックを待ってから次のログを要求してください。これらは tar-stream のドキュメントに記載されているパック操作です。
import type { Writable } from 'node:stream'
import { createWriteStream } from 'node:fs'
import { link, mkdtemp, rm } from 'node:fs/promises'
import path from 'node:path'
import { pipeline } from 'node:stream/promises'
import tar from 'tar-stream'
export interface LogEntry {
filename: string
content: string | Buffer
}
type LogProducer = (signal: AbortSignal) => Iterable<LogEntry> | AsyncIterable<LogEntry>
interface ArchiveOptions {
signal?: AbortSignal
}
function validateFilename(filename: string): string {
if (
!filename || filename.includes('\0') ||
path.posix.isAbsolute(filename) || path.win32.isAbsolute(filename) ||
filename.includes(':') || filename.split(/[\\/]/).some((part) => !part || part === '.' || part === '..')
) {
throw new Error('Invalid archive filename')
}
return filename.replaceAll('\\', '/')
}
async function addLogToArchive(
pack: ReturnType<typeof tar.pack>, filename: string, content: string | Buffer,
): Promise<void> {
return new Promise((resolve, reject) => {
pack.entry({ name: validateFilename(filename), mode: 0o600 }, content, (error) => {
if (error) reject(error)
else resolve()
}).on('error', reject)
})
}
export async function createLogArchive(
getLogs: LogProducer, output: Writable, options: ArchiveOptions = {},
): Promise<void> {
const controller = new AbortController()
const signal = options.signal
? AbortSignal.any([options.signal, controller.signal])
: controller.signal
const pack = tar.pack()
const completed = pipeline(pack, output, { signal })
const producing = (async () => {
signal.throwIfAborted()
for await (const log of getLogs(signal)) {
signal.throwIfAborted()
await addLogToArchive(pack, log.filename, log.content)
}
signal.throwIfAborted()
pack.finalize()
})()
try {
await Promise.all([completed, producing])
} catch (error) {
// Stop both sides, then wait for the producer and file handle to finish cleanup.
controller.abort(error)
await Promise.allSettled([completed, producing])
throw error
}
}
export async function saveLogArchive(
getLogs: LogProducer, destination: string, options: ArchiveOptions = {},
): Promise<void> {
options.signal?.throwIfAborted()
const target = path.resolve(destination)
const staging = await mkdtemp(path.join(path.dirname(target), '.ci-logs-'))
const temporary = path.join(staging, 'archive.tar')
try {
await createLogArchive(
getLogs,
createWriteStream(temporary, { flags: 'wx', mode: 0o600 }),
options,
)
options.signal?.throwIfAborted()
await link(temporary, target)
} finally {
await rm(staging, { recursive: true, force: true })
}
}
ストリームヘルパーは、生成と書き込みを連携させます。Node の pipeline() はバックプレッシャーを処理し、キャンセル時に接続されたストリームを破棄します。どちらかが失敗すると、ヘルパーは生成元もキャンセルし、両方のタスクが終了するまで待機します。生成元では、以下のデモのタイマーと同様に、待機が発生しうるすべての操作へシグナルを渡す必要があります。シグナルを無視する任意の Promise は、キャンセルでは停止できません。
保存ヘルパーはハードリンクを使い、完成したファイルに最終的な名前を付けます。Linux の link(2) は、シンボリックリンクも含め、保存先がすでに存在する場合は処理を拒否します。存在確認と上書きする名前変更を別々に行うことはありません。一時ディレクトリは保存先の隣に配置するため、両方の名前が同じファイルシステム上に置かれます。公開後に一時的な名前を削除しても、最終アーカイブはそのまま残ります。
サンプルの実行と確認
次の内容を node-tar-demo/demo.ts として保存してください。タイマーは、次の CI 処理が完了するまでの待機を模擬しています。組み込む際は ciLogs を独自の生成元に置き換えてください。デモには空のエントリと小さなバイナリアーティファクトが含まれているため、テキスト以外も確認できます。
import { setTimeout as delay } from 'node:timers/promises'
import type { LogEntry } from './archive.ts'
import { saveLogArchive } from './archive.ts'
async function* ciLogs(signal: AbortSignal): AsyncGenerator<LogEntry> {
yield { filename: 'build.log', content: 'Build completed successfully.\n' }
await delay(25, undefined, { signal })
yield { filename: 'test.log', content: 'All tests passed.\n' }
yield { filename: 'empty.log', content: Buffer.alloc(0) }
yield { filename: 'artifacts/status.bin', content: Buffer.from([0, 255, 128, 10]) }
}
async function main(): Promise<void> {
const controller = new AbortController()
const cancel = () => controller.abort(new Error('Interrupted'))
process.once('SIGINT', cancel)
try {
const destination = process.argv[2] ?? 'ci-logs.tar'
await saveLogArchive(ciLogs, destination, {
signal: AbortSignal.any([controller.signal, AbortSignal.timeout(30_000)]),
})
console.log(`Created ${destination}`)
} finally {
process.removeListener('SIGINT', cancel)
}
}
main().catch((error: unknown) => {
console.error(error instanceof Error ? error.message : 'Archive failed')
process.exitCode = 1
})
セットアップに使った親ディレクトリで、次の内容を貼り付けてください。
(
cd node-tar-demo &&
node demo.ts &&
tar -tf ci-logs.tar &&
tar -xOf ci-logs.tar test.log
)
想定される出力:
Created ci-logs.tar
build.log
test.log
empty.log
artifacts/status.bin
All tests passed.
同じブロックを再実行して、名前の衝突時の動作を確認してください。Node はステータス 1 と EEXIST メッセージで終了し、確認用コマンドは実行されず、既存のアーカイブのバイト列は保持されます。別のアーカイブを作成するには、demo.ts の保存先引数に
ci-logs-next.tar などの別の値を指定してください。
パフォーマンス上の考慮事項
各エントリの完了を待つことで、低速な出力先への書き出しが続く間に、生成元がアーカイブ全体をキューに入れるのを防ぎます。ただし、個々の文字列や Buffer が小さくなるわけではありません。生成元がすでにすべてのログを収集している場合、そのメモリは引き続き保持されます。CI ジョブに適したサイズ上限を設け、完了したログを順次渡してください。
Tar はファイルをまとめますが、この例では圧縮しません。tar 出力全体をディスクに一度書き込みます。ハードリンクによる公開処理では、そのバイト列をコピーせずにファイル名を追加します。ここでは、コマンドラインのアーカイブツールに対する速度向上を示すベンチマークは行っていません。
セキュリティ上の考慮事項
エントリ名は相対ファイルパスでなければなりません。バリデーターは、バックスラッシュを正規化する前に、絶対パス、ドライブや代替ストリームの区切り文字、ヌルバイト、空のセグメント、および . または
.. セグメントを拒否します。このヘルパーはエントリの重複を拒否しないため、ログにはそれぞれ異なる名前を使ってください。通常のファイルエントリをモード 0600 で作成し、ファイル拡張子から実行権限を推測することはありません。
アーカイブする前に、CI ログにシークレットが含まれないようにしてください。Tar は暗号化を提供せず、これらの名前の検証によって、任意のサードパーティ製アーカイブを安全に展開できるようになるわけでもありません。後で展開ツールを作成する場合は、展開先とシンボリックリンクのポリシーを別途決めてください。
異なるファイル形式の扱い
UTF-8 テキストは文字列として、バイナリデータは Buffer として渡してください。tar-stream は、空の Buffer も含め、そのバイト列からエントリサイズを求めます。status.bin にテキストのデコードは不要です。ファイルストリームでは、tar はエントリ本体より先にバイトサイズを必要とします。この例では、最終サイズがまだ不明なログをアーカイブできるとはせず、意図的に完了済みのログを受け付けています。
よくある問題のトラブルシューティング
EEXIST: 最終的な保存先がすでに存在します。拒否されるのは、ログが生成された後の公開時です。別のファイル名を選んでください。このスクリプトが既存のファイルを置き換えることはありません。- 生成元の拒否、無効なエントリ、書き込みの失敗: 両方のタスクが終了してから、一時ファイルをクリーンアップします。新しい最終アーカイブは公開されません。
createLogArchiveを別の Writable と直接使う場合は、その保存先に残った部分的なバイト列の破棄を自身で処理する必要があります。 - タイムアウトまたは Ctrl+C: デモはキャンセルを要求し、クリーンアップ後に失敗として終了します。外部の生成元では、渡されたシグナルに従うようにしてください。最終リンク操作が始まると、キャンセルが間に合わず、公開を防げない場合があります。
- ディレクトリの不在またはハードリンクのエラー: 保存先の親ディレクトリを先に作成し、ローカルファイルシステムがハードリンクを許可していることを確認してください。エラーを抑えるために、リンクを上書きする名前変更に置き換えないでください。
- クリーンアップの失敗または突然の終了: 公開後にクリーンアップエラーが発生する場合があります。再試行する前に最終アーカイブを確認してください。クラッシュや
SIGKILLにより、.ci-logs-*ディレクトリが残る場合があります。その試行の一時ディレクトリは、プロセスが停止してから削除してください。この例は、電源喪失時の永続性を保証しません。
CI ログ生成元の接続
saveLogArchive をファイル出力の境界として維持し、デモのジェネレーターを CI の各処理の結果に置き換えてください。完了したログをひとつずつ yield し、待機やリクエストにもキャンセルを伝え、ジョブごとに一意のアーカイブファイル名を選んでください。保存先固有の公開ポリシーとクリーンアップポリシーを用意すれば、同じストリーミングヘルパーで別の Writable にも書き込めます。
