アドオン「テキストリンク」のWebExtensions移行、失敗と成功の分かれ目について

[この投稿は個人サイトとのクロスポストです](http://piro.sakura.ne.jp/latest/blosxom/mozilla/xul/textlink/2017-11-04_migration-we.htm)。

Firefox 57で従来型のアドオンが使えなくなるという事で進めているアドオンのWebExtensions移行作業ですが、[ツリー型タブ](https://qiita.com/piroor/items/21ce5c99d5311973661b)、[マルチプルタブハンドラ](http://piro.sakura.ne.jp/latest/blosxom/mozilla/extension/multipletab/2017-10-13_migration-we.htm)に続いて、[テキストリンク](http://piro.sakura.ne.jp/xul/textlink/)もWebExtensionsに移行しました。移行後の最初のバージョンは6.0.0で、そこから若干の修正を施した最新版は6.0.1となっています。

### テキストリンクってどんなアドオン？

テキストリンクは、[テストケースの各種の例](http://piro.sakura.ne.jp/xul/textlink/#testcases)のようにWebページ中に普通のテキストとして書かれたURI文字列を、ダブルクリックするだけでリンクのように読み込めるようにするという物です。最盛期には10万を超えるユーザーに使われていた事もあった、僕がMozilla Add-onsに登録していたアドオンの中では統計上最もユーザー数の多「かった」アドオンです。

個人的にもこれが無いとイラッとする場面が結構あって地味に依存度が高かったので、いずれWebExtensions移行はするつもりでいたのですが、先月末にMozilla Corporationのアドオンコミュニティマネージャーの方（[昨年のMozLondon](http://piro.sakura.ne.jp/latest/blosxom/mozilla/xul/2016-06-20_mozlondon-technical-topics.htm)にアテンドしてくださった方）から「そろそろFirefox 57リリースが近付いてるけど、テキストリンクの移行はどんな感じ？（大意）」というメールを頂いてしまい、顔を合わせた事のある人から直々にせっつかれてはやらないわけにはいくまい……と、予定を繰り上げて移行に着手したのでした。

メールをもらってからリリースまでに要したのがちょうど1週間で、これまでの2例の難航度合いに比べるとびっくりするぐらいあっさり完了した感があります。数を重ねてきてだんだん「WebExtensionsのやり方」に慣れてきたということでしょうか。

実を言うと、テキストリンクは[1年ちょっと前にWebExtensions移行に挑戦してみた事があった](https://github.com/piroor/textlink/tree/webextensions)のですが、その時は途中ですっかり投げ出してしまっていたのでした。今回は、この時の成果物をまるっきり無視しての再挑戦での成功と相成りました。

1回挫折した物が仕切り直して成功したという典型的な例なので、ここでは「何故前回は失敗し、今回は成功したか」という観点から語ってみようと思います。



### 移行に失敗した時にやった（やろうとした）事

過去の挑戦時の方針は、端的に言えば「最低限の手直しでの移行」ということになります。

テキストリンクは初版が2004年という非常に歴史の古いアドオンで、Firefoxの仕様変更に対し、その都度手直しでの追従を繰り返してきました。最初のバージョンからバージョン4までの間、テキストリンクはすべての処理が特権領域内で完結する仕様でした。バージョン5でのe10s（マルチプロセス）への対応にあたって、DOM RangeなどのWebページの生のDOMに触らないといけない「コンテントプロセス側で実行しなくてはならない処理」を分割するという変更を行いましたが、本質的な設計はずっと変化していなかったと言えます。

その延長線上にあったこの時の進め方は、[WebExtensions化の作業用にブランチを切って](https://github.com/piroor/textlink/tree/webextensions)、元のコードを「バックグラウンドスクリプト用」や「コンテントスクリプト用」といったフォルダに移動し、XPCOMやXULに依存していた部分を除去していく形でそれぞれのソースの中身を破壊的に変更していく、というものでした。

旧版テキストリンクは、選択範囲（※カーソルも選択範囲の一種なのです）からのURI検出や、ユーザーの操作からタブで開くかウィンドウで開くかといった判断を行う部分など、主要な処理のほとんどがコンテントプロセス側で動作する設計でした。chromeプロセス側は、コンテントプロセスからの指示に従って実際にタブやウィンドウを開くだけという感じです。

また、それとは別にコンテキストメニュー周りの実装がchromeプロセス側にあり、こちらはユーザーがコンテキストメニューを開いたタイミングで処理を開始して、コンテントプロセスに処理を依頼してはその結果を受け取って……という事を繰り返すようになっていました。

これをそっくりそのままWebExtensionsに持っていこうとすると、主要な処理はすべて[コンテントスクリプト](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Content_scripts)に移植することになります。しかし、WebExtensionsではコンテントスクリプトでできる事の範囲が大きく制限されています。そこで「コンテントスクリプトではこの機能が動かないのでバックグラウンドスクリプトに移す」という事をその都度やっていると、キリが無い上に、場当たり的な切り貼りの繰り返しでコードはどんどんカオスになっていきます。

また、従来のアドオンでの「コンテントプロセスで動作するスクリプト」とWebExtensionsの「コンテントスクリプト」には大きな違いがあります。それは、*従来のコンテントプロセス用スクリプトは「1つのプロセスにつき1つのインスタンスが作られる」のに対し、コンテントスクリプトはタブ内のフレームの数だけインスタンスが作られる*という点です。プロセスの数だけインスタンスが増えるという時点でいかがな物かという感じですが、フレームの数だけ増えるとなると、さすがに主要な機能をそこで動かすのは非効率的です。

このほか、コンテキストメニュー項目の動的な更新についての知見がなかったために、選択範囲からのURI文字列の検出結果を受けてメニュー項目を制御するやり方が分からなかった事や、XPCOMとXULがあることを前提として書かれたコードを総点検してXPCOMフリーに書き直すにあたって、代替手段が見つからなかった処理がいくつかあった（WebExtensionsでも最新のWeb技術でも機能が提供されていない部分があった）事など、数々の困難に嫌気がさし、また[「シス管系女子」](http://system-admin-girl.com/)の連載の〆切が迫っていた事も相まって、道半ばで移行作業を放棄してしまったのでした。

[TSTの移行に際しての振り返り](http://piro.sakura.ne.jp/latest/blosxom/mozilla/extension/treestyletab/2017-10-03_migration-we-ja.htm)で「直接Firefoxの中身をいじくり回していたレガシーなアドオンを『若干手直ししてFirefox 57でも使えるようにする』ということは不可能」と書きましたが、この時の失敗はまさにこれが原因であったと総括できます。例えて言うなら、従来バージョンから持ち越した既存の実装という大荷物を背負って道を歩いていて、道のど真ん中にある車止めに荷物が引っかかってしまい先に進めず、「こんなもんどけてやる！」とばかりに軽く考えて邪魔な車止めを取り除こうとして、でも地面にしっかりコンクリートで固定されていて蹴っても叩いても動きやしなくて、その埒の明かなさと背負っている荷物の重みとのダブルパンチで心が折れてしまった……という感じでしょうか。


### 移行に成功した時にやった事

今回の再挑戦では、TSTやMTHのWebExtensions移行で成功をもたらした*「旧版の動作をリファレンスとして、同等のユーザー体験をもたらす新しいWebExtensionsベースのアドオンを新規に開発する（つもりで臨む）」というやり方*を取りました。具体的には以下の順で作業を進めました。

 1.  「選択範囲とその前後のテキストの抽出」といった必須の要素技術をコンテントスクリプトで実装する。
 2. 文字列からのURI文字列の検出という、純粋にJavaScriptのコードだけで完結できるモジュールを、従来版から選択的にバックグラウンドスクリプトとして移植する。
 3. ダブルクリック操作をトリガーとして、コンテントスクリプトで可視状態のテキストを抽出し、それをバックグラウンドスクリプトに送ってURIを検出させて開く、という形で最も基本的な機能を実装する。
 4. 開いた後のURI文字列を選択範囲にする、という挙動を実装する。
 5. 選択範囲の変化をトリガーとして、コンテントスクリプトで可視状態のテキストを抽出し、それを材料にバックグラウンドスクリプトでURI文字列の検出とコンテキストメニューの更新を行う、という一連の事を実装する。
 6. テキスト編集領域内での動作に対応する。
 7. 設定画面を実装する。

この説明にも表れている通り、今バージョンのほとんどのコードはスクラッチで書いた物で、旧版からコードを引き継いだのは「文字列の中からURIらしき部分を検出する」部分だけです。以下、一般的な話は省略してテキストリンクに固有の事情だった部分に絞って詳しく述べます。


#### 選択範囲やその前後にあるテキストの、見た目通りの状態での抽出

URI文字列を検出するにあたっては、`window.getSelection()`で取得できるRangeの`toString()`の結果ではなく、「ページ中で目に見えているとおりのテキスト」を対象にマッチングを行わなくてはいけません。というのも、Rangeの`toString()`はその範囲にあるテキストノードの内容を単純に連結した結果を返す物なので、親要素が非表示であるテキストノードがある場合や、CSSの`display:block`などで見た目上改行されているだけの部分がある場合に、「見た目上は改行されているように見えるのにデータ上は改行が存在しないので、複数の行が連結されて見える（そのためURI文字列の検出結果がおかしくなる）」という事が起こるからです。

旧版では、Webページをプレーンテキスト形式で保存する場面や、ThunderbirdでHTMLメールとして編集された本文からプレーンテキストの本文を生成する場面などで使われる[nsDocumentEncoderというXPCOMコンポーネント](http://doxygen.db48x.net/mozilla-full/html/d6/d14/interfacensIDocumentEncoder.html)（`@mozilla.org/layout/documentEncoder;1?type=text/plain`）を使ってこれを一発で行えていたのですが、WebExtensionsでは当然使えません。[相当する機能を提供して欲しいというbug](https://bugzilla.mozilla.org/show_bug.cgi?id=1271534)はずいぶん前に立てたのですが、今に至るまで具体的な実装はまだなされていないままなので、諦めて自力で実装してみました。

詳しい事は[当該処理のソース](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/content_scripts/range.js#L8)を見てもらうのが一番早いのですが、簡単にいうと、[DOM2 TraversalのTreeWalker](https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker)を使って泥臭い事をやっています。TreeWalkerは`nextNode()`と`previousNode()`を使うとDOMツリー上の全ノードをツリー構造を無視して文書順で参照するイテレータとして使えるので、CSSのセレクタやXPathでは条件にできない生のDOMの情報を条件とした絞り込みを行っています。具体的には、[まず`NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT`でざっくりテキストノードと要素ノードに絞り込んで](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/content_scripts/range.js#L110)、さらに[そのノードの祖先に非表示の要素ノードがないかを`window.getComputedStyle()`で順にチェックして](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/content_scripts/range.js#L122)、確かに可視状態だと確認できたノードだけを取り出しています。その後、[テキストノードであれば`nodeVaue`を、要素ノードで`display:inline`以外の物があれば適宜改行文字を「表示されているテキスト」として取り出しています](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/content_scripts/range.js#L39)。

以上のようなやり方で、一応実用に耐える精度で「見た目通りのテキストを抽出する」を実現できたのですが、想像の及んでいなかったエッジケースなどで想定外の結果になる可能性は依然としてありそうな気がしています。[nsDocumentEncoder相当の機能](https://bugzilla.mozilla.org/show_bug.cgi?id=1271534)が実現されるまでは、まだまだ悩みは尽きない感じです。


#### 文字列からのURIの検出処理

[与えられた文字列からURIを検出する処理](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/background/uriMatcher.js)は、今回の移行で唯一、旧バージョンからほとんどそのままコードを引き継いだ箇所です。

この処理は、データ量にして最終的に完成したWebExtensions版テキストリンクの全体の1/3を占める巨大なモジュールなのですが、やっている事は至って単純で、[「相対パスも許容するのか？」「全角英数字も許容するのか？」等の条件に基づいてURIらしき文字列にマッチする正規表現を組み立てるだけの物です](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/background/uriMatcher.js#L155)。相対パスを絶対パスに解決する部分などでXPCOMコンポーネントの機能を使っている部分はありましたが、全体の中ではそういった箇所はごく一部に限られており、ほとんどは単純な文字列処理だけで構成されていました。

また、元々自動テストを容易にするためにモジュール間の結合を弱めていた結果、[機能を使うのに必要なパラメータはほとんどすべて外部から与えられるようになっており](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/background/uriMatcher.js#L928)、旧テキストリンクの実装の中ではここだけ突出して浮いているようにも感じられるほどでした。

そういう事情があったため、このモジュールについてはほとんど苦労する事なくほぼそのままの形でWebExtensions版に組み込む事ができました。


#### ダブルクリック操作で開いた後のURI文字列を選択範囲にする

旧版テキストリンクでコンテントプロセス側に大部分の処理があったのは、[「URI文字列として検出した部分を新しい選択範囲にする」という挙動](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/content_scripts/range.js#L204)を実現したかったからでした。これをやるには、Rangeを対象に文字列を検索してヒット箇所をRangeで返すというAPIが不可欠です。

旧版では[nsFindというXPCOMコンポーネント](http://doxygen.db48x.net/mozilla-full/html/df/def/interfacensIFind.html)（`@mozilla.org/embedcomp/rangefind;1`）を使ってこれを実現していましたが、当然ですがこれはWebExtensionsでは使えません。また、W3Cで提案されていたらしい[RangeFinderというAPI](http://w3c.github.io/rangefinder/)が実装されていればそれで代替できたのですが、こちらは残念ながら未実装です。という具合で代わりの手段がなかったという事が、過去の移行失敗時に移行を断念した理由の1つでもありました。

幸い、最近になってWebExtensionsに[`browser.find`](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/find)というAPIが追加され、Firefox 57ではRangeFinder的な事ができるようになっています。なので今回はこれを使ってみる事にしました。

RangeFinderを使う時にネックになるのが、DOM Rangeの取り扱いです。コンテントスクリプトとバックグラウンドスクリプトの間ではJSON文字列に変換できるデータしか交換できないのですが、`browser.find`はコンテントスクリプトでは動作しないためバックグラウンドスクリプトで呼び出す必要があり、しかし選択範囲の操作はコンテントスクリプト側でやらなくてはならない……ということで、どうやってDOM Rangeの情報を双方の間で受け渡すかが問題となります。

この事について何かヒントはないかと[`browser.find.find()`](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/find/find)の説明を読み進めてみた所、まさに[この通りの事をやる例](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/find/find#Using_rangeData)が載っていました。このAPIは[`rangeData`という形式](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/find/find#Return_value)で検索結果のRangeをシリアライズして返すようになっており、その情報に基づいて[コンテントスクリプト側でRangeを組み立てれば良い](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/content_scripts/range.js#L233)ようです。DOM Rangeをシリアライズして受け渡す事自体は容易に考えつくものの、どういう考え方でシリアライズするかという事についてはいろいろな考え方が可能であったため、自分で考えていたらそれだけでまた時間がかかってしまっていたでしょう。「既に動いている実装があるのなら、それとフォーマットを揃える」という具合に考える手間を省けたのは助かりました。

ただ、実際に`browser.find.find()`を使ってみるとメチャクチャ遅いです。それもそのはず、このAPIは検索対象の範囲をRangeで絞り込む事ができなくて、実行すると必ずページ全体を対象に検索し、しかもすべてのヒット箇所を列挙してくるのです。検出対象のURIの数が増えれば増えるほど実行回数が増え、ページが長くなればなるほど1回あたりの処理時間が増えるという感じで、テストケースのページ全体からURIとしてマッチした箇所をRandeで取り出すのにトータルで10秒とかそのくらいかかってしまいました。なので最終的には、バージョン6.0.1の時点では「選択範囲が変化したらまず`browser.find.find()`無しでURI文字列の検出だけを行い、それらを開くとかコピーするとかの操作が行われた時点で初めて`browser.find.find()`を実行してRangeを取り出す」という風にして、日常的な操作であるテキストの範囲選択とコンテキストメニューの操作に悪影響が出ないようにしています。


#### 選択範囲の内容に応じてコンテキストメニュー項目の表示・非表示を切り替える

Firefoxの各種メニューに項目を追加するためのAPIである[`browser.menus`（`browser.contextMenus`）](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/menus)では、[`menus.ContextType`](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/menus/ContextType)のいずれかを伴って定義したメニュー項目については、その指定にマッチする場面でのみ表示されるようになります。その中に`selection`というコンテキストもあり、テキストリンクの「選択範囲内のURIを待て馬手開く」系の機能はそのようにして登録しています。

しかし、ここに1つ問題があります。このコンテキストでは*「テキストを範囲選択しているかどうか」しか考慮されず、「その中にどういう内容が含まれているか」までを判断材料とする事ができないの*です。

テキストリンクは選択範囲のURI文字列を開く物ですから、選択範囲にURIらしき文字列が無い時にまでメニュー項目が表示されるのは混乱の元です。そこで旧版ではコンテキストメニューが開かれる瞬間に発火する`popupshowing`イベントを検知してメニュー項目の表示・非表示を切り替えていたのですが（これ自体はXULで作られたアドオンの一般的な作法です）、他方、WebExtensionsの[`browser.menus`で監視できるイベント](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/menus#Events)には「メニューが開かれた時」に発火されるイベントがありません。これじゃあ動的にメニューの表示・非表示を切り替えられないじゃないか！ということで、これも過去の移行失敗時の躓きポイントの1つとなっていました。

現時点に至るまで`popupshowing`を代替できるイベント型はまだ実装されていないままなのですが、この回避策はTSTやMTHのWebExtensions移行を進める中で知らず知らずのうちに気が付いていました。要するに、*「コンテキストメニューが表示されようとしているその時にメニューを更新する」のではなく、「コンテキストメニューの内容に影響を与える変化が起こったまさにその時に先行してメニュー項目を変化させておく（メニューが開かれる時には、既に定義済みのメニュー項目が表示されるだけになる）」*という事なのです。その後実際にコンテキストメニューが開かれなければこの時の処理はまるっきり無駄になってしまいますが、これ以外に方法がない以上は仕方ありません。

WebExtensions版テキストリンクでもこの方針に則って、「[`selectionchange`イベント](https://developer.mozilla.org/en-US/docs/Web/Events/selectionchange)を[コンテントスクリプトで監視し](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/content_scripts/content.js#L149)、変化があったらその時点で[選択範囲からのURI文字列の検出を開始する指示をバックグラウンドスクリプトに送る](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/content_scripts/content.js#L196)」→「[バックグラウンドスクリプトでコンテキストメニューの内容を更新する](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/background/background.js#L94)」という事を行うようにしました。バージョン6.0.0の時点では前述の`browser.find.find()`がメチャクチャ遅いという問題に引きずられて、範囲選択から数秒待たないとコンテキストメニューの内容が更新されないという状況でしたが、バージョン6.0.1で[範囲選択時のURI検出には`browser.find.find()`をバイパスした簡易的な処理を使うようにした](https://github.com/piroor/textlink/blob/52b3cb102df31c18a0649ee6ff0a2903864105cb/webextensions/background/uriMatcher.js#L112)結果、概ね一瞬でメニューを更新できるようになり、実用上ほとんどの場合では「しばらくお待ち下さい」的なメッセージを目にする事はなくなりました。

この件を通じて、コンテキストメニューで[APIで用意されているコンテキスト](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/menus/ContextType)以上にきめ細かい判断を行いたい場合に、WebExtensionsでのベストプラクティスはレガシーなXULアドオンでのベストプラクティスとはまったく異なるのだ、という事をまざまざと思い知らされたのでした。


#### テキスト編集領域への対応

旧版テキストリンクでは、`<textarea>`などのテキスト入力欄についてもXPCOMコンポーネントの機能を経由して内部的なDOMツリーに触っていました。これは、上記の「検出したURIの箇所を新しい選択範囲にする」という挙動を実現したかったからです。しかしWebExtensionsではその方法が使えず、テキスト入力欄内部のDOMツリーには触れません。

じゃあどうすればいいのかという話なのですが、これについては「無理なものは無理」という事で、テキスト入力欄の選択範囲はその要素ノードの`selectionStart`/`selectionEnd`/`setSelectionRange()`を介して触れる範囲以上の事はしない事にしました。

移行に失敗した時の考え方だと、こういう時も何か対策はないかと手を尽くして、それでも機能が見つからなくて仕方なくBugを立ててそれが解決されるのを待つ、という事になっていたでしょうが、今回は「完全でなくても今できる範囲でできる事だけをする」という方針だったため、この点はリリースをブロックする要因にはなりませんでした。


### まとめ

[はじめからやり直したい症候群](http://www.hyuki.com/kokoro/#hajime)や、それに類する言葉を見かける事があります。プログラミングの世界においても、メジャー製品の大規模アップデートで「ここらで一区切り付けて、最初から作り直してもっとスッキリした設計にしよう」みたいな事をやろうとして、収拾がつかなくなり失敗に終わってしまい、最終的に旧版からの小規模な修正のみに留めるしかなかった……みたいな事はたまにあります。そういった事例をいくつか見聞きして、また自分自身もそういった無謀な挑戦をしようとして挫折するという経験を何度かした結果、*「スクラップ＆ビルドですべてが上手くいくようになるというのは甘い幻想で、実際には地道な改良をコツコツ続けていくしか無い」という教訓*が、自分の中である種の呪いのように刻み込まれていました。

しかし実際には、その「教訓」に従って進めようとした前回の移行は失敗に終わり、大部分でスクラッチに近いレベルでの作り直しとなった今回の移行の方が成功するという皮肉な結果となりました。ただし、今回スクラッチせず引き継いだ部分まで作り直していたら、この移行は再び失敗に終わっていた事でしょう。

 * 「ああもうめんどくさい、リセットしちまおう」と乱暴に投げ出してしまわず、小さな改良の積み重ねで乗り切るのが適切な場合
 * 「これは小さな変更で乗り切れるようなレベルの話じゃない」と割り切って、一からやり直す方が適切な場合

今まさに自分が直面している問題がどちらのケースなのか、を適切に見極めるのは難しい事です。考える事を放棄して当て推量で雑な判断をすれば、痛い目を見ることになるのは自分自身です。確実な成功に繋げるためには、そこで使おうとしている・使わなければならない技術の特性と限界、現行技術とのギャップの大きさ、取り組んでいる問題の複雑さなど、様々な要因を考慮に入れた総合的な判断を、プログラム全体やモジュール単位で下す必要がある、という当たり前といえば当たり前の事を、自分は今回の移行を通じて実感した次第です。