<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_http_perl_module"
        link="/ru/docs/http/ngx_http_perl_module.html"
        lang="ru"
        rev="8">

<section id="summary">

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

<para>
По умолчанию этот модуль не собирается, его сборку необходимо
разрешить с помощью конфигурационного параметра
<literal>--with-http_perl_module</literal>.
<note>
Для сборки этого модуля необходим
<link url="https://www.perl.org/get.html">Perl</link> версии 5.6.1 и выше.
Компилятор C должен быть совместим с тем, которым был собран Perl.
</note>
</para>

</section>


<section id="issues" name="Известные проблемы">

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

<para>
Для того чтобы во время переконфигурации Perl перекомпилировал
изменённые модули, его нужно собрать с параметрами
<literal>-Dusemultiplicity=yes</literal> или
<literal>-Dusethreads=yes</literal>.
Кроме того, чтобы во время работы Perl терял меньше памяти,
его нужно собрать с параметром
<literal>-Dusemymalloc=no</literal>.
Узнать значения этих параметров у уже собранного
Perl можно так (в примере приведены желаемые значения параметров):
<example>
$ perl -V:usemultiplicity -V:usemymalloc
usemultiplicity='define';
usemymalloc='n';
</example>
</para>

<para>
Необходимо учитывать, что после пересборки Perl с новыми параметрами
<literal>-Dusemultiplicity=yes</literal> или
<literal>-Dusethreads=yes</literal>
придётся также пересобрать и все бинарные модули Perl, так как они
просто перестанут работать с новым Perl.
</para>

<para>
Возможно, главный процесс, а вслед за ним и рабочие процессы,
будут увеличиваться в размерах при каждой переконфигурации.
Когда главный процесс вырастет до неприемлемых размеров, можно
воспользоваться процедурой
<link doc="../control.xml" id="upgrade">обновления сервера на лету</link>,
не меняя при этом сам исполняемый файл.
</para>

<para>
Если модуль Perl выполняет длительную операцию, например, определяет
адрес по имени, соединяется с другим сервером, делает запрос к базе данных,
то на это время все остальные запросы, обслуживаемые данным рабочим процессом,
не будут обрабатываться. Поэтому рекомендуется ограничиться операциями,
время исполнения которых короткое и предсказуемое, например, обращение
к локальной файловой системе.
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
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;
        }
    }
</example>
</para>

<para>
Модуль <path>perl/lib/hello.pm</path>:
<example>
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&lt;br/&gt;");

    if (-f $r->filename or -d _) {
        $r->print($r->uri, " exists!\n");
    }

    return OK;
}

1;
__END__
</example>
</para>

</section>


<section id="directives" name="Директивы">

<directive name="perl">
<syntax><value>модуль</value>::<value>функция</value>|'sub { ... }'</syntax>
<default/>
<context>location</context>
<context>limit_except</context>

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

</directive>


<directive name="perl_modules">
<syntax><value>путь</value></syntax>
<default/>
<context>http</context>

<para>
Задаёт дополнительный путь для модулей Perl.
</para>

</directive>


<directive name="perl_require">
<syntax><value>модуль</value></syntax>
<default/>
<context>http</context>

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

</directive>


<directive name="perl_set">
<syntax>
    <value>$переменная</value>
    <value>модуль</value>::<value>функция</value>|'sub { ... }'</syntax>
<default/>
<context>http</context>

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

</directive>

</section>


<section id="ssi" name="Вызов Perl из SSI">

<para>
Формат команды SSI с вызовом Perl следующий:
<example>
&lt;!--# perl sub="<value>модуль</value>::<value>функция</value>" arg="<value>параметр1</value>" arg="<value>параметр2</value>" ...
--&gt;
</example>
</para>

</section>


<section id="methods" name="Методы объекта запроса $r">

<para>
<list type="tag">

<tag-name><literal>$r->args</literal></tag-name>
<tag-desc>
возвращает аргументы запроса.
</tag-desc>

<tag-name><literal>$r->filename</literal></tag-name>
<tag-desc>
возвращает имя файла, соответствующее URI запроса.
</tag-desc>

<tag-name>
    <literal>$r->has_request_body(<value>обработчик</value>)</literal>
</tag-name>
<tag-desc>
возвращает 0, если в запросе нет тела.
Если же в запросе есть тело, то устанавливается
указанный обработчик и возвращается 1.
По окончании чтения тела запроса nginx вызовет установленный обработчик.
Обратите внимание, что нужно передавать ссылку на функцию обработчика.
Пример:
<example>
package hello;

use nginx;

sub handler {
    my $r = shift;

    if ($r->request_method ne "POST") {
        return DECLINED;
    }

    if ($r->has_request_body(<emphasis>\&amp;post</emphasis>)) {
        return OK;
    }

    return HTTP_BAD_REQUEST;
}

sub <emphasis>post</emphasis> {
    my $r = shift;

    $r->send_http_header;

    $r->print("request_body: \"", $r->request_body, "\"&lt;br/&gt;");
    $r->print("request_body_file: \"", $r->request_body_file, "\"&lt;br/&gt;\n");

    return OK;
}

1;

__END__
</example>
</tag-desc>

<tag-name><literal>$r->allow_ranges</literal></tag-name>
<tag-desc>
разрешает использовать диапазоны байт (byte ranges) при передаче ответа.
</tag-desc>

<tag-name><literal>$r->discard_request_body</literal></tag-name>
<tag-desc>
указывает nginx игнорировать тело запроса.
</tag-desc>

<tag-name><literal>$r->header_in(<value>поле</value>)</literal></tag-name>
<tag-desc>
возвращает значение заданного поля в заголовке запроса клиента.
</tag-desc>

<tag-name><literal>$r->header_only</literal></tag-name>
<tag-desc>
определяет, нужно ли передавать клиенту только заголовок ответа или весь ответ.
</tag-desc>

<tag-name>
    <literal>$r->header_out(<value>поле</value>,
    <value>значение</value>)</literal>
</tag-name>
<tag-desc>
устанавливает значение для заданного поля в заголовке ответа.
</tag-desc>

<tag-name id="r_internal_redirect">
    <literal>$r->internal_redirect(<value>uri</value>)</literal>
</tag-name>
<tag-desc>
делает внутреннее перенаправление на указанный <value>uri</value>.
Перенаправление происходит уже после завершения обработчика Perl.
<note>
Начиная с версии 1.17.2 метод принимает экранированные URI и
поддерживает перенаправления в именованные location.
</note>
</tag-desc>

<tag-name><literal>$r->log_error(<value>код_ошибки</value>,
<value>сообщение</value>)</literal></tag-name>
<tag-desc>
записывает указанное <value>сообщение</value> в
<link doc="../ngx_core_module.xml" id="error_log"/>
на уровне <literal>error</literal>.
Если <value>код_ошибки</value> ненулевой, то к сообщению будет добавлен
код ошибки и её описание.
</tag-desc>

<tag-name><literal>$r->print(<value>текст</value>, ...)</literal></tag-name>
<tag-desc>
метод передаёт клиенту данные.
</tag-desc>

<tag-name><literal>$r->request_body</literal></tag-name>
<tag-desc>
возвращает тело запроса клиента при условии,
что тело не записано во временный файл.
Для того чтобы тело запроса клиента гарантированно находилось в памяти,
нужно ограничить его размер с помощью
<link doc="ngx_http_core_module.xml" id="client_max_body_size"/>
и задать достаточной размер для буфера
<link doc="ngx_http_core_module.xml" id="client_body_buffer_size"/>.
</tag-desc>

<tag-name><literal>$r->request_body_file</literal></tag-name>
<tag-desc>
возвращает имя файла, в котором хранится тело запроса клиента.
По завершению обработки файл необходимо удалить.
Для того чтобы тело запроса клиента всегда записывалось в файл,
следует включить
<link doc="ngx_http_core_module.xml" id="client_body_in_file_only"/>.
</tag-desc>

<tag-name><literal>$r->request_method</literal></tag-name>
<tag-desc>
возвращает HTTP-метод запроса клиента.
</tag-desc>

<tag-name><literal>$r->remote_addr</literal></tag-name>
<tag-desc>
возвращает IP-адрес клиента.
</tag-desc>

<tag-name><literal>$r->flush</literal></tag-name>
<tag-desc>
немедленно передаёт данные клиенту.
</tag-desc>

<tag-name>
    <literal>$r->sendfile(<value>имя</value>[,
    <value>смещение</value>[,
    <value>длина</value>]])</literal>
</tag-name>
<tag-desc>
передаёт клиенту содержимое указанного файла.
Необязательные параметры
задают начальное смещение и длину передаваемых данных.
Непосредственно передача данных происходит уже после завершения
обработчика Perl.
</tag-desc>

<tag-name>
    <literal>$r->send_http_header([<value>тип</value>])</literal>
</tag-name>
<tag-desc>
передаёт клиенту заголовок ответа.
Необязательный параметр <value>тип</value> устанавливает значение поля
<header>Content-Type</header> в заголовке ответа.
Пустая строка в качестве типа запрещает передачу поля
<header>Content-Type</header>.
</tag-desc>

<tag-name><literal>$r->status(<value>код</value>)</literal></tag-name>
<tag-desc>
устанавливает код ответа.
</tag-desc>

<tag-name>
    <literal>$r->sleep(<value>миллисекунды</value>,
    <value>обработчик</value>)</literal>
</tag-name>
<tag-desc>
устанавливает указанный обработчик
и останавливает обработку запроса на заданное время.
nginx в это время продолжает обрабатывать другие запросы.
По истечении указанного времени nginx вызовет установленный обработчик.
Обратите внимание, что нужно передавать ссылку на функцию обработчика.
Для передачи данных между обработчиками следует использовать
<literal>$r->variable()</literal>.
Пример:
<example>
package hello;

use nginx;

sub handler {
    my $r = shift;

    $r->discard_request_body;
    $r->variable("var", "OK");
    $r->sleep(1000, <emphasis>\&amp;next</emphasis>);

    return OK;
}

sub <emphasis>next</emphasis> {
    my $r = shift;

    $r->send_http_header;
    $r->print($r->variable("var"));

    return OK;
}

1;

__END__
</example>
</tag-desc>

<tag-name><literal>$r->unescape(<value>текст</value>)</literal></tag-name>
<tag-desc>
декодирует текст, заданный в виде “%XX”.
</tag-desc>

<tag-name><literal>$r->uri</literal></tag-name>
<tag-desc>
возвращает URI запроса.
</tag-desc>

<tag-name>
    <literal>$r->variable(<value>имя</value>[,
    <value>значение</value>])</literal>
</tag-name>
<tag-desc>
возвращает или устанавливает значение указанной переменной.
Переменные локальны для каждого запроса.
</tag-desc>

</list>
</para>

</section>

</module>