9.9 KiB
Эндпоинты внешних сервисов, с которыми взаимодействует cde-orchestration-demo
Документ описывает все HTTP/AMQP/gRPC-эндпоинты внешних сервисов, к которым обращается оркестратор (сервер cmd/http и воркеры). Это исходящие вызовы; описание API, который оркестратор предоставляет, — в openapi.yaml.
Как устроено взаимодействие
Клиенты внешних сервисов лежат в internal/adapters/http/* и internal/adapters/*. Базовые URL берутся из переменных окружения (см. CONFIGURATION.md). Для HTTP используются два клиента: Fiber client (camunda, flows, pdm, workspaces, system_log) и go-resty (workflows, sarexbackend). Аутентификация — по-разному в зависимости от сервиса (OAuth client_credentials, Bearer-токен пользователя/админа, Basic).
Базовые адреса по сервисам
| Сервис | Переменная базового адреса | Клиент | Назначение |
|---|---|---|---|
| Camunda Operate / REST | OPERATE_URL |
Fiber | Управление инстансами процессов, переменными, сообщениями |
| Camunda Keycloak | CAMUNDA_KEYCLOAK_URL |
Fiber | OAuth-токен для Operate |
| Zeebe Gateway | ZEEBE_GATEWAY |
gRPC (SDK) | Деплой BPMN, обработка job'ов воркерами |
| Auth (токены) | AUTH_HOST |
Fiber/resty | Токены пользователя/админа для flows и pdm |
| Flows | FLOWS_URL, FLOWS_INTERNAL_URL |
Fiber | Ревью, действия пользователя, обновление бандлов/документов |
| PDM | PDM_URL |
Fiber | Маркировка бандлов (клиент не подключён — см. примечание) |
| Workflows | WORKFLOWS_HOST |
resty | Создание workflow обработки PDF |
| Workspaces | WORKSPACES_URL |
Fiber | Создание рабочих областей |
| System log | SYSTEM_LOG_URL |
Fiber | Отправка системных логов |
| Sarex backend | SAREX_BACKEND_BASE_URL |
resty | Получение MRPA по id |
| Telegram Bot API | TELEGRAM_TOKEN |
tgbotapi | Алертинг воркеров |
| RabbitMQ (AMQP) | AMQP_* |
amqp091 | Маркировка бандлов (RPC), вычисление хеш-сумм |
Эндпоинты по сервисам
Camunda Operate / REST (OPERATE_URL, CAMUNDA_KEYCLOAK_URL)
internal/adapters/http/camunda/client.go. Все запросы (кроме получения токена) идут с заголовком Authorization: Bearer <access_token>.
| Метод | Путь | Назначение |
|---|---|---|
| POST | {CAMUNDA_KEYCLOAK_URL}/auth/realms/camunda-platform/protocol/openid-connect/token |
OAuth-токен (grant_type=client_credentials) |
| POST | {OPERATE_URL}/v2/process-instances |
Создать инстанс процесса |
| GET | {OPERATE_URL}/api/process-instances/{key} |
Получить инстанс процесса |
| POST | {OPERATE_URL}/v1/variables/search |
Поиск переменных процесса по имени/значению |
| GET | {OPERATE_URL}/api/process-instances/{key}/variables/{varId} |
Значение конкретной переменной |
| POST | {OPERATE_URL}/api/process-instances/{key}/variables |
Список переменных инстанса (scopeId) |
| POST | {OPERATE_URL}/v2/messages/publication |
Публикация сообщения процессу (напр. signRequest) |
Zeebe Gateway (ZEEBE_GATEWAY)
internal/adapters/zeebe. gRPC через официальный SDK camunda/zeebe/clients/go/v8. Используется для деплоя определений процессов (NewProcessDefinition) и для job-воркеров, которые слушают Service Task типа ZEEBE_WORKER_JOB_TYPE и по завершении/ошибке возвращают результат в инстанс процесса.
Auth — токены (AUTH_HOST)
Используется адаптерами flows и pdm для получения Bearer-токенов.
| Метод | Путь | Назначение |
|---|---|---|
| GET | {AUTH_HOST}/token/user/{userID}/ |
Токен от имени пользователя |
| POST | {AUTH_HOST}/token/ |
Токен админа (username/password) |
Flows (FLOWS_URL, FLOWS_INTERNAL_URL)
internal/adapters/http/flows/adapter.go. Запросы (кроме update-documents) идут с Authorization: Bearer <token>; часть операций — с ретраями (экспоненциальный backoff).
| Метод | Путь | Назначение |
|---|---|---|
| POST | {FLOWS_URL}/user-actions/ |
Добавить действие в историю |
| PATCH | {FLOWS_URL}/reviews/{reviewID}/approve/ |
Утвердить review (со статусом/комментарием) |
| PATCH | {FLOWS_URL}/reviews/{reviewID}/update-bundles/ |
Обновить бандлы review |
| PATCH | {FLOWS_INTERNAL_URL}/reviews/{reviewID}/update-documents/ |
Обновить документы review (внутренний URL, без авторизации) |
| GET | {FLOWS_URL}/reviews/{reviewID}/documents/ |
История бандлов документов review |
PDM (PDM_URL, AUTH_HOST) — не подключён
internal/adapters/http/pdm/client.go. Клиент реализован, но в текущей сборке нигде не инициализируется (см. примечание в конце). Для полноты — какие вызовы он делает:
| Метод | Путь | Назначение |
|---|---|---|
| GET | {AUTH_HOST}/token/user/{userID}/ |
Токен пользователя (Basic auth логин/пароль) |
| PUT | {PDM_URL}/bundles/{bundleID}/marks |
Проставить маркировки бандлу |
Workflows (WORKFLOWS_HOST, AUTH_HOST)
internal/adapters/http/workflows/adapter.go (resty). Используется воркером split_pdf.
| Метод | Путь | Назначение |
|---|---|---|
| POST | {WORKFLOWS_HOST}/internal/v1/companies/{companyID}/workflows |
Создать workflow обработки/оптимизации PDF |
Базовый URL resty-клиента установлен в
AUTH_HOST, а адрес workflows подставляется полным (WORKFLOWS_HOST). В параметрах задач передаётсяdjango_host = AUTH_HOST.
Workspaces (WORKSPACES_URL)
internal/adapters/http/workspaces/client.go. Используется воркерами copy/copyv2.
| Метод | Путь | Назначение |
|---|---|---|
| POST | {WORKSPACES_URL}/internal/v2/workspaces |
Создать рабочую область |
System log (SYSTEM_LOG_URL)
internal/adapters/http/system_log/client.go. Используется воркерами copy, copyv2, create_versions, create_versionsv2.
| Метод | Путь | Назначение |
|---|---|---|
| POST | {SYSTEM_LOG_URL}/api/v0/system_log |
Отправить пакет системных логов |
Sarex backend (SAREX_BACKEND_BASE_URL)
internal/adapters/sarexbackend/client.go (resty). Используется HTTP-сервером при подписи (проверка MRPA). Токены проксируются из входящего запроса (Authorization, опц. Identity).
| Метод | Путь | Назначение |
|---|---|---|
| GET | {SAREX_BACKEND_BASE_URL}/api/core/mrpa/{id}/ |
Получить MRPA по id |
Telegram Bot API (TELEGRAM_TOKEN, TELEGRAM_ALERT_GROUP_ID)
internal/adapters/http/telegram/client.go через go-telegram-bot-api. Отправка алертов в заданную группу при ошибках/паниках в задачах воркеров.
RabbitMQ / AMQP (AMQP_*)
Подключение вида amqp://{USER}:{PASSWORD}@{HOST}:{PORT}/{PATH_API}.
| Адаптер | Назначение |
|---|---|
internal/adapters/amqp/markings |
Маркировка бандла и получение его хеш-суммы (RPC поверх временной очереди, correlation_id). Используется воркерами markingsv2/copyv2 |
internal/adapters/amqp/rpc |
Общий RPC-клиент RabbitMQ (переподключение, вычисление хеш-сумм объектов) |
Обработка ошибок
Каждый адаптер проверяет StatusCode() ответа и оборачивает не-200 OK в ошибку с телом ответа (internal/errors). Отдельно у sarexbackend маппинг: 404 → ErrNotFound, 403 → ErrForbidden, прочие → generic. Адаптеры flows и pdm выполняют ретраи с экспоненциальным backoff (до 5 попыток).
Примечания
- PDM-клиент не подключён.
internal/adapters/http/pdmреализован, а переменнаяPDM_URLприсутствует в Helm-секрете, ноpdm.New(...)не вызывается ни в одном бинарнике. Раздел оставлен для полноты; при фактическом использовании актуализируйте документ. - Пути даны относительно базовых URL из окружения; итоговый URL =
<базовый адрес>+путь.