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 module::function|'sub { ... }';
デフォルト: -
コンテキスト: location, limit_except

指定されたlocationのPerlハンドラを設定します。

構文: perl_modules path;
デフォルト: -
コンテキスト: http

Perlモジュールのパスの追加を設定します。

構文: perl_require module;
デフォルト: -
コンテキスト: http

それぞれの再設定の間にロードされるモジュール名を定義します。複数のperl_require ディレクティブを指定できます。

構文: perl_set $variable module::function|'sub { ... }';
デフォルト: -
コンテキスト: 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])
指定された変数の値を返す、あるいは設定する。変数はリクエストごとに固有です。

TOP
inserted by FC2 system