update MDC, otel, WFlow

.github/workflows/build.yml

@@ -7,4 +7,6 @@ on:
 
 jobs:
   build:
-    uses: valitydev/java-workflow/.github/workflows/maven-library-build.yml@v2
+    uses: valitydev/java-workflow/.github/workflows/maven-library-build.yml@v3
+    with:
+      java-version: "11"

.github/workflows/deploy.yml

@@ -8,7 +8,9 @@ on:
 
 jobs:
   deploy:
-    uses: valitydev/java-workflow/.github/workflows/maven-library-deploy.yml@v2
+    uses: valitydev/java-workflow/.github/workflows/maven-library-deploy.yml@v3
+    with:
+      java-version: "11"
     secrets:
       server-username: ${{ secrets.OSSRH_USERNAME }}
       server-password: ${{ secrets.OSSRH_TOKEN }}

README.md

@@ -1,18 +1,141 @@
-# dev.vality.woody
+# Woody
+[![Maven Central](https://img.shields.io/maven-central/v/dev.vality.woody/woody.svg)](https://central.sonatype.com/artifact/dev.vality.woody/woody)
 
-Java реализация [Библиотеки RPC вызовов для общения между микросервисами](http://52.29.202.218/design/ms/platform/rpc-lib/).
+Java реализация [Библиотеки RPC вызовов][rpc-lib] для общения между
+микросервисами.
 
 ## Описание
 
 1. [woody-api](woody-api/woody-api.md)
 1. [woody-thrift](woody-thrift/woody-thrift.md)
 
+## Архитектура
+
+- **woody-api** – базовая библиотека трассировки: управляет `TraceContext`,
+  генерирует `trace_id/span_id`, переносит контекст между потоками (`WFlow`,
+  `WCallable/WRunnable/WExecutorService`), содержит цепочку прокси и
+  перехватчиков для событий, дедлайнов и маппинга ошибок.
+- **woody-thrift** – интеграция с Thrift over HTTP: билдеры
+  клиентов/сервисов (`THClientBuilder`, `THServiceBuilder`) добавляют
+  transport/message интерсепторы, логирование, поддержку `traceparent` и
+  расширения метаданных.
+- **libthrift** – локальный модуль с патчами Apache Thrift (HTTP-клиент 5,
+  сервлеты и TLS), используется как зависимость для `woody-thrift`.
+
+## Ключевые возможности
+
+- Сквозная трассировка вызовов через `TraceData`, автоматическое измерение
+  длительности и интеграция со SLF4J MDC и OpenTelemetry.
+- Расширенный MDC: автоматически публикует идентификаторы Woody/OTel, дедлайны,
+  RPC-метаданные и может отключаться через `-Dwoody.mdc.extended=false`.
+- Потокобезопасная обработка фоновых задач с сохранением контекста
+  (`WFlow.create`, `createServiceFork`).
+- Расширяемая система перехватчиков и `MetadataExtensionKit` для
+  обогащения метаданных и настройки transport/message уровней.
+- HTTP Thrift клиенты и сервисы с пуллингом, логированием, маппингом ошибок и
+  готовыми EventListener’ами.
+- Обновлённый маппинг ошибок и транспорта (`THProviderErrorMapper`), покрытый
+  изолированными тестами и сценариями с сетевыми исключениями.
+
 ## Для ознакомления
 
 [Thrift](https://thrift.apache.org/)  
 [Dapper](http://research.google.com/pubs/pub36356.html)
 
 ## Выпуск новой версии
-Версии _woody-pom_ и всех его модулей должны совпадать, для этого перед началом работы над новой версией библиотеки нужно увеличить версию _woody-pom_ и в корневой директории проекта выполнить команду:  
+
+Версии _woody-pom_ и всех его модулей должны совпадать, для этого перед
+началом работы над новой версией библиотеки нужно увеличить версию
+_woody-pom_ и в корневой директории проекта выполнить команду:  
 `mvn versions:update-child-modules -DgenerateBackupPoms=false`  
-Параметр `generateBackupPoms` можно опустить, если нужны резервные копии изменяемых файлов.
+Параметр `generateBackupPoms` можно опустить, если нужны резервные копии
+изменяемых файлов.
+
+## Общая структура
+
+- Maven-монорепо (`pom.xml`) с тремя артефактами: базовая библиотека
+  `woody-api`, интеграция `woody-thrift`, а также пропатченный `libthrift`
+  (форк Apache Thrift, переиспользующий HttpClient5 и подключающийся как
+  модуль).
+- Основной стек: Java 11, SLF4J, Apache Commons Pool 2, OpenTelemetry
+  (API/SDK/OTLP), Jakarta Servlet 5, Jetty и EasyMock в тестах.
+
+## Woody API
+
+- `TraceContext`/`TraceData` управляют client/service span’ами в
+  `ThreadLocal`, автоматически создают `trace_id/span_id`, фиксируют
+  длительность, синхронизируют SLF4J MDC и завершают OTEL-спаны.
+- `WFlow` и `flow.concurrent` оборачивают `Runnable`/`Callable`/
+  `ExecutorService`, сохраняя контекст при выполнении в других потоках,
+  поддерживают форки с новыми root- и service-span’ами.
+- Система перехватчиков (`proxy`, `interceptor`, `event`):
+  - `ProxyFactory` строит динамические прокси вокруг клиентов и
+    обработчиков, направляя вызовы через `MethodCallTracer`.
+  - `AbstractClientBuilder`/`AbstractServiceBuilder` подключают
+    `ContextTracer`, контроль дедлайнов, маппинг ошибок и event-трейсеры.
+  - События (`ClientEvent`, `ServiceEvent`) обрабатываются композиционными
+    слушателями; `TransportEventInterceptor` и `ProviderEventInterceptor`
+    публикуют события до и после вызовов.
+- Расширяемость через `interceptor.ext` и `MetadataExtensionKit`:
+  расширения получают `TraceData` и транспортный контекст для обогащения
+  метаданных.
+- Ошибки классифицируются `WErrorType`/`WErrorDefinition`;
+  `ErrorMapProcessor` и `ErrorMappingInterceptor` мэппят транспортные и
+  бизнес-ошибки; `DeadlineTracer` обеспечивает контроль таймаутов.
+
+## Woody Thrift
+
+- Thrift over HTTP поверх Woody.
+  - Клиенты (`THClientBuilder`, `THSpawnClientBuilder`,
+    `THPooledClientBuilder`) создают `TServiceClient`, добавляют
+    транспортные и message перехватчики (метаданные, traceparent, события),
+    управляют ресурсами HttpClient5.
+  - Сервисы (`THServiceBuilder`) собирают `TServlet` с обёртками над
+    `TProcessor`, прокидывая `TraceContext.forService`, подключая
+    транспортные перехватчики и error-mapping (`THErrorMapProcessor`);
+    логирование (`THSEventLogListener`, `THCEventLogListener`) включено по
+    умолчанию.
+  - Транспорт и сообщения расширяются через bundles
+    (`MetadataExtensionBundle` и др.), создавая `THCExtensionContext`/
+    `THSExtensionContext` для клиента и сервиса.
+  - Поддержка W3C traceparent (`TraceParentUtils`), заполнение
+    дедлайнов/ошибок в метаданные, HTTP-логгеры.
+  - Дополнительные пакеты: `error` (конвертация исключений и
+    HTTP-статусов), `event` (логирование), `transport` (конфигурация HTTP
+    servlet’ов и клиентов).
+
+## Libthrift
+
+- Локальный модуль с модифицированными классами Apache Thrift
+  (HTTP-транспорт, сервлеты, TLS и т.д.) под HttpClient5 и расширения Woody;
+  подключается к `woody-thrift` как зависимость той же версии.
+
+## Тесты и утилиты
+
+- `woody-api/src/test` покрывает генераторы идентификаторов, трассировку и
+  прокси.
+- `woody-thrift/src/test` (Jetty quickstart + EasyMock) проверяет
+  HTTP-интеграцию, обработку исключений и метаданные, включая
+  интеграционные сценарии `TraceLifecycleIntegrationTest` для проверки
+  сквозной OpenTelemetry-трассировки, восстановления контекста, ошибок и
+  работы с неполными заголовками.
+- Профиль `gen_thrift_classes` включает `thrift-maven-plugin` для генерации
+  Thrift IDL.
+- Интеграционные тесты `MetadataMdcPropagationTest` и
+  `TraceLifecycleIntegrationTest` контролируют перенос MDC-метаданных,
+  OpenTelemetry-трассировку и восстановление контекста при ошибках.
+
+## Дополнительные материалы
+
+- [Контекст Woody Java](context.md) — сводный обзор модулей,
+  инструментов и ключевых понятий.
+
+## Итог
+
+Реализация обеспечивает сквозную трассировку, управление временем жизни
+span’ов и доступ к событиям через единую API-обвязку; `woody-thrift` поверх
+неё инкапсулирует создание HTTP-клиентов и сервисов Thrift с `traceparent`,
+логированием и расширяемыми метаданными, опираясь на локально
+модифицированный `libthrift`.
+
+[rpc-lib]: http://52.29.202.218/design/ms/platform/rpc-lib/

context.md

@@ -0,0 +1,125 @@
+# Woody Java – Reference Context
+
+## Project Overview
+
+- Maven multi-module library delivering RPC tracing infrastructure for
+  microservices.
+- Java 11 baseline; core dependencies include SLF4J, Apache Commons Pool 2,
+  OpenTelemetry (API/SDK/OTLP exporter), Jakarta Servlet 5, HttpClient5, Jetty
+  (tests), EasyMock.
+- Modules share version `woody` (root POM); `dependencyManagement` keeps `woody-
+  api` version-aligned.
+
+## Module Breakdown
+
+### woody-api
+
+- Thread-local tracing via `TraceContext`/`TraceData` managing client/service
+  spans, auto ID generation, duration tracking, SLF4J MDC sync, OTEL span
+  lifecycle.
+- `MDCUtils` публикует trace/span идентификаторы Woody и OpenTelemetry,
+  дедлайны и RPC-метаданные (отключаемо через системное свойство
+  `woody.mdc.extended`).
+- Concurrency helpers (`WFlow`, `WCallable`, `WRunnable`, `WExecutorService`)
+  clone/propagate trace context across threads, including service/client forks.
+- Proxy/interceptor pipeline:
+  - `ProxyFactory` wraps interfaces with dynamic proxies and
+    `MethodCallTracer`.
+  - `AbstractClientBuilder`/`AbstractServiceBuilder` assemble tracing,
+    deadline
+    enforcement (`DeadlineTracer`), error
+      mapping, and event dispatch.
+  - Event system (`ClientEvent`, `ServiceEvent`, composite listeners) plus
+    transport/provider interceptors for
+      lifecycle hooks.
+- Error framework (`WErrorType`, `WErrorDefinition`, `ErrorMapProcessor`,
+  `ErrorMappingInterceptor`) translating transport/business outcomes.
+- Metadata extensibility via `interceptor.ext`, `ExtensionBundle`,
+  `MetadataExtensionKit`.
+
+### woody-thrift
+
+- Thrift-over-HTTP implementation layered on woody-api.
+- Client builders (`THClientBuilder`, `THSpawnClientBuilder`,
+  `THPooledClientBuilder`) construct `TServiceClient`, inject message/transport
+  interceptors, traceparent propagation, metadata extensions, logging
+  (`THCEventLogListener`); support custom or pooled HttpClient5.
+- Service builder (`THServiceBuilder`) wraps `TProcessor` into `TServlet`,
+  applies transport interceptors, `THErrorMapProcessor`, logging
+  (`THSEventLogListener`), and ensures `TraceContext.forService`.
+- Extension bundles produce `THCExtensionContext`/`THSExtensionContext`;
+  `TraceParentUtils` handles W3C traceparent parsing/serialization.
+- Supplemental packages: `error` (exception ↔ response mapping), `event` (HTTP
+  logging), `transport` (servlet/client wiring).
+- Обновлённый `THProviderErrorMapper` синхронизирует статус, источники ошибок,
+  метаданные и обеспечивает трассировку при транспортных исключениях.
+
+### libthrift
+
+- Local fork of Apache Thrift with HttpClient5 transport adjustments,
+  servlet/TLS tweaks, and hooks compatible with woody interceptors.
+- Packaged as module dependency for `woody-thrift` (same version).
+
+## Build & Tooling
+
+- Root `pom.xml` наследуется от `dev.vality:library-parent-pom:3.1.0` и
+  управляет версией через `${revision}`.
+- `woody-thrift` offers `gen_thrift_classes` profile running `thrift-maven-
+  plugin` (`thrift` executable required).
+- Target Java version 11; uses Checkstyle suppressions and Renovate config.
+
+## Testing
+
+- `woody-api/src/test`: ID generators, tracing logic, proxy behavior.
+- `woody-thrift/src/test`: Jetty quickstart servers + EasyMock cover HTTP
+  integration, metadata propagation, error mapping, а также свежие
+  интеграционные сценарии `TraceLifecycleIntegrationTest`, проверяющие
+  сквозную OpenTelemetry-трассировку (новый/восстановленный контекст,
+  обработку ошибок, отсутствие обязательных метаданных).
+- Дополнительно `THProviderErrorMapperTest` и `MetadataMdcPropagationTest`
+  контролируют обработку ошибок и перенос MDC/OTel данных.
+
+## Key Concepts for Agents
+
+- Always maintain root/service/client span consistency; `TraceContext`
+  orchestrates init/destroy hooks and ensures MDC/Otel sync.
+- Cross-thread execution must wrap tasks with
+  `WFlow.create`/`createServiceFork`.
+- Interceptors are composable; metadata extensions rely on extension bundles
+  (client/service contexts differ).
+- `libthrift` should be treated as authoritative transport layer—do not upgrade
+  Apache Thrift without reconciling local changes.
+
+## Ready-to-Use Snippets
+
+- Create forked service task: `WFlow.createServiceFork(runnable)` or callables
+  with custom ID generators.
+- Client build pattern:
+
+  ```java
+  ThriftServiceSrv.Iface client = new THClientBuilder()
+      .withAddress(URI.create("https://example"))
+      .withHttpClient(HttpClientBuilder.create().build())
+      .withEventListener(listener)
+      .build(ThriftServiceSrv.Iface.class);
+  ```
+
+- Service servlet:
+
+  ```java
+  Servlet servlet = new THServiceBuilder()
+      .withEventListener(listener)
+      .build(ThriftServiceSrv.Iface.class, handlerImpl);
+  ```
+
+## Operational Notes
+
+- Logging depends on composite listeners; disable via `withLogEnabled(false)`.
+- Deadlines propagate through spans; ensure upstream services respect
+  `DeadlineTracer`.
+- Error mapping distinguishes transport errors vs business
+  (`WErrorType.BUSINESS_ERROR` leaves transport metadata intact).
+- For new metadata, implement `MetadataExtensionKit` and include via builder
+  `withMetaExtensions`.
+- Для фоновых задач используйте `WFlow.createServiceFork(...)` — он создаёт
+  новый service-span и корректно инициализирует OpenTelemetry контекст.

libthrift/pom.xml

@@ -2,16 +2,44 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
     <parent>
         <artifactId>woody</artifactId>
         <groupId>dev.vality.woody</groupId>
-        <version>2.0.9</version>
+        <version>2.1.0</version>
     </parent>
-    <modelVersion>4.0.0</modelVersion>
 
     <artifactId>libthrift</artifactId>
     <packaging>jar</packaging>
 
+    <name>Woody LibThrift Extensions</name>
+    <description>Thrift transport helpers and HTTP client integrations for Woody.</description>
+    <url>https://github.com/valitydev/woody_java</url>
+
+    <licenses>
+        <license>
+            <name>The Apache Software License, Version 2.0</name>
+            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+        </license>
+    </licenses>
+
+    <developers>
+        <developer>
+            <id>vality</id>
+            <name>Vality Developers</name>
+            <email>devs@vality.dev</email>
+            <organization>Vality</organization>
+            <organizationUrl>https://vality.dev</organizationUrl>
+        </developer>
+    </developers>
+
+    <scm>
+        <connection>scm:git:git://github.com/valitydev/woody_java.git</connection>
+        <developerConnection>scm:git:ssh://github.com/valitydev/woody_java.git</developerConnection>
+        <url>https://github.com/valitydev/woody_java/tree/master</url>
+    </scm>
+
     <properties>
         <checkstyle.skip>true</checkstyle.skip>
     </properties>