hachiflow.com

この記事は、当社の以前の製品 Buzz についてのものです。現在、当社は Waggle を作っています。

ペアリング

QR デバイスペアリングが 404 になる理由。起動されなかったサイドカー

コードを読み取り、失敗を見る。デバイスペアリングには、まだペアリングしていない端末でも届くチャネルが必要です。メンバーシップで守られたリレーでは、それはループバックにバインドされた別プロセスです。リレーのイメージに同梱されているからこそ、起動し忘れても気づきません。私たちもそうでした。

QR コード以外はすべて動いている

届く報告には、役に立つ詳細がありません。そもそも伝えられる詳細がないからです。誰かがデスクトップで Buzz を開き、スマートフォンを追加する項目を選ぶと、すぐに QR コードが表示されます。それを読み取ります。数秒後、デスクトップにペアリングエラーが表示され、その文面には 404 が含まれています。

これは不可解です。リレーは明らかに正常だからです。メッセージは届き、ファイルはアップロードでき、招待も機能し、ペアリングに失敗しているそのデスクトップ自体も、いまこの瞬間リレーに接続しています。壊れているのはペアリングだけです。理由は、ペアリングが、設定したリレーと通信しない唯一の機能だからです。

未ペアリングのスマートフォンは、正面玄関をノックできない

メンバーシップを強制するリレーは、WebSocket 接続そのものに関門を設けます。ソケットを得る前に、自分が誰かを証明しなければなりません。それこそが、この機能を有効にする目的です。しかし、一度もペアリングしていないスマートフォンは、リレーが認識できるアイデンティティを何も持っていません。ペアリングのハンドシェイクを受け取るためにメインのリレーへ接続することはできません。接続に必要な鍵を手に入れる手段が、まさにそのハンドシェイクだからです。鶏が先か、卵が先か。

そのため、ペアリングのハンドシェイクは別の場所で、誰でも受け入れるチャネルを通じて行われます。1 種類のイベントだけを運び、履歴を持たず、2 分で相手を忘れる小さなリレーです。メンバーシップを強制しない公開リレーであれば、こうした仕組みは不要です。スマートフォンは、ほかの見知らぬ相手と同じように、メインのリレーへそのまま接続できるからです。帯域外のチャネルが存在するのは、まさに正面玄関に鍵をかけたからです。

チャネルは別プロセスで、目の前に隠れている

そのチャネルとは buzz-pair-relay で、Buzz のソースツリーにある別のバイナリです。意図的に小さく作られています。永続化なし、認証なし、履歴なし、イベントは 1 種類のみ。署名を検証し、重複を排除し、鮮度の期限を設け、接続数の上限は 128、フレームの上限は 4 KiB、接続ごとの寿命は厳格に 120 秒です。一度腰を据えて読み通せば、あとは気にしなくてよくなる類の部品です。

この記事の話は、そのデプロイに関する注記にすべて詰まっています。バインド先はループバックのみで、デフォルトは 127.0.0.1:5000。前段にリバースプロキシを置き、/pair をそこへルーティングし、TLS を終端し、読み取りタイムアウトを強制することが必要だと明記されています。パスの制限やアップグレード前の接続数の制限は、あえて自分では行いません。それはプロキシの仕事だからです。127.0.0.1 で待ち受けていても、何もルーティングされていないプロセスは、何もしないプロセスです。静かに、いつまでも。

そして、ここが厄介なところです。このバイナリは標準のリレーイメージの中に同梱されています。Dockerfile はリレーと一緒にこれをビルドし、/usr/local/bin/buzz-pair-relay にコピーします。探しに行けば、コンテナの中にちゃんとあります。インストールされているように見えるのは、実際にインストールされているからです。ただ一度も起動されず、何もそこへルーティングされていなかったのです。

クライアントはペアリング先をどう決めるか

QR コードを描く前に、デスクトップはどこでペアリングするのかをリレーに尋ねます。問い合わせは、リレーのオリジンに対する Accept: application/nostr+json 付きの素の HTTP GET で、標準の NIP-11 情報文書を取得するものです。その答えが、以降のすべてを決めます。

結果は 3 通りです。文書に pairing_relay_url があり、ws または wss の URL として解釈できれば、デスクトップはそれを使い、ほかは関係ありません。そうでなく、supported_nips に 43 が含まれていれば、リレーはメンバーシップを強制していると表明していることになり、デスクトップは従来の慣例にフォールバックします。リレー自身の URL に /pair を付け足すのです。どちらにも当てはまらなければ、メインのリレーを直接使います。公開リレーならそれが正解です。

罠は 2 番目の分岐です。この分岐は、実際に確かめた結果ではなく、リレーが公開している情報をもとに選ばれます。QR コードが画面に出る前に /pair が存在するかを確かめるものは何もありません。QR コードは、接続に成功した結果からではなく、URL から組み立てられるからです。そのため、メンバーシップを強制し、したがって正直に NIP-43 を公開しているリレーは、すべてのペアリングの試みを 404 かもしれないパスへ向かわせます。そして、それに気づくのはお客様です。

Buzz デスクトップ NIP-11 を読む pairing_relay_url リレーが公開 supported_nips: 43 従来方式: 同じホスト + /pair 404: 誰も待ち受けていない wss://pairing.example wss://relay.example/pair buzz-pair-relay ループバックのみ・ポート 5000 プロキシが /pair をここへ振り分ける
QR コードを描く前に、デスクトップはどこでペアリングするのかをリレーに尋ねます。ペアリングホストを公開しているリレーは、そのまま使われます。NIP-43 だけを公開しているリレーは、自分のホスト名に /pair を付けた先へクライアントを送ります。そのパスは、誰かがサイドカーを起動してルーティングするまで 404 のままです。事前に確認はしないので、どちらの場合でも QR コードは表示されます。

リクエスト 1 回で分かる

確認にスマートフォンも QR コードも 2 台目の端末もいりません。どこからでも curl で、リレーの公開ホスト名に /pair を問い合わせてください。

404 なら、そのリレーではいま、全員のペアリングが壊れています。知っておくべきなのは正常な場合の答えのほうです。それも失敗のように見えるからです。正しくルーティングされたサイドカーは 400 Bad Request を返します。curl は WebSocket アップグレードを送らず、サイドカーは正しい形式のアップグレードでないものを、何よりも先に 400 で拒否します。つまり 400 は良い知らせで、404 は悪い知らせです。その差は数字ひとつ、しかも誰も注意深く見ていない場所にあります。

次に、リレーが何を主張しているかを読みます。そもそも /pair をテストすべきかどうかが、それで決まるからです。pairing_relay_url が設定されていれば、クライアントはそちらへ向かうので、同じ 400 か 404 かのテストをそのホストに対して行います。設定がなく、一覧に NIP-43 があれば、従来方式のパスが有効で、/pair こそ、すべてのクライアントがたどり着く場所です。

診断はこれだけ
# /pair に何か応答しているか? $ curl -i https://<relay-host>/pair # 404 ならペアリングは壊れています。400 Bad Request が正解です。WebSocket アップグレードではないリクエストをサイドカーが拒否している証拠です。 # リレーは NIP-11 文書で何を約束しているか? $ curl -sH 'Accept: application/nostr+json' https://<relay-host>/ \ | jq '{pairing_relay_url, nip43: (.supported_nips | index(43))}'

pairing_relay_url に値が返ってきたら、テストすべきはその URL で、/pair は使われません。null が返り、NIP-43 のチェックが null ではなく添字を返したなら、このホストの /pair こそ、すべてのクライアントが向かう先です。

修正方法は 3 つ、必要なのは 1 つだけ

起動して、ルーティングする。バイナリはすでにイメージに入っているので、必要なのは再ビルドではなく、2 つ目のサービスとプロキシのルールです。リレーと並べて buzz-pair-relay を実行し、前段に /pair のルートを追加して、WebSocket アップグレードをポート 5000 のサイドカーへ転送します。ルーティングするのは /pair だけにし、TLS と読み取りタイムアウトはプロキシ側に置いてください。サイドカーはそれを前提に書かれています。

あるいは、専用のホスト名を与える。リレーに BUZZ_PAIRING_RELAY_URL を設定すると、リレーは NIP-11 文書で pairing_relay_url を公開します。クライアントは従来の慣例を完全に飛ばし、専用のエンドポイントへ直接接続します。Helm チャートでは pairingRelay.enabled と pairingRelay.url がそれにあたり、サイドカーを独立した Deployment と Service としてポート 5000 で動かします。チャートは意図的にそのための Ingress を作成しないので、そのホスト名のルーティングは引き続きあなたの仕事です。

あるいは、していないことを公開するのをやめる。リレーが実際にはメンバーシップを強制していないなら、そもそも NIP-43 を公開すべきではありません。そうすれば、クライアントが従来方式の分岐を取ることはありません。上流はまさにこの理由で、サポートする NIP の静的な一覧から NIP-43 を外しており、その判断をテストで固定しています。そのテストのコメントには、公開リレーでこれを公開すると、ペアリングの相手が存在しない /pair サイドカーへ誤ってルーティングされる、とはっきり書かれています。

私たちもこの穴を出荷していました

私たちのマネージドテナントも、サイドカーを一度も起動しないままリレーイメージを動かしていました。バイナリはその間ずっとコンテナの中にありました。見つけ方は誰もが同じで、QR コードを読み取ったときです。この問題を隠す要因は 3 つ重なっており、どれも誰かの不注意ではありません。サイドカーはループバックにバインドするので、派手に失敗することがありません。イメージに同梱されているので、存在しているように見えます。そしてクライアントは確認ではなく宣言をもとに従来方式のパスを選ぶので、QR コードは接続を試みるその瞬間まで完璧に表示されます。自分は大丈夫だと決めつけるより、確かめておく価値のある故障モードです。メンバーシップを強制する Buzz リレーを運用しているなら、誰かがコードを読み取る前に、このページの冒頭にあるリクエストを 1 回送ってみてください。

← フィールドノート一覧