クイックスタート

インストール

wacz-validator は 7 つの package からなる pnpm workspace です。ビルドしてから bin を system-wide に登録します。

pnpm install --frozen-lockfile
pnpm build

pnpm --dir packages/validate-cli add -g .   # wacz-validator-validate
pnpm --dir packages/tui          add -g .   # wacz-validator
pnpm --dir packages/daemon       add -g .   # wacz-validator-daemon (常駐 daemon を使うときだけ)

登録後は monorepo の外でも wacz-validator 直下でも、bin 名だけで呼べます。

3 行目は任意です。wacz-validator は daemon を自分で起動するので、wacz-validator-daemon を PATH に置く必要があるのは、セッションをまたいで生きる daemon を動かすときだけです — 依存 package の bin は global に link されないため、tui だけを入れてもこの名前は 使えません。

archive を 1 本検証する

wacz-validator-validate samples/wikipedia.wacz

これが非対話の経路です。report を出力し、CI で分岐できる exit code を返します。

ローカルのファイルだけでなく、S3 互換ストア上の archive も同じコマンドで 検証できます。同梱の SeaweedFS に置いた WACZ なら、AWS SDK の default chain を そちらへ向けるだけです。

export AWS_ENDPOINT_URL_S3=http://seaweedfs.crawler-storage:8333
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=wacz-validator AWS_SECRET_ACCESS_KEY=wacz-validator

wacz-validator-validate --s3-force-path-style s3://wacz-validator/wikipedia.wacz

--s3-force-path-style は SeaweedFS や MinIO のような path-style でしか 応答しないストアに要ります（WACZ_VALIDATOR_S3_FORCE_PATH_STYLE=true でも同じ）。 report の source が { "kind": "s3", "uri": "s3://…" } になるほかは、 ローカルファイルのときと変わりません。

AWS_PROFILE は上の変数より強い

shell で AWS_PROFILE を export していると SDK はそちらを使い、上の access key を無視します。unset AWS_PROFILE するか、コマンドの前に env -u AWS_PROFILE を付けてください。

ストアの起動と archive の upload はコンテナにあります。

URL で渡す

鍵を持たずに検証したいときは、URL をそのまま渡せます。署名付き URL （S3 の presigned URL など）でも構いません —— query は報告に載りません。

wacz-validator-validate "https://example.com/archives/wikipedia.wacz"

読むのは range GET です。ZIP の中央ディレクトリと、rule が要る entry だけを 取るので、全体を落とす必要はありません。HEAD は使いません —— 署名付き URL の 署名は GET に対して作られており、HEAD は 403 になるからです。総サイズは最初の range GET の Content-Range から読みます。

Range を返さない相手は開けません

Range を無視して 200 で全体を返すサーバでは、検証を始めずに止まります。 その応答を「指定した範囲」として読むと ZIP の中央ディレクトリを本文の先頭から 読むことになり、壊れていない WACZ を「壊れている」と報告してしまうためです。 壊れているのは相手の Range 対応であって、archive ではありません。

report の source は { "kind": "http", "url": "https://…" } になります （query は落とした形）。

同じ report を対話的に読むなら TUI を使います。

wacz-validator samples/wikipedia.wacz

wacz-validator は既定で wacz-validator-daemon を子プロセスとして起動し、WebSocket で 接続します。ここまでの手順では port を意識する必要はありません。

セッションをまたいで生きる daemon に繋ぐ場合は、まず port を決めて起動します。

wacz-validator-daemon --port 7333 &

listen している URL が出力されます。

wacz-validator-daemon ws://127.0.0.1:7333

その URL をそのまま渡します。

wacz-validator --server ws://127.0.0.1:7333 samples/wikipedia.wacz

port はどこから来るか

--port を省略すると 0、つまり OS が空いている port を選び、起動のたびに 番号が変わります。固定したいときは --port か WACZ_VALIDATOR_DAEMON_PORT を使い、 そうでないときは daemon が出力した URL をコピーしてください。推測できる既定 port は存在しません。

同じ daemon は素の HTTP でも答えます —— 同じハンドラに口が 1 つずつ: POST /validate と、 archive の中身への窓（POST /lines・/line・/records・/record、raster の画像の 実体を bytes で返す /record/body）。どの要求も archive の URI を運ぶので、daemon は 呼び出しの間に何も持ちません。TUI では tab で配置へ、enter でファイル（行）か WARC（レコード）を開き、もう一度 enter で field に割った 1 行、または 1 レコードを開きます。

profile を選ぶ

既定の profile は spec です。この profile で exit 0 になる archive は ReplayWeb.page で正しく replay できることが 期待されます。

wacz-validator-validate --profile browserhive        samples/wikipedia.wacz   # より厳しく
wacz-validator-validate --profile browserhive@2.1.0  samples/wikipedia.wacz   # producer のバージョンまで指定
wacz-validator-validate --profile lenient     samples/wikipedia.wacz   # トリアージ用

profile が組み替えるのは producer 固有 / 様式的な rule の severity だけで、 spec が要求する check を抑止することはありません。 プロファイルを参照。

機械可読な出力

wacz-validator-validate は常に JSON を標準出力に書きます。切り替えるフラグはありません。

wacz-validator-validate samples/wikipedia.wacz | jq '.summary'

形式は安定しており、JSON レポートに文書化しています。

次に読むもの

• 各 rule が何を見るか → Rules
• 意図的に失敗する archive → Corpus