Netty 4.2のJPMS設計を読む：codec分割とネイティブ transport の境界

この README の対象：Netty 4.2 の JPMS 対応

この README は Netty の主要ドキュメントではない。testsuite-jpms ディレクトリに属し、Java Platform Module System（JPMS）上での Netty の振る舞いという一点を扱う。リポジトリメタデータは Netty をイベント駆動・非同期のネットワークアプリケーションフレームワークと説明しているが、この README はフレームワークのコア API、性能、一般的な使い方は説明しない。明示されているのは、4.2 以降で Netty が明示モジュールを提供し、4.1 で使われていた名前付き自動モジュールを置き換えること、そして本文がユーザーガイドと開発者ガイドの二部構成であることだ。

Netty 4.2 の明示モジュール名

Netty 4.2 はモジュール名を逆 DNS 形式で宣言しており、名前はルートパッケージではなくサブプロジェクト名から来ている。README はこれを歴史的な理由によるものとしている。一覧には io.netty.buffer、io.netty.codec、io.netty.handler、io.netty.transport、io.netty.resolver、io.netty.common と、多くの codec 専用モジュールが含まれる。ネイティブトランスポートでは native が Java の予約語のため省略され、transport には epoll、kqueue、io_uring が使える。README は Netty が強いカプセル化を使わず、すべての Java パッケージをエクスポートすると明言している。また、netty-transport-rxtx、netty-transport-sctp、netty-transport-udt の一部 Maven モジュールは JPMS をサポートしなくなったとも記している。

io-netty-codec の分割

Netty 4.2 では io-netty-codec Maven モジュールが 4 つに分割されている。io-netty-codec-base は io.netty.codec Java モジュールを宣言し、io.netty.handler.codec パッケージと、追加依存の不要な組み込み codec を含む。io-netty-codec-compression、io-netty-codec-protobuf、io-netty-codec-marshalling はそれぞれ独自の Java モジュールを宣言し、サードパーティライブラリに依存する。後方互換のため従来の io-netty-codec Maven モジュールは 4 つすべてに依存するので、これに依存すると compression、protobuf、marshalling も引き込まれる。不要なら除外するか、io-netty-codec-base に直接依存できる。このモジュールは jlink のようなモジュール化 jar を期待するツールに合わせるため、空の io.netty.codec.unused JPMS モジュールも宣言している。

ネイティブライブラリは実行時専用モジュールに分離される

ネイティブトランスポート、HTTP/3、OpenSSL の対応は同じパターンを取る。io.netty.transport.classes.epoll や io.netty.tcnative.classes.openssl のような classes モジュールは EpollServerSocketChannel などの Java クラスを含み、必須だ。名前の中に os.name と os.arch を含む別のモジュール（例：io.netty.transport.${transport}.${os.name}.${os.arch}）はネイティブライブラリを保持し、実行時に存在すればよい。README は、OS とアーキテクチャが変わるため、classes モジュールに依存し、ネイティブモジュールは実行時に追加することを推奨している。圧縮モジュールはアルゴリズムを実際に使うときにだけ必要になる。

サードパーティ依存関係と JPMS の状態

README は Netty モジュールが依存するサードパーティライブラリの表を示している。jar が module-info.class 記述子を提供する場合は explicit（明示）、名前付き自動モジュールの場合は automatic（自動）、省略可能な依存は optional（任意）と分類される。例えば io.netty.common は commons-logging、log4j、log4j2、slf4j のいずれも使え、すべて明示かつ任意である。io.netty.codec.protobuf は Google Protobuf と protobuf.nano を自動モジュールとして必要とし、この依存は任意ではない。この表が情報の唯一の出典であり、README はこれらの依存が保守されているか、安全であるかについては評価していない。

アプリケーションイメージとサンプルサーバー

jlink ツールはアプリケーションイメージを作成でき、Netty はこれをサポートしているが、依存が明示モジュールでなければならないという制限がある。testsuite-jpms モジュールには、ネイティブトランスポートと OpenSSL を統合した単純な HTTP サーバーが含まれ、Apache Maven JLink プラグインでビルドされる。README は生成されたイメージの実行コマンドとして ./target/maven-jlink/default/bin/java -m io.netty.testsuite_jpms.main/io.netty.testsuite_jpms.main.HttpHelloWorldServer の形を示している。サーバーはトランスポートクラスとブートレイヤーのモジュールを出力し、ポート、トランスポート（nio、kqueue、epoll、io_uring）、SSL プロバイダ、HTTP/3 のオプションを受け付ける。各オプションの完全なコマンド例は README に記載されている。

開発者ガイド：モジュールをきれいに保つ

開発者ガイドは JPMS に詳しくない Netty 貢献者を対象としている。新しい Java パッケージは分割パッケージを作るべきではないとされ、つまりそのパッケージを別の Netty モジュールで使ってはならない。これを強制するツールは今のところなく、レビューは開発者に依存している。新しい外部依存は可能なら明示モジュールを使うべきで、自動モジュールは依存を任意（requires static）にするか、新しい Maven モジュールを導入することで許容できる。プロジェクトで唯一の META-INF サービス利用は ChannelInitializerExtension で、module-info.yml 記述子に宣言されている。testsuite-jpms はクラスパスなしのモジュール実行環境でテストを実行し、Surefire 設定の classpathDependencyExcludes で jar を除外する。ネイティブライブラリのリソースはパッケージ構造の外、例えば META-INF/native/libnetty_quiche42_osx_aarch_64.jnilib に置かれるため、ネイティブライブラリモジュールはエクスポート不要で、コンパイル時に存在する必要もない。

提供された資料が述べていないこと

README はベンチマーク、ユーザー数、セキュリティ保証、本番結果を確立しておらず、本稿もそれらを追加しない。リポジトリメタデータは Apache-2.0 の SPDX 識別子を記録しているが、このレビューのために提供されたライセンス抜粋にはライセンス文面が含まれておらず、Apache-2.0 が何を許諾するのかをここで説明することはできない。完全な評価に必要な事実、例えば特定の OS 上の特定ネイティブトランスポートの挙動や、挙げられたサードパーティ依存の保守状況は README に書かれておらず、別途確認が必要だ。

編集部の結論

JPMSでNetty 4.2を組み込みたいJava開発者には、モジュール名とcodec分割を確認できる資料です。4.1互換やネイティブ transport の実機挙動を先に確かめる必要がある人は、testsuite-jpmsのjlink例を対象環境で再現してください。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes