Skip to content

Commit fa2eab8

Browse files
karle0wnerenovate[bot]
karle0wne
and
renovate[bot]
authored
update MDC, otel, WFlow (#74)
* init plan * guarantee MDC cleanup plus span termination when traces are absent (#73) * bump test log level * Update dependency org.apache.commons:commons-lang3 to v3.18.0 [SECURITY] (#70) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * Replace dependency org.slf4j:slf4j-log4j12 with org.slf4j:slf4j-reload4j (#67) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * Update all non-major maven dependencies (#51) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * add missing pom sonatype elements * Refine THProviderErrorMapper error mapping and MDC tests (#78) - extend MDC utils and interceptor logic, adding MdcUtilsExtendedTest coverage - align THProviderErrorMapper errorSource/generationSource rules and normalize HTTP messages using EnglishReasonPhraseCatalog - add dedicated THProviderErrorMapper tests and adjust thrift test suite expectations - declare missing httpcore5/httpclient5 dependencies * refactor: unify trace metadata and rpc handling and add MDC propagation tests (#79) * feat: align OTel trace propagation across transport bundles and asynс flows (#80) * fixes * codacy * codacy * codacy * codacy * codacy * add otel attributes (#81) * second put mdc after filling metadata (#82) * add MdcRefreshInterceptor (#83) * bump * bump * bump --------- Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
1 parent 5d63ff4 commit fa2eab8

45 files changed

Lines changed: 2915 additions & 406 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/basic-linters.yml‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎.github/workflows/build.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,6 @@ on:
77

88
jobs:
99
build:
10-
uses: valitydev/java-workflow/.github/workflows/maven-library-build.yml@v2
10+
uses: valitydev/java-workflow/.github/workflows/maven-library-build.yml@v3
11+
with:
12+
java-version: "11"

‎.github/workflows/deploy.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,9 @@ on:
88

99
jobs:
1010
deploy:
11-
uses: valitydev/java-workflow/.github/workflows/maven-library-deploy.yml@v2
11+
uses: valitydev/java-workflow/.github/workflows/maven-library-deploy.yml@v3
12+
with:
13+
java-version: "11"
1214
secrets:
1315
server-username: ${{ secrets.OSSRH_USERNAME }}
1416
server-password: ${{ secrets.OSSRH_TOKEN }}

‎README.md‎

Lines changed: 127 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,141 @@
1-
# dev.vality.woody
1+
# Woody
2+
[![Maven Central](https://img.shields.io/maven-central/v/dev.vality.woody/woody.svg)](https://central.sonatype.com/artifact/dev.vality.woody/woody)
23

3-
Java реализация [Библиотеки RPC вызовов для общения между микросервисами](http://52.29.202.218/design/ms/platform/rpc-lib/).
4+
Java реализация [Библиотеки RPC вызовов][rpc-lib] для общения между
5+
микросервисами.
46

57
## Описание
68

79
1. [woody-api](woody-api/woody-api.md)
810
1. [woody-thrift](woody-thrift/woody-thrift.md)
911

12+
## Архитектура
13+
14+
- **woody-api** – базовая библиотека трассировки: управляет `TraceContext`,
15+
генерирует `trace_id/span_id`, переносит контекст между потоками (`WFlow`,
16+
`WCallable/WRunnable/WExecutorService`), содержит цепочку прокси и
17+
перехватчиков для событий, дедлайнов и маппинга ошибок.
18+
- **woody-thrift** – интеграция с Thrift over HTTP: билдеры
19+
клиентов/сервисов (`THClientBuilder`, `THServiceBuilder`) добавляют
20+
transport/message интерсепторы, логирование, поддержку `traceparent` и
21+
расширения метаданных.
22+
- **libthrift** – локальный модуль с патчами Apache Thrift (HTTP-клиент 5,
23+
сервлеты и TLS), используется как зависимость для `woody-thrift`.
24+
25+
## Ключевые возможности
26+
27+
- Сквозная трассировка вызовов через `TraceData`, автоматическое измерение
28+
длительности и интеграция со SLF4J MDC и OpenTelemetry.
29+
- Расширенный MDC: автоматически публикует идентификаторы Woody/OTel, дедлайны,
30+
RPC-метаданные и может отключаться через `-Dwoody.mdc.extended=false`.
31+
- Потокобезопасная обработка фоновых задач с сохранением контекста
32+
(`WFlow.create`, `createServiceFork`).
33+
- Расширяемая система перехватчиков и `MetadataExtensionKit` для
34+
обогащения метаданных и настройки transport/message уровней.
35+
- HTTP Thrift клиенты и сервисы с пуллингом, логированием, маппингом ошибок и
36+
готовыми EventListener’ами.
37+
- Обновлённый маппинг ошибок и транспорта (`THProviderErrorMapper`), покрытый
38+
изолированными тестами и сценариями с сетевыми исключениями.
39+
1040
## Для ознакомления
1141

1242
[Thrift](https://thrift.apache.org/)
1343
[Dapper](http://research.google.com/pubs/pub36356.html)
1444

1545
## Выпуск новой версии
16-
Версии _woody-pom_ и всех его модулей должны совпадать, для этого перед началом работы над новой версией библиотеки нужно увеличить версию _woody-pom_ и в корневой директории проекта выполнить команду:
46+
47+
Версии _woody-pom_ и всех его модулей должны совпадать, для этого перед
48+
началом работы над новой версией библиотеки нужно увеличить версию
49+
_woody-pom_ и в корневой директории проекта выполнить команду:
1750
`mvn versions:update-child-modules -DgenerateBackupPoms=false`
18-
Параметр `generateBackupPoms` можно опустить, если нужны резервные копии изменяемых файлов.
51+
Параметр `generateBackupPoms` можно опустить, если нужны резервные копии
52+
изменяемых файлов.
53+
54+
## Общая структура
55+
56+
- Maven-монорепо (`pom.xml`) с тремя артефактами: базовая библиотека
57+
`woody-api`, интеграция `woody-thrift`, а также пропатченный `libthrift`
58+
(форк Apache Thrift, переиспользующий HttpClient5 и подключающийся как
59+
модуль).
60+
- Основной стек: Java 11, SLF4J, Apache Commons Pool 2, OpenTelemetry
61+
(API/SDK/OTLP), Jakarta Servlet 5, Jetty и EasyMock в тестах.
62+
63+
## Woody API
64+
65+
- `TraceContext`/`TraceData` управляют client/service span’ами в
66+
`ThreadLocal`, автоматически создают `trace_id/span_id`, фиксируют
67+
длительность, синхронизируют SLF4J MDC и завершают OTEL-спаны.
68+
- `WFlow` и `flow.concurrent` оборачивают `Runnable`/`Callable`/
69+
`ExecutorService`, сохраняя контекст при выполнении в других потоках,
70+
поддерживают форки с новыми root- и service-span’ами.
71+
- Система перехватчиков (`proxy`, `interceptor`, `event`):
72+
- `ProxyFactory` строит динамические прокси вокруг клиентов и
73+
обработчиков, направляя вызовы через `MethodCallTracer`.
74+
- `AbstractClientBuilder`/`AbstractServiceBuilder` подключают
75+
`ContextTracer`, контроль дедлайнов, маппинг ошибок и event-трейсеры.
76+
- События (`ClientEvent`, `ServiceEvent`) обрабатываются композиционными
77+
слушателями; `TransportEventInterceptor` и `ProviderEventInterceptor`
78+
публикуют события до и после вызовов.
79+
- Расширяемость через `interceptor.ext` и `MetadataExtensionKit`:
80+
расширения получают `TraceData` и транспортный контекст для обогащения
81+
метаданных.
82+
- Ошибки классифицируются `WErrorType`/`WErrorDefinition`;
83+
`ErrorMapProcessor` и `ErrorMappingInterceptor` мэппят транспортные и
84+
бизнес-ошибки; `DeadlineTracer` обеспечивает контроль таймаутов.
85+
86+
## Woody Thrift
87+
88+
- Thrift over HTTP поверх Woody.
89+
- Клиенты (`THClientBuilder`, `THSpawnClientBuilder`,
90+
`THPooledClientBuilder`) создают `TServiceClient`, добавляют
91+
транспортные и message перехватчики (метаданные, traceparent, события),
92+
управляют ресурсами HttpClient5.
93+
- Сервисы (`THServiceBuilder`) собирают `TServlet` с обёртками над
94+
`TProcessor`, прокидывая `TraceContext.forService`, подключая
95+
транспортные перехватчики и error-mapping (`THErrorMapProcessor`);
96+
логирование (`THSEventLogListener`, `THCEventLogListener`) включено по
97+
умолчанию.
98+
- Транспорт и сообщения расширяются через bundles
99+
(`MetadataExtensionBundle` и др.), создавая `THCExtensionContext`/
100+
`THSExtensionContext` для клиента и сервиса.
101+
- Поддержка W3C traceparent (`TraceParentUtils`), заполнение
102+
дедлайнов/ошибок в метаданные, HTTP-логгеры.
103+
- Дополнительные пакеты: `error` (конвертация исключений и
104+
HTTP-статусов), `event` (логирование), `transport` (конфигурация HTTP
105+
servlet’ов и клиентов).
106+
107+
## Libthrift
108+
109+
- Локальный модуль с модифицированными классами Apache Thrift
110+
(HTTP-транспорт, сервлеты, TLS и т.д.) под HttpClient5 и расширения Woody;
111+
подключается к `woody-thrift` как зависимость той же версии.
112+
113+
## Тесты и утилиты
114+
115+
- `woody-api/src/test` покрывает генераторы идентификаторов, трассировку и
116+
прокси.
117+
- `woody-thrift/src/test` (Jetty quickstart + EasyMock) проверяет
118+
HTTP-интеграцию, обработку исключений и метаданные, включая
119+
интеграционные сценарии `TraceLifecycleIntegrationTest` для проверки
120+
сквозной OpenTelemetry-трассировки, восстановления контекста, ошибок и
121+
работы с неполными заголовками.
122+
- Профиль `gen_thrift_classes` включает `thrift-maven-plugin` для генерации
123+
Thrift IDL.
124+
- Интеграционные тесты `MetadataMdcPropagationTest` и
125+
`TraceLifecycleIntegrationTest` контролируют перенос MDC-метаданных,
126+
OpenTelemetry-трассировку и восстановление контекста при ошибках.
127+
128+
## Дополнительные материалы
129+
130+
- [Контекст Woody Java](context.md) — сводный обзор модулей,
131+
инструментов и ключевых понятий.
132+
133+
## Итог
134+
135+
Реализация обеспечивает сквозную трассировку, управление временем жизни
136+
span’ов и доступ к событиям через единую API-обвязку; `woody-thrift` поверх
137+
неё инкапсулирует создание HTTP-клиентов и сервисов Thrift с `traceparent`,
138+
логированием и расширяемыми метаданными, опираясь на локально
139+
модифицированный `libthrift`.
140+
141+
[rpc-lib]: http://52.29.202.218/design/ms/platform/rpc-lib/

‎context.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Woody Java – Reference Context
2+
3+
## Project Overview
4+
5+
- Maven multi-module library delivering RPC tracing infrastructure for
6+
microservices.
7+
- Java 11 baseline; core dependencies include SLF4J, Apache Commons Pool 2,
8+
OpenTelemetry (API/SDK/OTLP exporter), Jakarta Servlet 5, HttpClient5, Jetty
9+
(tests), EasyMock.
10+
- Modules share version `woody` (root POM); `dependencyManagement` keeps `woody-
11+
api` version-aligned.
12+
13+
## Module Breakdown
14+
15+
### woody-api
16+
17+
- Thread-local tracing via `TraceContext`/`TraceData` managing client/service
18+
spans, auto ID generation, duration tracking, SLF4J MDC sync, OTEL span
19+
lifecycle.
20+
- `MDCUtils` публикует trace/span идентификаторы Woody и OpenTelemetry,
21+
дедлайны и RPC-метаданные (отключаемо через системное свойство
22+
`woody.mdc.extended`).
23+
- Concurrency helpers (`WFlow`, `WCallable`, `WRunnable`, `WExecutorService`)
24+
clone/propagate trace context across threads, including service/client forks.
25+
- Proxy/interceptor pipeline:
26+
- `ProxyFactory` wraps interfaces with dynamic proxies and
27+
`MethodCallTracer`.
28+
- `AbstractClientBuilder`/`AbstractServiceBuilder` assemble tracing,
29+
deadline
30+
enforcement (`DeadlineTracer`), error
31+
mapping, and event dispatch.
32+
- Event system (`ClientEvent`, `ServiceEvent`, composite listeners) plus
33+
transport/provider interceptors for
34+
lifecycle hooks.
35+
- Error framework (`WErrorType`, `WErrorDefinition`, `ErrorMapProcessor`,
36+
`ErrorMappingInterceptor`) translating transport/business outcomes.
37+
- Metadata extensibility via `interceptor.ext`, `ExtensionBundle`,
38+
`MetadataExtensionKit`.
39+
40+
### woody-thrift
41+
42+
- Thrift-over-HTTP implementation layered on woody-api.
43+
- Client builders (`THClientBuilder`, `THSpawnClientBuilder`,
44+
`THPooledClientBuilder`) construct `TServiceClient`, inject message/transport
45+
interceptors, traceparent propagation, metadata extensions, logging
46+
(`THCEventLogListener`); support custom or pooled HttpClient5.
47+
- Service builder (`THServiceBuilder`) wraps `TProcessor` into `TServlet`,
48+
applies transport interceptors, `THErrorMapProcessor`, logging
49+
(`THSEventLogListener`), and ensures `TraceContext.forService`.
50+
- Extension bundles produce `THCExtensionContext`/`THSExtensionContext`;
51+
`TraceParentUtils` handles W3C traceparent parsing/serialization.
52+
- Supplemental packages: `error` (exception ↔ response mapping), `event` (HTTP
53+
logging), `transport` (servlet/client wiring).
54+
- Обновлённый `THProviderErrorMapper` синхронизирует статус, источники ошибок,
55+
метаданные и обеспечивает трассировку при транспортных исключениях.
56+
57+
### libthrift
58+
59+
- Local fork of Apache Thrift with HttpClient5 transport adjustments,
60+
servlet/TLS tweaks, and hooks compatible with woody interceptors.
61+
- Packaged as module dependency for `woody-thrift` (same version).
62+
63+
## Build & Tooling
64+
65+
- Root `pom.xml` наследуется от `dev.vality:library-parent-pom:3.1.0` и
66+
управляет версией через `${revision}`.
67+
- `woody-thrift` offers `gen_thrift_classes` profile running `thrift-maven-
68+
plugin` (`thrift` executable required).
69+
- Target Java version 11; uses Checkstyle suppressions and Renovate config.
70+
71+
## Testing
72+
73+
- `woody-api/src/test`: ID generators, tracing logic, proxy behavior.
74+
- `woody-thrift/src/test`: Jetty quickstart servers + EasyMock cover HTTP
75+
integration, metadata propagation, error mapping, а также свежие
76+
интеграционные сценарии `TraceLifecycleIntegrationTest`, проверяющие
77+
сквозную OpenTelemetry-трассировку (новый/восстановленный контекст,
78+
обработку ошибок, отсутствие обязательных метаданных).
79+
- Дополнительно `THProviderErrorMapperTest` и `MetadataMdcPropagationTest`
80+
контролируют обработку ошибок и перенос MDC/OTel данных.
81+
82+
## Key Concepts for Agents
83+
84+
- Always maintain root/service/client span consistency; `TraceContext`
85+
orchestrates init/destroy hooks and ensures MDC/Otel sync.
86+
- Cross-thread execution must wrap tasks with
87+
`WFlow.create`/`createServiceFork`.
88+
- Interceptors are composable; metadata extensions rely on extension bundles
89+
(client/service contexts differ).
90+
- `libthrift` should be treated as authoritative transport layer—do not upgrade
91+
Apache Thrift without reconciling local changes.
92+
93+
## Ready-to-Use Snippets
94+
95+
- Create forked service task: `WFlow.createServiceFork(runnable)` or callables
96+
with custom ID generators.
97+
- Client build pattern:
98+
99+
```java
100+
ThriftServiceSrv.Iface client = new THClientBuilder()
101+
.withAddress(URI.create("https://example"))
102+
.withHttpClient(HttpClientBuilder.create().build())
103+
.withEventListener(listener)
104+
.build(ThriftServiceSrv.Iface.class);
105+
```
106+
107+
- Service servlet:
108+
109+
```java
110+
Servlet servlet = new THServiceBuilder()
111+
.withEventListener(listener)
112+
.build(ThriftServiceSrv.Iface.class, handlerImpl);
113+
```
114+
115+
## Operational Notes
116+
117+
- Logging depends on composite listeners; disable via `withLogEnabled(false)`.
118+
- Deadlines propagate through spans; ensure upstream services respect
119+
`DeadlineTracer`.
120+
- Error mapping distinguishes transport errors vs business
121+
(`WErrorType.BUSINESS_ERROR` leaves transport metadata intact).
122+
- For new metadata, implement `MetadataExtensionKit` and include via builder
123+
`withMetaExtensions`.
124+
- Для фоновых задач используйте `WFlow.createServiceFork(...)` — он создаёт
125+
новый service-span и корректно инициализирует OpenTelemetry контекст.

‎libthrift/pom.xml‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,44 @@
22
<project xmlns="http://maven.apache.org/POM/4.0.0"
33
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
44
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
57
<parent>
68
<artifactId>woody</artifactId>
79
<groupId>dev.vality.woody</groupId>
8-
<version>2.0.9</version>
10+
<version>2.1.0</version>
911
</parent>
10-
<modelVersion>4.0.0</modelVersion>
1112

1213
<artifactId>libthrift</artifactId>
1314
<packaging>jar</packaging>
1415

16+
<name>Woody LibThrift Extensions</name>
17+
<description>Thrift transport helpers and HTTP client integrations for Woody.</description>
18+
<url>https://github.com/valitydev/woody_java</url>
19+
20+
<licenses>
21+
<license>
22+
<name>The Apache Software License, Version 2.0</name>
23+
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
24+
</license>
25+
</licenses>
26+
27+
<developers>
28+
<developer>
29+
<id>vality</id>
30+
<name>Vality Developers</name>
31+
<email>devs@vality.dev</email>
32+
<organization>Vality</organization>
33+
<organizationUrl>https://vality.dev</organizationUrl>
34+
</developer>
35+
</developers>
36+
37+
<scm>
38+
<connection>scm:git:git://github.com/valitydev/woody_java.git</connection>
39+
<developerConnection>scm:git:ssh://github.com/valitydev/woody_java.git</developerConnection>
40+
<url>https://github.com/valitydev/woody_java/tree/master</url>
41+
</scm>
42+
1543
<properties>
1644
<checkstyle.skip>true</checkstyle.skip>
1745
</properties>

0 commit comments

Comments
 (0)