Skip to main content

Сервис SysProcesses

Сервис для асинхронного выполнения фоновых процессов бизнес-логики. Процессы могут быть инициированы через API или автоматически путём вставки записей в служебную таблицу sysprocesses.sysprocesses.

Конфигурация: SysProcesses.disableCheck – если true, автоматическая проверка очереди процессов отключается (полезно для отладки).

Основные возможности:

  • Автоматический запуск процессов, ожидающих выполнения в таблице sysprocesses.sysprocesses.
  • Поддержка очередей (QUEUE): внутри одной очереди процессы выполняются строго последовательно.
  • Отложенный запуск по полю START_AT.
  • Ограничение количества одновременно выполняющихся процессов (maxProcessses, по умолчанию 1).
  • Сохранение результатов или ошибок в БД.
  • API для добавления, удаления и просмотра процессов.
  • Оповещение о завершении/ошибке через события onProcessCompleted и onProcessError.

Сервис поддерживает три типа процессов:

  • csp - вызов сервисов
  • db - выполнение хранимых процедур в БД с транзакцией ()
  • sql - выполнение произвольного SQL-кода ()

Методы

addProcess

Добавляет новый процесс в очередь.

Параметры:

  • session – объект сессии пользователя (обязательно, для записи user_id).
  • type – тип процесса ('csp', 'db', 'sql').
  • name – имя процесса:
    • для csp – строка вида 'ServiceName.requestName'.
    • для db – полное имя хранимой функции (например, 'PKG_VOCAB.INSERT_VALUE').
    • для sql – произвольное описание (сам код передаётся в sourceCode).
  • params – объект с параметрами (для csp и db). При вызове сервиса (csp) параметры будут переданы в запрос, а также будет добавлено поле session с userId.
  • sourceCode – SQL-код для типа sql.
  • queue – имя очереди (строковый идентификатор). Процессы в одной очереди выполняются последовательно.
  • startAt – время отложенного запуска в формате ISO.
  • keep – если true, запись о процессе не удаляется автоматически после завершения. Полезно для отслеживания выполнения процесса.

Возвращает: идентификатор созданного процесса (id).

Пример:

const id = await gsvc.sendRequest('addProcess', {
  session: { userId: 123, isAdmin: true },
  type: 'csp',
  name: 'ReportService.generate',
  params: { date: '2026-01-01' },
  queue: 'reports',
  keep: true
}, log);

delProcess

Удаляет процесс по идентификатору. Запрещено удалять выполняющийся в данный момент процесс.

Нужно только для процессов соданых с keep: true

Параметры:

  • session – сессия (обязательно).
  • id – ID процесса.

Права доступа: администратор или владелец процесса (совпадение user_id).

Ошибки:

  • NOT_AUTHORIZED – отсутствует сессия.
  • PROCESS_IS_RUNNING – процесс выполняется.
  • PROCESS_NOT_FOUND – процесс не найден.
  • FORBIDDEN – недостаточно прав.

Пример:

await gsvc.sendRequest('delProcess', {
  session: { userId: 123 },
  id: 42
}, log);

list

Возвращает список процессов с информацией о статусе.

Параметры:

  • session – обязателен.

Права: администратор видит все процессы, обычный пользователь – только свои (user_id совпадает с session.userId).

Возвращаемый формат:

[
  {
    "ID": 1,
    "TYPE": "csp",
    "NAME": "ReportService.generate",
    "USER_ID": 123,
    "QUEUE": "reports",
    "START_AT": null,
    "STARTED": "2026-06-22T10:00:00",
    "COMPLETED": null,
    "ERROR_TEXT": null,
    "STATUS": "running",
    "INFO": { ... }
  }
]

Поле STATUS может принимать значения:

  • 'waiting' – ожидает запуска.
  • 'running' – выполняется в данный момент.
  • 'completed' – успешно завершён.
  • 'failed' – завершён с ошибкой.

Для выполняющихся процессов в INFO попадают данные, возвращаемые методом getInfo() конкретного обработчика (например, идентификатор транзакции).

checkList

Инструмент отладки. Принудительно проверяет таблицу процессов и запускает все ожидающие (с учётом очередей и лимитов).

Требует прав администратора.

Пример:

await gsvc.sendRequest('checkList', {}, log);

События

  • onProcessCompleted – возникает при успешном завершении процесса. Параметры обработчика: { process, result }.
  • onProcessError – возникает при ошибке. Параметры: { process, errorText }.

Внутреннее устройство

Сервис использует два механизма для обнаружения новых процессов:

  1. Таймер checkTimer – периодически (каждые 60 секунд) вызывает checkList().
  2. Подписка на уведомления PostgreSQL через клиент PgNotify. При вставке новой записи в таблицу sysprocesses.sysprocesses (через триггер в БД) отправляется уведомление new_sysprocess, которое мгновенно активирует проверку очереди.

При запуске сервиса (start()) выполняется первоначальная проверка очереди, затем запускается таймер и оформляется подписка на канал new_sysprocess. При остановке (stop()) подписка снимается.

Примечания

  • Максимальное число одновременно выполняющихся процессов задаётся жёстко (maxProcessses = 1). При необходимости изменения можно унаследовать сервис и переопределить это свойство.
  • Автоматическое удаление записи после завершения можно отключить флагом keep: true при добавлении процесса.
Back to top