Стандартная библиотека и расширения

В этом разделе описаны основные способы организации обработки входящих запросов: при помощи функций из набора Открытого пакета интеграций и при помощи функций из пользовательских расширений

Методы ОПИ (стандартный набор)

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

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

Документация ОПИ

warning

Имена библиотек указываются в форме CLI приложения. Например, telegram или gdrive (Google Drive)

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

Web консоль

Расширения

Помимо стандартного набора функций из набора ОПИ, в качестве функций-обработчиков Melezh можно использовать методы из произвольных .os скриптов. Для их корректной интерпретации должно быть соблюдено три условия:

Метод должен быть функцией, возвращающей двоичные данные, строку или сериализуемую в JSON коллекцию (массив, структуру или соответствие без несериализуемых полей)
Файл скрипта должен иметь корректное имя (без пробелов, желательно латинскими буквами), расширение .os и быть помещен в подкаталог extensions/Modules основного каталога Melezh:

Windows (стандартная установка из exe установщика):
```
C:\Program Files (x86)\OInt\share\oint\lib\melezh\extensions\Modules
```
Linux:
```
share/oint/lib/melezh/extensions/Modules
```
OneScript, в качестве OPM пакета:
```
<каталог OneScript>/lib/melezh/extensions/Modules
```
Метод должны иметь документирующий комментарий следующего вида:
```
// Отображаемое имя метода
// Описание метода
//
// Параметры:
//  Поле1 - Строка  - Значение поля 1 - field1
//  Поле2 - Строка  - Значение поля 2 - field2
//  Поле3 - Строка  - Значение поля 3 - field3
//
// Возвращаемое значение:
//  Структура Из КлючИЗначение - возвращаемое значение
```
Это - стандартный формат комментария EDT, но с тремя отличительными особенностями: второй строкой является краткое описание функции (не обязательно), у параметров есть четвертый блок описания - имя аргумента в CLI стиле, в описании параметра нельзя использовать знак - кроме как для разделения его блоков

warning
Использование - в тексте описания параметра приведет к ошибке

В стандартной поставке, в каталоге extensions/Modules есть модуль RequestsEcho.os, который может быть использован в качестве примера для создания нового расширения:

RequestsEcho.os

// Эхо полей
// Возвращает в ответе поля, отправленные в запросе
//
// Параметры:
//  Поле1 - Строка  - Значение поля 1 - field1
//  Поле2 - Строка  - Значение поля 2 - field2
//  Поле3 - Строка  - Значение поля 3 - field3
//
// Возвращаемое значение:
//  Структура Из КлючИЗначение - Эхо
Функция ЭхоПолей(Знач Поле1, Знач Поле2, Знач Поле3 = "") Экспорт
	Возврат Новый Структура("field1,field2,field3", Поле1, Поле2, Поле3);
КонецФункции

В списке выбора Web-консоли данный модуль будет отображен следующим образом

RequestsEcho

Для использования его в качестве библиотеки при работе через терминал (командную строку), в качестве опции library необходимо указать имя файла модуля без расширения

Также важно отметить, что при использовании функций-расширений, в частности для обработчиков с типом GET или POST + form-data, значения могут приходить в неподходящих типах данных. Melezh не преобразует данные в нужные типы автоматически, за исключением тех, которые могут быть явно выявлены при чтении JSON или разборе multipart/form-data (двоичные или строка)

Для приведения значений к нужным типам можно использовать самописные преобразователи или же те, которые используются в основных функциях Открытого пакета интеграций. Их можно найти в модуле OPI_ПреобразованиеТипов

important

Рекомендуется дополнительно сохранять копии модулей расширений в другом месте, так как в отдельных случаях обновления и удаления Melezh, а также при пересборке образа (если используется Docker), данные файлы могут быть удалены! Также вы можете указать любой сторонний каталог для хранения расширений при помощи настройки ext_path (рекомендуется)

`--melezhcontext`

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

Для использования данной опции, необходимо указать melezhcontext в качестве CLI-названия для любого из параметров функции в документирующем комментарии:

Пример из Static.os - одного из предустановленных расширений Melezh

// Получить файл из каталога
//
// Параметры:
//  Каталог  - Строка       - Путь к каталогу файла   - catalog
//  ИмяФайла - Строка       - Имя файла с расширением - file
//  MIME     - Строка       - MIME тип файлов         - mime
//  Контекст - HTTPКонтекст - Контекст вызова         - melezhcontext
//
// Возвращаемое значение:
//  Структура Из КлючИЗначение, ДвоичныеДанные - данные файла или информация об ошибке
Функция ПолучитьФайлИзКаталога(Знач Каталог, Знач ИмяФайла, Знач MIME, Знач Контекст) Экспорт

	Каталог = СтрЗаменить(Каталог, "\", "/");
	Каталог = ?(СтрЗаканчиваетсяНа(Каталог, "/"), Каталог, Каталог + "/");

	ПолныйПуть = Каталог + ИмяФайла;
	ФайлПути   = Новый Файл(ПолныйПуть);

	Если Не ФайлПути.Существует() Тогда

		Контекст.Ответ.КодСостояния = 404;
		Контекст.Ответ.ТипКонтента = "application/json";
		Возврат Новый Структура("result,error", Ложь, "Not Found");

	Иначе
		Контекст.Ответ.ТипКонтента = MIME;
		Возврат Новый ДвоичныеДанные(ПолныйПуть);
	КонецЕсли;

КонецФункции

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

important

При необходимости добавлять собственные расширения (с melezhcontext в частности), для разработки рекомендуется использовать OneScript версию Melezh. Это позволит запустить проект в режиме отладки (VSCode) и ставить точки останова для просмотра содержимого значений

Контекст процесса

Помимо контекста веб-сервера Kestrel, в коде расширения также доступен глобальный объект Melezh, позволяющий вызывать некоторые дополнительные функции в контексте текущего процесса Melezh:

ВызватьОбработчик(Знач Путь, Знач Параметры) - позволяет вызвать другой созданный обработчик из списка обработчиков по его ключу

// Аналогично вызову обработчика через HTTP localhost:<port>/myhandler

Результат = Melezh.ВызватьОбработчик("myhandler", Новый Структура("param1", "value1"));

ЗаписатьЗначениеВКэш(Знач Имя, Знач Значение) - записывает выбранное значение в глобальный кэш. Значение существует до перезагрузки сервера или ручного удаления
ПолучитьЗначениеИзКэша(Знач Имя) - получает значение по имени, указанному при записи
УдалитьЗначениеИзКэша(Знач Имя) - удаляет значение из кэша по имени

Методы ОПИ (стандартный набор)​

Расширения​

--melezhcontext​

Контекст процесса​

Методы ОПИ (стандартный набор)

Расширения

`--melezhcontext`

Контекст процесса