Perl#

Модуль позволяет писать обработчики location и переменных на Perl, а также вставлять вызовы Perl в SSI.

При сборке из исходного кода модуль не собирается по умолчанию; его необходимо включить с помощью параметра сборки ‑‑with‑http_perl_module.

В наших репозиториях модуль собран динамически и доступен отдельным пакетом angie-module-perl или angie-pro-module-perl; подключить его можно с помощью директивы load_module.

Важно

Для сборки этого модуля необходим Perl версии 5.6.1 и выше. Компилятор C должен быть совместим с тем, которым был собран Perl.

Известные проблемы#

Модуль экспериментальный, поэтому возможно все.

Для того чтобы во время переконфигурации Perl перекомпилировал измененные модули, его нужно собрать с параметрами -Dusemultiplicity=yes или -Dusethreads=yes. Кроме того, чтобы во время работы Perl терял меньше памяти, его нужно собрать с параметром -Dusemymalloc=no. Узнать значения этих параметров у уже собранного Perl можно так (в примере приведены желаемые значения параметров):

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

Необходимо учитывать, что после пересборки Perl с новыми параметрами -Dusemultiplicity=yes или -Dusethreads=yes придется также пересобрать и все бинарные модули 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__

Директивы#

perl#

Синтаксис

perl модуль :: функция | 'sub { ... }';

По умолчанию

—

Контекст

location, limit_except

Устанавливает обработчик Perl для данного location.

perl_modules#

Синтаксис

perl_modules путь;

По умолчанию

—

Контекст

http

Задает дополнительный путь для модулей Perl.

perl_require#

Синтаксис

perl_require модуль;

По умолчанию

—

Контекст

http

Задает имя модуля, который будет подгружаться при каждой переконфигурации. Директив perl_require может быть несколько.

perl_set#

Синтаксис

perl_set $переменная модуль :: функция | 'sub { ... }';

По умолчанию

—

Контекст

http

Устанавливает обработчик Perl для указанной переменной.

Вызов Perl из SSI#

Формат команды SSI с вызовом Perl следующий:

<!--# perl sub="модуль::функция" arg="параметр1" arg="параметр2" ...
-->

Методы объекта запроса $r#

$r->args#

возвращает аргументы запроса.

$r->filename#

возвращает имя файла, соответствующее URI запроса.

$r->has_request_body (обработчик)#

возвращает 0, если в запросе нет тела. Если же в запросе есть тело, то устанавливается указанный обработчик и возвращается 1. По окончании чтения тела запроса Angie вызовет установленный обработчик. Обратите внимание, что нужно передавать ссылку на функцию обработчика. Пример:

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#

разрешает использовать диапазоны байт (byte ranges) при передаче ответа.

$r->discard_request_body#

указывает Angie игнорировать тело запроса.

$r->header_in (поле)#

возвращает значение заданного поля в заголовке запроса клиента.

$r->header_only#

определяет, нужно ли передавать клиенту только заголовок ответа или весь ответ.

$r->header_out (поле, значение)#

устанавливает значение для заданного поля в заголовке ответа.

$r->internal_redirect (uri)#

делает внутреннее перенаправление на указанный uri. Перенаправление происходит уже после завершения обработчика Perl. Метод принимает экранированные URI и поддерживает перенаправления в именованные location.

$r->log_error (код_ошибки, сообщение)#

записывает указанное сообщение в error_log. Если код_ошибки ненулевой, то к сообщению будет добавлен код ошибки и ее описание.

$r->print (текст, ...)#

метод передает клиенту данные.

$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 (имя [, смещение [, длина ]])#

передает клиенту содержимое указанного файла. Необязательные параметры задают начальное смещение и длину передаваемых данных. Непосредственно передача данных происходит уже после завершения обработчика Perl.

$r->send_http_header ([тип])#

передает клиенту заголовок ответа. Необязательный параметр тип устанавливает значение поля "Content-Type" в заголовке ответа. Пустая строка в качестве типа запрещает передачу поля "Content-Type".

$r->status (код)#

устанавливает код ответа.

$r->sleep (миллисекунды, обработчик)#

устанавливает указанный обработчик и останавливает обработку запроса на заданное время. Angie в это время продолжает обрабатывать другие запросы. По истечении указанного времени Angie вызовет установленный обработчик. Обратите внимание, что нужно передавать ссылку на функцию обработчика. Для передачи данных между обработчиками следует использовать $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 (текст)#

декодирует текст, заданный в виде "%XX".

$r->uri#

возвращает URI запроса.

$r->variable (имя [, значение ])#

возвращает или устанавливает значение указанной переменной. Переменные локальны для каждого запроса.