Правило модификации SIP-сообщений на границе (sipmodrule)

Описание

Правило модификации входящих и исходящих SIP-сообщений на границах системы с внешним миром. Применяется для глубокой тонкой адаптации SIP-сообщений на границах. В том числе в результате применения правила с полнотекстовой обработкой принятый пакет может быть отброшен.

Сообщения отдаются на модификацию в текстовом неразобранном виде. Поскольку применение правил модификации довольно затратно с точки зрения производительности, применение правил привязывается к конкретным экземплярам фасадных микросервисов обработки SIP сообщений (sg и esg). Для любого из них в конфигурационных параметрах задается список кодов для фильтрации правил.

С одним кодом может существовать несколько правил. Обнаруженные по кодам правила применяеются в порядке убывания приоритета (увеличения значения поля priority). Правила обрабатываются вплоть до последнего подходящего, либо процесс прерывается, если очередное подошедшее правило задает действие apply_last.

Обычный режим - использование регулярных выражений и фильтров. Для ускорения обработки можно применить функцию из кастомного erlang-модуля, загруженного с помощью патча. Для еще более глубокой кастомизации и выхода за пределы сообщения можно использовать режим модификации с помощью служебного сценария (значительно менее производительно).

Ограничения

  • Коллекция доступна только в мастер-домене.

Поля

Структура сущности
{
  "id": uuid,
  "priority": str,
  "enabled": intbool,
  "code": str,
  "dir": str,

  "mode": str,
  "mode_extension": str,

  "extractors": array of str,
  "filter": array,
  "modifiers": array of str,

  "action": str,
  "repair_contentlen": intbool,

  "opts": {
    "title": str,
    "comment": str
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}

Описание характеристик спецификации

Table 1. Поля
Спецификация Описание

Поле: id
Режим: inout
Тип: uuid
По умолчанию: generated

Идентификатор. Может быть задан при создании, иначе генерируется системой.

Поле: enabled
Режим: in
Тип: intbool
По умолчанию: 1

Выключатель правила

Поле: priority
Режим: in
Тип: int
По умолчанию: required

Приоритет. Меньшее значение означает более высокий приоритет в процессе обхода.

Поле: code
Режим: in
Тип: str
По умолчанию: required

Код группы правил, задаваемый в конфигурационных параметрах фасадных микросервисов sg и esg.
Может совпадать у нескольких правил.

Поле: dir
Режим: in
Тип: str
По умолчанию: required

Направление SIP-сообщения
Варианты значений:

  • incoming - Применяется только к входящим SIP-сообщениям.

  • outgoing - Применятся только к исходящим SIP-сообщениям.

Поле: mode
Режим: in
Тип: str
По умолчанию: "mask"

Режимы применения правил

Поле: mode_extension
Режим: in
Тип: str
По умолчанию: empty

Имя модуля или служебного сценария для режимов module и svcscript соответственно.

Поле: extractors
Режим: in
Тип: array of str
По умолчанию: []

Список строк-экстракторов. Каждая строка представляет собой команду в регулярных выражениях.
Применяется только в режиме 'mask'.

Формат: /reg/PATTERN или /reg/PATTERN/OPTS.

Варианты опций (перечисляются в произвольной последовательности в конкатенации):

  • i — поиск без учета кейса (caseless);

  • f — поиск только в первой строке (firstline);

  • m — многострочный поиск (multiline);

  • s — поиск с покрытием маркером '.' всех спецсимволов, в том числе конца строки (dotall).

Если в теле PATTERN содержится именованное выделение

(?<some_key>...)

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

Экстракторы могут и не содержать именованных групп, тогда они просто являются проверочными.

В любом случае, чтобы правило применилось, необходимо чтобы все строки-экстракторы в применении к тексту SIP-сообщения обнаружили совпадения.

Поле: filter
Режим: in
Тип: array
По умолчанию: []

Фильтр в формате REST-API, применяемый к объекту с выделенными значениями.
Применяется только в режиме 'mask'.

Если на этапе применения экстраторов правило не было проигнорировано, то к объекту-результату извлечения применяется фильтр.

Правило применяется только если фильтр возвращает true.

Поле: modifiers
Режим: in
Тип: array of str
По умолчанию: []

Список строк-модификаторов. Каждая строка представляет собой команду в регулярных выражениях.
Применяется только в режиме 'mask'.

Формат: /reg/PATTERN/REPLACEMENT или /reg/PATTERN/REPLACEMENT/OPTS.

К сообщению применяются последовательно все модификаторы. Модификаторы могут использовать в разделе REPLACEMENT специальные команды для подстановки значений из объекта-результата извлечения (например с целью перемещения значений из одного заголовка в другой). Для этого необходимо указать '{{some_key}}'.

Варианты опций (перечисляются в произвольной последовательности в конкатенации):

  • g — множественный поиск и применение (global);

  • i — поиск без учета кейса (caseless);

  • f — поиск только в первой строке (firstline);

  • m — многострочный поиск (multiline);

  • s — поиск с покрытием маркером '.' всех спецсимволов, в том числе конца строки (dotall).

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

Поле: action
Режим: in
Тип: str
По умолчанию: required

Действия при применении правила.

Поле: repair_contentlen
Режим: in
Тип: intbool
По умолчанию: 0

Если хотя бы у одного примененного правила выставлен режим, то по завершению будет автоматически пересчитано значение заголовка Content-Length.
Включать режим следует в том случае, если правило модифицирует контент, но не пересчитывает заголовок Content-Length. Либо если несколько правил модифицируют контент в целях экономии ресурсов.

Поле: opts
Режим: in
Тип: object
Составное поле

Поле: opts.title
Режим: in
Тип: str
По умолчанию: empty

Произвольный заголовок

Поле: opts.comment
Режим: in
Тип: str
По умолчанию: empty

Произвольный комментарий

Поле: ext
Режим: inout
Тип: object
Составное поле

Позволяет расширять состав произвольными ключами и значениями

Поле: ext.ct
Режим: out
Тип: date
По умолчанию: generated

Время создания объекта

Поле: ext.lwt
Режим: out
Тип: date
По умолчанию: generated

Время последней модификации объекта

Режимы применения правил

Table 2. Режимы применения правил
Значение Описание

"mask"

Стандартный режим с использованием регулярных выражений.

Алгоритм концептуально следующий:

  1. Сначала применяются регулярные выражения-экстракторы (extractors), обнаруживая и выделяя из SIP-сообщения значения. Если какой-то экстрактор не обнаружил совпадения, правило считается не подошедшим. Экстракторы могут быть просто проверочными регулярными выражениями, либо выделять значения для дальнейшего анализа в фильтре с помощью использования синтаксиса

    (?<some_key>...)

    Например:

    [
  "/reg/^(?!SIP)/f",
  "/reg/CSeq:\s*(?<cseq>\d+)\s+(?<method>[A-Z]+)/i",
  "/reg/User-Agent:\s*(?<ua>Avaya CM.*)/i",
  "/reg/Contact:.*sip:(?<cun>.+)@.*/i",
  "/reg/Contact:\\s*(?<cdn>[^<]*)<sip:.*@.*/i"
]

    проверит, что сообщение — это запрос (а не ответ), выделит из заголовка CSeq номер транзакции и название метода в поля 'cseq' и 'method' соответственно, из заголовка User-Agent — название устройства целиком в поле 'ua', если это "Avaya CM", а из первого подходящего заголовка Contact — username из URI в поле 'cun', если там содержится username, и displayname в поле 'cdn'. В результате применения всех экстракторов на базе выделенных значений формируется объект (к которому на следующем шаге применится фильтр):

    {
  "cseq": "2",
  "method": "INVITE",
  "ua": "Avaya CM/R018x.01.0.890.0",
  "cun": "91234567890",
  "cdn": " "
}

    Форматы и опции экстракторов приведены в описании параметра extractors.

  2. Выделенные значения формируют объект, к которому применяется фильтр (filter), аналогичный REST. Правило применяется только если фильтр возвращает true.

    Например:

    [
  "and",
  [
    "equals",
    ["property", "method"],
    "INVITE"
  ],
  [
    "greater",
    ["integer",["property","cseq"]],
    1
  ]
]

    проверит, что это сообщение в рамках транзакции INVITE с индексом более 1, в дополнение к предыдущему шагу, где были отфильтрованы только запросы от устройства 'Avaya CM'.

    Формат фильтра приведен в описании свойства filter.

  3. Последовательно применяются регулярные выражения-модификаторы (modifiers), которые могут использовать в том числе значения, выделенные на первом шаге экстракторами, с помощью синтаксиса

    {{some_key}}

    Полноценно доступны подстановки групп в регулярных выражениях. Hапример:

    [
  "/reg/From: ([^<]*)(<sip:)[^@]+(.*)/From: \\1\\g{2}{{cun}}\\3/g",
  "/reg/From: [^<]*(<sip:.*)/From: {{cdn}}\\g{1}/g"
]

    последовательно применит два модификатора, подставив в URI заголовка From выделенные на первом шаге значения displayname и username из подходящего заголовка Contact.

    Форматы и опции модификаторов приведены в описании параметра modifiers.

"module"

Производительный режим применения специального внешнего erlang-модуля, загруженного с помощью патча или вручную.
В поле mode_extension указывается имя модуля.

Если обнаруживается и сам модуль, и в нем функция modify_message/1 (или /2 или /3), то она вызывается с целью модификации сообщения, в противном случае правило не применяется, в лог выводится ошибка.

Функция возвращает новое сообщение, если должно быть применено действие правила и изменение сообщения, либо false, если если правило игнорируется, либо drop, если принятый пакет должен быть отброшен без обработки.

Спецификация вариантов callback-функций
-spec modify_message(Msg::binary())
   -> {ok, NewMsg::binary()} | false | drop.

-spec modify_message(Msg::binary(), Dir)
   -> {ok, NewMsg::binary()} | false | drop
   when Dir :: incoming|outgoing.

-spec modify_message(Msg::binary(), Dir, Rule::map())
   -> {ok, NewMsg::binary()} | false | drop.
   when Dir :: incoming|outgoing.

Если callback-функция возвращает новое сообщение ({ok,NewMsg}), но действие (action) в правиле задано 'drop', то сообщение отбрасывается.
Если callback-функция возвращает 'drop', то этот результат перекрывает заданное действие (action) правила и становится финальным в обработке правил.
Если callback-функция возвращает 'false', то правило пропускается.
Любой другой результат игнорируется.

"svcscript"

Тонкий режим применения специального служебного сценария, созданного в мастер-домене.
В поле mode_extension указывается код служебного сценария.

Первым параметром передается сообщение, вторым параметром направление передачи сообщения: incoming | outgoing.

(В РЕАЛИЗАЦИИ)

Действия при применении правила модификации входящего или исходящего запроса

Table 3. Действия при применении правила модификации входящего или исходящего запроса
Значение Описание

"apply_next"

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

"apply_last"

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

"drop"

Отбрасывает сообщение, прекращая его обработку, и завершает цикл обработки правил. Имеет смысл только для входящего направления и правил, не производящих модификацию.

См. также

API

Логические роли

  • sg реализует SBC (Session Border Controller) на границе с устройствами.

  • esg реализует SBC (Session Border Controller) на границе с аплинками.

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт