=head1 Russian doc for L<Nginx::ReadBody>

=encoding utf-8

=head1 Languages

Английский: L<Nginx::ReadBody>

Русский: L<Nginx::ReadBody::Russian>

=head1 NAME

Nginx::ReadBody - Модуль для встроенного perl web-сервера nginx, позволяющий "заглянуть" в тело запроса

I<Версия 0.04>

=head1 SYNOPSIS

  #nginx.conf (part of)
  location /post_here {
   error_page 345 = @get_there;
   error_page 346 = @good_post;
   error_page 347 = @bad_post;

   if ($request_method != POST)
    { return 345; }

   set $read_body_debug  1;
   set $read_body_check  'My::Own::check_userdata';
   set $read_body_done   346;
   set $read_body_nodata 347;
   set $read_body_false  347;

   perl  Nginx::ReadBody::read;
   }

=head1 DESCRIPTION

В nginx нет средств, позволяющих принимать решения об обработке запроса на основании информации, содержащейся в его теле.
Этот модуль добавляет такие средства.

=head1 Методы C<Nginx::ReadBody>

=over 4

=item C<read($request);>

Предназначен быть обработчиком того location, с телами запросов в который надо работать.

=item C<handler($request, $variableName, $defaultValue, $debug)>

Метод извлекает из внутренних структур модуля обработчик, соответствующий содержимому C<$variableName>.
Если необходимо, обработчик сначала создается. Не используется, как обработчик location, но вызывается из таковых.

Возвращает указатель на функцию, определенную в C<$variableName> (или C<$defaultValue>).

Функция создается на основе содержимого C<$variableName> (см. ниже) с помощью C<eval>, результат кешируется для повышения производительности.

Параметры метода:

=over 8

=item C<$request>

Обект запроса, предоставляемый nginx (см. L<http://wiki.nginx.org/NginxEmbeddedPerlModule>).

=item C<$variableName>

Имя переменной, определенной в C<nginx.conf> и содержащей описание функции-обработчика.

Варианты описания функции:

=over 12

=item Числовой код

Превращается в ссылку на тривиальный метод, возвращающий этот код. Вот так:

    $handler = eval "sub { return $variableValue; }";

=item Имя функции

Например, C<My::Own::method>.

Превращается в ссылку на указанную функцию. Вот так:

    $handler = eval "\\&$variableValue";

=item Описание функции perl

Примерно такое: C<"sub {...}">.

Превращается в ссылку на скомпилированную описанную функцию. Вот так:

    $handler = eval $variableValue;

B<Я вообще не тестировал этот вариант!>
И сам я им пользоваться никогда не буду - содержимое C<$variableName> С<eval>ится прямо во время выполнения, и к чему это может привести, если в нем будут ошибки - я не знаю.

=back

Если содержимое C<$variableName> не соответствет ни одному из трех вариантов,
или если компиляция содержимого в ссылку на функцию по каким-либо причинам не удалась -
возвращается ссылка на функцию, просто возвращающую код C<500>.

=item C<$defaultValue>

Этот параметр используется вместо содержимого переменной, имя которой указано в C<$variableName>, если она не определена или пределена как пустая строка.

=item C<$debug>

Определяет уровень логирования. См. L<$read_body_debug>.

=back

=item C<variable($request, $variableName, $defaultValue, $debug)>

Умный - ну, не совсем тупой - извлекатель переменных, определенных в конфигурации C<nginx>. Не используется, как обработчик location, но вызывается из таковых.

Параметры:

=over 8

=item C<$request>

Обект запроса, предоставляемый nginx (см. L<http://wiki.nginx.org/NginxEmbeddedPerlModule>).

=item C<$variableName>

Имя переменно, содержимое которой надо вернуть.

=item C<$defaultValue>

Значение, возвращаемое, если переменная не определена или определена как пустая строка. Может быть неопределенным (C<undef>).

Если переменная не определена, а это значение определено - переменная устанавливливается в это значение. И, таким образом, становится определенной на протяжении последующей обработки запроса.

=item C<$debug>

Определяет уровень логирования. См. L<$read_body_debug>.

=back

=back

=head1 Переменные конфигурационного файла C<nginx.conf>, определяюще поведение модуля

=over 4

=item C<$read_body_debug>

Определяет, должны ли отладочные сообщения быть записаны в error.log.

Возможные значения:

=over 8

=item Число C<0> или пустая строка

B<Значение по умолчанию>. Сообщения не записываются в error.log.

=item Положительное число, например C<1> или непустая строка

Отладочные сообщения записываются со всеми подробностями.

=item Специальное значение C<'0 but true'> или отрицательное число

Отладочные сообщения записываются, но некоторые подробности опускаются.

=back

=item C<$read_body_nodata>

Ссодержит описание функции (см. C<handler>).

Значение по умолчанию: C<400>.

Обработчик C<read()> вызывает эту функцию, если переданный ему запрос не содержит тела.

Функция вызывается с одним параметром: объектом запроса (см. L<http://wiki.nginx.org/NginxEmbeddedPerlModule>).

Поведение функции должно быть таким, как если бы она предназначалась быть обработчиком location.

=item C<$read_body_check>

Содержит описание функции (см. C<handler>).

Значение по умолчанию: C<'0 but true'>. Это означает, что, если эта переменная не определена,
запрос будет направлен в функцию, определенную в C<$read_body_done>.

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

Функция вызывается с одним параметром: объектом запроса (см. L<http://wiki.nginx.org/NginxEmbeddedPerlModule>).

Вернуть фунция должна C<TRUE> или C<FALSE> (истинное или ложное значение).

=item C<$read_body_done>

Содержит описание функции (см. C<handler>).

Значение по умолчанию: C<500>. Это означает, что, если эта переменная не определена, клиенту уйдет код ошибки 500. Это чтобы администратор сразу заметил, что он забыл определить эту переменную.

Запрос передается этой функции, если C<$read_body_check> вернет C<TRUE>.

Функция вызывается с одним параметром: объектом запроса (см. L<http://wiki.nginx.org/NginxEmbeddedPerlModule>).

Поведение функции должно быть таким, как если бы она предназначалась быть обработчиком location.

=item C<$read_body_false>

Содержит описание функции (см. C<handler>).

Значение по умолчанию: C<400>.

Запрос передается этой функции, если C<$read_body_check> вернет C<FALSE>.

Функция вызывается с одним параметром: объектом запроса (см. L<http://wiki.nginx.org/NginxEmbeddedPerlModule>).

Поведение функции должно быть таким, как если бы она предназначалась быть обработчиком location.

=back

=head2 EXPORT

Не экспортирует ничего.

=head1 SEE ALSO

L<http://wiki.nginx.org/NginxEmbeddedPerlModule>.

=head1 AUTHOR

Даниил Подольский, E<lt>tpaba@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2010 by Daniel Podolsky

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.4 or,
at your option, any later version of Perl 5 you may have available.

=cut
