# 文字化けで宛先が決まらない1件がキューを永久に詰まらせるのを直す 自動化パイプラインの「キューから1件取り出して、宛先を決めて、投げる」型の処理は、 **宛先が決まらないアイテムを『失敗』ではなく『スキップ』として扱う**ことが多い。 スキップは exit 0 で終わるので、そのアイテムは**毎晩静かにリトライされ続け、誰も気付かない**。 この指示書は、実際に2日間詰まっていた1件を題材に ①詰まりの検出 ②化けた文字列から正体を特定する方法 ③再発しない宛先解決の設計 ④「対象外にする」出口 の4つをまとめる。フィードバック中継に限らず、**メール振り分け・Webhook ルーティング・チケット自動起票・ バッチのシャーディング**など「キー→宛先」を引くすべての処理に当てはまる。 --- ## 0. 前提と用語 - **キュー**: 未処理アイテムを保持する外部サービス（DB / Pub-Sub / 独自の中継 API など）。 取り出し（pending 取得）と完了通知（ack）が分かれているものを想定する。 - **宛先解決**: アイテムの属性（アプリ名・テナント名・製品名など）から、投げ先 （リポジトリ・チャンネル・担当キュー）を決める処理。 - **スキップ**: 宛先が決まらないので何もしないこと。ack しないため、次回も同じアイテムが返ってくる。 --- ## 1. 詰まりを検出する **症状はログにしか出ない。** 「毎晩正常終了しているのに、キューの残件数が減らない」が唯一の兆候。 ``` : 未マッピングなのでスキップ app=<化けた文字列> message_id= 作成: 0件 / スキップ: 1件（未マッピング:1）/ 残り: 1件 ``` チェックすべきこと: 1. **`残り` が何日も同じ値で止まっていないか**。0 に落ちない残件は詰まりの疑い。 2. **同じ `message_id` が複数日のログに出ていないか**。出ていればそのアイテムは永久リトライ状態。 3. スキップ理由の内訳（`未マッピング:N`）が毎回同じか。 > `--dry` / `--dry-run` 相当の「投げずに判定だけする」フラグが無ければ、**まずそれを足す**。 > 本番キューに実データを当てて安全に観測できないと、この後の切り分けが全部できない。 --- ## 2. アイテムの実体を「見る」— 端末の表示を信用しない ログに出た文字列が化けていても、**それが本当に壊れているのか、端末のコードページで化けて見えているだけか**は 表示からは判別できない。必ず**コードポイント列**を出す。 ```js // pending を1件取り出して、問題のフィールドのコードポイントを出す const name = String(item.app_name ?? ''); console.log([...name].map((c) => c.codePointAt(0).toString(16)).join(' ')); ``` 判定: - `U+FFFD`（置換文字）が混ざっている → **データそのものが壊れている**（不可逆。表示の問題ではない） - 正常な日本語が並ぶ → 端末の表示だけの問題。データは無事なので、原因は別のところにある さらに、**同じアイテムの他のフィールドが健全かどうか**を必ず見る。 今回の題材では `app_name` が壊れている一方、`source_url` は完全に健全だった。 **壊れやすいフィールドと壊れにくいフィールドは共存する**ので、ここが後の設計の分かれ目になる。 --- ## 3. 化けた文字列から元テキストを同定する（指紋照合） `U+FFFD` が混ざった時点で**復元は不可能**だが、**元が何だったかを同定することはできる**。 「レガシーな1バイト/2バイト系エンコーディングのバイト列を、UTF-8 として decode した」場合、 壊れ方には決まった規則があり、それが指紋になる。 規則（レガシー→UTF-8 誤 decode）: | 元のバイト | UTF-8 として読むと | |---|---| | `0x00`–`0x7F` | **そのまま ASCII 文字として生き残る** | | 単独の `0x80`–`0xBF`、不正なリードバイト | `U+FFFD` に潰れる（ここで情報が消える） | | 偶然そろった正しい UTF-8 の多バイト列 | **実在の文字**として残る（例: `C7 97` → `U+01D7`） | つまり **「生き残った ASCII 文字」と「U+FFFD の個数と位置」の並びが、元の文字列の指紋**になる。 同定手順: 1. 元テキストの候補を立てる（サービス名・定型文・想定される文面）。 2. 候補を**疑わしいレガシーエンコーディング**でバイト列にする。 3. そのバイト列を **UTF-8 として replacement 付きで decode** する。 4. 得られた並びが、実データのコードポイント列と**一致するか**照合する。 ```js // 候補を検証する（ は疑うエンコーディング名に置き換える） const bytes = Buffer.from('<候補テキスト>', ''); const decoded = new TextDecoder('utf-8').decode(bytes); // 不正バイトは U+FFFD になる console.log([...decoded].map((c) => c.codePointAt(0).toString(16)).join(' ')); // これが実データのコードポイント列と一致すれば、候補が元テキストで確定 ``` **なぜこれをやる価値があるのか**: 化けたアイテムを「読めないゴミ」として機械的に捨てると、 **本当は対応が必要な報告だった場合に失われる**。逆に、同定した結果それが 「テスト投稿」「対応不要」だと分かれば、**自信を持って対象外にできる**。 今回の題材では本文末尾が定型の「対応不要」文だと確定し、不要なチケットを起票せずに済んだ。 > 文字列がどのタイミングで壊れたかも押さえておく。多くは**シェル経由で非 ASCII を argv 渡しした**ときに起きる > （OS やシェルがネイティブ実行ファイルへの引数をレガシーコードページへ変換するため）。 > 検証スクリプトに非 ASCII を渡すときは argv を通さず、ヒアドキュメント／ファイル／stdin で渡す。 --- ## 4. 再発しない宛先解決の設計 原因は「文字化け」そのものではなく、**宛先解決を単一キーの完全一致に賭けていたこと**。 そのキーが壊れた瞬間、アイテムは永久に宙に浮く。 ### 4-1. 壊れにくい第2キーへフォールバックする **人が入力した名前より、システムが生成した値（URL・ホスト名・ID）のほうが化けにくい。** ```js export function resolveTargetForItem(item, mapValue = '', hostMapValue = '') { // 第1キー（従来どおり）。ここで解決できた場合の挙動は絶対に変えない。 return resolveByName(item?.app_name, mapValue) // 第2キー。第1キーで解決できなかったときだけ使う。 || resolveByUrl(item?.source_url, mapValue, hostMapValue); } ``` **既存の優先順位を変えないこと**が重要。第1キーで解決できるアイテムの宛先が変わると、 直したつもりが別の事故になる。回帰テストで固定する（後述）。 ### 4-2. フォールバックは必ず許可リスト方式にする URL から**未知の宛先を推測してはいけない**。無関係な宛先へ投げる事故になる。 **既にマッピング表にある値にしか解決しない**よう縛る。 ```js export function resolveByUrl(sourceUrl, mapValue = '', hostMapValue = '') { let hostname; try { hostname = new URL(String(sourceUrl ?? '').trim()).hostname.toLowerCase(); } catch { return null; // 空文字・不正 URL でも例外を投げない } if (!hostname) return null; // 明示表が最優先（独自ドメインなど、自動導出が効かないケース用） const explicit = parseHostMap(hostMapValue)[hostname]; if (explicit) return explicit; // 自動導出: ホストの先頭ラベルが、既存の表の値と一致するときだけ解決する const firstLabel = hostname.split('.')[0]; const map = { ...DEFAULT_MAP, ...parseMap(mapValue) }; return Object.values(map).find((target) => nameOf(target).toLowerCase() === firstLabel) || null; } ``` 設計上の勘所: - **`hostname` を使う**（`host` ではない）。ポート付き URL でも動く。 - **小文字化して比較する**。ホスト名は大文字小文字を区別しない。 - **不正 URL で例外を投げない**。ここで throw するとキュー全体が落ちる。 - **設定値の検証を第1キーと同じ厳しさで掛ける**。宛先文字列をシェル経由のコマンド （チケット CLI など）に渡すなら、コマンドとして解釈される文字を通さない: ```js if (/^[A-Za-z0-9.-]+$/.test(host) && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(target)) { /* 採用 */ } ``` - **明示表を環境変数で受ける**（`_HOST_MAP="host=owner/name,..."`）。 自動導出が効かない独自ドメインを、コード変更なしで救えるようにする。 ### 4-3. どの経路で解決したかを必ずログに出す ```js if (!primaryTarget) { console.log(`: 第1キーで解決できないため URL のホストで解決 host=${hostname} target=${target}`); } ``` **無言でフォールバックすると、後から「なぜこの宛先になったのか」を追えない。** 誤配送が起きたときに、原因がマッピング表なのかフォールバックなのか切り分けられなくなる。 --- ## 5. 「対象外にする」出口を用意する 宛先解決を強化しても、**どうしても投げるべきでないアイテム**は残る（テスト投稿、重複、対応不要と明記された報告）。 出口が「投げる」しかないと、次の二択になってしまう: - 読めないタイトルのチケットを本番に残す - 永久に詰まらせる どちらも悪い。**ack だけして対象外にする経路**を用意する。 ```js // 完了通知（ack）だけを送って、キューから外す const res = await fetch(ackUrl, { method: 'POST', headers: { 'Content-Type': 'application/json', authorization: `Bearer ${secret}` }, body: JSON.stringify({ message_id: TARGET_ID }), }); ``` 運用上の条件: - **対象外にする根拠を残す**（手順3の同定結果、元メッセージへのリンク）。ack は取り消せない。 - 元アイテムがチャット等に残っているなら、そのリンクをアイテムが持っているか確認してから外す。 **一次ソースが消えない**ことが、ack を安全にする唯一の担保。 - 繰り返し発生するなら、ツール本体に `--dismiss ` のような**サポートされた出口**として実装する。 --- ## 6. 検証（ここを飛ばすと直っていない） ### 6-1. 単体テストは「実測値」で書く 化けた文字列は**適当な代用文字列で代替しない**。実データのコードポイント列をそのまま再現する。 代用すると、実際の壊れ方（`U+FFFD` の位置と個数、偶然生き残った実在文字）を再現できず、 **テストが緑でも実データが通らない**。 ```js const brokenName = String.fromCodePoint(0xfffd, 0x77, 0xfffd, /* …実測列… */); ``` 固定すべきケース: | # | ケース | 期待 | |---|---|---| | 1 | 設定表の解析（正常値・不正な宛先・不正なホスト・空要素） | 不正値だけ落ちる | | 2 | URL の先頭ラベルから既知の宛先を自動導出 | 設定なしで解決 | | 3 | 表に無いホスト | `null`（推測しない） | | 4 | 明示表が自動導出より優先 | 明示表の値 | | 5 | 空文字・不正 URL | 例外を投げず `null` | | 6 | 化けた名前 + 健全な URL | 候補になる | | 7 | **正常な名前**（回帰防止） | 従来と同じ宛先 | | 8 | 化けた名前 + URL も無い | 候補にならない | | 9 | **正常な名前 + 別宛先を指す明示表**（優先順位の回帰防止） | 名前側が勝つ | ### 6-2. 実データで通し確認する **テストが緑でも、実データの1件が通る証拠にはならない。** 必ず**本番キューに `--dry` を当てて**、詰まっていたそのアイテムが解決されることを目視する。 ``` : 第1キーで解決できないため URL のホストで解決 host=… target=… : 作成予定 target=… title=… ``` ### 6-3. 修正が「実際に走る場所」に届いているか確認する **main にマージしただけでは、定期実行しているマシンでは動かない。** 定期タスクが参照している作業ツリーが、古いブランチや未同期のままになっていないか必ず確認する: ```bash # 定期実行が参照しているディレクトリで git branch --show-current grep -c '<新しく足した関数名>' <対象ファイル> # 0 なら修正は届いていない ``` 0 だった場合は「直った」と報告してはいけない。同期の段取りまでが作業の範囲。 --- ## 7. チェックリスト - [ ] キューの `残り` が何日も減っていないログを確認した - [ ] 問題フィールドを**コードポイント列**で見て、データ破損か表示問題かを判別した - [ ] 同じアイテムの**他のフィールドが健全か**を確認した - [ ] 化けた文字列を指紋照合で同定し、**対応要否を判断できる根拠**を得た - [ ] 第2キーへのフォールバックを**許可リスト方式**で実装した - [ ] 第1キーで解決できる場合の挙動が**変わっていない**（回帰テストで固定） - [ ] どの経路で解決したかを**ログに出している** - [ ] 「対象外にする」出口があり、一次ソースが消えないことを確認した - [ ] 実測コードポイントを使ったテストが緑 - [ ] **本番キューに `--dry` を当てて**、詰まっていた1件が解決されることを確認した - [ ] **定期実行しているマシンの作業ツリーに修正が届いている**ことを確認した ---