ngx_http_perl_module

ngx_http_perl_module 모듈은 Perl로 위치 및 변수 핸들러를 구현하고, Perl 호출을 SSI에 삽입하는 데 사용합니다.

이 모듈은 기본적으로 구축되지 않으므로 –with-http_perl_module 구성 매개변수로 활성화해야 합니다.

이 모듈은 Perl 버전 5.6.1 이상이 필요합니다. C 컴파일러는 Perl을 구축하는 데 사용한 컴파일러와 호환되어야 합니다.

알려진 문제

이 모듈은 실험 단계이며, 사용하는 사람이 위험을 감수해야 합니다.

Perl이 재구성 시 수정된 모듈을 컴파일하려면 -Dusemultiplicity=yes 또는 -Dusethreads=yes 매개변수로 구축해야 합니다. 또한, 런타임에서 Perl로 인한 메모리 누수를 줄이려면 -Dusemymalloc=no 매개변수로 구축해야 합니다. 이미 구축된 Perl의 매개변수 값을 확인하려면(예시에서는 자주 사용하는 값 지정) 다음을 실행하세요.

$ perl -V:usemultiplicity -V:usemymalloc
usemultiplicity='define';
usemymalloc='n';

새로운 -Dusemultiplicity=yes, -Dusethreads=yes 매개변수로 Perl을 재구축한 다음에는 모든 바이너리 Perl 모듈도 다시 구축해야 합니다. 새로운 Perl에서는 작동이 중단되기 때문입니다.

재구성 후에 메인 프로세스와 작업자 프로세스의 용량이 늘어날 가능성이 있습니다. 메인 프로세스의 용량이 지나치게 늘어날 경우, 실행 가능한 파일을 변경하지 않고 라이브 업그레이드 절차를 적용할 수 있습니다.

Perl 모듈이 장기 실행 작업(예: 도메인 이름 분석, 다른 서버로 연결, 데이터베이스 쿼리)을 실행하는 동안, 현재 작업자 프로세스에 할당된 다른 작업은 처리되지 않습니다. 그러므로 예측 가능하고 실행 시간이 짧은 작업(예: 로컬 파일 시스템 액세스)만 실행하는 것이 좋습니다.

예제 구성

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__

Directives

Syntax:  perl module::function|'sub { ... }';
Default: —
Context: location, limit_except

특정 위치에 Perl 핸들러를 설정합니다.

Syntax:  perl_modules path;
Default: —
Context: http

Perl 모듈에 추가 경로를 설정합니다.

Syntax:  perl_require module;
Default: —
Context: http

각 재구성 시 로드할 모듈 이름을 정의합니다. 여러 perl_require 명령을 사용할 수 있습니다.

Syntax:  perl_set $variable module::function|'sub { ... }';
Default: —
Context: 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)

요청에 본문이 없으면 0을 반환합니다. 본문이 있으면 요청에 대해 특정 핸들러가 설정되고 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를 받고, 이름이 지정된 위치로의 리디렉션을 지원합니다.

$r->log_error(errno, message)

지정된 message를 error_log로 작성합니다. 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])

지정된 변수 값을 반환하거나 설정합니다. 변수는 각 요청에 로컬 상태입니다.