Módulo HTTP Perl#

Este módulo permite escribir manejadores de ubicación y variables en Perl, así como insertar llamadas Perl en SSI.

Este módulo se compila dinámicamente y está disponible como un paquete separado llamado angie-module-perl o angie-pro-module-perl; se puede cargar mediante la directiva load_module.

Nota

Este módulo requiere Perl versión 5.6.1 o superior. El compilador C debe ser compatible con el utilizado para compilar Perl.

Problemas conocidos#

El módulo es experimental, así que cualquier cosa es posible.

Para que Perl recompilie los módulos modificados durante la reconfiguración, debe ser compilado con los parámetros -Dusemultiplicity=yes o -Dusethreads=yes. Además, para que Perl pierda menos memoria en tiempo de ejecución, debe compilarse con el parámetro -Dusemymalloc=no. Para comprobar los valores de estos parámetros en un Perl ya compilado (los valores preferidos se especifican en el ejemplo), ejecute:

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

Tenga en cuenta que después de reconstruir Perl con los nuevos parámetros -Dusemultiplicity=yes o -Dusethreads=yes, todos los módulos binarios de Perl tendrán que ser reconstruidos también — simplemente dejarán de funcionar con el nuevo Perl.

Existe la posibilidad de que el proceso principal y luego los procesos de trabajo crezcan en tamaño después de cada reconfiguración. Si el proceso principal crece hasta un tamaño inaceptable, se puede aplicar el procedimiento de actualización en vivo sin cambiar el archivo ejecutable.

Mientras el módulo Perl está realizando una operación de larga duración, como resolver un nombre de dominio, conectarse a otro servidor o consultar una base de datos, otras solicitudes asignadas al proceso de trabajo actual no se procesarán. Por lo tanto, se recomienda realizar solo operaciones que tengan un tiempo de ejecución predecible y corto, como acceder al sistema de archivos local.

Ejemplo de configuración#

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;
        }
    }

El módulo 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__

Directivas#

perl#

Syntax

perl module :: function | 'sub { ... }';

Predeterminado

—

Context

location, limit_except

Establece un manejador Perl para la ubicación dada.

perl_modules#

Syntax

perl_modules path;

Predeterminado

—

Context

http

Establece una ruta adicional para los módulos Perl.

perl_require#

Syntax

perl_require module;

Predeterminado

—

Context

http

Define el nombre de un módulo que se cargará durante cada reconfiguración. Pueden estar presentes varias directivas perl_require.

perl_set#

Syntax

perl_set $variable module :: function | 'sub { ... }';

Predeterminado

—

Context

http

Establece un manejador Perl para la variable especificada.

Llamando a Perl desde SSI#

Un comando SSI que llama a Perl tiene el siguiente formato:

<!--# perl sub="module::function" arg="parameter1" arg="parameter2" ...
-->

Los Métodos del Objeto de Solicitud $r#

$r->args#

Devuelve los argumentos de la solicitud.

$r->filename#

Devuelve un nombre de archivo correspondiente al URI de la solicitud.

$r->has_request_body (handler)#

Devuelve 0 si no hay cuerpo en una solicitud. Si hay un cuerpo, el manejador especificado se establece para la solicitud y se devuelve 1. Después de leer el cuerpo de la solicitud, Angie llamará al manejador especificado. Tenga en cuenta que la función del manejador debe pasarse por referencia. Ejemplo:

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#

Permite el uso de rangos de bytes al enviar respuestas.

$r->discard_request_body#

Indica a Angie que descarte el cuerpo de la solicitud.

$r->header_in (field)#

Devuelve el valor del campo de cabecera de solicitud especificado.

$r->header_only#

Determina si se debe enviar al cliente la respuesta completa o solo su cabecera.

$r->header_out (field, value)#

Establece un valor para el campo de cabecera de respuesta especificado. El valor especial undef elimina el campo de encabezado.

$r->internal_redirect (uri)#

Realiza una redirección interna a un URI especificado. La redirección real ocurre después de que se complete la ejecución del manejador Perl. El método acepta URIs codificadas y admite redirecciones a ubicaciones con nombre.

$r->log_error (errno, message)#

Escribe el mensaje especificado en el error_log. Si errno no es cero, se añadirá al mensaje un código de error y su descripción.

$r->print (text, ...)#

Envía datos al cliente.

$r->request_body#

Devuelve el cuerpo de la solicitud del cliente si no se ha escrito en un archivo temporal. Para asegurar que el cuerpo de la solicitud del cliente esté en memoria, su tamaño debe estar limitado por client_max_body_size, y se debe establecer un tamaño de búfer suficiente mediante client_body_buffer_size.

$r->request_body_file#

Devuelve el nombre del archivo con el cuerpo de la solicitud del cliente. Después del procesamiento, el archivo debe ser eliminado. Para escribir siempre el cuerpo de la solicitud en un archivo, se debe habilitar client_body_in_file_only.

$r->request_method#

Devuelve el método HTTP de la solicitud del cliente.

$r->remote_addr#

Devuelve la dirección IP del cliente.

$r->flush#

Envía datos inmediatamente al cliente.

$r->sendfile (name [, offset [, length ]])#

Envía el contenido del archivo especificado al cliente. Los parámetros opcionales especifican el desplazamiento inicial y la longitud de los datos a transmitir. La transmisión real de los datos ocurre después de que el manejador de Perl haya completado.

$r->send_http_header ([type])#

Envía la cabecera de respuesta al cliente. El parámetro opcional type establece el valor del campo de cabecera de respuesta Content-Type. Si el valor es una cadena vacía, el campo de cabecera Content-Type no se enviará.

$r->status (code)#

Establece un código de respuesta.

$r->sleep (milliseconds, handler)#

Establece el temporizador y detiene el procesamiento de la solicitud durante el tiempo especificado. Mientras tanto, Angie continúa procesando otras solicitudes. Después de que transcurra el tiempo especificado, Angie llamará al manejador instalado. Tenga en cuenta que la función del manejador debe pasarse por referencia. Para pasar datos entre manejadores, se debe utilizar $r‑>variable(). Ejemplo:

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)#

Decodifica un texto codificado en el formato "%XX".

$r->uri#

Devuelve un URI de solicitud.

$r->variable (name [, value ])#

Devuelve o establece el valor de la variable especificada. Las variables son locales para cada solicitud.