A2A (Agent2Agent) is a protocol for AI agents to collaborate with each other. By using A2A, it becomes possible for AI agents built by different vendors or with different frameworks to communicate with each other. As an example of such communication, one could imagine a scenario where an internal "accounting agent" (client) requests a "tax check agent" (remote) operated by an external tax accountant firm to check monthly journal entries.

In this example, let's say the external tax accountant firm does not want to expose the tax check agent publicly on the internet. To meet such needs, Seera Networks, Inc. has developed and released ISEKAI portal. ISEKAI portal is an application that runs on top of ISEKAI link, whose mechanism was introduced in a past article. In this article, as a demonstration, I would like to introduce an example of connecting to helloworld-server included in a2a-rs, which is an implementation of A2A written in Rust, via ISEKAI portal using a2acli, which is also included in a2a-rs.

Note that terms from ISEKAI link such as Endpoint and Grant appear in this article. An Endpoint is an endpoint identified by a key, and a Grant is a time-limited permission that allows a specific Endpoint to connect to a Listener. A Listener is a gateway through which portal-server, etc. waits for connections. For details, please refer to the past article.

Also, since we use a2a-rs, both the local Windows environment and the remote Linux environment need the Rust toolchain and git. On Windows, MSVC build tools (Visual Studio Build Tools) are also required.

Installing ISEKAI portal

Since ISEKAI portal publishes its source code under the MIT license, you can clone the repository and build it yourself. However, since the build process is a bit of a hassle, it is convenient to download pre-built binaries from Releases. Currently, binaries are available for the following three platforms:

• Windows (amd64)
• Linux (Ubuntu, amd64)
• Mac (arm64)

All binaries are provided in zip format, and when extracted, a directory with the same name as the file is created (on Windows, portal-windows-latest), so add it to your PATH. Now you are ready to run it from the terminal.

Setting up ISEKAI portal

Once installed, perform the setup. In the following, I will explain under the assumption that the server runs on Linux and the client runs on Windows.

Setting up portal-server

Preparation for setup

If you are accessing the Linux machine running the server remotely, forward TCP port 38700 locally using ssh as follows.

PS C:\Users\foo> ssh -L 38700:127.0.0.1:38700 foo@bar.example.com

As described later, login must be performed via a web browser, and after logging in, the web browser connects to TCP port 38700 opened by portal-server. When accessing remotely, however, TCP port 38700 is open on the remote Linux machine, so it needs to be forwarded to the local environment. This step is not necessary if you are operating Linux locally.

Also, create a directory to store the configuration files used by ISEKAI portal.

$ mkdir -p ~/.config/ISEKAI-portal

Agreeing to the privacy policy

Using ISEKAI link requires signing up, and at that time you are asked to agree to the privacy policy that defines how personal information collected is handled. When you start portal-server, the privacy policy is displayed, so please review it and run the following command to agree. Until agreement is given, portal-server will display the privacy policy and exit.

$ portal-server --accept-privacy-policy

The privacy policy is also published on the web (Japanese version and English version).

Logging in

ISEKAI link uses Auth0 for account management. Logging in is required to use it. To log in, run the following command (the --key option specifies the file of the Endpoint's private key, but since the file that stores login information is created in the same directory, it is also specified here).

$ portal-server --key ~/.config/ISEKAI-portal/portal-server.pem --login

When started, a URL is displayed, so access it with a web browser. When you access it, a screen saying "Enter Your Organization" appears, so click "Continue with personal account." Then a login screen saying "Welcome" appears, so if you already have an account, log in. If you do not have an account, click "Sign up" to move to the account creation screen. An account can be created with an email address and password, but it can also be created with a Google account or a GitHub account.

Creating the configuration file

In ISEKAI portal, the connection destination is specified by the service name. The portal-server configuration file is used for this setting. Here, save it as ~/.config/ISEKAI-portal/portal-server.toml with the following contents.

[service.a2a]
protocol = "tcp"
target   = "127.0.0.1:3000"

Starting portal-server

Now that preparation for startup is complete, run portal-server as follows. --key specifies the path to the private key; if the file does not exist, a private key is generated. If the file exists, the private key is read from it. --register must be specified if the Endpoint is not yet registered. On the first startup, a private key is generated and a new Endpoint is created, so --register is required. From the second time onward, do not add it (adding it will cause an error).

$ portal-server --key ~/.config/ISEKAI-portal/portal-server.pem --config ~/.config/ISEKAI-portal/portal-server.toml --register

Setting up portal-client

The setup for portal-client is almost the same as for portal-server. First, create a directory (folder) to store the configuration file.

PS C:\Users\foo> mkdir $HOME\.config\ISEKAI-portal

Next, log in while agreeing to the privacy policy. Note that from the second time onward, such as when you want to log in with a different account, --accept-privacy-policy is not necessary.

PS C:\Users\foo> portal-client --key $HOME\.config\ISEKAI-portal\portal-client.pem --login --accept-privacy-policy

Enter the URL output as before into a web browser and log in (for organization selection, click "Continue with personal account"). Here, use the account created earlier to log in (since it can be configured to accept connections from Endpoints of different users, there is no problem with creating a new separate account).

Finally, find out the Endpoint ID.

PS C:\Users\foo> portal-client --key $HOME\.config\ISEKAI-portal\portal-client.pem --whoami

A string starting with "ep:" is output, and this is the Endpoint ID. It will be needed when creating a Grant, so make a note of it.

Issuing a Grant

There are various ways to issue a Grant, but here I will introduce how to issue one manually from the dashboard. This method can be used as long as the destination portal-server is running.

First, access the ISEKAI link dashboard with a web browser. Since login is required, enter the information of the account you are logged in with on portal-server (as mentioned repeatedly, for organization selection, click "Continue with personal account").

Once logged in, a menu appears at the top, so click "Grant" ("Grants" in the English version). You will move to the Grant screen, so fill in the "Create a grant" form ("Grantを作る" in the Japanese version). The Listener should be listed among those displayed when portal-server was started during setup, so select it. In the text input for "Endpoint to let in" ("入れる相手の Endpoint" in the Japanese version), enter the Endpoint ID of portal-client that you noted earlier. "Lifetime" ("寿命" in the Japanese version) is the expiration period of the Grant to be created. Choose from 1 hour, 8 hours, or 24 hours. The "Label" text input ("ラベル" in the Japanese version) allows you to enter a memo for your own management. Here, enter "a2a". Once you have finished entering the information, click the "Create grant" button ("Grant を作る").

This completes the setup.

Actually connecting

First, start portal-client on the local Windows machine and connect to portal-server on the remote Linux machine. --register is required only on the first startup (adding it from the second time onward will cause an error). The meaning of the --map argument is to accept connections on TCP port 3000 of the local host and forward those connections to the a2a destination specified by portal-server. The reason portal-client listens on TCP port 3000 is that a2acli's default connection destination is TCP port 3000.

PS C:\Users\foo> portal-client --key $HOME\.config\ISEKAI-portal\portal-client.pem --map 3000:a2a --register

After starting, if the following string is output, it is successful.

tcp 127.0.0.1:3000 -> a2a
ready

Next, on the remote Linux machine, perform the work of launching helloworld-server, which is an A2A sample server. The portal-server you started earlier is running in the foreground, so leave that session as is and perform the following work either by connecting with a new ssh session or by starting a new session with tmux, etc. (in the case of ssh, local port forwarding is not necessary).

First, clone the a2a-rs repository.

$ git clone https://github.com/a2aproject/a2a-rs.git
$ cd a2a-rs

Next, modify helloworld-server.

$ vi examples/src/helloworld/server.rs

The modifications are as follows.

--- a/examples/src/helloworld/server.rs
+++ b/examples/src/helloworld/server.rs
@@ -53,8 +53,8 @@ async fn main() {
     tracing::info!("REST:        http://localhost:3000/rest");
     tracing::info!("gRPC:        http://localhost:50051");

-    let http_listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
-    let grpc_listener = tokio::net::TcpListener::bind("0.0.0.0:50051")
+    let http_listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
+    let grpc_listener = tokio::net::TcpListener::bind("127.0.0.1:50051")
         .await
         .unwrap();

This modification is made because, by default, the helloworld-server service may be exposed to the internet. helloworld-server is written to listen on the address 0.0.0.0. To prevent this, we rewrite the listening address to 127.0.0.1.

After rewriting, run cargo run as follows.

$ cargo run -p examples --bin helloworld-server

Then, in a separate session, verify that it is only listening on localhost.

$ ss -tlnp | grep "hello"

If the listening address is 127.0.0.1 as shown below, it is successful.

LISTEN 0      128                      127.0.0.1:3000       0.0.0.0:*    users:(("helloworld-serv",pid=1732081,fd=9))                
LISTEN 0      128                      127.0.0.1:50051      0.0.0.0:*    users:(("helloworld-serv",pid=1732081,fd=10))

Finally, start a2acli on the local Windows machine. By default, a2acli connects to TCP port 3000 on localhost via HTTP, so it connects to the portal-client started earlier and is forwarded to helloworld-server on the remote Linux machine.

PS C:\Users\foo> git clone https://github.com/a2aproject/a2a-rs.git
PS C:\Users\foo> cd a2a-rs
PS C:\Users\foo\a2a-rs> cargo run --bin a2acli -- card get

If the connection succeeds, a string like the following is output.

Name: Hello World Agent
Description: A simple echo agent that returns the input message.
Version: 1.0
Streaming: true
Push Notifications: false
Extended Card: false
Interfaces:
  - JSONRPC http://localhost:3000/jsonrpc (v1.0)
  - HTTP+JSON http://localhost:3000/rest (v1.0)
  - GRPC localhost:50051 (v1.0)

Skills: 1

Let's also try running a task. Run it as follows.

PS C:\Users\foo\a2a-rs> cargo run --bin a2acli -- send "hello from rust"

If a string like the following is output, it is successful.

Task ID: 01a119a8-885d-76dc-abde-1dea996fc2e4
Context ID: 01a119a8-885d-76dc-abde-1debf9b5c586
State: COMPLETED
Text:
Echo: hello from rust

In this way, we were able to communicate via A2A through ISEKAI portal. Note that GRPC is not forwarded, so it cannot be used in this example.

Summary

In this article, I introduced an example of connecting from a2acli on Windows to helloworld-server on Linux via A2A through ISEKAI portal.

What I would like you to pay attention to here is that no configuration for accepting external connections is performed at all on the Linux side running helloworld-server. portal-server only connects outbound to ISEKAI link. Therefore, there is no need to change firewall or router settings, and the agent is never directly exposed to the internet.

Also, who can connect is managed by Grants. This time, only the Endpoint of portal-client was specified as the connection partner, and an expiration period was also set. For parties without an issued Grant, portal-server does not reveal what Listeners are open, so they cannot even know that the service exists. Moreover, even for parties with an issued Grant, once the period expires, they can no longer connect.

Applying this to the example at the beginning, the tax accountant firm can let only the client company's accounting agent use the tax check agent for the necessary period, without making it publicly available. A2A provides a common language for connecting agents to each other, but "which parties to open to and to what extent" needs to be considered separately. ISEKAI portal can take on that role.

This time it was a minimal example of retrieving the Agent Card and exchanging messages, but any service that runs on TCP or UDP can be forwarded using the same procedure. Please try it with your own agents and services as well.

A2A (Agent2Agent) はAIエージェント同士が連携するためのプロトコルです。A2A を使うことで、異なるベンダーや異なるフレームワークで作られたAIエージェント同士でやり取りをすることが可能になります。やり取りの例としては、社内の「経理エージェント」（クライアント）が、外部の税理士事務所が運営する「税務チェックエージェント」（リモート）に、月次仕訳のチェックを依頼する、というようなものが考えられます。

この例において、外部の税理士事務所は、税務チェックエージェントをインターネット上に一般公開はしたくないと考えたとしましょう。そのようなニーズに応えるため、セーラ・ネットワークス株式会社では ISEKAI portal を開発・公開しています。ISEKAI portal は、過去の記事で仕組みを紹介した ISEKAI link の上で動くアプリケーションです。この記事では、その実証として、Rust で書かれた A2A の実装である a2a-rs に含まれる helloworld-server に ISEKAI portal を経由して、a2a-rs に含まれる a2acli を使って繋ぐ例を紹介してみようと思います。

なお、この記事の中で Endpoint や Grant などの ISEKAI link の用語が登場します。Endpoint は鍵で識別される端点、Grant は特定の Endpoint に Listener への接続を許可する期限付きの許可です。Listener は portal-server などが接続を待ち受ける窓口です。詳しくは、過去の記事を参照してください。

また、a2a-rs を使用するので、ローカルの Windows、リモートの Linux 共に Rust ツールチェーンと git が必要です。Windows では、MSVC のビルドツール（Visual Studio Build Tools）も必要です。

ISEKAI portal のインストール

ISEKAI portal は MITライセンスでソースコードを公開しているので、レポジトリ を clone して、ビルドすることもできます。しかし、ビルドの作業 は少し手間なので、ビルド済のバイナリを Releases からダウンロードするのが便利です。バイナリは現在

• Windows (amd64)
• Linux (Ubuntu, amd64)
• Mac (arm64)

の3種類を用意しています。バイナリはいずれも zip 形式になっており、展開するとファイル名と同じ名前のディレクトリができるので（Windowsだと、portal-windows-latest）、そこにパスを通します。これでターミナル上から実行する準備ができました。

ISEKAI portal のセットアップ

インストールができたら、セットアップを行います。なお、以下ではサーバーを Linux 上で、クライアントを Windows 上で動かすという前提で説明します。

portal-server のセットアップ

セットアップのための準備

サーバーを動かす Linux にリモートアクセスしている場合、次のように ssh を使って TCP の 38700 ポートをローカルに転送するようにします。

PS C:\Users\foo> ssh -L 38700:127.0.0.1:38700 foo@bar.example.com

後述するようにログインを Webブラウザ で行う必要があり、ログイン後に Webブラウザ が portal-server が開いているTCP の 38700 ポートに接続するようになっているのですが、リモートアクセスしている場合には、TCP の 38700 ポートが開いているのはリモートの Linux であり、これをローカルの環境に転送してあげる必要があるわけです。この処理は Linux をローカルで操作している場合は必要ありません。

また、ISEKAI portal が利用する設定ファイルを保存するディレクトリを作っておきます。

$ mkdir -p ~/.config/ISEKAI-portal

プライバシーポリシーへの同意

ISEKAI linkを利用するにはサインアップが必要になりますが、その際に収集する個人情報の扱い方を定めたプライバシーポリシーに同意をいただくことにしています。portal-server を起動するとプライバシーポリシーが表示されますので、確認の上、以下のコマンドを実行して同意してください。同意がなされるまで、portal-server はプライバシーポリシーを表示して終了します。

$ portal-server --accept-privacy-policy

なお、プライバシーポリシーは Web上でも公開しています（日本語版および英語版）。

ログイン

ISEKAI link では Auth0 を用いてアカウント管理を行っています。利用のためにはログインが必要です。ログインするためには次のコマンドを実行します（--keyオプションは Endpoint の秘密鍵のファイルを指定するものですが、ログイン情報を保存するファイルが同じディレクトリに作られるのでここでも指定しています）。

$ portal-server --key ~/.config/ISEKAI-portal/portal-server.pem --login

起動するとURLが表示されるので、Webブラウザ でアクセスしてください。アクセスすると"Enter Your Organization"と表示された画面がでますので、"Continue with personal account"をクリックします。すると、"Welcome"と表示されたログイン画面がでるので、アカウントが既にある場合はログインしてください。アカウントがない場合は"Sign up"をクリックしてアカウント作成画面に移ります。アカウントはメールアドレスとパスワードで作成できますが、Googleのアカウントやgithubのアカウントで作成することもできます。

設定ファイルの作成

ISEKAI portal では接続先の情報をサービスの名前で指定します。その設定を行うのが portal-server の設定ファイルです。ここでは、~/.config/ISEKAI-portal/portal-server.toml という名前で次のような内容で保存します。

[service.a2a]
protocol = "tcp"
target   = "127.0.0.1:3000"

portal-server の起動

起動の準備ができたので、portal-server を次のように実行します。--key は秘密鍵のパスを指定するもので、ファイルがない場合、秘密鍵を生成します。ファイルがある場合はそこから秘密鍵を読み取ります。--registerは Endpoint がまだ登録されていない場合にはつける必要があります。初回起動時は秘密鍵を生成して新しい Endpoint を作っていますので、--register が必要です。2回目以降はつけないようにします（つけるとエラーになります）。

$ portal-server --key ~/.config/ISEKAI-portal/portal-server.pem --config ~/.config/ISEKAI-portal/portal-server.toml --register

portal-client のセットアップ

portal-client のセットアップは portal-server とほとんど同じです。まず、設定ファイルを保存するディレクトリ（フォルダ）を作成します。

PS C:\Users\foo> mkdir $HOME\.config\ISEKAI-portal

次にプライバシーポリシーに同意しつつ、ログインを行います。なお、ログインを別のアカウントで行いたい場合など、2回目以降では、--accept-privacy-policyは必要ありません。

PS C:\Users\foo> portal-client --key $HOME\.config\ISEKAI-portal\portal-client.pem --login --accept-privacy-policy

先ほどと同様に出力された URL を Webブラウザ に入力してログインします（組織の選択では、"Continue with personal account"をクリックしてください）。ここでは、ログインするアカウントに先ほど作成したものを使います（異なるユーザーの Endpoint からでも接続を受け付けるように設定できるので、新しく別のアカウントを作っても問題はありません）。

最後に Endpoint ID を調べます。

PS C:\Users\foo> portal-client --key $HOME\.config\ISEKAI-portal\portal-client.pem --whoami

"ep:"から続く文字列が出力されますが、これが Endpoint ID です。Grantを作成する際に必要になるので、メモしておきます。

Grant の発行

Grant を発行する方法はいろいろありますが、ここではダッシュボードから手動で発行する方法を紹介します。この方法は接続先の portal-server が起動した状態であれば使うことができます。

まず、Webブラウザ で ISEKAI link ダッシュボード にアクセスします。ログインが必要なので、portal-server でログインしているアカウントの情報を入力してください（繰り返しになりますが、組織の選択では、"Continue with personal account"をクリックしてください）。

ログインすると一番上にメニューがあるので、"Grant"をクリックします（英語版の場合は"Grants"）。Grantの画面に移るので、"Grantを作る"のフォーム（英語版の場合は"Create a grant"）を埋めます。Listenerは portal-server のセットアップで起動した際に出ているものが一覧にあるはずなので、それを選びます。"入れる相手の Endpoint"のテキスト入力（英語版の場合は"Endpoint to let in"）に先ほどメモしておいた portal-client の Endpoint ID を入力します。"寿命"（英語版では"Lifetime"）は作成する Grant の有効期限です。1時間、8時間、24時間の中から選びます。"ラベル"のテキスト入力（英語版の場合は"Label"）は自分で管理するためのメモを入力できます。ここでは"a2a"と入力しておきましょう。入力を終えたら、"Grant を作る"のボタンをクリックします（"Create grant"）。

これでセットアップは完了です。

実際に接続してみる

まず、ローカルの Windows で portal-client を起動して、リモートの Linux の portal-server に接続します。--registerは初回起動時のみ必要です（2回目以降につけるとエラーになります）。--mapの引数の意味は、ローカルホストの TCP 3000 ポートで接続を受け付け、その接続を portal-server が指定する a2a の宛先に転送するという意味です。portal-client のリスニングを TCP 3000 ポートにしているのは、a2acli のデフォルトの接続先が TCP 3000 ポートになっているからです。

PS C:\Users\foo> portal-client --key $HOME\.config\ISEKAI-portal\portal-client.pem --map 3000:a2a --register

起動した後、次の文字列が出力されれば成功です。

tcp 127.0.0.1:3000 -> a2a
ready

次にリモートの Linux で、A2Aのサンプルサーバーである helloworld-server を立ち上げる作業を行います。先ほど立ち上げた portal-server はフォアグラウンドで動いていますので、そのセッションはそのままにして、以下の作業は新しく ssh で接続して行うか、tmux などで新しくセッションを立ち上げて行ってください（ssh の場合、ローカルポートのフォワードは必要ありません）。

最初に a2a-rs のレポジトリを clone します。

$ git clone https://github.com/a2aproject/a2a-rs.git
$ cd a2a-rs

次に、helloworld-server の修正を行います。

$ vi examples/src/helloworld/server.rs

修正内容は次の通りです。

--- a/examples/src/helloworld/server.rs
+++ b/examples/src/helloworld/server.rs
@@ -53,8 +53,8 @@ async fn main() {
     tracing::info!("REST:        http://localhost:3000/rest");
     tracing::info!("gRPC:        http://localhost:50051");

-    let http_listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
-    let grpc_listener = tokio::net::TcpListener::bind("0.0.0.0:50051")
+    let http_listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
+    let grpc_listener = tokio::net::TcpListener::bind("127.0.0.1:50051")
         .await
         .unwrap();

この修正を行うのは、デフォルトでは、helloworld-server のサービスがインターネットに公開されてしまう可能性があるからです。helloworld-server はアドレス 0.0.0.0 を使ってリスニングするように書かれています。これを防ぐため、リスニングするアドレスを 127.0.0.1 に書き換えるわけです。

書き換え後、次のように cargo run を実行します。

$ cargo run -p examples --bin helloworld-server

その後、別のセッションでローカルホストでしかリスニングしていないことを確かめます。

$ ss -tlnp | grep "hello"

次のようにリスニングしているアドレスが 127.0.0.1 になっていれば成功です。

LISTEN 0      128                      127.0.0.1:3000       0.0.0.0:*    users:(("helloworld-serv",pid=1732081,fd=9))                
LISTEN 0      128                      127.0.0.1:50051      0.0.0.0:*    users:(("helloworld-serv",pid=1732081,fd=10))

最後にローカルの Windows で、a2acli を起動します。a2acli はデフォルトでは localhost の TCP 3000 ポートに HTTP で接続するようになっているので、先ほど立ち上げた portal-client に接続し、リモートの Linux の helloworld-server へと転送されることになります。

PS C:\Users\foo> git clone https://github.com/a2aproject/a2a-rs.git
PS C:\Users\foo> cd a2a-rs
PS C:\Users\foo\a2a-rs> cargo run --bin a2acli -- card get

接続に成功すると次のような文字列が出力されます。

Name: Hello World Agent
Description: A simple echo agent that returns the input message.
Version: 1.0
Streaming: true
Push Notifications: false
Extended Card: false
Interfaces:
  - JSONRPC http://localhost:3000/jsonrpc (v1.0)
  - HTTP+JSON http://localhost:3000/rest (v1.0)
  - GRPC localhost:50051 (v1.0)

Skills: 1

タスクも実行してみます。次のように実行します。

PS C:\Users\foo\a2a-rs> cargo run --bin a2acli -- send "hello from rust"

次のような文字列が出力されれば成功です。

Task ID: 01a119a8-885d-76dc-abde-1dea996fc2e4
Context ID: 01a119a8-885d-76dc-abde-1debf9b5c586
State: COMPLETED
Text:
Echo: hello from rust

このようにして ISEKAI portal を経由して A2A でやり取りすることができました。なお、GRPCについては転送するようにしていないので、今回は使えないことに注意してください。

まとめ

この記事では、ISEKAI portal を経由して、Linux 上の helloworld-server に Windows 上の a2acli から A2A で接続する例を紹介しました。

ここで注目していただきたいのは、helloworld-server を動かしている Linux 側で、外部からの接続を受け付けるための設定を一切行っていないことです。portal-server は ISEKAI link に自分から接続しに行くだけです。そのため、ファイアウォールやルーターの設定を変える必要はなく、エージェントがインターネットに直接さらされることもありません。

また、誰が接続できるかは Grant で管理されます。今回は portal-client の Endpoint だけを接続相手として指定し、有効期限も付けました。Grant を発行していない相手には、portal-server がどのような Listener を開いているかが見えないので、サービスがあることすら分かりません。また、Grant を発行した相手であっても、期限が切れれば接続できなくなります。

冒頭の例に当てはめると、税理士事務所は税務チェックエージェントを一般公開しないまま、顧客企業の経理エージェントにだけ、必要な期間だけ使わせることができます。A2A はエージェント同士をつなぐ共通の言葉を提供しますが、「どの相手にどこまで開くか」は別に考える必要があります。ISEKAI portal は、その部分を担うことができます。

今回は Agent Card の取得とメッセージのやり取りという最小限の例でしたが、TCP や UDP で動くサービスであれば同じ手順で転送できます。ぜひ手元のエージェントやサービスでも試してみてください。

Tunneling LLM Chat Over MASQUE: the ISEKAI Portal Client

ISEKAI link is Seera Networks' service for connecting devices on different networks over QUIC: it handles authentication and connection brokering, and relays traffic for peers that can't reach each other directly. The relay speaks MASQUE, the IETF's family of HTTP/3-based proxying protocols (here CONNECT-UDP, RFC 9298), so a peer's own QUIC connection travels tunneled inside the relay's. Its first application was a live-video camera pair, covered in the previous article.

The ISEKAI Portal client is the second, and it carries request/response traffic instead of a one-way video stream: a small Android chat app that forwards HTTP requests to a locally running Ollama instance on a remote box, over the same relay stack. It's built on portal-core and isekai-p2p — the same forwarding protocol and session/relay machinery the camera apps use — proving out the general-purpose half of ISEKAI link: instead of a hardcoded video path, an operator declares a named service in a catalogue, and any paired peer can reach it as if it were local.

flowchart LR
  A["Android app<br/>(chat UI)"] -- "HTTP to 127.0.0.1" --> F["portal-client-ffi<br/>(local forwarder)"]
  F -- "inner QUIC<br/>ALPN isekai-portal-v1" --> R["ISEKAI link relay<br/>(MASQUE CONNECT-UDP)"]
  R --> S["portal-server<br/>(Jetson)"]
  F -. "direct path, when one validates" .-> S
  S -- "TCP" --> O["Ollama<br/>127.0.0.1:11434"]

Every session starts on the relay and moves to a direct path when one validates. In the demo below, the phone starts on the same Wi-Fi network as the Jetson; after it switches to 5G, the reconnected session stays on the relay.

An Android phone pairs with the Jetson and asks two questions over Wi-Fi, then switches to 5G mid-session; the app reconnects through the relay, and a follow-up question is answered from the chat history.

Reusing the Relay, Changing the Stream Shape

portal-core's forwarding model is deliberately generic: one bidirectional QUIC stream per TCP connection, and datagrams keyed by session id for UDP. That's a different shape from camera-client's one-unidirectional-stream-per-frame design — there's no "drop the stale frame" logic here, because a chat request isn't live media, it's a regular request/response HTTP exchange that just happens to be tunneled. The relay, certificates and pairing underneath (isekai-p2p) serve both without change — portal even reuses the camera's P2P protocol string. What portal adds sits on top: its own inner ALPN (isekai-portal-v1, so a peer that speaks neither video nor portal fails at the handshake rather than mid-stream), the forwarding protocol in portal-core, and the service catalogue.

The Catalogue Is the Whole Policy

This build runs on an NVIDIA Jetson Orin Nano, an edge board small enough to sit on a desk with enough GPU to run a local LLM. Nothing in the design depends on it, though: any on-premise machine that can run the model works just as well, such as a Mac mini or an AMD Ryzen AI Halo. The Jetson runs portal-server, started with a service catalogue that declares exactly one entry:

[service.ollama]
protocol = "tcp"
target = "127.0.0.1:11434"

The client asks for a service by name ("ollama") — never an address — so a paired peer can reach only what the catalogue explicitly offers, and the initiator can never name an arbitrary target. This catalogue is deliberately kept out of portal-server's default config path/name specifically because Ollama has no auth of its own — a catalogue picked up silently by an operator who forgot --config would hand a raw local LLM endpoint to any paired peer.

The catalogue draws the line at ports, not at requests. Forwarding is plain layer 4: portal-server copies bytes between the tunnel and 127.0.0.1:11434 without reading them, so a paired peer gets the whole Ollama API — not just /api/chat, but /api/pull, /api/delete and /api/create too. Limiting individual endpoints would take an HTTP-aware proxy in front of Ollama, which is outside this layer's job. What the design does control is who gets in and where the port lives: only a peer that redeemed a pairing code the operator minted (valid for at most five minutes, and revocable afterwards with portal-server --revoke) can open the tunnel, and Ollama stays bound to 127.0.0.1, so it is never exposed on the LAN.

Streaming as a Liveness Signal

The first working version used Ollama's stream: false and waited for the whole reply. It didn't just look broken — a minute or more of silence over the tunnel made non-streamed replies fail outright. Switching to stream: true (Ollama's newline-delimited-JSON streaming format) fixed it without changing total latency; what changed is the time to first token. Real bytes now cross the tunnel continuously while the model generates, the same principle behind the camera product's decision to keep relay keepalives flowing rather than let a path go quiet. The app still allows 90 seconds per read, enough to cover a cold model load, which alone took about 40 seconds on the Jetson.

Model Choice Is Just a Config String

The model running this time is qwen3.5:4b — chosen because it fits comfortably in this Jetson Orin Nano's unified memory (shared by its CPU and GPU) alongside everything else sharing the box, not because anything upstream of Ollama cares which model it is. Neither portal-core's forwarding nor the client's HTTP layer look at the model name beyond passing it through in the /api/chat request body. Any open-weights model works as a drop-in replacement, as long as it fits the on-premise GPU/NPU hardware it's meant to run on — the tradeoff is entirely local (memory budget, cold-load time, tokens/sec), not architectural.

The same goes for the server itself: Ollama isn't special here. The catalogue can point at Lemonade Server: an open-source server that runs AI models — LLM chat as well as image generation, speech and embeddings — locally on your own PC and serves them through the standard OpenAI-compatible API, on Windows, macOS and Linux. Adding a [service.lemonade] entry that targets its port on 127.0.0.1 is all it takes; the app then sends /api/v1/chat/completions requests instead of /api/chat, and the relay, pairing and forwarding stay exactly the same.

Multi-Turn Memory Is Resent, Not Stored

Ollama keeps no state between requests on either /api/generate or /api/chat — a client has to resend everything it wants remembered. The first version of this app didn't: every request went to /api/generate with only the current turn's text, so each reply was effectively the first message the model had ever seen.

The fix switched the client to /api/chat and resends the whole conversation on every turn, with the new question last:

{"model": "qwen3.5:4b", "stream": true, "messages": [
  {"role": "user", "content": "whats your model"},
  {"role": "assistant", "content": "I am Qwen3.5."},
  {"role": "user", "content": "what was the question I asked previously?"}
]}

Each streamed line's text then arrives under message.content instead of /api/generate's flat response field.

I verified it with the simplest test that proves memory rather than plausible continuation: I told the model "My favorite color is teal." in one message, asked "What is my favorite color?" in a separate one, and got back "Teal."

The tradeoff this leaves open: the app does no truncation of its own, so the full conversation is resent on every turn. How much of it the model actually sees is bounded on the Ollama side by its context-window setting (num_ctx); past that, Ollama silently drops the oldest turns, and a long enough chat will eventually fail the teal test. Raising num_ctx pushes that point out, but the value should be sized to the local hardware — a bigger context window means a bigger KV cache, competing for the same memory as the model itself. Fine for a demo's scope; a real deployment would want its own truncation or summarization strategy.

Auth, Inherited Wholesale

The endpoint-key/Auth0 device-flow pairing model is identical to camera-client's: a fresh ECDSA key generated on first launch and kept in the app's private storage, an Auth0 sign-in, and a pairing Grant tied to the Endpoint ID rather than the session — meaning it survives portal-server restarts on the Jetson without needing to be re-paired.

Design Philosophy

The interesting result isn't the chat UI — it's that swapping "stream video frames" for "tunnel a stateless HTTP API" left the relay, the pairing model and the certificates untouched. Everything new sat on top of them: an inner ALPN, portal-core's forwarding protocol, and a one-entry catalogue. On the client, the only transport-adjacent decisions were streaming the reply and a per-read timeout long enough to survive a cold model load. That's the bet the generic service-catalogue design was making, and it held.

MASQUE越しにLLMチャットを流す：ISEKAI Portal クライアント

ISEKAI link は、異なるネットワーク上のデバイス同士を QUIC で接続するセーラ・ネットワークスのサービスです。認証と接続の仲介を行い、互いに直接到達できないピア同士の通信はリレーします。リレーは、IETF が標準化している HTTP/3 ベースのプロキシプロトコル群である MASQUE（ここでは CONNECT-UDP、RFC 9298）を話すため、ピア自身の QUIC 接続はリレーの QUIC 接続の中をトンネルされて流れます。最初のアプリケーションはライブ映像のカメラアプリの組で、前回の記事で紹介しました。

ISEKAI Portal クライアントはその2つ目のアプリで、一方向の映像ストリームではなく、リクエスト／レスポンス型の通信を運びます。リモートのマシン上でローカルに動いている Ollama に、同じリレー基盤を通して HTTP リクエストを転送する、小さな Android チャットアプリです。カメラアプリと同じ転送プロトコルとセッション／リレーの仕組みを持つ portal-core と isekai-p2p の上に作られており、ISEKAI link の汎用的な側面を実証しています。映像専用の経路をハードコードする代わりに、運用者がカタログに名前付きのサービスを宣言すれば、ペアリング済みのピアはそれをローカルにあるかのように利用できます。

flowchart LR
  A["Android アプリ<br/>(チャット UI)"] -- "127.0.0.1 への HTTP" --> F["portal-client-ffi<br/>(ローカル転送)"]
  F -- "内側の QUIC<br/>ALPN isekai-portal-v1" --> R["ISEKAI link リレー<br/>(MASQUE CONNECT-UDP)"]
  R --> S["portal-server<br/>(Jetson)"]
  F -. "直接経路（検証できた場合）" .-> S
  S -- "TCP" --> O["Ollama<br/>127.0.0.1:11434"]

すべてのセッションはまずリレー経由で始まり、直接経路が検証できた時点でそちらに移ります。下のデモでは、スマートフォンは最初 Jetson と同じ Wi-Fi ネットワーク上にあり、5G に切り替わった後に再接続したセッションはリレー経由のままです。

Android スマートフォンが Jetson とペアリングし、Wi-Fi 経由で2つ質問した後、セッションの途中で 5G に切り替えます。アプリはリレー経由で再接続し、続けて送った質問にはチャット履歴を踏まえた答えが返ってきます。

リレーはそのまま、ストリームの形を変える

portal-core の転送モデルは意図的に汎用的に作られています。TCP 接続1本につき双方向の QUIC ストリームを1本、UDP にはセッション ID をキーにしたデータグラムを使います。これは、フレームごとに単方向ストリームを1本使う camera-client の設計とは異なる形です。ここには「古いフレームを捨てる」ロジックはありません。チャットのリクエストはライブメディアではなく、たまたまトンネルされているだけの通常のリクエスト／レスポンス型の HTTP のやり取りだからです。その下にあるリレー、証明書、ペアリング（isekai-p2p）は、変更なしで両方に使えます。portal はカメラの P2P プロトコル文字列まで再利用しています。portal が追加したものはその上に乗っています。独自の内側の ALPN（isekai-portal-v1。映像も portal も話さないピアは、ストリームの途中ではなくハンドシェイクの時点で失敗します）、portal-core の転送プロトコル、そしてサービスカタログです。

ポリシーはカタログがすべて

今回のビルドは NVIDIA Jetson Orin Nano 上で動いています。机の上に置ける小さなエッジボードでありながら、ローカル LLM を動かせるだけの GPU を備えています。ただし、設計はこのボードに依存していません。Mac mini や AMD Ryzen AI Halo など、モデルを動かせるオンプレミスのマシンであれば同じように使えます。Jetson では portal-server が動いており、エントリが1つだけのサービスカタログを指定して起動しています。

[service.ollama]
protocol = "tcp"
target = "127.0.0.1:11434"

クライアントはサービスを（アドレスではなく）名前で（"ollama"）要求します。そのため、ペアリング済みのピアが到達できるのはカタログが明示的に提供するものだけで、接続元が任意の接続先を指定することはできません。このカタログは、あえて portal-server のデフォルトの設定ファイルのパス／名前にはしていません。Ollama には独自の認証がないためです。--config を付け忘れた運用者のもとで黙ってカタログが読み込まれてしまうと、生のローカル LLM エンドポイントをペアリング済みのすべてのピアに渡すことになります。

カタログが線を引くのはポートの単位であって、リクエストの単位ではありません。転送は単純なレイヤー4で、portal-server はトンネルと 127.0.0.1:11434 の間でバイト列を読まずにコピーします。そのため、ペアリング済みのピアは Ollama の API 全体を使えます。/api/chat だけでなく、/api/pull、/api/delete、/api/create もです。エンドポイント単位で制限するには Ollama の前に HTTP を解釈するプロキシが必要で、それはこのレイヤーの役割の外です。この設計が制御しているのは、誰が入れるかと、ポートがどこにあるかです。トンネルを開けるのは、運用者が発行したペアリングコード（有効期限は最大5分で、後から portal-server --revoke で取り消せます）を使ったピアだけで、Ollama は 127.0.0.1 にバインドされたままなので、LAN に公開されることはありません。

接続を保つためのストリーミング

最初に動いたバージョンでは Ollama の stream: false を使い、返答全体を待っていました。これは単に壊れているように見えただけではありません。トンネル越しに1分以上無通信が続くと、ストリーミングしない返答はそのまま失敗していました。stream: true（Ollama の改行区切り JSON によるストリーミング形式）に切り替えることで、全体のレイテンシーは変えずに問題が解決しました。変わったのは最初のトークンが届くまでの時間です。モデルが生成している間、実際のバイト列がトンネルを途切れなく流れるようになりました。これは、経路を無通信にせずリレーのキープアライブを流し続けるというカメラ製品の判断と同じ原則です。アプリは今でも1回の読み取りに90秒を許容しています。モデルのコールドロードだけで Jetson では約40秒かかったため、それをカバーできる長さです。

モデルの選択は設定文字列ひとつ

今回動かしているモデルは qwen3.5:4b です。これを選んだのは、この Jetson Orin Nano のユニファイドメモリ（CPU と GPU で共有）に、同じマシン上の他のすべてと一緒に無理なく収まるからであって、Ollama より上流の何かがモデルの種類を気にしているからではありません。portal-core の転送も、クライアントの HTTP レイヤーも、モデル名は /api/chat のリクエストボディでそのまま渡すだけで、中身を見ていません。想定するオンプレミスの GPU／NPU ハードウェアに収まりさえすれば、どのオープンウェイトモデルでもそのまま置き換えられます。トレードオフは完全にローカルなもの（メモリ予算、コールドロード時間、トークン/秒）であって、アーキテクチャ上のものではありません。

サーバー自体についても同じことが言えます。ここで Ollama は特別な存在ではありません。カタログの接続先を Lemonade Server にすることもできます。Lemonade Server は、LLM によるチャットに加えて画像生成・音声・埋め込みなどの AI モデルを自分の PC 上で動かし、標準的な OpenAI 互換 API で提供するオープンソースのサーバーで、Windows・macOS・Linux で動作します。必要なのは、127.0.0.1 上のそのポートを指す [service.lemonade] のエントリを追加することだけです。アプリは /api/chat の代わりに /api/v1/chat/completions にリクエストを送るようになり、リレー、ペアリング、転送はまったく変わりません。

マルチターンの記憶は保存ではなく再送

Ollama は /api/generate でも /api/chat でもリクエスト間で状態を保持しません。覚えておいてほしいことは、クライアントがすべて再送する必要があります。このアプリの最初のバージョンはそうしていませんでした。すべてのリクエストを、そのターンのテキストだけを付けて /api/generate に送っていたため、どの返答も、事実上モデルが初めて見たメッセージへの返答になっていました。

修正では、クライアントを /api/chat に切り替え、毎ターン会話全体を、新しい質問を最後にして再送するようにしました。

{"model": "qwen3.5:4b", "stream": true, "messages": [
  {"role": "user", "content": "whats your model"},
  {"role": "assistant", "content": "I am Qwen3.5."},
  {"role": "user", "content": "what was the question I asked previously?"}
]}

ストリーミングされる各行のテキストは、/api/generate のフラットな response フィールドではなく、message.content に入って届きます。

もっともらしい続きではなく、記憶していることを証明できる最も単純なテストで確認しました。1つ目のメッセージでモデルに「My favorite color is teal.」（好きな色はティール）と伝え、別のメッセージで「What is my favorite color?」（私の好きな色は？）と尋ねると、「Teal.」と返ってきました。

ただし、トレードオフが残ります。アプリ自身は会話の切り詰めを一切行わないため、毎ターン会話全体が再送されます。モデルが実際にそのうちどれだけを見られるかは、Ollama 側のコンテキストウィンドウの設定（num_ctx）で上限が決まります。それを超えると Ollama は古いターンから黙って捨てるため、十分に長いチャットでは、いずれティールのテストに失敗します。num_ctx を上げればその時点を先に延ばせますが、値はローカルのハードウェアに合わせて決めるべきです。コンテキストウィンドウが大きいほど KV キャッシュも大きくなり、モデル自体と同じメモリを奪い合うからです。デモの範囲としてはこれで十分ですが、実運用では独自の切り詰めや要約の戦略が必要になるでしょう。

認証はそのまま流用

エンドポイント鍵と Auth0 のデバイスフローによるペアリングモデルは、camera-client とまったく同じです。初回起動時に新しい ECDSA 鍵を生成してアプリのプライベートストレージに保存し、Auth0 でサインインします。ペアリングの Grant はセッションではなく Endpoint ID に紐づくため、Jetson 上の portal-server を再起動しても、ペアリングし直す必要はありません。

設計思想

注目すべきはチャット UI ではありません。「映像フレームをストリーミングする」を「ステートレスな HTTP API をトンネルする」に置き換えても、リレー、ペアリングモデル、証明書には手を入れずに済んだことです。新しく加えたものはすべてその上に乗っています。内側の ALPN、portal-core の転送プロトコル、そしてエントリが1つのカタログです。クライアント側でトランスポートに関わる判断は、返答をストリーミングすることと、モデルのコールドロードを乗り切れるだけの長さの読み取りタイムアウトを設けることだけでした。汎用的なサービスカタログという設計はこの点を見込んだもので、実際にそのとおりになりました。

Suppose an engineer at a subcontractor says to you, "If I could just let Claude Code see the staging DB directly, the investigation would be over in an instant." If you issue a VPN, the entire internal network becomes visible, and if you hand over the DB password, you can't tell whether a human or an agent touched it, nor can you be sure it was properly shut off after the contract ended. What you want is a path that connects "only to this DB," "in a form that makes it clear it's agent access," and "only during the contract period." This article introduces how ISEKAI link achieves this.

ISEKAI link is a relay service developed by Seera Networks, Inc. that connects devices on different networks via QUIC. ISEKAI link has a mode that, rather than inviting the other party into the network, draws a single path only between an authorized party and a specific resource. Applying this to the earlier example, it works as "drawing a path only between the staging DB and the subcontractor's Claude Code."

The elements that make this behavior possible are the following three. The first is identity (Endpoint) that can be used differently depending on the purpose; by seeing which Endpoint an access comes from, human access and agent access can be distinguished and recorded. The second is permission (Grant) that determines who may connect to which resource, and once revoked, connection becomes impossible. The third is the connection mechanism that connects via a relay without opening ports, and switches to a direct path when possible. Below, after explaining these three, I will discuss how we made it possible to realize a path that connects "only to this DB," "in a form that makes it clear it's agent access," and "only during the contract period."

What is an Endpoint

An Endpoint is the unit for using ISEKAI link's services, and each holds an ECDSA P-256 key. An Endpoint is identified by an ID derived from its public key, and is registered linked to an account managed by Auth0. The outline of the flow for Endpoint registration and Endpoint token issuance is as follows.

sequenceDiagram
    autonumber
    participant App as App
    participant Auth as Auth0
    participant ID as Identity API
    App->>Auth: Sign in (individual or organization)
    Auth-->>App: Auth0 access token
    App->>ID: Endpoint registration (authenticated with Auth0 access token)<br/>ECDSA P-256 public key
    App->>ID: Endpoint token request
    ID-->>App: Endpoint token expires in a few minutes<br/>auto-reissued during session

Accounts managed by Auth0 have a type of individual/organization. A user (email address, etc.) always has an individual account, and can additionally belong to multiple organizations. A user belonging to an organization has that organization's account.

That said, account types of individual/organization in ISEKAI link were introduced only very recently; before that, there was no concept of an organization. The reason we created the concept of an organization was to solve use cases like the one at the beginning. This example is about wanting an engineer (who has a subcontract with the company) running Claude Code—a temporary "internal" person—to access a staging DB that is a resource "inside the company," and the fact that both are "internal" serves as one basis for the judgment to permit access to the resource. In order to use this in actual authorization decisions, it is necessary to know whether the resource's Endpoint (and the user registering it) and the agent's Endpoint (and the user registering it) are both "internal," and that is why we created the concept of an organization.

Also, the fact that the Endpoint is the unit for using ISEKAI link's services, one level finer than a user, is important for solving use cases like the one at the beginning. If the user were the unit for using the service, then in the records you could not distinguish whether the user themselves accessed the DB or whether an agent such as Claude Code accessed the DB. If you allow multiple Endpoints to be registered to a single account, you can separate the Endpoint used by a human from the Endpoint used by an agent, and by seeing which Endpoint an access comes from, you can distinguish and record which kind of access it was.

Note that what must be presented when using ISEKAI link's services is not an Auth0 access token but an Endpoint token. This is because the subject of authorization in these services is not which user is trying to use the service, but which Endpoint is trying to use the service.

What is a Grant

ISEKAI link's mode of drawing a single path only between an authorized party and a specific resource is realized as communication between Endpoints. The permission for this communication between Endpoints is a Grant.

The concept of a Grant did not exist from the beginning either; it was introduced to solve a certain problem. That problem was that establishing communication between Endpoints required exchanging information through human hands. To show what this was like, let's look at the procedure for establishing communication between Endpoints without using a Grant.

sequenceDiagram
    participant A as Endpoint A (initiator)
    participant CP as Control Plane
    participant B as Endpoint B (target)
    B->>CP: Listener creation request  (Endpoint token + protocol)
    CP-->>B: listener_id
    B->>CP: Capability issuance request (Endpoint token + listener_id + protocol + Endpoint A's ID)
    A->>CP: Connection request (Endpoint token + listener_id + protocol + Capability)
    CP-->>A: connection_id + masque_uri
    B->>CP: Connection confirmation (Endpoint token + connection_id)
    CP-->>B: masque_uri

Suppose there are Endpoint A and Endpoint B, with B being the side tied to a resource such as a DB, and A being the side tied to an agent. In each case, at the end they obtain the MASQUE URI used when sending a CONNECT-UDP request, and use these to draw a path between the Endpoints.

However, getting there involves the problem that necessary information must be passed outside the protocol through human hands. Focusing on B's side, no special information is needed to create a Listener, but in order to accept a connection request from A using that Listener, it must obtain A's ID in advance, use it, and issue a Capability. And on A's side, that Capability must be received by some means, used, and a connection requested.

Grants were introduced to solve this problem. What a Capability indicates is the qualification that A may connect to this Listener, and if A presents it, the connection request is accepted. If that is the case, then if the authorization decision that A may connect is made in advance and that decision is remembered, the exchange of Capabilities becomes unnecessary. The record of such an advance authorization decision is a Grant. Note that what a Grant is linked to is not the Listener that B creates, but B itself. This is because a Listener is created each time B waits for a connection, so linking to it would make it unusable for subsequent Listeners, and creating a Grant only after B has created a Listener would be inconvenient.

The first method introduced for creating a Grant was pairing. In pairing, the target side B issues a short code embedded in a QR code, and the initiator side A presents it to the Control Plane. Then, a permanent Grant enabling A to connect to B is generated and stored on the Control Plane. This made it so that, although a human must hand over the pairing code the first time, from the second time onward the connection is automatic.

sequenceDiagram
    participant A as Endpoint A (initiator)
    participant CP as Control Plane
    participant B as Endpoint B (target)
    B->>CP: Pairing code issuance request  (Endpoint token + protocol)
    CP-->>B: Pairing code
    A->>CP: Pairing code submission  (Endpoint token)
    CP->>CP: Create Grant
    B->>CP: Listener creation request  (Endpoint token + protocol)
    CP-->>B: listener_id
    A->>CP: Connection request (Endpoint token + listener_id + protocol)
    CP-->>A: connection_id + masque_uri
    B->>CP: Connection confirmation (Endpoint token + connection_id)
    CP-->>B: masque_uri

Also, we created tickets as something similar to but different from pairing. A pairing code is premised on being consumed immediately, so only one can be issued at a time (issuing a new code invalidates the old one). However, this is inconvenient when multiple Endpoints are trying to connect. Tickets were created to resolve this inconvenience, and multiple can be issued at the same time. Note that, unlike pairing, a Grant created by consuming a ticket has an expiration (this expiration is set when the ticket is issued and cannot be made permanent). The organization is that if you want a persistent relationship you use pairing, and if you want to grant temporary access you use tickets.

In this way, mechanisms for generating Grants such as pairing and tickets were prepared, but these do not work well for solving the use case at the beginning. The ideal unit for creating Endpoints, from the perspectives of auditing and security, is per task, and the use case at the beginning precisely calls for that. Therefore, we prepared a mode (in the ISEKAI portal app described later) in which an Endpoint is created for each task and disabled when the task is finished, but in this case, because Endpoints change one after another, pairing or tickets—which issue a single Grant for a specific Endpoint—do not work well. To handle this case, a mechanism is needed in which a Grant is automatically created that allows Endpoints registered to a certain account to connect.

How is this mechanism configured? Various approaches are conceivable, but currently, thinking that it is common to have "internal" resources used by "internal" agents as in the use case at the beginning, we have made it so that an organization's administrator can set a policy per organization, and we call this policy an entitlement. In the example at the beginning of "drawing a path only between the staging DB and the subcontractor's Claude Code," the entitlement mainly consists of the account of the subcontractor engineer using Claude Code (it is assumed that the engineer is made a member of the organization), the ID of the staging DB's Endpoint, and the protocol used for connection.

Connection mechanism

A staging DB is usually on the internal network and not accessible from outside. ISEKAI link removes this limitation by creating a path between Endpoints. There is no need to open ports on the internal side, because both Endpoints connect outbound to ISEKAI link's relay server. However, since the path carries UDP, TCP applications cannot use it. Therefore, QUIC is layered on top, and TCP/UDP listened to on the agent side is forwarded over that QUIC. The application that realizes this is ISEKAI portal.

The figure below shows the solution to the example at the beginning using ISEKAI portal.

flowchart LR
    subgraph PC["Subcontractor engineer's PC"]
        CC["Claude Code"]
        PCL["portal-client<br/>(Endpoint A)"]
        CC -- "TCP<br/>localhost:5432" --> PCL
    end

    subgraph LINK["ISEKAI link"]
        RELAY["Relay<br/>(MASQUE CONNECT-UDP)"]
    end

    subgraph CORP["Internal network"]
        PS["portal-server<br/>(Endpoint B)"]
        DB[("Staging DB<br/>PostgreSQL")]
        PS -- "TCP" --> DB
    end

    PCL -- "QUIC over CONNECT-UDP" --> RELAY
    PS -- "QUIC over CONNECT-UDP<br/>(outbound connection)" --> RELAY
    PCL -. "Switch to direct path if possible" .-> PS

Switching to a direct path uses the same mechanism (QUIC Multipath and NAT-Traversal) introduced in the earlier camera app article. That said, because it is difficult to provide a mechanism for changing settings interactively, unlike the camera app it is not freely switchable; instead, it automatically moves to a direct path when one is found.

Note that portal-client is designed so that it cannot freely choose the TCP/UDP destination, and can only specify by name the destinations set by portal-server. By limiting TCP/UDP forwarding to the destinations specified by portal-server, the requirement to access only the staging DB is realized.

How the three requirements are satisfied

So far, I have explained the three—Endpoint, Grant, and the connection mechanism—including the motivations from which they emerged. First, "only to this DB" is realized by two things: specifying the ID of the Endpoint on the staging DB side in the entitlement, and limiting portal-server's forwarding to the configured destinations. Next, "in a form that makes it clear it's agent access" is realized by separating the Endpoint for agents from the Endpoint used by humans.

However, the distinction here is only a distinction in records, and does not limit access to agents only. Since entitlements are set per account, any Endpoint registered to the same account can also connect from the Endpoint used by a human. Also, because portal-client listens on localhost, any process on the same PC other than Claude Code can use it, and in that case too it will be recorded as access from the agent's Endpoint. If you want to limit access to agents only, you need to combine this with measures on the PC side, such as running the agent in a dedicated environment (e.g., a container).

Finally, "only during the contract period" can be realized by revoking the entitlement or disabling the Endpoint in use once the contract period ends. In particular, disabling an Endpoint is powerful, and is designed so that running connections are also automatically disconnected.

However, it is inconvenient that an administrator must manually perform such revocation or disabling without forgetting. Such manual execution also risks accidents. Therefore, we introduced guest settings as a feature that automatically makes access impossible once the contract period ends.

Guest settings can be granted to an organization account, and an expiration is specified when granting. Once the expiration passes, the account is disabled and can no longer issue Endpoint tokens, but furthermore, already-issued Endpoint tokens and Grants are also automatically invalidated. Running connections are also automatically disconnected. There is no longer any risk of an administrator forgetting to perform the work.

There is also the restriction that an Endpoint registered by an account granted guest settings can only be an initiator. A person who only temporarily belongs to an organization through a subcontract, etc., would not need to be on the side providing the organization's resources, and in fact, abuse such as falsely presenting a non-organizational resource as an organizational resource to gain access is conceivable, so we prohibit it from acting as a target.

Conclusion

Using ISEKAI link, you can realize a path that connects "only to this DB," "in a form that makes it clear it's agent access," and "only during the contract period." The service is currently in a proof-of-concept phase and can be used for free. In particular, individual accounts can be used immediately just by signing up, so if you are interested, please give it a try. For documentation, etc., refer to the ISEKAI link repository. We also plan to deliver a simple guide article soon.

As for organization accounts, due to the service configuration, they cannot be created freely, but there is a possibility we can provide them as part of participating in the proof-of-concept, so we would appreciate it if you could contact us by email at info at seera-networks.com.

委託先のエンジニアから「Claude Code にステージングDBを直接見せられれば、調査が一瞬で終わるんですが」と言われたとします。VPNを発行すれば社内ネットワーク全体が見えてしまうし、DBのパスワードを渡せば、人とエージェントのどちらが触ったのか区別がつかず、契約終了後に確実に止められたかもわかりません。欲しいのは「このDBだけに」「エージェントのアクセスと分かる形で」「契約期間中だけ」繋がる経路です。本記事では、ISEKAI link がこれをどのように実現しているかを紹介します。

ISEKAI link は、セーラ・ネットワークス株式会社が開発している、異なるネットワークにある機器同士を QUIC で繋ぐための中継サービスです。ISEKAI link には、相手をネットワークの中に招き入れるのではなく、許可した相手と特定のリソースの間にだけ、一本の経路を引くモードがあります。先ほどの例に当てはめれば、「ステージングDBと委託先の Claude Code の間にだけ経路を引く」という動作です。

この動作を可能としている要素は次の三つです。一つ目は、用途ごとに使い分けられる身元（Endpoint）で、どの Endpoint からのアクセスかを見ることで、人のアクセスとエージェントのアクセスを区別して記録できます。二つ目は、誰がどのリソースに繋いでよいかを決める許可（Grant）で、取り消せば繋げなくなります。三つ目は、ポートを開けなくても中継を経由して繋がり、可能なら直接経路に切り替わる接続の仕組みです。以下では、これら三つを説明した上で、「このDBだけに」「エージェントのアクセスと分かる形で」「契約期間中だけ」繋がる経路をどう実現するようにしたのかをお話しします。

Endpoint とは何か

Endpoint は ISEKAI link のサービスを利用する単位で、それぞれ ECDSA P-256 の鍵を持ちます。Endpoint はその公開鍵から導出された ID によって特定され、Auth0 で管理しているアカウントに紐づけられて登録されます。Endpoint の登録および Endpoint token の発行フローの概略は以下の通りです。

sequenceDiagram
    autonumber
    participant App as アプリ
    participant Auth as Auth0
    participant ID as Identity API
    App->>Auth: サインイン（個人 or 組織）
    Auth-->>App: Auth0 access token
    App->>ID: Endpoint 登録（Auth0 access tokenで認証）<br/>ECDSA P-256 公開鍵
    App->>ID: Endpoint token 要求
    ID-->>App: Endpoint token 数分で失効するため<br/>セッション中に自動再発行

Auth0 で管理しているアカウントには個人/組織の種別があります。ユーザー（メールアドレス等）は必ず個人アカウントを持ち、加えて複数の組織に所属できます。ある組織に所属するユーザーは、その組織のアカウントを持ちます。

もっとも、ISEKAI link でアカウントに個人/組織の種別ができたのはごく最近で、それまでは組織の概念がありませんでした。なぜ組織の概念を作ったのかといえば、冒頭の例のようなユースケースを解くためです。この例は「社内」にあるリソースであるステージングDBに対し、（会社と委託契約を結んでいる）一時的な「社内」の人であるエンジニアが走らせている Claude Code からアクセスさせたいというもので、「社内」同士であるということがリソースへのアクセスを認める判断の根拠の一つになっています。これを実際の認可の判断に使うためには、リソースの Endpoint（を登録するユーザー）と、エージェントの Endpoint（を登録するユーザー）とが「社内」同士であるかがわかる必要があり、そのために組織の概念を作ったわけです。

また、Endpoint が ISEKAI link のサービスを利用する単位になっていて、ユーザーより一段細かくなっていることも、冒頭の例のようなユースケースを解く上では重要です。もし、ユーザーがサービスを利用する単位だとすると、そのユーザー本人がDBにアクセスしたのか、それとも、Claude Code のようなエージェントがDBにアクセスしたのか、記録の上で区別できません。一つのアカウントに複数の Endpoint を登録できるようにしておけば、人が使う Endpoint とエージェントが使う Endpoint を分けておくことができ、どの Endpoint からのアクセスかを見れば、どちらのアクセスかを区別して記録できるのです。

なお、ISEKAI link のサービスを利用する際に提示しなければいけないのは、Auth0 access token ではなく、Endpoint token になります。これらのサービスでの認可の対象は、どのユーザーがサービスを利用しようとしているのかではなく、どの Endpoint がサービスを利用しようとしているのか、だからです。

Grant とは何か

ISEKAI link の許可した相手と特定のリソースの間にだけ、一本の経路を引くモードは、Endpoint 同士の通信として実現されています。この Endpoint 同士の通信の許可が Grant です。

Grant の概念も当初からあったわけではなく、ある問題を解決するために導入されました。その問題とは、Endpoint 同士の通信の確立にあたって人間の手を介して情報をやりとりしなければいけなかったというものです。これがどのようなものだったかを示すため、Grant を使わずに Endpoint 同士の通信を確立させる手順をみてみます。

sequenceDiagram
    participant A as Endpoint A (initiator)
    participant CP as Control Plane
    participant B as Endpoint B (target)
    B->>CP: Listener 作成要求  (Endpoint token + protocol)
    CP-->>B: listener_id
    B->>CP: Capability 発行要求 (Endpoint token + listener_id + protocol + Endpoint A の ID)
    A->>CP: 接続要求（Endpoint token + listener_id + protocol + Capability）
    CP-->>A: connection_id + masque_uri
    B->>CP: 接続確認（Endpoint token + connection_id)
    CP-->>B: masque_uri

Endpoint A と Endpoint Bがあり、BがDBなどのリソースと結びついている側、Aがエージェントと結びついている側と考えてください。いずれも最後には CONNECT-UDP リクエストを送る際に用いる MASQUE の URI を獲得しており、これらを使って Endpoint の間に経路を引きます。

しかし、そこに至るまでには、必要な情報をプロトコル外で人間の手を介して渡さなければいけないという問題があります。Bの側に着目してみると、Listener の作成には何も特別な情報は必要ありませんが、その Listener を使ってAからの接続要求を受け付けるためには、Aの ID を事前に入手し、使用して、Capability を発行しなければいけません。そして、Aの側ではその Capability を何かの手段で受け取り、使用して、接続を要求することになります。

この問題を解決するために、Grant は導入されました。Capability が示しているのは、この Listener にAは接続してよいという資格であり、これをAが提示すれば接続要求を受け入れるようになっています。そうであるなら、Aが接続してよいという認可の判断を事前にして、その判断を覚えておけば、Capability のやり取りは必要なくなります。そのような事前の認可の判断の記録が Grant です。なお、Grant が紐づけられるのは、Bが作る Listener ではなく、Bそれ自体です。Listener はBが接続を待ち受けるごとにつくられるものなので、それに紐づけてしまうと、次回以降の Listener には使えないし、そもそもBが Listener を作った後でないと Grant を作れないというのは不便だからです。

Grant を作る手法として最初に導入したのはペアリングです。ペアリングでは target であるB側で QR コードに埋め込まれた短いコードを発行し、それを initiator であるA側から Control Plane に提示します。すると、Control Plane 上にAがBに接続できるようにする無期限の Grant が生成され、保存されます。これにより、初回はペアリング・コードを人間が受け渡す必要はありますが、次回以降は自動的に繋がるようになりました。

sequenceDiagram
    participant A as Endpoint A (initiator)
    participant CP as Control Plane
    participant B as Endpoint B (target)
    B->>CP: ペアリング・コード 発行要求  (Endpoint token + protocol)
    CP-->>B: ペアリング・コード
    A->>CP: ペアリング・コード 送信  (Endpoint token)
    CP->>CP: Grant 作成
    B->>CP: Listener 作成要求  (Endpoint token + protocol)
    CP-->>B: listener_id
    A->>CP: 接続要求（Endpoint token + listener_id + protocol）
    CP-->>A: connection_id + masque_uri
    B->>CP: 接続確認（Endpoint token + connection_id)
    CP-->>B: masque_uri

また、ペアリングと似ているものの、それとは異なるものとしてチケットも作っています。ペアリングのコードはすぐに消費することを前提としているため、同時に1つしか発行できません（新しいコードを発行すると、古いものは無効になる）。しかし、これでは接続をしようとしている Endpoint が複数ある場合に不便です。チケットはこの不便さを解消するために作ったもので、同時に複数発行できます。なお、ペアリングと異なり、チケットを消費して作られる Grant には有効期限があります（この有効期限はチケットを発行するときに設定し、無期限にすることはできません）。永続的な関係を作るならペアリングを使えばよく、一時的なアクセスを付与するのがチケットというように整理したわけです。

このようにペアリングやチケットといった Grant を生成する仕組みは用意されましたが、冒頭のユースケースを解決するにはこれらではうまくいきません。Endpoint を作成する単位は、監査やセキュリティの観点では作業ごとにするのが理想で、冒頭のユースケースではまさにそれが求められます。そこで、作業ごとに Endpoint を作成し、作業を終えたら Endpoint を無効にするモードを（後述する ISEKAI portal のアプリに）用意しましたが、この場合、Endpoint が次々に変わるので、特定の Endpoint についてGrantを一つ発行するペアリングやチケットではうまくいきません。この場合に対応するには、あるアカウントに登録された Endpoint は接続ができるようにする Grant が自動的に作成されるという仕組みが必要です。

この仕組みはどうやって設定するのでしょうか。色々なやり方が考えられますが、現在は冒頭のユースケースのように「社内」のリソースを「社内」のエージェントに使わせることが多いと考え、組織単位で組織の管理者がポリシーを設定できるものとし、そのポリシーをエンタイトルメントと呼んでいます。冒頭の「ステージングDBと委託先の Claude Code の間にだけ経路を引く」の例だと、エンタイトルメントは、主に、Claude Code を使う委託先のエンジニアのアカウント（同エンジニアは組織のメンバーにすることが前提）、ステージングDBの Endpoint の ID、接続に使う protocol から構成されます。

接続の仕組み

ステージングDBは社内ネットワークにあって、外からアクセスできるようになっていないことが多いでしょう。ISEKAI link は Endpoint と Endpoint との間で経路を作ることでこの限界を解消します。社内側でポートを開けることも必要ありません。両 Endpoint が外向きに ISEKAI link の中継サーバーへ接続するからです。しかし、経路が運ぶのは UDP なので、TCPのアプリケーションはその経路を利用できません。そこで、その上に QUIC を張り、エージェント側で待ち受けた TCP/UDP をその QUIC で転送します。これを実現するのが ISEKAI portal というアプリケーションです。

以下の図は ISEKAI portal を用いた冒頭の例の解決を示したものです。

flowchart LR
    subgraph PC["委託先エンジニアの PC"]
        CC["Claude Code"]
        PCL["portal-client<br/>（Endpoint A）"]
        CC -- "TCP<br/>localhost:5432" --> PCL
    end

    subgraph LINK["ISEKAI link"]
        RELAY["中継<br/>（MASQUE CONNECT-UDP）"]
    end

    subgraph CORP["社内ネットワーク"]
        PS["portal-server<br/>（Endpoint B）"]
        DB[("ステージングDB<br/>PostgreSQL")]
        PS -- "TCP" --> DB
    end

    PCL -- "QUIC over CONNECT-UDP" --> RELAY
    PS -- "QUIC over CONNECT-UDP<br/>（外向きに接続）" --> RELAY
    PCL -. "可能なら直接経路に切り替え" .-> PS

直接経路への切り替えは、以前のカメラ・アプリの記事で紹介したのと同じ仕組み（QUIC の Multipath と NAT-Traversal）を使っています。もっとも、インタラクティブに設定を変更する仕組みを設けるのが難しいことから、カメラ・アプリと違って自由に切り替えるようにはしておらず、直接経路が見つかったら自動的に移るようにしています。

なお、portal-client は TCP や UDP の宛先を自由に選ぶことはできず、portal-server が設定した宛先を名前で指定することしかできない設計になっています。TCP や UDP の転送は portal-server が指定した宛先に限定することで、ステージングDBにだけアクセスできるという要求を実現しているわけです。

三つの要求をどう満たすか

ここまで Endpoint、Grant、接続の仕組みの三つを、どういう動機から出てきたのかという点も含めて説明してきました。まず「このDBだけに」は、エンタイトルメントでステージングDB側の Endpoint の ID を指定することと、portal-server が転送先を設定した宛先に限定していることの二つで実現しています。次に「エージェントのアクセスと分かる形で」は、エージェント用の Endpoint を人が使う Endpoint と分けておくことで実現しています。

ただし、ここでいう区別はあくまで記録の上の区別で、アクセスをエージェントだけに限定するものではありません。エンタイトルメントはアカウント単位で設定するので、同じアカウントに登録された Endpoint であれば、人が使う Endpoint からも接続できます。また portal-client は localhost で待ち受けているため、同じ PC 上であれば Claude Code 以外のプロセスからも使えてしまい、その場合もエージェント用の Endpoint からのアクセスとして記録されます。エージェントによるアクセスだけに限定したい場合には、エージェントを専用の環境（コンテナなど）で動かすといった、PC 側での対策と組み合わせる必要があります。

最後に「契約期間中だけ」は、契約期間が終了したら、エンタイトルメントを取り消したり、使用している Endpoint を無効化したりすることで、実現が可能です。特に、Endpoint の無効化は強力で、動いている接続も自動的に切断されるように設計されています。

しかし、そのような取消しや無効化を管理者が忘れずに手動で実行しなければいけないのは不便です。そのような手動による実行だと事故が起こる恐れもあります。そこで、契約期間が終了したら自動的にアクセスが出来なくなる機能として、guest 設定を導入しています。

guest 設定は組織のアカウントに付与できるもので、付与時に有効期限を指定します。そして有効期限が過ぎると、アカウントが無効化されて Endpoint token の発行などができなくなりますが、さらに発行済みの Endpoint token や Grant なども自動的に無効になります。動いている接続も自動的に切断されます。管理者の作業し忘れなどの危険はもはやありません。

また、guest 設定を付与したアカウントが登録する Endpoint は initiator にしかなれないという制約もあります。委託契約などで一時的に組織に属しているだけの人は、組織のリソースを提供する側になる必要はないでしょうし、実際には組織のリソースでないものを偽って組織のリソースとしてアクセスさせる悪用なども考えられますので、target としての動作を禁止しているのです。

おわりに

ISEKAI link を用いると、「このDBだけに」「エージェントのアクセスと分かる形で」「契約期間中だけ」繋がる経路を実現できます。サービスは現在は実証実験中で、無料で利用できます。特に個人アカウントはサインアップしさえすればすぐに利用できるので、ご関心をお持ちの方は是非お試しください。ドキュメント等はISEKAI linkのリポジトリを参照してください。簡単なガイドの記事も近日中にお届けする予定です。

組織アカウントについては、サービス構成の関係で、自由には作成できませんが、実証実験にご参加いただく形で提供できる可能性はありますので、電子メールにてinfo at seera-networks.com宛でお問い合わせいただけますと幸いです。

SEERA Networks Inc. maintains SEERA MsQuic as a fork of MsQuic, which Microsoft creates and publishes (for details, see the introduction article of SEERA MsQuic). One feature that SEERA MsQuic has which upstream MsQuic does not is that the client side can initiate migration. In this article, we will discuss this feature.

Let's start by reviewing the migration content specified in RFC9000. Migration can occur after the connection establishment handshake is complete. Specifically, section 9.2 states that a QUIC endpoint can migrate to a new local address by sending packets containing non-probing frames (non-probing packets) from that new local address. A non-probing frame is any frame other than a probing frame, where probing frames are defined as PATH_CHALLENGE, PATH_RESPONSE, NEW_CONNECTION_ID, and PADDING. For example, a packet containing a STREAM frame qualifies as a non-probing packet. Then, section 9.3 states that an endpoint that receives a non-probing packet from a different peer address must subsequently send packets to that peer address. In short, QUIC switches the address used for communication through the transmission and reception of non-probing packets sourced from a new address.

However, it would be problematic if simply receiving a non-probing packet sourced from a new address were sufficient. Since QUIC packet authentication only covers the UDP payload, the new address could be spoofed and not actually owned by the endpoint. This could enable attacks such as connection hijacking or sending packets to unrelated hosts. Therefore, section 9.3, introduced earlier, actually specifies that the destination address should only be changed if the received non-probing packet has the largest packet number. This prevents replay attacks where past packets are re-sent with spoofed addresses. Furthermore, QUIC specifies Path Validation in section 8.2. Path validation involves an endpoint sending a PATH_CHALLENGE frame containing data that the peer cannot predict to the new address, and checking whether the peer returns that data in a PATH_RESPONSE frame. Since the peer does not know what data the endpoint will send, it cannot return the data unless it has actually received the PATH_CHALLENGE. Therefore, successfully returning the correct data in a PATH_RESPONSE proves that the PATH_CHALLENGE sent to the new address was received, confirming that the endpoint owns that new address. Additionally, when sending PATH_CHALLENGE, it is also required to use PADDING frames to make the datagram at least 1200 bytes. This is to simultaneously verify that the path's MTU meets the minimum size required for QUIC communication.

Another point that requires attention is that only the client side can start sending packets on a new path. This measure is in place to prevent confusion caused by both client and server migrating simultaneously, so migration must be initiated from only one side. The reason it is limited to the client side is likely because clients are more often behind NATs. Therefore, the migration flow always begins with the client, as shown below.

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    Note over C,S: Connection established with pair of C:A address and S:A address

    C->>S: Non-probing packet (including STREAM frames, etc.) with src=C:B, dst=S:A
    Note over S: Switch destination to C:B. However, until validation is complete, limit transmission amount (up to 3 times received amount) for amplification attack countermeasures
    S->>C: PATH_CHALLENGE (including unpredictable data (UD)) with src=S:A, dst=C:B
    C->>S: PATH_RESPONSE (including UD) with src=C:B, dst=S:A
    Note over S: Confirm that Client owns C:B. Lift restrictions

Additionally, as specified in RFC9000, for privacy measures (avoiding linkability), QUIC requires using an unused ConnectionID when sending data on a new path. Therefore, to perform migration, both client and server must add unused ConnectionIDs via NEW_CONNECTION_ID frames. However, in SEERA MsQuic (as well as upstream MsQuic), the API is designed so that users do not need to be aware of ConnectionIDs, as this is handled automatically in the protocol stack, so users do not need to worry about it.

By the way, some of you may have wondered while reading this far: what is the purpose of distinguishing between probing and non-probing? I thought the same when I first saw it, but upon closer consideration, it becomes clear that this distinction is very useful. The fact that migration occurs with non-probing packets means, conversely, that probing packets can be sent on a new path without causing migration. And the frames used in path validation are defined as probing frames. Yes, path validation can be performed on a new path without triggering migration. This allows you to verify in advance whether the path is actually usable before migrating. RFC9000 does not support multipath, which is why the Multipath extension is being developed, but the concept of multiple paths itself already exists.

That concludes the discussion on migration and related topics. Now, let's look at how the SEERA MsQuic API works. For this extension, five APIs that do not exist upstream have been added. All of them are used by calling the SetParam function on the Connection object. Note that if the server sends the disable_active_migration transport parameter during the handshake, migration is not possible. Be aware of this if you are testing against a server you do not manage.

The definitions of QUIC_PATH_PARAM and QUIC_ADDR are as follows.

typedef struct QUIC_PATH_PARAM {
    QUIC_ADDR* LocalAddress;
    QUIC_ADDR* RemoteAddress;
} QUIC_PATH_PARAM;

// For Linux/macOS. On Windows, it is an alias for SOCKADDR_INET
typedef union QUIC_ADDR {
    struct sockaddr Ip;
    struct sockaddr_in Ipv4;
    struct sockaddr_in6 Ipv6;
} QUIC_ADDR;

First, let me show a concrete example of QUIC_PARAM_CONN_ADD_PATH (error handling omitted). In this example, we add a path with a local address that differs only in port from the existing local address, and a remote address that is the same as the existing remote address. Note that if the handshake is not complete (per RFC definition, handshake confirmed; on the client side, reception of the HANDSHAKE_DONE frame), an error will occur, so this must be executed after the QUIC_CONNECTION_EVENT_CONNECTED event.

    QUIC_ADDR SecondAddr = {0}, RemoteAddr = {0};
    // Create a new local address
    uint32_t Addrlen = sizeof(SecondAddr);
    MsQuic->GetParam(Connection, QUIC_PARAM_CONN_LOCAL_ADDRESS, &Addrlen, &SecondAddr);
    // Setting the port to 0 makes SEERA MsQuic assign an open port
    QuicAddrSetPort(&SecondAddr, 0);

    // Use the same remote address as the existing one
    Addrlen = sizeof(RemoteAddr);
    MsQuic->GetParam(Connection, QUIC_PARAM_CONN_REMOTE_ADDRESS, &Addrlen, &RemoteAddr);
    
    QUIC_PATH_PARAM PathParam = {&SecondAddr, &RemoteAddr};
    MsQuic->SetParam(Connection, QUIC_PARAM_CONN_ADD_PATH, sizeof(PathParam), &PathParam);

When the client calls QUIC_PARAM_CONN_ADD_PATH, path validation is performed and a PATH_CHALLENGE frame is sent. Upon receiving the PATH_CHALLENGE, the server responds with a PATH_RESPONSE frame. Then, when the client receives the PATH_RESPONSE and passes validation, the QUIC_CONNECTION_EVENT_PATH_VALIDATED event is triggered. This event indicates that the path has become actually usable.

The QUIC_CONNECTION_EVENT_PATH_VALIDATED event provides two arguments: LocalAddress and RemoteAddress. This allows you to identify which path was validated. By calling QUIC_PARAM_CONN_ACTIVATE_PATH with these, you can achieve migration after pre-validating the path. Then, calling QUIC_PARAM_CONN_REMOVE_PATH on the old path to clean it up completes the migration. This entire flow is illustrated in the following diagram.

stateDiagram-v2
    state "Call QUIC_PARAM_CONN_ADD_PATH" as AddPath
    state "QUIC_CONNECTION_EVENT_PATH_VALIDATED fires" as Validated
    state "Call QUIC_PARAM_CONN_ACTIVATE_PATH" as Activate
    state "Call QUIC_PARAM_CONN_REMOVE_PATH" as Remove
    [*] --> AddPath: Handshake complete
    AddPath --> Validated: PATH_CHALLENGE / PATH_RESPONSE exchanged
    Validated --> Activate
    Activate --> Remove: Migration complete
    Remove --> [*]: Cleanup complete

Next, I will introduce QUIC_PARAM_CONN_ADD_BOUND_ADDRESS. This is used on the server side to add an address to listen on. For example, it can be used when you want to migrate to IPv6 after starting communication over IPv4. Additionally, this API is used for the characteristic behavior of ISEKAI Link, which was introduced in the article about creating a camera app: communication initially goes through a relay path and later switches to a direct path. This is because the server initially listens on the loopback address 127.0.0.1 and needs to migrate to an address on an interface such as Wi-Fi.

Note that even if the server starts listening on a new address, it is meaningless unless the client knows about it. For this, you can use the ADD_ADDRESS frame defined in the NAT-T extension. However, since the behavior of ADD_ADDRESS involves the punchhole mechanism that has not been explained, I would like to leave the details for a separate article. Alternatively, you can also communicate at the application level; in that case, you can set that address as the RemoteAddress on the client side and call QUIC_PARAM_CONN_ADD_PATH. By doing so, migration can be achieved not only for the local address but also for the remote address.

This concludes the explanation of the Client Initiated Migration feature. As a continuation of this series, I hope to discuss NAT-T next time.

セーラ・ネットワークス株式会社ではMicrosoftが作成・公開しているMsQuicのforkとしてSEERA MsQuicをメンテナンスしていますが（詳しくはSEERA MsQuic の紹介記事を参照）、SEERA MsQuicではupstreamのMsQuicにない機能としてクライアント側がMigrationを開始することができます。今回はこの機能について話をしたいと思います。

RFC9000で規定されたMigrationの内容を確認するところから始めましょう。Migrationは接続確立のハンドシェークが完了した後に行うことができるもので、具体的には9.2において、QUICエンドポイントは、非probingフレームを含むパケット（非probingパケット）を新しいローカルアドレスから送ることにより、その新しいローカルアドレスにmigrateすることができる、と規定しています。非probingフレームとは、probingフレーム以外のフレームで、probingフレームはPATH_CHALLENGE、PATH_RESPONSE、NEW_CONNECTION_ID、PADDINGと定義されていますので、例えば、STREAMフレームを含むパケットは、非probingパケットに該当します。そして、9.3は、非probingパケットをこれまでとは違うピアアドレスから受け取ったエンドポイントは、以降はそのピアアドレスに対してパケットを送るようにすると規定しています。要するに、QUICでは新しいアドレスをsourceとする非probingパケットの送受信により、通信で用いるアドレスを切り替えるようになっているわけです。

もっとも、新しいアドレスをsourceとする非probingパケットの受信だけでokとしてしまっては問題です。QUICのパケットの認証はUDPのデータ部分にしか及んでいないため、新しいアドレスはエンドポイントが所持していないアドレスを詐称したものである可能性があります。このままでは、コネクションのハイジャックや無関係のホストにパケットを送り付けるといった攻撃ができてしまいます。そこで、先ほど紹介した9.3ですが、実際には受け取った非probingパケットのうちパケット番号が最大のものである場合に限り送信先アドレスを変えるとしています。これにより、過去のパケットをアドレスを詐称して送り付けるリプレイ攻撃が防がれます。そして、さらにQUICでは8.2でパス検証（Path Validation）を規定しています。パス検証は、エンドポイントがPATH_CHALLENGEフレームでピアが予測できないデータを新しいアドレス宛に送り、ピアがPATH_RESPONSEフレームでそのデータを返してくるかどうかをチェックするものです。ピアはエンドポイントがどういうデータを送ってくるのか知らないので、実際にPATH_CHALLENGEを受信していない限りそのデータを返すことはできません。そのため、PATH_RESPONSEで正しいデータを返せたということは、新しいアドレス宛のPATH_CHALLENGEを受け取ったことの証拠となり、その新しいアドレスをエンドポイントが所持していることが確認されるということになります。なお、PATH_CHALLENGEを送る際にはPADDINGフレームを使ってデータグラムを1200バイト以上の大きさにすることも求められています。これはパスのMTUがQUICの通信に最低限必要なサイズを満たしているか同時に確認する目的で定められているものです。

もう1点注意が必要なことがあります。それは新しいパスでパケットを送信するのを始められるのはクライアント側だけだということです。これはクライアントとサーバーが同時にMigrationしてしまうことによる混乱を防ぐためにはどちらか一方からしかMigrationできないようにする必要があるための措置です。なぜクライアント側だけなのかというと、NAT配下なのはクライアント側が多いからという理由によるものと思われます。そのため、Migrationのフローは以下のように必ずクライアント側が開始することになります。

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    Note over C,S: C:AアドレスとS:Aアドレスのペアで接続確立済み

    C->>S: srcがC:B、dstがS:Aのペアで非probingパケット（STREAMフレーム等含む）
    Note over S: 宛先を C:B に切り替え。ただし検証完了までは増幅攻撃対策で送信量制限（受信量の3倍まで）
    S->>C: srcがS:A、dstがC:BのペアでPATH_CHALLENGE（予測できないデータ（UD）を含む）
    C->>S: srcがC:B、dstがS:AのペアでPATH_RESPONSE（UDを含む）
    Note over S: C:B を Client が所持していることを確認。制限解除

なお、RFC9000の規定として、プライバシー対策（linkability回避）のためにQUICでは新しいパスでデータを送る際には未使用のConnectionIDを使うことになっています。そのため、Migrationを行うためには、クライアント・サーバー共にNEW_CONNECTION_IDフレームで未使用のConnectionIDを追加しておく必要がありますが、SEERA MsQuicでは（upstreamのMsQuicも）、ユーザーがConnectionIDを意識しなくていいようにAPIが設計されており、プロトコルスタック上で自動で行われるため、ユーザーとしては気にする必要はありません。

ところで、ここまで読んできて、probing・非probingの区別は何のためにあるのだろう？と疑問を持たれた方もおられると思います。私も最初見た時はそう思ったのですが、よくよく考えるとその区別はとても有用だとわかります。非probingパケットだとMigrationが起きるということは、裏を返すと、probingパケットはMigrationを引き起こさずに新しいパスでパケットを投げられるということを意味します。そして、パス検証で使われるフレームはprobingフレームと定義されています。そう、パス検証はMigrationを起こすことなく、新しいパスで行うことが出来るのです。これにより、Migrationを行う前にパスが実際に利用可能か事前に検証することが出来ることになります。RFC9000はマルチパスには対応しておらず、そのためMultipath拡張の策定が進められているのですが、複数パスの概念自体は存在するというわけです。

Migrationとそれに関連する話はだいたいこれで終わりました。それでは、SEERA MsQuicのAPIがどうなっているかをみることにしましょう。この拡張に関して、upstreamにはないAPIが5つ追加されています。いずれも、Connectionオブジェクトを対象にSetParam関数を呼び出す形で使います。なお、ハンドシェーク時にサーバーがdisable_active_migrationトランスポートパラメーターを送っている場合はMigrationできません。自分が管理していないサーバーを相手に試す場合はこの点に注意してください。

QUIC_PATH_PARAMとQUIC_ADDRの定義は次の通りです。

typedef struct QUIC_PATH_PARAM {
    QUIC_ADDR* LocalAddress;
    QUIC_ADDR* RemoteAddress;
} QUIC_PATH_PARAM;

// Linux/macOSの場合。WindowsではSOCKADDR_INETの別名
typedef union QUIC_ADDR {
    struct sockaddr Ip;
    struct sockaddr_in Ipv4;
    struct sockaddr_in6 Ipv6;
} QUIC_ADDR;

まず、QUIC_PARAM_CONN_ADD_PATHの具体例を示します（エラー処理は省略）。この例では既存のローカルアドレスとポートだけ違うローカルアドレスと既存のリモートアドレスと同じリモートアドレスのパスを追加しています。なお、ハンドシェークが完了（RFCの定義としては、handshake confirmedで、クライアント側ではHANDSHAKE_DONEフレームの受信）していないとエラーになりますので、QUIC_CONNECTION_EVENT_CONNECTEDが発生した後に実行する必要があります。

    QUIC_ADDR SecondAddr = {0}, RemoteAddr = {0};
    // 新しいローカルアドレスを作る
    uint32_t Addrlen = sizeof(SecondAddr);
    MsQuic->GetParam(Connection, QUIC_PARAM_CONN_LOCAL_ADDRESS, &Addrlen, &SecondAddr);
    // ポートを0にしておくと、SEERA MsQuicが開いているポートを割り当てる
    QuicAddrSetPort(&SecondAddr, 0);

    // リモートアドレスは既存と同じものを使う
    Addrlen = sizeof(RemoteAddr);
    MsQuic->GetParam(Connection, QUIC_PARAM_CONN_REMOTE_ADDRESS, &Addrlen, &RemoteAddr);
    
    QUIC_PATH_PARAM PathParam = {&SecondAddr, &RemoteAddr};
    MsQuic->SetParam(Connection, QUIC_PARAM_CONN_ADD_PATH, sizeof(PathParam), &PathParam);

クライアントがQUIC_PARAM_CONN_ADD_PATHを呼び出すと、パス検証が実行され、PATH_CHALLENGEフレームが送信されます。サーバーはPATH_CHALLENGEを受信すると応答でPATH_RESPONSEフレームを返します。そして、クライアントがPATH_RESPONSEを受信し、検証をパスするとQUIC_CONNECTION_EVENT_PATH_VALIDATEDイベントが発生します。このイベントによりパスが実際に使えるようになったことがわかるわけです。

QUIC_CONNECTION_EVENT_PATH_VALIDATEDイベントでは、LocalAddressとRemoteAddressの2つの引数が渡ります。これによりどのパスが検証されたのか特定することができますので、これらを用いてQUIC_PARAM_CONN_ACTIVATE_PATHを呼び出せば、パス検証を事前に行ったうえでのMigrationが実現できるということになります。そして、旧パスについてQUIC_PARAM_CONN_REMOVE_PATHを呼び出して掃除をすればMigrationは完全に終了することになります。この一連の流れを図にすると次のようになります。

stateDiagram-v2
    state "Call QUIC_PARAM_CONN_ADD_PATH" as AddPath
    state "QUIC_CONNECTION_EVENT_PATH_VALIDATED fires" as Validated
    state "Call QUIC_PARAM_CONN_ACTIVATE_PATH" as Activate
    state "Call QUIC_PARAM_CONN_REMOVE_PATH" as Remove
    [*] --> AddPath: Handshake complete
    AddPath --> Validated: PATH_CHALLENGE / PATH_RESPONSE exchanged
    Validated --> Activate
    Activate --> Remove: Migration complete
    Remove --> [*]: Cleanup complete

次にQUIC_PARAM_CONN_ADD_BOUND_ADDRESSを紹介します。これはサーバー側で待ち受けているアドレスを追加するもので、例えば、IPv4で通信を開始した後にIPv6に移行したいという用途で使えます。また、カメラアプリを作った話の記事で紹介したISEKAI Linkの特徴である、最初はRelay経路の通信で、後から直接経路の通信に切り替わるという動作にもこのAPIを使っています。サーバーは最初は127.0.0.1のloopbackアドレスで待ち受けており、そこからWi-Fiなどのインターフェースのアドレスなどに移行する必要があるからです。

なお、サーバー側が新しいアドレスで待ち受けるようになっても、それをクライアントが知らなければ意味がないわけですが、これにはNAT-T拡張が規定しているADD_ADDRESSフレームを使うことができます。もっとも、ADD_ADDRESSの動作は説明していないpunchholeの仕組みも絡んでくるので、このあたりの詳細は別の記事にしたいと思います。また、それ以外にもアプリケーションのレベルでやり取りすることもできますので、そのアドレスをクライアント側でRemoteAddressに設定してQUIC_PARAM_CONN_ADD_PATHを呼ぶわけです。こうすることにより、ローカルアドレスだけでなく、リモートアドレスに関してもMigrationが実現できることになります。

Client Initiated Migrationの機能の説明は以上になります。このシリーズの続きとしては、次回はNAT-Tの話をできればと思います。

At Seera Networks, we are developing ISEKAI link, a relay service that connects devices on different networks over QUIC. ISEKAI link provides authentication, connection mediation, and relay for parties that cannot connect directly.

As our first application, we wrote two desktop applications for streaming camera video. camera-server captures and distributes video from a webcam, and camera-client receives and displays it. Both are built with eframe/egui. This article is about the insights we gained while developing these applications.

Here's what we accomplished.

• Capture from a webcam at 640×480 and encode to JPEG
• Distribute to multiple viewers over QUIC (up to 8 viewers)
• Relay traffic for peers that cannot connect directly
• Switch to a direct path when possible
• Use pairing to determine who is allowed to view

Why a webcam? Because it's the minimal example that exercises all the requirements of a relay service: latency, bandwidth, one-to-many distribution, and NAT traversal. And there's no inherent reason this needs to be a webcam for human viewing; we'll discuss that at the end.

Overall Connection Architecture

Below, we'll discuss three key design decisions: how to transport video, how to transition paths, and how to grant permissions.

1. How to Transport Video

A Naive Approach Gets Stuck

If you stream live video over a single stream like TCP, you'll run into trouble when a viewer's reception is slow. Undelivered data accumulates on the sender side, causing that viewer's video to lag further behind real-time. This delay never recovers because the accumulated data must be drained before catching up.

Worse, one slow viewer can impact others. If the send buffer fills up and blocks writes to the TCP socket, the accept loop stalls, preventing new viewers from connecting.

In live video, buffered frames are just delay.

One Unidirectional Stream per Frame

Instead, we open a unidirectional QUIC stream for each frame, place the JPEG data on it, and close the stream.

This allows us to use the stream ID as a frame sequence number. Since each stream is independent, if packet loss delays a particular stream, subsequent streams can still be received as soon as they arrive. The receiver tracks the highest stream ID it has seen and can discard frames with lower IDs without decoding them.

let mut largest_seq = 0u64;
let mut latest: Option<Bytes> = None;
while let Ok((seq, data)) = rx.try_recv() {
    if seq > largest_seq || largest_seq == 0 {
        largest_seq = seq;
        latest = Some(data);
    } else {
        tracing::debug!("Discarding old frame with seq {seq}");
    }
}

Displaying old frames is pointless. Since JPEG decoding is relatively expensive, it's efficient to decide to discard frames before decoding.

Additionally, the one-stream-per-frame design has a secondary benefit: stream closure naturally marks the end of a frame, eliminating the need for custom framing like length prefixes. The receiver can simply treat "reading a stream to completion" as "one frame received".

No Queues on the Sender Side

The sender follows the same philosophy. Instead of maintaining a send queue per viewer, it keeps a single slot for the latest frame. A viewer that can't keep up will receive the latest frame when they become available again; frames in between are simply not delivered to them.

This is the correct behavior for live video. Slow viewers see thinned-out video, not delayed video.

/// Push the newest frame to one client, for as long as it keeps up with itself.
///
/// Whatever arrives while `push_one` is in flight replaces the pending frame
/// rather than queueing behind it, so this always sends what the camera has
/// *now*.
async fn push_frames(conn: Connection, mut frames: watch::Receiver<Option<Bytes>>) {
    // Sample on a timer rather than per frame. Counting frames looks equivalent
    // and is not: when the peer stops acknowledging, `push_one` blocks on flow
    // control and the frame counter stops advancing — so the logging goes quiet
    // exactly when something has gone wrong and the numbers matter most. A
    // stalled server then leaves no record of which path it was using.
    let stats = tokio::spawn(log_stats_until_closed(conn.clone()));
    while let Some(frame) = next_frame(&mut frames).await {
        if let Err(e) = push_one(&conn, &frame).await {
            tracing::debug!("video push ended: {e}");
            break;
        }
    }
    stats.abort();
}

/// The next frame to send, skipping any superseded while the last one was in
/// flight. `None` once the server stops publishing.
///
/// This is where "latest wins" actually happens: several frames may have been
/// published while `push_one` was awaiting, and only the last of them is worth
/// sending.
async fn next_frame(frames: &mut watch::Receiver<Option<Bytes>>) -> Option<Bytes> {
    loop {
        frames.changed().await.ok()?;
        // A published `None` cannot happen today, but skipping rather than
        // stopping keeps this honest if an empty slot is ever published.
        if let Some(frame) = frames.borrow_and_update().clone() {
            return Some(frame);
        }
    }
}

The Significance of MTU 1248

Another number emerged only after actually working with MASQUE: we set the maximum MTU for QUIC communication to 1248.

This is both the minimum value MsQuic accepts and the size that fits within the outer packet when encapsulated with CONNECT-UDP. If we didn't set this, the path would fail as soon as we switched to relaying.

When running QUIC inside a tunnel, the inner MTU must be set conservatively to account for outer headers. This seems obvious in hindsight, but it's the kind of thing you only notice once you start testing.

2. Transitioning from Relay to Direct Path

This was the most challenging part.

Direct Communication is Hard from the Start

For individuals to make a webcam accessible from the internet, one might consider exposing it publicly via cloud services or home router port forwarding. However, using the cloud means, even temporarily, storing data, raising security concerns. Router port forwarding enables direct communication, avoiding data storage and being more secure, but configurations vary between routers, making it cumbersome. Additionally, allowing anyone to connect is a security concern.

Therefore, ISEKAI link initially establishes a QUIC connection via relay. Since the proxy mediates between the two parties, the connection succeeds regardless of NAT types or firewall configurations. However, always relying on the relay is inefficient. We therefore leverage QUIC's NAT-Traversal extension to establish a direct path even when both ends are behind NATs, and switch from the proxy path to the direct path to optimize the route.

The opposite order – "try direct first, fall back to relay" – is also possible. WebRTC, for example, does this. However, the time to establish the initial connection varies depending on the peer's network. Since the worst outcome for users is "sometimes it connects, sometimes it doesn't", we prioritize establishing a reliable path first.

The Utility and Limitations of Migration

QUIC offers Migration as a standard feature (RFC 9000). We can use this to switch from the relay path to a direct path. Initially, we naively thought we could simply migrate as soon as the direct path became available, close the relay path, and be done. Migration can indeed satisfy the basic requirements, but there are two shortcomings.

First, we cannot switch to the direct path at an arbitrary time. Second, if the direct path dies later, it's difficult to switch back to the relay path.

QUIC has a PING frame that can be used to keep a path alive, but per the QUIC specification, it can only be used after migration. Therefore, if we don't migrate immediately after the direct path becomes available, no packets will flow, the NAT mapping will expire, and the path will go stale. This prevents us from providing the ability to switch at any time. While the relay path is less efficient, it is stable, and naturally, users would want the flexibility to switch at their convenience.

Furthermore, the direct path can be lost if the camera temporarily stops sending data; the NAT mapping might expire. In such cases, it would be good to fall back to the relay, but since we've already migrated, we cannot send PING frames over the relay path either. The relay path might also close naturally if no packets flow for a while, so when we want to go back, it might already be unusable.

Keeping Both Paths Alive with Multipath

Instead, we chose to keep both paths active.

stateDiagram-v2
    state "Relay only" as RelayOnly
    state "Direct path kept as backup" as DirectBackup
    state "Direct path active" as DirectActive
    state "Relay path active" as RelayActive
    [*] --> RelayOnly: Proxy mediates
    RelayOnly --> DirectBackup: PathAdded (validated)
    note right of DirectBackup
        No traffic flows until declared
    end note
    DirectBackup --> DirectActive: Viewer requests switch
    note right of DirectActive
        Declare relay as backup / direct as available
        Keep the relay alive with keepalives, never discard it
    end note
    DirectActive --> RelayActive: Viewer requests switch
    note right of RelayActive
        Declare direct as backup / relay as available
        Keep the relay alive with keepalives, never discard it
    end note
    RelayActive --> DirectActive: Viewer requests switch

Here's the step-by-step breakdown:

1. Both sides advertise their addresses that are visible to the peer.
2. When the direct path is verified, a PathAdded event fires. However, it's initially kept as a backup, and no communication flows until it's activated.
3. When the viewer requests a switch, we declare the relay as backup and the direct path as available.
4. We do not discard the relay path. We keep it alive with per-path keepalives.

The key is step 3: "when the viewer requests it." We separate the fact that a direct path is available from the decision to use it. By making verification and switching two separate events, the application can control the timing of the switch.

Effect

The client measures RTT every second and plots it as a line chart. Around the 54-second mark, it switches to the direct path, and the line drops a level after the switch.

Once the direct path is established, video no longer traverses the relay.

3. Who to Grant Permission To

Finally, let's discuss authorization. The implementation effort was small, but choosing the wrong model would cause problems later.

Permissions Should Not Be Tied to a Specific Broadcast

A naive approach is to grant permissions tied to a broadcast, like "can view this Listener".

This approach is flawed. Cameras crash and restart. Each time, the Listener is recreated, and the permission disappears with it. Viewers would have to re-pair every time the camera restarts.

Grants Belong to the owner Endpoint

Instead, we tied the permission to the device itself.

Each device has an ECDSA P-256 key pair, and the public key is used to derive an Endpoint ID. Grants are issued to this owner Endpoint. Even if the camera side recreates its Listener, the Grant remains valid.

The Trade-off: More Complexity on the Client Side

To be honest, this decision shifted complexity to the client side.

Since Grants are tied to Endpoints, the proxy returns all Listeners belonging to the same Endpoint. And a crashed camera-server leaves behind "unreachable Listeners" until their leases expire. Therefore, if we simply displayed the entire list, the same camera would appear multiple times, and some of them would be dead.

To handle this, we select the listener with the latest expires_at among those with the same owner, showing one line per camera. This isn't perfect (it would break if the same Endpoint intentionally had multiple cameras), but it works for our current use case.

Since this decision is also shared with the iOS viewer, we placed this logic in camera-core to avoid divergence between the two implementations.

What Short-Lived Tokens Drag In

One more lesson we learned after implementing: Endpoint Tokens expire after a few minutes. They are automatically reissued during a session, but each reissue requires an Auth0 authentication state, meaning a valid Auth0 access token is a prerequisite.

As a result, we had to implement a mechanism using the Device Authorization Grant (RFC 8628) for sign-in and automatic refresh using the obtained refresh token. We kept a manual access token field, but it's not practically usable since it can't be refreshed after expiry.

Choosing short-lived tokens always entails providing "non-expiring tokens" underneath.

The Connected Device Doesn't Have to Be a Camera

Of the three decisions discussed – delivering only the latest video, maintaining both relay and direct paths, and tying Grants to Endpoints – only the first is specific to cameras.

The second and third work the same regardless of what runs over QUIC, whether it's MCP or PostgreSQL. And if we direct "who gets a Grant" towards AI agents instead of humans, this becomes a layer where only authorized agents can reach internal resources.

The camera app was a vehicle to test all these elements together before that.

Incidentally, the camera app source code is released under the MIT license. You can access it from the ISEKAI link repository. We also distribute binaries for Windows, Linux, and Mac on the releases page, so please give it a try!

Next time (for real this time), we'll discuss Client Initiated Migration.

セーラ・ネットワークス株式会社では、異なるネットワークにある機器同士を QUIC で繋ぐための中継サービスISEKAI linkを開発しています。ISEKAI linkは認証と接続の仲介、そして直接繋がらない相手のためのリレーを提供します。

その最初の適用先として、カメラ映像を配信するデスクトップアプリを 2 つ書きました。camera-server がWebカメラの映像をキャプチャして配り、camera-client が受け取って表示します。どちらも eframe/egui です。今回はこれらのアプリの開発で得られた知見の話です。

やったことは、これだけです。

• Webカメラから 640×480 でキャプチャし、JPEG に符号化する
• QUIC で 1 対多に配信する（最大 8 視聴者）
• 直接繋がらない相手にはリレーを経由する
• 繋がるなら、途中から直接経路へ移る
• 誰が見てよいかはペアリングで決める

なぜWebカメラかというと、遅延・帯域・1 対多・NAT 越えという、中継サービスに要求されるものが全部乗る最小の実例だからです。そして、これが人間の見るWebカメラである必然性は実はありません。その話は最後にします。

接続の全体像

以下では、この中で設計判断が要った 3 か所を書きます。映像の運び方、経路の移り方、そして誰に許可を出すかです。

1. 映像をどう運ぶか

素朴にやると詰まる

ライブ映像をTCPのような単一のストリームに流すと、視聴者の受信が遅いときに困ります。送れなかった分は送信側に溜まり、その視聴者に見えている映像は現在から遅れ続けます。しかも、その遅延は回復しません。溜まった分を消化しない限り追いつけないからです。

さらに悪いのは、その 1 人が他に波及することです。送信バッファが一杯になってTCPへの書き込みがブロックすると、accept ループが止まり、新しい視聴者が繋がらなくなります。

ライブ映像において、貯めたフレームは遅延でしかありません。

1 フレームに 1 本の単方向ストリームを割り当てる

そこで、QUIC の単方向ストリームを 1 フレームにつき 1 本 開き、JPEG をそのまま載せて閉じる形にしました。

こうすると、ストリーム ID をフレームの連番として扱うことができます。しかも、それぞれは独立したストリームなので、あるストリームが揃うのがパケットロスで遅れた場合でも、その後のストリームは揃ったらそのまま受信できます。そして、受信側は自分が見た最大の ID を覚えておいて、それより小さい ID のフレームは復号せずに捨てることができます。

let mut largest_seq = 0u64;
let mut latest: Option<Bytes> = None;
while let Ok((seq, data)) = rx.try_recv() {
    if seq > largest_seq || largest_seq == 0 {
        largest_seq = seq;
        latest = Some(data);
    } else {
        tracing::debug!("Discarding old frame with seq {seq}");
    }
}

古いフレームを表示する意味はありません。JPEG のデコードは安くないので、捨てる判断を復号の前に置くのが効きます。

また、1フレームに1ストリームという構成には副次的な利点もあります。ストリームが閉じることがそのままフレームの終端になるので、長さプレフィックスのような独自のフレーミングが要りません。受信側は「ストリームを最後まで読んだら 1 枚」とだけ考えればよくなります。

送信側はキューを持たない

送信側も同じ思想です。視聴者ごとに送信キューを持たず、最新フレームの置き場所を 1 つ持ちます。追いつけない視聴者には、次に受け取れるようになったときの最新フレームが渡ります。その間のフレームは、その人には届きません。

これがライブ映像として正しい振る舞いです。遅い視聴者は、遅れた映像ではなく、間引かれた映像を見ることになります。

/// Push the newest frame to one client, for as long as it keeps up with itself.
///
/// Whatever arrives while `push_one` is in flight replaces the pending frame
/// rather than queueing behind it, so this always sends what the camera has
/// *now*.
async fn push_frames(conn: Connection, mut frames: watch::Receiver<Option<Bytes>>) {
    // Sample on a timer rather than per frame. Counting frames looks equivalent
    // and is not: when the peer stops acknowledging, `push_one` blocks on flow
    // control and the frame counter stops advancing — so the logging goes quiet
    // exactly when something has gone wrong and the numbers matter most. A
    // stalled server then leaves no record of which path it was using.
    let stats = tokio::spawn(log_stats_until_closed(conn.clone()));
    while let Some(frame) = next_frame(&mut frames).await {
        if let Err(e) = push_one(&conn, &frame).await {
            tracing::debug!("video push ended: {e}");
            break;
        }
    }
    stats.abort();
}

/// The next frame to send, skipping any superseded while the last one was in
/// flight. `None` once the server stops publishing.
///
/// This is where "latest wins" actually happens: several frames may have been
/// published while `push_one` was awaiting, and only the last of them is worth
/// sending.
async fn next_frame(frames: &mut watch::Receiver<Option<Bytes>>) -> Option<Bytes> {
    loop {
        frames.changed().await.ok()?;
        // A published `None` cannot happen today, but skipping rather than
        // stopping keeps this honest if an empty slot is ever published.
        if let Some(frame) = frames.borrow_and_update().clone() {
            return Some(frame);
        }
    }
}

MTU 1248 という数字

もうひとつ、実際に MASQUE を通して初めて出てきた数字があります。QUIC通信の最大MTUを 1248 に設定しています。

これは MsQuic が受け付ける下限であると同時に、CONNECT-UDP でカプセル化したときに外側のパケットに収まる大きさです。ここを詰めておかないと、リレー経由になった途端に通らなくなります。

トンネルの中で QUIC を喋るとき、内側の MTU は外側のヘッダ分だけ余裕を持って決める必要があります。当たり前のようでいて、動かして初めて気づく類のものでした。

2. リレーから直接経路へ移る

ここが一番悩んだところです。

最初から直接通信は難しい

個人がWebカメラをインターネットからアクセスできるようにする手法としては、クラウドや家庭ネットワークのルーターでの外部公開も思いつきます。しかし、クラウドを利用すると一時的にとはいえデータを貯めておくことになり、セキュリティが気になります。ルーターで外部公開すれば直接通信できるので、データを貯めておく必要がなくセキュアですが、ルーターごとに設定が異なって手間な上に誰でも繋げてしまうのもセキュリティ上気になるところです。

そこでISEKAI linkでは、まずリレー経由でQUICを繋げます。プロキシが両者を仲介するので、NAT の形やファイアウォールの設定によらず接続は成立します。もっとも、常にリレーを経由するのは効率的ではありません。そこで、QUICのNAT-Traversal拡張を利用して、両端がNATの配下にある場合でも直接通信できる経路を作り、プロキシ経由から直接経路へと切り替えて経路を最適化します。

逆の順序、つまり「まず直接を試して、駄目ならリレーに落とす」というやり方もあり得ます。例えばWebRTCがそういう方式ですが、最初の接続までの時間が相手のネットワーク次第でぶれます。ユーザーから見て「繋がるときと繋がらないときがある」のが最悪なので、確実に繋がる経路を先に確保しました。

Migrationの有用性と限界

QUICには標準（RFC 9000）の機能として、Migrationがあります。これを利用してリレー経由の経路から直接経路へと切り替えることができます。最初は素朴に直接経路が有効になったら直ぐにMigrationを使って切り替えて、リレー経路は閉じてしまって足りると考えていました。実際、Migrationでも基本的な要件は満たせます。ただし 2 つの足りないところがあります。

ひとつは、任意のタイミングで直接経路に切り替えることができないこと。もうひとつは、直接経路が後から死んだときにリレー経由の経路に戻ることが難しいことです。

QUICにはPINGフレームという経路を生かし続けるのに使える仕組みがありますが、QUICの仕様でこれはMigrationをした後にしか使えません。そのため、直接経路は有効になった直後にMigrationしないと、パケットが流れず、NATのマッピングが切れて腐ってしまいます。そのため、任意のタイミングで切り替える機能を提供することができませんでした。リレー経由の経路は効率の面では劣るとはいえ、安定してますから、好きなタイミングで切り替えたいというのは自然な要望だと思います。

また、直接経路はカメラのデータ送信を一時的に止めるようなことをすると、NATのマッピングが切れて失われることもあり得ます。そのような場合にはリレー経由に戻れるのが良いのですが、Migrationしてしまっているので、同様にPINGをリレー経由の経路に送ることができません。リレーの経路もしばらくパケットが流れないと自然に閉じるようにしているので、戻りたいときには使えなくなっているということが起こるわけです。

multipath で両方を持ち続ける

採ったのは、両方の経路をアクティブに保つ形です。

stateDiagram-v2
    [*] --> リレーのみ: プロキシが仲介
    リレーのみ --> 直接経路をbackupで保持: PathAdded 検証済み
    note right of 直接経路をbackupで保持
        宣言するまで通信は流れない
    end note
    直接経路をbackupで保持 --> 直接経路がactive: 視聴者が切替を要求
    note right of 直接経路がactive
        relay を backup / direct を available と宣言
        リレーは破棄せず keepalive で温存
    end note
    直接経路がactive --> リレー経由の経路がactive: 視聴者が切替を要求
    note right of リレー経由の経路がactive
        direct を backup / relay を available と宣言
        relayは破棄せず keepalive で温存
    end note
    リレー経由の経路がactive --> 直接経路がactive: 視聴者が切替を要求

順を追うと、こうなります。

1. 双方が、相手から見えている自分のアドレスを広告する
2. 直接経路が検証されると PathAdded が上がる。ただしまず backup として保持され、宣言するまで通信は流れない
3. 視聴者が切り替えを要求したときに、relay を backup、direct を available と宣言する
4. リレー経路は破棄しない。 経路ごとの keepalive で温存する

3 の「視聴者が要求したとき」がポイントです。直接経路が使えるようになったことと、それを使うことを分けています。検証と切り替えを別のイベントにしておくと、切り替えのタイミングをアプリ側で選べます。

効果

クライアントは 1 秒ごとに RTT を測って折れ線で出しています。54秒あたりで直接経路に切り替えていますが、切り替えの前後で、線が一段下がります。

直接経路が確立したあとの映像はリレーを通りません。

3. 誰に許可を出すか

最後に認可の話です。ここは実装量こそ少ないものの、モデルを間違えると後から効いてくる部分でした。

「この配信への許可」にしてはいけない

素朴に考えると、権限は配信に対して出したくなります。「この Listener を見てよい」という形です。

これは破綻します。カメラは落ちますし、再起動します。そのたびに Listener は作り直され、権限も一緒に消えます。視聴者は、カメラが再起動するたびにペアリングをやり直すことになります。

Grant は owner Endpoint に属する

そこで、紐づけ先を端末そのものにしました。

端末ごとに ECDSA P-256 の鍵を持ち、公開鍵から Endpoint ID を導出します。Grant はこの owner Endpoint に対して発行されます。カメラ側が Listener を作り直しても、Grant は有効なままです。

その代わり、クライアントが少し複雑になる

正直に書くと、この判断はクライアント側に面倒を押し出しました。

Grant が Endpoint に対するものなので、プロキシは同じ Endpoint の Listener を全部返します。そして、落ちた camera-server は、リースが切れるまで「繋がらない Listener」を残します。つまり、一覧をそのまま出すと、同じカメラが複数行になり、しかもそのうち何本かは死んでいます。

対処として、同じ owner の中では expires_at が後のものを採り、カメラ 1 台につき 1 行にしています。完全ではありません（同一 Endpoint が意図的に複数のカメラを持つ場合は破綻します）が、現状の使い方では機能しています。

この判断は iOS ビューアとも共有しているため、2 か所に書いて食い違うのを避けて camera-core に置きました。

短命トークンが芋づるで連れてくるもの

もう 1 点、実装してから気づいたことを書いておきます。

Endpoint Token は数分で失効します。セッション中は自動で再発行するのですが、再発行のたびに Auth0 の認証状態が要求されます。つまり、Auth0 のアクセストークンが生きていることが前提になります。

結果として、デバイス認可グラント（RFC 8628）でサインインし、得た refresh token で自動更新し続ける仕組みが必須になりました。手貼りのアクセストークン欄も残してはありますが、期限が切れたら更新できないので実用にはなりません。

短命なトークンを選ぶと、その裏側に「切れないトークン」を用意する仕事が必ず生えます。

繋ぐ先がカメラである必要はない

ここまで書いてきた 3 つ——最新が勝つ映像の運び方、リレーと直接経路の両立、Endpoint に紐づく Grant——のうち、カメラに固有なのは 1 つ目だけです。

2 つ目と 3 つ目は、QUIC の上に何を載せても同じように働きます。MCP でも PostgreSQL でも構いません。そして「誰に Grant を出すか」を人間ではなく AI エージェントに向けたとき、これは認可したエージェントだけが社内リソースに到達できる層になります。

カメラアプリは、その手前で全部の要素を一度に試すために書いたものでした。

なお、カメラアプリのソースコードはMITライセンスで公開しています。ISEKAI linkのレポジトリからアクセスできます。また、このレポジトリでは、Windows、Linux、Mac向けのバイナリもリリースで配布していますので、是非自身でもお試しください！

次回（こそ）は、Client Initiated Migrationの話をします。

SEERA Networks Inc. is developing a product that uses QUIC (ISEKAI link). While there are various QUIC implementations, we have adopted MsQuic, developed by Microsoft. The reasons for choosing MsQuic include its support for major platforms such as Windows, Linux, and macOS (macOS is officially best-effort, but it works without issues in practice), its optimization for high throughput and low latency, and the fact that some of our members contribute to MsQuic, which gives us some flexibility.

Why we forked it

However, MsQuic also has its limitations. Although QUIC supports Migration by default, the upstream MsQuic does not implement the client-side behavior of migrating paths (the server-side behavior to handle a client's migration is implemented). Since the multipath extension is also based on the Migration feature, MsQuic does not support it either. Because ISEKAI link leverages these features, we cannot use the upstream code as-is.

That said, it's not as if no efforts have been made to incorporate these features into upstream. One of our members created pull requests, and reviews for merging have been conducted (see PR #4218 for client-side path migration, and PR #4724 for Multipath). However, these are large changes with significant code modifications, yet they don't seem to be a high priority for Microsoft, so the reviews have not progressed smoothly, and they have not been merged yet (judging from the discussions on Discord, Microsoft does seem interested in merging them eventually).

Therefore, we decided to fork MsQuic and create and maintain a branch that includes patches for these features. That is SEERA MsQuic. While we haven't clearly defined an exit strategy at this point, we aim to have everything merged upstream as much as possible, and once that goal is achieved, we plan to wind down the fork.

Features of SEERA MsQuic

SEERA MsQuic is also released under the MIT license. The differences from upstream are as follows (the Server Initiated Migration extension is proposed by one of our members):

• Client Initiated Migration
• Multipath extension
• Address Discovery extension
• Server Initiated Migration extension
• NAT-T extension

Since upstream is also actively developed, we merge the HEAD of upstream's main branch into seera-main, our branch for SEERA MsQuic, about once a month. The differences are mainly in path handling, and since path handling isn't frequently changed upstream, we've been able to keep up without much trouble so far. By the way, upstream creates release branches every six months to a year and maintains them for over 18 months (see upstream Release documentation), but we have not created SEERA MsQuic for those various versions at this point.

For CI, we use almost exactly what upstream uses. The only things we removed are the checks that use Microsoft's internal resources to verify operation on the latest OS. We've also added tests for these extensions, such as the test for adding new paths shown below, so it's confirmed that these extensions work correctly.

void
QuicTestProbePath(
    _In_ int Family,
    _In_ BOOLEAN ShareBinding,
    _In_ BOOLEAN DeferConnIDGen,
    _In_ uint32_t DropPacketCount
    )
{
    PathTestContext Context;
    CxPlatEvent PeerStreamsChanged;
    MsQuicRegistration Registration(true);
    TEST_TRUE(Registration.IsValid());

    MsQuicConfiguration ServerConfiguration(Registration, "MsQuicTest", ServerSelfSignedCredConfig);
    TEST_TRUE(ServerConfiguration.IsValid());

    if (DeferConnIDGen) {
        BOOLEAN DisableConnIdGeneration = TRUE;
        TEST_QUIC_SUCCEEDED(
            ServerConfiguration.SetParam(
                QUIC_PARAM_CONFIGURATION_CONN_ID_GENERATION_DISABLED,
                sizeof(DisableConnIdGeneration),
                &DisableConnIdGeneration));
    }

    MsQuicCredentialConfig ClientCredConfig;
    MsQuicConfiguration ClientConfiguration(Registration, "MsQuicTest", ClientCredConfig);
    TEST_TRUE(ClientConfiguration.IsValid());

    MsQuicAutoAcceptListener Listener(Registration, ServerConfiguration, PathTestContext::ConnCallback, &Context);
    TEST_QUIC_SUCCEEDED(Listener.GetInitStatus());
    QUIC_ADDRESS_FAMILY QuicAddrFamily = (Family == 4) ? QUIC_ADDRESS_FAMILY_INET : QUIC_ADDRESS_FAMILY_INET6;
    QuicAddr ServerLocalAddr(QuicAddrFamily);
    TEST_QUIC_SUCCEEDED(Listener.Start("MsQuicTest", &ServerLocalAddr.SockAddr));
    TEST_QUIC_SUCCEEDED(Listener.GetLocalAddr(ServerLocalAddr));

    MsQuicConnection Connection(Registration, CleanUpManual, ClientCallback, &PeerStreamsChanged);
    TEST_QUIC_SUCCEEDED(Connection.GetInitStatus());

    if (ShareBinding) {
        Connection.SetShareUdpBinding();
    }

    TEST_QUIC_SUCCEEDED(Connection.Start(ClientConfiguration, ServerLocalAddr.GetFamily(), QUIC_TEST_LOOPBACK_FOR_AF(ServerLocalAddr.GetFamily()), ServerLocalAddr.GetPort()));
    TEST_TRUE(Connection.HandshakeCompleteEvent.WaitTimeout(TestWaitTimeout));
    TEST_TRUE(Context.HandshakeCompleteEvent.WaitTimeout(TestWaitTimeout));
    TEST_NOT_EQUAL(nullptr, Context.Connection);

    //
    // Wait for handshake confirmation.
    //
    CxPlatSleep(100);

    QuicAddr SecondLocalAddr;
    TEST_QUIC_SUCCEEDED(Connection.GetLocalAddr(SecondLocalAddr));
    SecondLocalAddr.SetEphemeralPort();
    QuicAddr RemoteAddr;
    TEST_QUIC_SUCCEEDED(Connection.GetRemoteAddr(RemoteAddr));
    QUIC_PATH_PARAM PathParam = { &SecondLocalAddr.SockAddr, &RemoteAddr.SockAddr };
    PathProbeHelper *ProbeHelper = new(std::nothrow) PathProbeHelper(SecondLocalAddr.GetPort(), DropPacketCount, DropPacketCount);

    QUIC_STATUS Status = QUIC_STATUS_SUCCESS;
    uint32_t Try = 0;
    do {
        Status = Connection.SetParam(
            QUIC_PARAM_CONN_ADD_PATH,
            sizeof(PathParam),
            &PathParam);

        if (QUIC_FAILED(Status)) {
            delete ProbeHelper;
            SecondLocalAddr.SetEphemeralPort();
            ProbeHelper = new(std::nothrow) PathProbeHelper(SecondLocalAddr.GetPort(), DropPacketCount, DropPacketCount);
        }
    } while (QUIC_FAILED(Status) && ++Try <= 3);
    TEST_EQUAL(Status, QUIC_STATUS_SUCCESS);

    if (DeferConnIDGen) {
        BOOLEAN ReplaceExistingCids = FALSE;
        TEST_QUIC_SUCCEEDED(Context.Connection->SetParam(QUIC_PARAM_CONN_GENERATE_CONN_ID, sizeof(ReplaceExistingCids), &ReplaceExistingCids));
    }

    TEST_TRUE(ProbeHelper->ServerReceiveProbeEvent.WaitTimeout(TestWaitTimeout * 10));
    TEST_TRUE(ProbeHelper->ClientReceiveProbeEvent.WaitTimeout(TestWaitTimeout * 10));
    delete ProbeHelper;
}

Note that since automated interop testing hasn't been set up for Migration and the multipath extension, we can't verify them regularly, but for the multipath extension, we have confirmed interoperability with noq, which is forked from quinn and supports the multipath, Address Discovery, and NAT-T extensions.

How to use SEERA MsQuic

It's exactly the same as using upstream MsQuic. Change the clone source to SEERA MsQuic and build following the upstream Build documentation. We'll cover how to use the Multipath and NAT-T extensions in separate articles.

We also welcome Issues, Pull Requests, and Discussions directed at SEERA MsQuic. If something is more appropriate for upstream, we'll let you know, so feel free to use it.

Next time, I plan to discuss Client Initiated Migration (including an introduction to its API).
Due to circumstances, the next article will be about a camera app using ISEKAI Link. The Client Initiated Migration topic will follow after that!

セーラ・ネットワークス株式会社では、QUICを使ったプロダクト（ISEKAI link）を開発しています。QUICの実装には色々ありますが、採用しているのはMicrosoftが開発しているMsQuicです。MsQuicを採用した理由としては、Windows、Linux、macOSという主要なプラットフォームで動作すること（macOSは公式にはbest-effortですが、実用上は問題なく動いています）、高スループット・低レイテンシーとなるように最適化されていること、MsQuicにコントリビュートしているメンバーがいて融通が利くこと、が挙げられます。

なぜforkしたか

ところがMsQuicには制約もあります。QUICは標準でMigrationに対応していますが、MsQuicのupstreamだとクライアントが経路をMigrateする動作を実装していません（クライアントがMigrateしたのに対応するサーバー側の動作は実装されています）。multipath拡張はMigration機能をベースにしていることもあり、これもMsQuicはサポートしていません。ISEKAI linkではこれらの機能を活用しているので、upstreamをそのまま使うことはできないわけです。

もっとも、upstreamにこれらの機能を取り込む努力がなされてこなかったわけではありません。弊社メンバーの一人によりPull Requestが作成され、マージのためのレビューも行われています（クライアントが経路をMigrateする動作については、PR #4218参照。Multipathについても、PR #4724参照）。しかし、コードの変更量が多い大きな変更である割に、Microsoftにとって優先度が高くないようで、レビューが順調には進まず、取り込まれるには至っていないのが現状です（Discordでのやり取りを見ると、Microsoftとしてもいずれは取り込みたいと考えているようですが）。

そこで、MsQuicをforkし、これらの機能のパッチを取り込んだブランチを作ってメンテナンスすることにしました。それがSEERA MsQuicです。出口戦略は、現時点では明確に決めているわけではありませんが、なるべくすべてupstreamに取り込んでもらうことを目指し、その目標が達成できたら畳むことを予定しています。

SEERA MsQuicの特徴

SEERA MsQuicもMITライセンスで公開しています。upstreamとの差分は次の通りです（Server Initiated Migration extensionは弊社のメンバーの一人が提案しているものです）。

• Client Initiated Migration
• Multipath extension
• Address Discovery extension
• Server Initiated Migration extension
• NAT-T extension

upstreamも活発に開発されていますので、upstreamのブランチであるmainのHEADをSEERA MsQuicのブランチであるseera-mainに1ヵ月に一度くらいの頻度でマージしています。差分は経路関係が主で、経路関係がupstreamで変更されることは多くないので、今のところそこまで苦労することなく追随できています。ちなみに、upstreamは半年〜1年ごとにリリースブランチが切られ、18ヵ月以上メンテナンスされるようになっていますが（upstreamのReleaseドキュメント参照）、今のところ、それらの各種バージョン向けにはSEERA MsQuicは作成していません。

CIについては、upstreamのものをほぼそのまま利用しています。外したのは、最新のOSでの動作チェックをするためにMicrosoft社内のリソースを利用するものだけです。また、例えば下記のような、新しい経路を追加するテストなど、これらの拡張のテストも追加しているので、そのような拡張を含め、正常に動作することが確認されています。

void
QuicTestProbePath(
    _In_ int Family,
    _In_ BOOLEAN ShareBinding,
    _In_ BOOLEAN DeferConnIDGen,
    _In_ uint32_t DropPacketCount
    )
{
    PathTestContext Context;
    CxPlatEvent PeerStreamsChanged;
    MsQuicRegistration Registration(true);
    TEST_TRUE(Registration.IsValid());

    MsQuicConfiguration ServerConfiguration(Registration, "MsQuicTest", ServerSelfSignedCredConfig);
    TEST_TRUE(ServerConfiguration.IsValid());

    if (DeferConnIDGen) {
        BOOLEAN DisableConnIdGeneration = TRUE;
        TEST_QUIC_SUCCEEDED(
            ServerConfiguration.SetParam(
                QUIC_PARAM_CONFIGURATION_CONN_ID_GENERATION_DISABLED,
                sizeof(DisableConnIdGeneration),
                &DisableConnIdGeneration));
    }

    MsQuicCredentialConfig ClientCredConfig;
    MsQuicConfiguration ClientConfiguration(Registration, "MsQuicTest", ClientCredConfig);
    TEST_TRUE(ClientConfiguration.IsValid());

    MsQuicAutoAcceptListener Listener(Registration, ServerConfiguration, PathTestContext::ConnCallback, &Context);
    TEST_QUIC_SUCCEEDED(Listener.GetInitStatus());
    QUIC_ADDRESS_FAMILY QuicAddrFamily = (Family == 4) ? QUIC_ADDRESS_FAMILY_INET : QUIC_ADDRESS_FAMILY_INET6;
    QuicAddr ServerLocalAddr(QuicAddrFamily);
    TEST_QUIC_SUCCEEDED(Listener.Start("MsQuicTest", &ServerLocalAddr.SockAddr));
    TEST_QUIC_SUCCEEDED(Listener.GetLocalAddr(ServerLocalAddr));

    MsQuicConnection Connection(Registration, CleanUpManual, ClientCallback, &PeerStreamsChanged);
    TEST_QUIC_SUCCEEDED(Connection.GetInitStatus());

    if (ShareBinding) {
        Connection.SetShareUdpBinding();
    }

    TEST_QUIC_SUCCEEDED(Connection.Start(ClientConfiguration, ServerLocalAddr.GetFamily(), QUIC_TEST_LOOPBACK_FOR_AF(ServerLocalAddr.GetFamily()), ServerLocalAddr.GetPort()));
    TEST_TRUE(Connection.HandshakeCompleteEvent.WaitTimeout(TestWaitTimeout));
    TEST_TRUE(Context.HandshakeCompleteEvent.WaitTimeout(TestWaitTimeout));
    TEST_NOT_EQUAL(nullptr, Context.Connection);

    //
    // Wait for handshake confirmation.
    //
    CxPlatSleep(100);

    QuicAddr SecondLocalAddr;
    TEST_QUIC_SUCCEEDED(Connection.GetLocalAddr(SecondLocalAddr));
    SecondLocalAddr.SetEphemeralPort();
    QuicAddr RemoteAddr;
    TEST_QUIC_SUCCEEDED(Connection.GetRemoteAddr(RemoteAddr));
    QUIC_PATH_PARAM PathParam = { &SecondLocalAddr.SockAddr, &RemoteAddr.SockAddr };
    PathProbeHelper *ProbeHelper = new(std::nothrow) PathProbeHelper(SecondLocalAddr.GetPort(), DropPacketCount, DropPacketCount);

    QUIC_STATUS Status = QUIC_STATUS_SUCCESS;
    uint32_t Try = 0;
    do {
        Status = Connection.SetParam(
            QUIC_PARAM_CONN_ADD_PATH,
            sizeof(PathParam),
            &PathParam);

        if (QUIC_FAILED(Status)) {
            delete ProbeHelper;
            SecondLocalAddr.SetEphemeralPort();
            ProbeHelper = new(std::nothrow) PathProbeHelper(SecondLocalAddr.GetPort(), DropPacketCount, DropPacketCount);
        }
    } while (QUIC_FAILED(Status) && ++Try <= 3);
    TEST_EQUAL(Status, QUIC_STATUS_SUCCESS);

    if (DeferConnIDGen) {
        BOOLEAN ReplaceExistingCids = FALSE;
        TEST_QUIC_SUCCEEDED(Context.Connection->SetParam(QUIC_PARAM_CONN_GENERATE_CONN_ID, sizeof(ReplaceExistingCids), &ReplaceExistingCids));
    }

    TEST_TRUE(ProbeHelper->ServerReceiveProbeEvent.WaitTimeout(TestWaitTimeout * 10));
    TEST_TRUE(ProbeHelper->ClientReceiveProbeEvent.WaitTimeout(TestWaitTimeout * 10));
    delete ProbeHelper;
}

なお、Migrationやmultipath拡張については自動interopが作成されていないので、定期的には確認できていませんが、multipath拡張については、quinnからforkされ、multipath拡張、Address Discovery拡張、NAT-T拡張をサポートするnoqとの間で相互運用できることを確認しています。

SEERA MsQuicの利用方法

upstreamのMsQuicと全く同じです。clone先をSEERA MsQuicに変えた上で、upstreamのBuildドキュメントに従ってビルドしてください。Multipath拡張やNAT-T拡張の利用方法はまた別記事にします。

また、SEERA MsQuic宛のIssueやPull Request、Discussionも歓迎します。upstreamの方が適切である場合にはそのように案内しますので、お気軽にご利用ください。

次回はClient Initiated Migrationの話（APIの紹介などを含む）をする予定です。
都合により、ISEKAI Linkを使ったカメラアプリの話になりました。Client Initiated Migrationの話はその次に！