Plugin Development Introduction

この章ではプラグインの設計と書き方の基礎について説明します。この章を読むことは下記の理解の手助けになるでしょう。

• 非同期イベントモード。 Traffic Server 全体で用いられる設計パラダイムです。プラグインもこの設計に従っていなければなりません。これは Traffic Server がプラグインを "起こして" 処理を実行するコールバックメカニズムを含みます。
• HTTP ステートマシンの概要を伴う Traffic Server の HTTP 処理
• プラグインがフックを入れて、 Traffic Server の HTTP 処理を変更 / 拡張する方法
• Traffic Server API により提供される機能の概要を伴う Roadmap

Roadmap

This chapter has provided an overview of Traffic Server's HTTP processing, API hooks, and the asynchronous event model. Next, you must understand the capabilities of Traffic Server API functions. These are quite broad:

• HTTP header manipulation functions

  Obtain information about and manipulate HTTP headers, URLs, & MIME headers.

• HTTP transaction functions

  Get information about and modify HTTP transactions (for example: get the client IP associated to the transaction; get the server IP; get parent proxy information)

• IO functions

  Manipulate vconnections (virtual connections, used for network and disk I/O)

• Network connection functions

  Open connections to remote servers.

• Statistics functions

  Define and compute statistics for your plugin's activity.

• Traffic Server management functions

  Obtain values for Traffic Server configuration and statistics variables.

Below are some guidelines for creating a plugin:

1. Decide what you want your plugin to do, based on the capabilities of the API and Traffic Server. The two kinds of example plugins provided with this SDK are HTTP-based (includes header-based and response transform plugins), and non-HTTP-based (a protocol plugin). These examples are discussed in the following chapters.
2. Determine where your plugin needs to hook on to Traffic Server's HTTP processing (view the HTTP トランザクションの状態遷移図.
3. Read Header-Based Plugin Examples to learn the basics of writing plugins: creating continuations and setting up hooks. If you want to write a plugin that transforms data, then read HTTP Transformations.
4. Figure out what parts of the Traffic Server API you need to use and then read about the details of those APIs in this manual's reference chapters.
5. Compile and load your plugin (see はじめに.
6. Depending on your plugin's functionality, you might start testing it by issuing requests by hand and checking for the desired behavior in Traffic Server log files. See the *Traffic Server Administrator's Guide* for information about Traffic Server logs.

Asynchronous Event Model

Traffic Server はマルチスレッドで動作するプロセスです。サーバがマルチスレッドを使用する主な理由は二つあります。

• 複数 CPU と複数 I/O デバイスが使用可能な平行性の利点を得るため
• 同時に大量のクライアントコネクションを持つことによる平行性を管理するため。例として、OS にスレッドの切り替えを制御させることでコネクション毎に一つのスレッドを作成できます。

Traffic Server は最初の理由の為に複数スレッドを使用します。しかしながら数千の同時コネクションを処理する際に効率が悪くなるため、 Traffic Server はトランザクション処理毎の OS スレッドの分離を行いません。

代わりに、効率的な処理のスケジューリングのために Traffic Server は特殊なイベント駆動メカニズム、イベントシステムと継続を提供します。 イベントシステム はスレッド上で行われる処理のスケジューリングに使用されます。 継続 は待機点に到達するまで幾つかの処理を実行可能な、受動的なイベント駆動ステートマシンです。これは更なる処理を行うのに適した状態の通知を受け取るまでスリープします。例として、 HTTP ステートマシン（ HTTP トランザクションを処理するもの）は継続として実装されます。

継続オブジェクトは Traffic Server 全体で使用されます。その幾つかは Traffic Server プロセスが実行中ずっと生存する可能性がありますが、他のものは特定の要求に合わせて（おそらくは他の継続によって）生成され、その後破棄されます。 Traffic Server 内部構造 （下記）は Traffic Server の主要なコンポーネントがどのように影響し合うのかを示しています。 Traffic Server は、キャッシュやネットワーク I/O タスクを統合する キャッシュプロセッサー と ネットプロセッサー のような幾つかの プロセッサー を持ちます。プロセッサーはイベントシステムと対話し、スレッド上の作業をスケジュールします。実行スレッドは継続にイベントを送信することで継続をコールバックします。継続がイベントを受信した際、起動し、幾つかの処理を行い、自身を破棄するか再び眠り次のイベントを待ちます。

Traffic Server の内部構造

Traffic Server 内部構造

プラグインは一般的に継続として実装されます。（ hello-world を除く）プラグインのサンプルコードの全ては Traffic Server 起動時に作成される継続です。それらはその後、活動するきっかけとなるイベントを待ちます。

プラグインと Traffic Server

プラグインと Traffic Server

プラグインは特定のイベントが発生する度に毎回呼び出される、たった一つの静的な継続から成立する可能性があります。このようなプラグインの例として blacklist-1.c、 basic-auth.c そして redirect-1.c があります。あるいは、プラグインは必要に応じ他の継続を動的に作成する可能性があります。トランスフォームプラグインはこの方法で作られています。静的な親継続は全トランザクションが変換可能でないか確認するためにチェックを行い、トランザクションが変換可能な際は静的な継続は vconnection と呼ばれる継続の型を作成します。 vconnection は変換が完了するまで生存し続け、その後破棄されます。この設計は全てのサンプルのトランスフォームプラグインに見られます。新しいプロトコルのサポートを行うプラグインも、このアーキテクチャを持ちます。静的な継続はやって来るクライアントコネクションを listen し、その後各プロトコルのトランザクションを処理するため、トランザクションステートマシンを作成します。

プラグインを書く際、継続にイベントを送信する方法は幾つか存在します。 HTTP プラグインについては、 HTTP ステートマシンが必要に応じてプラグインを起こす呼び出しを送信することを可能にする "フック" のメカニズムが存在します。加えて、幾つかの Traffic Server API 関数、 TSContCall、 TSVConnRead、 TSCacheWrite そして TSMgmtUpdateRegister は Traffic Server サブプロセスがプラグインにイベントを送信するきっかけとなります。

Naming Conventions

Traffic Server HTTP ステートマシン

Traffic Server は高度な HTTP キャッシュとプロキシを行います。重要な特徴としてオルタネイトとドキュメントのフレッシュネスのチェック、フィルタリング、階層的キャッシュのサポート、そしてホスティングを含みます。 Traffic Server は同時に数千のクライアントリクエストを処理し、各リクエストは HTTP ステートマシンにより処理されます。これらのマシンは Traffic Server の機能をサポートするために要求される状態の全てを含む、複雑な状態遷移図に従います。 Traffic Server API は、プラグインとの関連を選択されたこれらの状態のサブセットへのフックを提供します。 HTTP トランザクションの状態遷移図 でAPI フックと関係する HTTP 状態が見られます。

この節（の下）の例ではプラグインの典型的な介入と Traffic Server の HTTP トランザクション処理の拡張方法について説明します。 Traffic Server の処理へのフックに関する完全な詳細は Hooks and Transactions にあります。

HTTP トランザクション

HTTP トランザクションはウェブドキュメントに対するクライアントリクエストと Traffic Server のレスポンスから成立します。レスポンスは要求されたウェブサーバーのコンテンツになるかも知れないし、エラーメッセージになるかも知れません。コンテンツは Traffic Server のキャッシュから配信されるかも知れませんし Traffic Server がオリジンサーバーから取得するであろうものから配信されるかも知れません。以下の図は典型的なトランザクション、特にコンテンツがキャッシュから配信される際のシナリオにおける幾つかの状態を示したものです。

簡略化された HTTP トランザクション

簡略化された HTTP トランザクション

上の図において、 Traffic Server はクライアントコネクションを accept し、リクエストヘッダーを読込み、オリジンサーバの IP アドレスをルックアップし、キャッシュ上でリクエストされたコンテンツを検索します。キャッシュにコンテンツがない場合（ "ミス" ）、 Traffic Server はオリジンサーバへのコネクションを open し、コンテンツのリクエストを発行します。キャッシュにコンテンツがある場合（ "ヒット" ）、 Traffic Server はフレッシュネスをチェックします。

If the content is fresh, then Traffic Server sends a reply header to the client. If the content is stale, then Traffic Server opens a connection to the origin server and requests the content. The figure above, 簡略化された HTTP トランザクション, does not show behavior in the event of an error. If there is an error at a any stage, then the HTTP state machine jumps to the "send reply header" state and sends a reply. If the reply is an error, then the transaction closes. If the reply is not an error, then Traffic Server first sends the response content before it closes the transaction.

API フックと状態の関係

リストの状態に対応した API フック

プラグインを開始するトリガーとしてフックを使用できます。フックの名前はちょうど完了した Traffic Server 状態を示します。例えば、 "OS DNS lookup" フックはオリジンサーバの DNS ルックアップの直 後 にプラグインが動作します。 リクエストされたオリジンサーバの IP アドレスを要求するプラグインのため、このフックは使用するのが正しいです。ブラックリストプラグインは下図の ブラックリストプラグイン で示す通り、この方法で動作します。

ブラックリストプラグイン

ブラックリストプラグイン

Traffic Server はオリジンサーバの DNS ルックアップの直後にブラックリストプラグインを呼び出します。このプラグインはリクエストされたホストをブラックリストに載ったサーバのリストと照合します。リクエストが許可される場合、トランザクションは進みます。ホストが許可されない場合、ブラックリストプラグインはトランザクションをエラー状態に送ります。 HTTP ステートマシンが "send reply header" 状態を取得した際、ブラックリストプラグインはクライアントへ送信するエラーメッセージを提供する為に呼び出します。

フックのタイプ

The Blacklist plugin's hook to the origin server DNS lookup state is a global hook, meaning that the plugin is called every time there's an HTTP transaction with a DNS lookup event. The plugin's hook to the send reply header state is a transaction hook, meaning that this hook is only invoked for specified transactions (in the ブラックリストプラグイン example, it's only used for requests to blacklisted servers). Several examples of setting up hooks are provided in Header-Based Plugin Examples and HTTP Transformations.

フィルタリング、ベーシック認証、リダイレクトを行うような ヘッダー操作プラグイン は通常 DNS ルックアップやリクエストヘッダの読込みの状態へのグローバルフックを持ちます。この先トランザクションに対して特定のアクションが実行される必要がある場合、プラグインは自身をトランザクションフックに追加します。 トランスフォームプラグイン は全トランザクションが、変換のために特別に使用されるトランザクションフックのタイプである トランスフォームフック により変換可能か確認するために、グローバルフックを必要とします。