Implements the Phase 2 hook from the previous commit. With this in
place, UserDisplayService.find chains:
hot cache → DB (user_display_cache) → Keycloak Admin API
so any realm user resolves on first display, even if they never made
an authenticated request to ordinis. The resolved entry is persisted
via UserDisplayService.upsert with source=KEYCLOAK_ON_DEMAND, so the
next render of the same sub hits the DB tier (~ms) instead of going
back to Keycloak.
Implementation notes:
- Spring RestClient (modern blocking HTTP, replaces RestTemplate).
- client_credentials grant against
{issuer}/realms/{realm}/protocol/openid-connect/token. Token cached
in-memory minus a 30s safety margin from `expires_in`.
- 401 on user lookup wipes the cached token and surfaces a
RuntimeException, so the next resolve refetches.
- 404 on user lookup → Optional.empty (definitive miss, sub not in
realm). UserDisplayService logs and the caller falls back to short
UUID. Negative cache TTL not implemented — added complexity not
justified for the current realm size (~50 users).
- Bean activated only when ordinis.keycloak.admin.enabled=true AND
the env vars are set. Default disabled — UserDisplayService treats
KeycloakUserResolver as @Autowired(required = false), so a
deployment without Keycloak admin creds keeps the previous behavior
(DB cache only) instead of crashing on startup.
Application config:
- ORDINIS_KEYCLOAK_ADMIN_ENABLED (false by default)
- ORDINIS_KEYCLOAK_ADMIN_URL e.g. https://auth.nstart.space
- ORDINIS_KEYCLOAK_ADMIN_REALM defaults to nstart
- ORDINIS_KEYCLOAK_ADMIN_CLIENT_ID via vault (see docs-internal/keycloak-admin-setup.md)
- ORDINIS_KEYCLOAK_ADMIN_CLIENT_SECRET via vault
Setup runbook (docs-internal/keycloak-admin-setup.md) covers:
- creating the Keycloak service-account client + assigning view-users
- writing the secret into both vault instances (different per env)
- wiring vault.hashicorp.com agent-inject annotations into the chart
- verification steps + common failure modes
Phase 3 (scheduled bulk sync) is documented at the end of the runbook
but deferred — depends on observed cache miss rate after this lands.
Phase 1d enforcement в DraftService.approve()/.reject() требует
realm role 'ordinis:record:reviewer'. Test fixtures используют
JwtTestSupport.signJwt() — добавляем role в JWT для reviewer'ов.
Changes в ApprovalWorkflowE2ETest:
- Новый helper reviewerTokenFor(subject) — internal scope + record:reviewer
- 4 reviewer call sites (bob/dave/julia/leo) → reviewerTokenFor()
- eve-solo (selfApproveBlocked test) тоже → reviewerTokenFor() чтобы
достичь self-approve check, иначе forbidden_role срабатывает раньше
Maker callsites (alice/carol/frank/ivan/kate) остаются на tokenFor()
без reviewer role — backend гейтит только approve/reject методы.
Fix для 4 failures в pipeline 6898:
- happyFlow_submitApprove_recordLiveAndOutboxEvent
- rejectFlow_keepsDraft_noLiveRecord
- selfApproveBlocked_409
- rejectWithoutComment_400
Failed pipeline 6805: /swagger-ui/index.html в test profile вернул 200
(springdoc enabled по умолчанию через ORDINIS_SWAGGER_UI_ENABLED default
true). Это валидно — Swagger render'ит реальную UI page.
Замена: проверяем generic non-API typo path который точно не имеет
controller'а и не SPA-route'д. Покрывает тот же NoResourceFoundException
branch handler'а независимо от springdoc env config.
GlobalExceptionHandler catch-all Exception → 500 ловил NoResourceFoundException
и NoHandlerFoundException. Симптомы на prod:
- /swagger-ui/index.html при disabled springdoc возвращал 500 (UI всё равно
не рендерился, но spring логировал 'Unhandled exception' на каждый запрос —
спамил alerting и затруднял поиск настоящих ошибок).
- GET /api/v1/typo от integrator'ов давал 500 вместо 404, осложняло
debugging без traceId-correlation.
- Любой stale frontend bundle с переименованным endpoint мог триггерить
false-positive incident alerts.
Fix: explicit @ExceptionHandler для обоих exception типов → 404 not_found.
Логирование DEBUG (не WARN/ERROR) — это ожидаемый 404, не аномалия.
Test: SmokeE2ETest.unknownPath_returns404WithNotFoundCode покрывает оба пути
(/api/v1/* и /swagger-ui/*) → 404 + body.code='not_found'.
OpenApiConfig:
- Добавлена OAuth2 security scheme (authorization_code flow с Keycloak
realm `nstart`). Auth/token URLs из ordinis.openapi.oauth.issuer-uri
configuration property (default: auth.nstart.space/realms/nstart).
- BearerAuth scheme сохранён secondary — для pre-issued tokens из CI/scripts.
- Servers list переупорядочен — prod первый, staging второй.
- Description обновлён с pointer на /docs/ для full integration guide.
application.yml:
- springdoc.swagger-ui.oauth: client-id (env override), use-pkce-with-
authorization-code-grant=true. Public client `ordinis-swagger`
настраивается отдельно в Keycloak — see keycloak-setup-swagger-client.md
в ordinis-infra repo.
- ORDINIS_OPENAPI_OAUTH_ISSUER_URI env var для override realm на разных
окружениях.
docs/integration/api/read-endpoints.md:
- Swagger UI section обновлён: акцент на Authorize button + Keycloak
PKCE login (no client_secret needed), tip про bearerAuth fallback.
docs/index.md:
- Добавлен tab "Я хочу пощупать API" с link на Swagger UI.
После deploy:
- https://ordinis.k8s.264.nstart.cloud/swagger-ui.html — Swagger UI
- https://ordinis.k8s.264.nstart.cloud/v3/api-docs — OpenAPI spec
Authorize → выбрать oauth2 → Keycloak login (PKCE) → Try it out с JWT.
Покрытие resolveGeometry() в DictionaryRecordService через REST API
(MockMvc + Postgres testcontainer с PostGIS):
- lat/lon → POINT(lon lat) с SRID 4326 (Москва 55.75, 37.62)
- latitude/longitude alias → тот же flow (СПб 59.93, 30.31)
- lat/lng alias → то же (Токио 35.68, 139.65)
- explicit geometryWkt приоритет над data.lat/lon
- out-of-range lat (200) / lon (300) → silent skip, geometry == null
- no lat/lon → geometry == null
Закрепляет недавнюю работу (commit 9214ee9) после которой Liquibase
0015 backfill заработал на staging. AOI spatial filter теперь работает
на ground_station и similar dictionaries автоматически — этот тест
гарантирует что регрессий не будет.
Прогон: 20/20 e2e (было 14, +6).
Fix CI flakiness: тест больше не полагается на @Scheduled тики каждые
200ms. NoSchedulingConfig подменяет TaskScheduler на no-op stub —
@Scheduled методы регистрируются, но никогда не запускаются. Тест
вручную дёргает dispatcher.matchTick() / sendTick() — synchronous,
deterministic, нет race с background threads.
Что изменилось:
- @Disabled убран
- Inject WebhookDispatcher, manual matchTick + sendTick после setup
- Await timeouts: 60s → 5s (manual ticks → нет 200ms scheduler delay)
- Pool=4 / send-interval-ms / match-interval-ms убраны (не нужны)
- Send-timeout-ms 1000 → 2000 (с запасом, но scheduler не работает)
- @AutoConfigureMockMvc сохранён, port=RANDOM_PORT, allowed-hosts тот же
Side-fix: @Autowired на Spring constructor WebhookTestPingService
(добавлен ранее package-private constructor для unit-тестов сделал
выбор конструктора неоднозначным; Spring 6 strict — требует
explicit @Autowired когда есть >1 candidate).
Локально: 2/2 PASSED 1.85s (было 9.9s — 5× быстрее).
CI: 14 e2e всех тестов passed (Smoke, OutboxKafka, Auth, Bitemporal,
Webhook).
Третий timeout подряд: pool=4 + send-timeout=1s + cleanup @BeforeEach
+ truncate outbox не помогли. ConditionTimeout 60s × 2 теста.
Локально 2/2 PASS за 9.9s — значит логика работает. CI runner
медленнее + race conditions между:
- Spring @Scheduled threads (даже pool=4)
- WebhookDispatcher @PostConstruct (фаерится при context init)
- Postgres testcontainer reuse (leftover deliveries из предыдущих CI runs)
- Наш @BeforeEach cleanup (происходит ПОСЛЕ context init)
Логика покрыта 26 unit tests (HmacSigner + SsrfGuard + DispatcherMatch +
DeliveryLifecycle). E2e только sanity на full pipeline — ROI не
оправдывает дальнейших попыток.
Re-enable варианты на будущее:
1. Dedicated CI runner с warm Docker images (отдельная инфра)
2. testcontainer без reuse (slower CI, но reliable state)
3. @Sql(executionPhase = BEFORE_TEST_CLASS) — cleanup ДО Spring context init,
до того как dispatcher @PostConstruct запустится с leftover state
4. Манульно invoke matchTick/sendTick без @Scheduled — deterministic
Предыдущий cleanup-fix не помог CI: ConditionTimeout 60s × 2 теста.
Trace показал WebhookDispatcher initialized + ZERO sendTick/matchTick
лог lines после этого. Spring @Scheduled default pool size = 1; если
sendTick блокируется на HTTP timeout (5s) к dead leftover URL —
matchTick тоже не запускается до конца HTTP send.
CI Postgres testcontainer withReuse(true) тащит leftover deliveries
из предыдущих runs. Их слишком много чтобы fail'ить за 60s с pool=1.
Фикс комбо:
- spring.task.scheduling.pool.size=4 — matchTick/sendTick параллельно,
один blocked на dead URL не стопает другие
- ordinis.webhook.send-timeout-ms=1000 — leftover dead URLs fail'ят
за 1с вместо 5с (5x faster cleanup)
- truncate outbox_events дополнительно — matchTick не порождает
delivery rows на старые события
Локально 2/2 passed за 9.9s. Race-warnings про FK violation
(matchTick видит cached subscription но row deleted в @BeforeEach) —
noise, тест проходит.
CI fail: ConditionTimeout 60s в recordCreate_dispatchedToWebhookReceiver.
Logs показали 'Webhook sendTick: 2 due deliveries' через 1с после
boot — dispatcher грузился leftover'ами из предыдущего CI run
(Postgres testcontainer с withReuse=true сохраняет данные между
запусками). Старые subscriptions с dead URLs ели 5s timeout каждая
× N циклов до того как наш новый event дойдёт до receiver.
Локально работало потому что DB была свежая.
Фикс:
- В @BeforeEach: deliveryRepo.deleteAllInBatch() + subRepo.deleteAllInBatch()
- Order важен: deliveries first (FK на subscriptions)
Локально 2/2 passed за 10.8s. Race-warnings StaleObjectStateException
в логах — dispatcher держит entity в Hibernate session и пытается
save после нашего deleteAll'а; assertion'ы это не задевает.
WebhookDispatcher читает outbox_events напрямую и не зависит от
Kafka. OutboxPoller (единственный consumer KafkaTemplate в runtime)
выключаем через ordinis.outbox.enabled=false, и spring-kafka
autoconfig — через spring.autoconfigure.exclude. Kafka container
теперь не нужен для этого теста.
E2ESupport: Kafka container теперь lazy. Тесты вызывающие
registerProperties() триггерят start(); тесты на новом
registerPostgresOnlyProperties() — нет.
Локально: WebhookE2ETest 2/2 PASSED за 9.8s (раньше timeout на CI
20-30s). Boot cold start 7s vs ~15s с Kafka. Уходит главный
источник flakiness — Kafka broker timing на shared CI runner.
OutboxKafkaE2ETest по-прежнему использует registerProperties() →
Kafka container стартует — поведение этого теста не изменено.
Pipeline #5667 failed: receiverReturning500_deliveryRetried_notDelivered
condition timeout 20s. Root cause: assertion inside HttpServer handler
(`assertThat(body.length).isGreaterThan(0)`) бросала AssertionError
ВНУТРИ handler потока — exchange.sendResponseHeaders никогда не звался,
client получал connection reset вместо 500. Test ждал
lastStatusCode==500, получал null → timeout.
Fix:
- Убрана assertion из handler (test её не нужно — focus на retry flow)
- Wrapped body-drain в try-catch чтобы handler не падал
- Bumped timeout 20s → 30s (CI cold start + schedule cycles)
Закрывает Phase 5 deferred item. Завершает webhooks v2 покрытие.
WebhookE2ETest (2 tests):
Test 1: success path
- Стартует JDK HttpServer на random localhost port (no extra deps)
- Создаёт WebhookSubscription указывающий на /hook
- POST record в dictionary → outbox event
- Ждёт что receiver получит POST в течение 20s
- Verify body содержит business_key
- Verify HMAC signature header валиден (HmacSigner.sign(secret, body)
matches X-Ordinis-Signature)
- Verify Ordinis headers (X-Ordinis-Event-Type, X-Ordinis-Scope=PUBLIC)
- Verify DB delivery row.status = delivered + lastStatusCode = 200
Test 2: retry path
- Receiver всегда 500
- POST record → outbox → dispatcher tries deliver
- Verify delivery transitions to status=retrying + lastStatusCode=500
- Не ждём DLQ (1000 attempts × 1m backoff = недели)
SSRF guard через ordinis.webhook.allowed-hosts=localhost,127.0.0.1
test override (production deny private CIDR остаётся включённым).
Test config:
- ordinis.outbox.enabled=true (для outbox poller)
- ordinis.webhook.enabled=true (для dispatcher)
- match-interval-ms=200, send-interval-ms=200 (faster tests)
Webhooks v2 — все 5 phases закрыты.
Spring Boot Micrometer по дефолту эмитит только _count/_sum/_max
для http.server.requests — без _bucket нельзя посчитать
histogram_quantile() в Prometheus, p50/p95/p99 latency дашборды
получают "No data".
Включён percentiles-histogram + кастомные SLO bucket boundaries
от 5ms до 5s — покрывают realistic range read-api JSON endpoints.
Server-side histograms точнее client-side percentiles (по которым
нельзя aggregate across instances).
Применить: build + push image + helm upgrade. После рестарта
ordinis-app/read-api/projection-writer Grafana дашборды покажут
latency графики.
ScopeContext.canAccess(DataScope) — единая точка проверки доступа,
использует DataScope.visibleTo (PUBLIC видит PUBLIC, INTERNAL видит
PUBLIC+INTERNAL, RESTRICTED видит всё).
DictionaryRecordController:
- requireReadAccess на GET /{businessKey} и /{businessKey}/history
→ 404 dictionary_not_found если scope словаря недоступен (намеренно
скрываем существование INTERNAL/RESTRICTED данных, защита от
enumeration)
- requireWriteAccess на POST/PUT/DELETE
→ 403 scope_insufficient если scope недостаточен для записи
DictionaryDefinitionController:
- list() фильтрует список по canAccess (PUBLIC-юзер не видит INTERNAL
словари в каталоге)
- get() → 404 если недоступен
- create()/update() → 403 если новый scope выше доступа юзера
(защита от scope escalation через PUT)
AuthE2ETest.publicUser_cannotSeeInternalRecords: TODO snять, expectation
обновлён на isNotFound() (раньше было isOk + комментарий о gap).
До этого fix: PUBLIC-юзер мог GET /api/v1/dictionaries/{n}/records/{k}
INTERNAL-словарь на writer-side. Read-api (отдельный модуль) фильтровал
корректно. Issue найден через AuthE2ETest в Phase 2c.
Все 6 AuthE2ETest и 24 unit-теста rest-api зелёные.
Найден production-bug на staging: ordinis-app в CrashLoopBackOff с
NoClassDefFoundError: com/nimbusds/jose/RemoteKeySourceException.
Причина: в Phase 2c e2e тестах я добавил nimbus-jose-jwt 9.37.3 как
test-scope direct dependency в ordinis-app/pom.xml. Maven scope
resolution: direct test-scope побеждает transitive compile-scope,
nimbus исключился из Spring Boot fat jar. На runtime
JwtDecoders.fromIssuerLocation() (использует Nimbus internally) падал.
Fix:
- ordinis-auth/pom.xml: explicit compile-scope dep на nimbus-jose-jwt
(раньше тянулся транзитивно через oauth2-resource-server starter)
- ordinis-app/pom.xml: убрал test-scope direct decl, JwtTestSupport
использует nimbus с compile classpath.
Verified: BOOT-INF/lib/nimbus-jose-jwt-9.37.3.jar в fat jar после rebuild.
e2e AuthE2ETest всё ещё зелёный (12/12).
ordinis-app/pom.xml:
- surefire excludes **/e2e/*E2ETest.java по умолчанию (быстрые unit без Docker)
- profile `e2e`: combine.self override снимает excludes + includes только e2e
.gitlab-ci.yml: новый job maven-e2e:
- maven image + docker:29.1.2-dind service (тот же что docker-* jobs)
- DOCKER_HOST=tcp://docker:2375, TESTCONTAINERS_HOST_OVERRIDE=docker, RYUK_DISABLED=true
- mvn -pl ordinis-app -am -P e2e test
- artifact: junit reports
- rules: backend-changes (как maven-test)
Локально:
mvn -pl ordinis-app -am test # быстро, без Docker
mvn -pl ordinis-app -am -P e2e test # с Docker, ~23 sec для 12 тестов
В CI оба job'а параллельно после path-filter. e2e будет ловить регрессии типа
audit_log INET/scope filter gap которые мы уже нашли через эти тесты.
Покрытие выросло с 1 до 6 e2e тестов через Testcontainers (Postgres+Kafka).
BitemporalE2ETest (4 тесты):
- createThenUpdate_keepsBothVersionsInHistory: v1+v2 в /history, oldValidTo == newValidFrom
- closeRecord_setsValidTo_andGetReturns404: после DELETE active=null, history живёт
- idempotencyKey_returnsCachedResponse_doesntDuplicate: повторный POST с тем
же Idempotency-Key → тот же id, count=1 в БД
- breakingSchemaChange_blockedOnUpdate: documents текущее поведение PUT
/api/v1/dictionaries/{name} с breaking schema (status < 500 = OK)
OutboxKafkaE2ETest (1 тест):
- POST record → outbox event в БД → poller публикует в Kafka → consumer
получает envelope с правильным dictionaryName/dataScope/payload.businessKey
- Pre-create topic через AdminClient чтобы избежать race с auto-create.
- ordinis.outbox.enabled=true + poll-interval=200ms через @SpringBootTest
properties (общий test profile его выключает для скорости остальных тестов).
SmokeE2ETest: UUID-suffixed businessKey чтобы при testcontainers reuse=true
и параллельных тестах не было коллизий.
Logging: outbox DEBUG для диагностики publish flow.
pom.xml: + awaitility для polling-based проверок.
Все 6 тестов зелёные: 1 smoke + 4 bitemporal + 1 outbox-kafka. Total ~16 sec
включая Spring context boot. Reuse=true ускоряет повторные прогоны.
Phase 1 e2e — proof framework работает:
- E2ESupport: Postgres 18 (postgis/postgis:18-3.6) + Kafka (cp-kafka 7.6.0)
через Testcontainers, reuse=true. db-init.sql создаёт postgis+btree_gist
расширения которые ожидает Liquibase 0001.
- application-test.yml: тушит cloud-config/vault/otel/outbox publishing,
включает Liquibase autoconfig. Auth disabled для упрощения.
- SmokeE2ETest: full e2e — POST dictionary → POST record → GET record →
проверка audit_log row. UUID-suffix в dictName для идемпотентности.
- master.xml: relativeToChangelogFile=true для всех include — иначе
Liquibase из ordinis-app classpath не находит changes/X.xml в JAR.
- pom.xml: testcontainers 1.21.3, surefire env DOCKER_HOST + DOCKER_API_VERSION
для macOS Docker Desktop.
Найден реальный prod-баг: audit_log.ip_address был INET, Hibernate JPA не
делает автоматический cast String→INET → INSERT падал. AuditLogger.write
обёрнут в try/catch, поэтому тихо съедал ошибку — на staging audit_log
оставался пустым после CRUD.
- 0012-audit-log-ipaddress-varchar.xml: ALTER COLUMN INET → VARCHAR(64)
- AuditLog entity: убрал columnDefinition="inet", length=64.
Tempo на staging (tempo.monitoring:4318) — single-process, принимает
только traces. Spring Boot OTel autoconfig по умолчанию отправляет всё
по тому же endpoint → 404 на каждой попытке (раз в секунду в логах
writer/read-api/projection-writer).
Override через ENV — можно переключить когда поднимем полный stack
(Mimir для metrics, Loki для logs).
Метрики Prometheus продолжают работать через actuator/prometheus
(scrape снаружи), это отдельный path.
Multi-module Maven build падал на 'Child module ordinis-auth does not exist'
потому что Dockerfile'ы копировали только конкретные используемые модули.
Добавлен COPY ordinis-auth ./ordinis-auth перед COPY ordinis-validation.
Новый модуль ordinis-auth:
- OrdinisAuthProperties — public-key, issuer, requireAuthentication, allowQueryScope
- ScopeContext — резолвит current scopes из JWT claim 'scopes' (приоритет),
потом legacy ?as_scope=, потом anonymous=PUBLIC
- SecurityConfig — Spring Security OAuth2 Resource Server + RSA public-key
decoder. Если public-key пуст — JWT validation отключён (permissive
fallback); rollout без auth-сервера не ломает API.
Read controller теперь делегирует scope resolution в ScopeContext вместо
прямого парсинга ?as_scope=. Backward compat: legacy query параметр
работает пока ordinis.auth.allow-query-scope=true (по умолчанию true в
dev/staging, false в prod после интеграции с @nstart/auth).
Vault: public-key читается из secret/ordinis/cuod/jwt-public-key (key=key).
Spring Cloud Vault flatten'ит в property 'key', resolved в
ordinis.auth.public-key=${key:}.
Stack trace showed io.opentelemetry.exporter.internal.http.HttpExporter
sending to :4317 — Tempo on 4317 expects gRPC frames, gets HTTP, sends
RST. Switch endpoint to :4318 (Tempo OTLP HTTP receiver) and protocol to
http/protobuf so the SDK and Tempo speak the same protocol.
The gRPC config never took effect — Spring Boot SDK on micrometer-tracing-
otlp pulls in only the HTTP exporter by default; gRPC needs the explicit
opentelemetry-exporter-otlp jar.
Hibernate validate mode threw 'wrong column type [supported_locales]:
found [_text (Types#ARRAY)] but expecting [text[] (Types#OTHER)]' against
the Liquibase-managed schema. This is a well-known hypersistence-utils +
PostgreSQL TEXT[] friction with Hibernate validate.
Schema is owned by Liquibase migrations; validate adds no safety here. Set
to 'none' (matches read-api and projection-writer).
K8s profile relied on shared/dev defaults for spring.datasource.url, but those
live inside the dev profile block — invisible when k8s profile is active.
Result: 'APPLICATION FAILED TO START — Failed to configure a DataSource'.
Move full datasource (and kafka/redis for projection-writer) wiring into the
k8s profile section. ENV vars come from Vault Agent injector
(ORDINIS_PG_USER/PASSWORD, ORDINIS_KAFKA_USER/PASSWORD, ORDINIS_REDIS_PASSWORD)
and chart-supplied ENV (ORDINIS_PG_HOST, ORDINIS_KAFKA_BOOTSTRAP, etc).
application.yml fallback URL was http://config-server.ordinis-dev:8888 — namespace
removed. Default now points to staging; SPRING_CLOUD_CONFIG_URI env still overrides
via Helm chart for any deployment.
- Remove spring-cloud-starter-bootstrap (deprecated в SC 2024.x; используем
spring.config.import вместо bootstrap context)
- Profile-based config: dev отключает Cloud Config + Vault + OTel + JPA
auto-config для standalone smoke testing; k8s profile подключает реальную
инфру (vault + config server)
- Dockerfile: COPY всех модулей parent pom их видит при reactor
- Уберём spring-boot-maven-plugin из read-api/projection-writer пока нет main
Validated:
- mvn install all 11 modules: BUILD SUCCESS
- Spring Boot стартует за 2.7s в dev profile
- /actuator/health UP, /actuator/prometheus отдаёт http_server_requests + jvm
- HelloController отвечает на GET /
Александр Зимин