ngx_http_perl_modules モジュール
知られていること 設定例 ディレクティブ perl perl_modules perl_require perl_set SSIからPerlを呼び出す $r リクエストオブジェクトメソッド |
ngx_http_perl_module
モジュールはPerlのlocationと変数を実装するために使われ、SSIにPerl呼び出しを挿入します。
このモジュールはデフォルトではビルドされず、--with-http_perl_module
configureパラメータを有効にする必要があります。
このモジュールはバージョン5.6.1以上のPerlを必要とします。CコンパイラはPerlをビルドしたものと互換性がある必要があります。
知られていること
このモジュールは実験的なもので、利用者責任です。
Perlが再configureの際に修正されたモジュールの再コンパイルをするためには、-Dusemultiplicity=yes
または -Dusethreads=yes
パラメータを使ってビルドする必要があります。また、Perlの実行時のメモリリークを少なくするために、-Dusemymalloc=no
パラメータを使ってビルドする必要があります。既にビルドされているPerl(例では望ましい値が指定されています)のこれらの値をチェックするには、以下を実行します:
$ perl -V:usemultiplicity -V:usemymalloc usemultiplicity='define'; usemymalloc='n';
新しく-Dusemultiplicity=yes
または -Dusethreads=yes
パラメータでPerlを再ビルトした後は、全てのバイナリのPerlモジュールを同様に再ビルドしなければならないことに注意してください - それらは新しいPerlでは動作しないでしょう。
それぞれの再configureの後で、メインプロセスとそれからworkerプロセスのサイズが大きくなる可能性があります。もしメインプロセスが許容できないサイズであれば、実行可能ファイルの変更無しにlive upgrade手順を適用することができます。
Perlモジュールが、ドメイン名の解決、他のサーバへの接続あるいはデータベースへの問い合わせのような長く実行される操作を実施している間は、現在のworkerプロセスに割り当てられている他のリクエストは処理されないでしょう。従ってローカルファイルシステムへのアクセスのような予測可能で実行時間が短い操作の実施だけがお勧めです。
設定例
http { perl_modules perl/lib; perl_require hello.pm; perl_set $msie6 ' sub { my $r = shift; my $ua = $r->header_in("User-Agent"); return "" if $ua =~ /Opera/; return "1" if $ua =~ / MSIE [6-9]\.\d+/; return ""; } '; server { location / { perl hello::handler; } }
perl/lib/hello.pm
モジュール:
package hello; use nginx; sub handler { my $r = shift; $r->send_http_header("text/html"); return OK if $r->header_only; $r->print("hello!\n<br/>"); if (-f $r->filename or -d _) { $r->print($r->uri, " exists!\n"); } return OK; } 1; __END__
ディレクティブ
構文: |
perl |
---|---|
デフォルト: | - |
コンテキスト: |
location , limit_except |
指定されたlocationのPerlハンドラを設定します。
構文: |
perl_modules |
---|---|
デフォルト: | - |
コンテキスト: |
http |
Perlモジュールのパスの追加を設定します。
構文: |
perl_require |
---|---|
デフォルト: | - |
コンテキスト: |
http |
それぞれの再設定の間にロードされるモジュール名を定義します。複数のperl_require
ディレクティブを指定できます。
構文: |
perl_set
|
---|---|
デフォルト: | - |
コンテキスト: |
http |
指定された変数のPerlハンドラをインストールします。
SSIからPerlを呼び出す
Perlを呼び出すSSIコマンドは次の書式です:
<!--# perl sub="module
::function
" arg="parameter1
" arg="parameter2
" ... -->
$r リクエストオブジェクトメソッド
$r->args
- リクエストの引数を返します。
$r->filename
- リクエストURIに対応するファイル名を返します。
-
$r->has_request_body(
handler
) -
リクエストにbodyが無い場合には0を返します。bodyがある場合は、指定されたハンドラがリクエストに設定され、1が返ります。リクエストボディを読み込んだ後に、nginxは指定されたハンドラを呼び出すでしょう。ハンドラ関数はリファレンスで渡されなければならないことに注意してください。例:
package hello; use nginx; sub handler { my $r = shift; if ($r->request_method ne "POST") { return DECLINED; } if ($r->has_request_body(\&post)) { return OK; } return HTTP_BAD_REQUEST; } sub post { my $r = shift; $r->send_http_header; $r->print("request_body: \"", $r->request_body, "\"<br/>"); $r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\n"); return OK; } 1; __END__
$r->allow_ranges
- 応答送信時にバイト範囲の使用を可能にします。
$r->discard_request_body
- nginxにリクエストボディの破棄を指示します。
$r->header_in(
field
)- 指定されたクライアントのリクエストヘッダフィールドの値を返します。
$r->header_only
- 応答全体あるいはヘッダだけのどちらかがクライアントに送信されなければならないことを決定します。
-
$r->header_out(
field
,value
) - 指定された応答ヘッダフィールドの値を設定します。
-
$r->internal_redirect(
uri
) -
指定された
uri
へ内部リダイレクトを行う。実際のリダイレクトはPerlハンドラの実行が完了した後で起こります。バージョン 1.17.2以降、メソッドはエスケープされたURIを受け付け、名前付きのlocationへのリダイレクトをサポートします。
$r->log_error(
errno
,message
)-
error_logに指定された
message
を書き込む。もしerrno
が0以外であれば、エラーコードと説明がメッセージに追加されるでしょう。 $r->print(
text
, ...)- クライアントにデータを渡す。
$r->request_body
- リクエストボディが一時ファイルに書き込まれていなければ、クライアントにそれを返す。クライアントのリクエストボディがメモリにあることを確実にするためには、そのサイズが client_max_body_sizeによって制限されている必要があり、十分なバッファサイズがclient_body_buffer_sizeで設定されていなければなりません。
$r->request_body_file
- クライアントのリクエストボディのファイル名を返す。処理が終わった後で、そのファイルは削除されるべきです。常にリクエストボディをファイルに書き込むために、 client_body_in_file_onlyが有効になっていなければなりません。
$r->request_method
- クライアントリクエストのHTTPメソッドを返す。
$r->remote_addr
- クライアントのIPアドレスを返す。
$r->flush
- 即座にクライアントにデータを送信する。
-
$r->sendfile(
name
[,offset
[,length
]]) - クライアントに指定されたファイルの内容を送信する。任意のパラメータは転送するデータの初期オフセットと長さを指定します。実際のデータの転送はPerlハンドラの実行が完了した後で起こります。
-
$r->send_http_header([
type
]) -
クライアントに応答ヘッダを送信します。任意の
type
パラメータは、"Content-Type"応答ヘッダフィールドの値を設定します。値が空文字であれば、"Content-Type"ヘッダフィールドは送信されないでしょう。 $r->status(
code
)- 応答コードを設定する。
-
$r->sleep(
milliseconds
,handler
) -
指定されたハンドラを設定し、指定された間リクエストの処理を停止します。その間、nginxは他のリクエストを処理し続けます。指定した時間が経過すると、nginxはインストールされたハンドラを呼び出すでしょう。ハンドラ関数はリファレンスで渡されなければならないことに注意してください。ハンドラ間データを渡すためには、
$r->variable()
が使用されなければなりません。例:package hello; use nginx; sub handler { my $r = shift; $r->discard_request_body; $r->variable("var", "OK"); $r->sleep(1000, \&next); return OK; } sub next { my $r = shift; $r->send_http_header; $r->print($r->variable("var")); return OK; } 1; __END__
$r->unescape(
text
)- "%XX"形式で符号化されたテキストを復号する。
$r->uri
- リクエストURIを返す。
-
$r->variable(
name
[,value
]) - 指定された変数の値を返す、あるいは設定する。変数はリクエストごとに固有です。