RasGate

RasGate на GitHub

RasGate — нижний инфраструктурный слой RasEcosystem. Его задача довольно узкая: принять HTTP-запрос, запустить rac с переданными аргументами и вернуть результат выполнения.

Сам Gate не знает, что такое кластер, информационная база или сеанс с точки зрения RasEcosystem. Для него это всего лишь команды внешней утилиты. Предметная логика, работа с версиями платформы и разбор результатов находятся выше — в RasHub.

Граница ответственности

Я специально оставил RasGate довольно тонким. Он не пытается строить собственную модель инфраструктуры 1С и не дублирует задачи RasHub.

RasGate отвечает за несколько вещей:

• принимает HTTP-запросы;
• запускает настроенный исполняемый файл rac;
• передаёт ему аргументы;
• ограничивает количество одновременно работающих процессов;
• читает stdout и stderr;
• контролирует время выполнения и отмену запроса;
• возвращает результат клиенту.

При этом RasGate не выбирает нужную команду под конкретную версию платформы, не разбирает предметное содержимое вывода rac и не приводит ответы разных версий к общей модели. Если перенести такую логику в Gate, он довольно быстро начнёт превращаться во второй RasHub.

Как проходит запрос

Основной endpoint RasGate принимает массив аргументов, которые затем передаются rac.

POST /rac/execute
Content-Type: application/json
X-Api-Key: <ключ>

{
    "arguments": [
        "cluster",
        "list",
        "localhost:1545"
    ]
}

Для такого запроса RasGate не пытается понять смысл команды cluster list. Он проверяет входные данные, получает свободный исполнительный слот и запускает отдельный процесс rac.

Аргументы передаются процессу отдельно, через ProcessStartInfo.ArgumentList. Shell для запуска команды не используется.

После завершения процесса Gate возвращает код завершения, стандартный вывод, поток ошибок и длительность выполнения.

{
    "success": true,
    "data": {
        "outcome": "succeeded",
        "exitCode": 0,
        "standardOutput": "...",
        "standardError": "",
        "durationMilliseconds": 42,
        "timedOut": false
    }
}

Сам HTTP-вызов при этом может пройти успешно, даже если rac завершился с ошибкой. Результат внешней команды передаётся отдельно через outcome и exitCode.

Процессы rac

Каждый вызов POST /rac/execute запускает отдельный процесс rac. Никакого постоянно работающего процесса или соединения с RAS внутри Gate нет.

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

Поэтому Gate ограничивает число одновременно работающих процессов, параллельно читает stdout и stderr, контролирует timeout и при необходимости пытается завершить процесс вместе с его деревом.

Здесь возникает ещё одна неприятная особенность работы с внешними административными командами. Если процесс был запущен, но RasGate не получил подтверждённый результат, это не всегда означает, что операция не выполнилась. Например, команда могла успеть изменить состояние RAS до timeout.

Для такого случая у результата есть состояние unknown. Автоматически повторять изменяющую команду после него небезопасно.

Работа с версиями rac

RasGate работает с одним исполняемым файлом, путь к которому задаётся в конфигурации:

{
    "Rac": {
        "ExecutablePath": "/opt/1cv8/x86_64/rac"
    }
}

Gate не ищет установленные версии платформы и не выбирает rac автоматически для каждого запроса. Конкретный экземпляр работает с тем исполняемым файлом, который указан в настройках.

Адрес RAS в конфигурации Gate не хранится. Хост и порт передаются вызывающей стороной среди аргументов rac. Поэтому один экземпляр RasGate технически может выполнять команды для нескольких доступных ему RAS.

Доступность утилиты можно проверить через GET /rac/status. При обновлении статуса RasGate выполняет rac --version и возвращает полученную строку версии.

Сам номер версии Gate не интерпретирует. В RasEcosystem этим занимается RasHub: он знает возможности разных вариантов rac, формирует подходящие команды и разбирает их результат.

Конфигурация и развёртывание

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

Основные настройки относятся к самому сервису и механизму запуска процессов:

• путь к rac;
• timeout выполнения;
• ограничение параллельных процессов;
• ограничение объёма вывода;
• API-ключ;
• адрес, на котором слушает HTTP-сервис.

RasGate собирается как self-contained приложение для Windows и Linux, поэтому отдельная установка .NET Runtime ему не нужна. Сам rac в поставку Gate не входит.

Для Linux предусмотрен запуск через systemd. На Windows RasGate может работать как системная служба.

HTTP API

Публичный API RasGate намеренно небольшой. В нём нет отдельных контроллеров для кластеров, информационных баз или сеансов.

GET /rasgate/status

Возвращает информацию о самом экземпляре RasGate: его имя и версию.

GET /rac/status

Проверяет, можно ли запустить настроенный rac, и возвращает его версию.

POST /rac/execute

Основной endpoint. Принимает массив аргументов, запускает отдельный процесс rac и возвращает результат его выполнения.

Запуск команд защищён API-ключом. Более сложной модели пользователей и разрешений внутри Gate нет.

Ограничения

Тонкая модель RasGate упрощает его границу ответственности, но у неё есть цена.

• Каждый запрос требует запуска отдельного внешнего процесса.
• Gate остаётся зависимым от установленного rac и его совместимости с конкретной версией платформы.
• Один экземпляр RasGate работает с одним настроенным исполняемым файлом rac.
• При использовании RasGate напрямую клиенту всё равно нужно знать синтаксис команд rac и формат их вывода.
• После timeout или другой ошибки, возникшей уже после запуска процесса, результат изменяющей операции может остаться неизвестным.

Внутри RasEcosystem большую часть этих деталей принимает на себя RasHub. Если использовать Gate отдельно, они остаются ответственностью клиента.

Место RasGate в RasEcosystem

RasGate находится в самом низу прикладной части RasEcosystem. RasStudio Mono работает с API RasHub. RasHub знает предметную модель, инфраструктуру и версии платформы, а также формирует команды для нужного варианта rac. RasGate получает уже готовый вызов и занимается только его выполнением.

В результате код, который работает с кластерами, базами и другими объектами 1С, не обязан напрямую управлять консольными процессами, путями к платформе, каналами вывода и временем жизни rac.