Кастомизация Angie (njs, Lua, Perl) / Habr

Сервер Angie вобрал в себя всю функциональность, которая десятилетиями формировалась в Nginx. Кроме того, разработчики за несколько лет добавили еще несколько модулей и расширили возможности существующих. Тем не менее, при реализации сложных задач может потребоваться индивидуальное решение, нестандартное поведение сервера и кастомизированная конфигурация. В таких задачах полезно использовать модули для расширения функциональности сервера на базе различных языков программирования: доступны njs, Lua и Perl.

Навигация по циклу

Видеоверсия

Для вашего удобства подготовлена видеоверсия этой статьи, доступна на Rutube, VKVideo и YouTube.

Модуль Perl

Начнём с классического модуля Perl, вносящего динамику в конфигурацию Angie. На всякий случай: документация предупреждает нас об экспериментальном статусе модуля. Он появился на ранних этапах развития Nginx и до сих пор поставляется в комплекте с Angie. Хотя сегодня язык Perl не пользуется большой популярностью у разработчиков, он имеет ряд преимуществ. Во‑первых, интерпретатор Perl входит в комплект большинства дистрибутивов Linux, то есть обладает высокой совместимостью. Также, язык обладает очень высокой стабильностью с точки зрения синтаксиса. Если вы найдёте решение, написанное лет 20 назад, практически всегда оно будет работать на современной версии интерпретатора.

Использовать модуль Perl можно для нескольких задач:

определение внутренних переменных Angie;
подключение полноценных обработчиков запросов;
использование при включении Perl‑скриптов в SSI.

Модуль Perl работает только в контексте HTTP. Установка и подключение модуля стандартны:

apt install angie-module-perl

Подключение (в контексте main):

load_module modules/ngx_http_perl_module.so;

Рассмотрим несложный пример определения переменных. Задача следующая: конвертировать URI запросов в нижний регистр. Например, /Uri -> /uri, /URI -> /uri, /TeSt -> /test.

Для решения задачи настроим переменную с изменённым URI через подпрограмму Perl:

http {
  perl_set $my_uri_to_lowercase 'sub {
    my $r = shift;
    my $uri = $r->uri;
    $uri = lc($uri);
    return $uri;
  }';
}

В директиве perl_set мы создаём переменную $my_uri_to_lowercase, которая будет содержать новый URI запроса. Для этого мы заносим в Perl‑переменную $uri исходный URI запроса и применяем к нему функцию lc — перевод в нижний регистр. Результат работы функции присваивается Angie‑переменной $my_uri_to_lowercase.

Использование новой переменной можно реализовать следующим образом: создаём локацию с для URI с символами в верхнем регистре и возвращаем редирект на новый URI из переменной:

server {
  location ~ [A-Z] {
    return 301 $scheme://$host$my_uri_to_lowercase;
  }
}

На этом наша задача решена. Если требуется менять регистр не для всех запросов, локацию можно сделать вложенной.

Для реализации более сложных сценариев наверняка пот��ебуется подключить дополнительные модули Perl (из CPAN). Сделать это можно директивой perl_require. Рассмотрим пример с подключением модуля и установкой обработчика запроса. Конфигурация Angie:

http {
    perl_modules perl/lib;
    perl_require hello.pm;

    server {
        location / {
            perl hello::handler;
        }
    } 
}

Здесь указывается директория для поиска Perl‑модулей (perl_modules) и подключается модуль hello.pm. В серверном блоке для локации определяется обработчик hello::handler — вызов функции handler из модуля hello.pm.

Код модуля Perl для обработчика (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__

Основная часть модуля — функция обработчика запроса (handler). Она выводит текст «hello!» и в случае наличия файла или директории, совпадающих с URI, добавляет «$uri exists!».

Важно понимать, что Perl‑модуль работает в синхронном режиме, поэтому во время исполнения кода рабочий процесс не может обрабатывать другие запросы. По этой причине не рекомендуется реализовывать таким образом длительные операции с непредсказуемым временем ответа.

Модуль Lua

Сторонние модули позволяют использовать популярный скриптовый язык Lua в Angie. Мы рассмотрим базовые возможности модуля lua из комплекта фреймворка OpenResty.

При подключении модуля lua также необходим модуль NDK. Установка:

apt install angie-module-lua

Подключение модулей:

load_module modules/ndk_http_module.so;
load_module modules/ngx_http_lua_module.so;

Для примера использования модуля будем использовать задачу записи тела запроса (request body) в лог-файл. Для этого определим соответствующий формат лога и дополнительную переменную:

http {
  log_format bodylog '$remote_addr - $remote_user [$time_local] '
      '"$request" $status $body_bytes_sent '
      '"$http_referer" "$http_user_agent" $request_time '
      '<"$request_body" >"$resp_body"';
  lua_need_request_body on;

  body_filter_by_lua '
    local resp_body = string.sub(ngx.arg[1], 1, 1000)
    ngx.ctx.buffered = (ngx.ctx.buffered or "") .. resp_body
    if ngx.arg[2] then
      ngx.var.resp_body = ngx.ctx.buffered
    end
  ';

  server {
    listen 80;
    set $resp_body "";
    access_log  /var/log/nginx/server.log bodylog;
  }
}

Этот код добавляет специальный формат лога и устанавливает директиву lua_need_request_body on, чтобы у Lua был доступ к телу запроса. Далее добавлен обработчик для тела запроса на Lua, задача которого — заполнить переменную в Angie ($resp_body). В данном примере размер ограничен 1000 байтами. Сама переменная объявляется на уровне блока сервера, и там же используется кастомный access_log.

В отличие от модуля Perl, Lua можно использовать как в контексте HTTP, так и в Stream. Кроме того, Lua позволяет создавать неблокирующий код для доступа к внешним системам. В общем, возможности модуля Lua широки и охватывают практически все аспекты работы с запросом и ответом в Angie.

Модуль NJS

Наконец, мы добрались до модуля NJS. Пожалуй, это самый естественный способ расширения функциональности для Angie. Дело в том, что NJS — подмножество языка JavaScript, специально адаптированное для использования в Nginx (а значит, и в Angie). Создание модуля NJS было обусловлено необходимостью создания гибких конфигураций сервера и нестандартных сценариев обработки запросов.

Модуль NJS поддерживает работу как в контексте HTTP, так и в Stream. Установка модуля стандартна:

apt install angie-module-lua

Подключение модуля, как обычно, производится в контексте main (существуют отдельные модули для http и stream):

load_module modules/ngx_http_js_module.so;
load_module modules/ngx_stream_js_module.so;

Для примера возьмём задачу перевода тела ответа в нижний регистр. Будем использовать код примеров из репозитория. Клонируем репозиторий в директорию /etc/angie:

cd /etc/angie
git clone https://github.com/nginx/njs-examples.git

В конфигурации сервера подключим файлы скриптов и обработчик NJS.

http {
  js_path "/etc/angie/njs-examples/njs/";
  js_import main from http/response/to_lower_case.js;

  server {
        listen 80;
        location / {
            js_body_filter main.to_lower_case;
            proxy_pass http://localhost:8080;
        }
  }

  server {
        listen 8080;
        location / {
            return 200 'Hello World';
        }
  }
}

Директива js_path определяет директорию для поиска файлов njs-скриптов. Далее мы импортируем файл скрипта по относительному пути (код мы получили из репозитория).

Первый блок server (80 порт) отвечает за основную точку входа в наше импровизированное приложение. При этом в корневой локации подключён обработчик js_body_filter. Он будет вызывать функцию to_lower_case из файла to_lower_case.js для обработки тела ответа. Код скрипта максимально лаконичен:

function to_lower_case(r, data, flags) {
    r.sendBuffer(data.toLowerCase(), flags);
}
export default {to_lower_case};

По сути, скрипт приводит к нижнему регистру любые входящие данные.

Второй блок server (8080) выступает бэкендом и отвечает на любой запрос фразой «Hello World».

При проверке такой конфигурации увидим эффект:

curl localhost
hello world

Возможности работы с запросами, ответами и заголовками здесь очень широкие. Для быстрого старта можно начать с примеров в эталонном репозитории модуля.

Итоги

Возможности Angie можно расширять за счет стандартных и сторонних модулей на базе ряда языков программирования. С помощью программной обработки можно преобразовывать заголовки, модифицировать ответ или запрос, создать собственную систему аутентификации. Наиболее близким по задумке к Angie является модуль NJS, так как он создавался специально для расширения возможностей сервера разработчиками Nginx. То есть, NJS в какой‑то степени позволяет создавать динамические модули для сервера без необходимости работать c внутренностями сервера Angie на языке C.

Следующая статья цикла: Запуск CGI-скриптов в Angie.