Модуль ngx_http_perl_module

• Известные проблемы
• Пример конфигурации
• Директивы
• perl
• perl_modules
• perl_require
• perl_set
• Вызов Perl из SSI
• Методы объекта запроса $r

Модуль 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';

Обратите внимание, что после перекомпиляции 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.

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

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

Вызов Perl из SSI

Команда SSI, вызывающая Perl, имеет следующий формат:

<!--# 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 отлично от нуля, к сообщению будет добавлено код ошибки и его описание.

$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])

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