chore(proxy-contur): preserve legacy Contour compatibility service

2026-07-16 02:24:31 +03:00
parent 7b55d887bc
commit fedaf24098
6 changed files with 1113 additions and 0 deletions
@@ -0,0 +1,123 @@
+# proxy-contur
+
+Прокси-сервис для тендерного контура (Synology upstream).
+
+> **Legacy Cesium note.** Контурные endpoints этого сервиса остаются
+> поддерживаемым назначением. Его `/proxy/cesium/fetch` сохраняется только как
+> историческая совместимость и не является production-маршрутом Foundry Map.
+> Канонический Cesium egress: `Map Gateway → dc-amd-proxy → dc-amd-connector →
+> Windows VPN`; см. `services/dc-amd-proxy/OPERATIONS.md`.
+
+## Назначение
+
+Сервис принимает запросы от локального backend NodeDC и делает внешний трафик:
+
+1. Поиск тендеров (Contour search).
+2. Карточка закупки (Contour purchases).
+3. Fetch документов по `url` с stream passthrough (без base64).
+4. Ограниченный VPN egress для Platform Map Gateway / Cesium.
+
+## Endpoints
+
+1. `GET /healthz`
+2. `POST /proxy/contour/search`
+3. `GET /proxy/contour/purchases/:purchaseId`
+4. `GET /proxy/contour/limit-groups`
+5. `GET /proxy/fetch?url=<encoded-url>`
+6. `GET /proxy/cesium/fetch?url=<encoded-url>`
+
+## Auth
+
+Если задан `PROXY_TOKEN`, требуется:
+
+1. `x-proxy-token: <token>`  
+или
+2. `Authorization: Bearer <token>`
+
+## Contour API key
+
+Рекомендуемый режим:
+
+1. Задать `CONTOUR_API_KEY` в `.env` на стороне `proxy-contur`.
+2. После этого ключ Контура не нужно передавать в каждом запросе.
+
+Совместимость:
+
+1. Если `CONTOUR_API_KEY` не задан, сервис возьмёт ключ из запроса (`x-kontur-apikey` / query / body), как раньше.
+
+## Security
+
+По умолчанию включено:
+
+1. Только `http/https`.
+2. Блок private/local/loopback сетей.
+3. Проверка каждого redirect.
+4. Лимиты timeout/size/redirect count.
+
+`/proxy/cesium/fetch` дополнительно принимает только канонические hosts
+Cesium Ion и Bing, проверяет каждый redirect и не допускает произвольные
+outbound headers. Внутренние `x-nodedc-cesium-authorization` и
+`x-nodedc-map-referer` передаёт только Map Gateway через закрытую сеть
+`nodedc-map-egress`; в логах query credentials маскируются.
+
+## Quick Start
+
+```bash
+cd proxy-contur
+cp .env.example .env
+npm install
+npm run start
+```
+
+## Docker Compose Start
+
+```bash
+cd proxy-contur
+cp .env.example .env
+docker compose up -d --build
+```
+
+Проверка:
+
+```bash
+docker compose ps
+curl -sS http://172.22.0.222:8787/healthz | jq
+```
+
+Остановка:
+
+```bash
+docker compose down
+```
+
+## Пример запросов
+
+Проверка:
+
+```bash
+curl -sS http://172.22.0.222:8787/healthz | jq
+```
+
+Contour search:
+
+```bash
+curl -sS -X POST "http://172.22.0.222:8787/proxy/contour/search" \
+  -H "x-proxy-token: change-me" \
+  -H "content-type: application/json" \
+  -d '{"PageNumber":0,"PageSize":50}' | jq
+```
+
+Contour purchase:
+
+```bash
+curl -sS "http://172.22.0.222:8787/proxy/contour/purchases/12345" \
+  -H "x-proxy-token: change-me" | jq
+```
+
+Fetch file stream:
+
+```bash
+curl -L -o out.bin \
+  "http://172.22.0.222:8787/proxy/fetch?url=https%3A%2F%2Fexample.com%2Ffile.pdf" \
+  -H "x-proxy-token: change-me"
+```