Pole C++ Thin SDK

pole-client-cpp 是框架无关的 Pole C++ Thin SDK。它只负责：

• 通过 Unix Domain Socket 与本 Pod Sidecar 建立内部双向 OpenControlSession；
• 首个服务端事件原子安装 HTTP、gRPC、Dubbo、Thrift listener 快照；
• 注册或注销本地服务；SDK 在会话重连后重放仍处于 desired 状态的注册；
• 为业务请求生成 latticehub-target-namespace 与 latticehub-target-service 元信息。

业务请求不会经过 bootstrap gRPC；应用仍按原协议访问 SDK 返回的 127.0.0.1:<listener-port>，由 Sidecar 代理到真实服务实例。

构建

仓库通过 Git submodule 固定引用官方 Specification，不复制生成代码：

git clone --recursive https://github.com/lattice-hub/pole-client-cpp.git
cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=/path/to/grpc
cmake --build build
ctest --test-dir build --output-on-failure

安装后可按标准 CMake package 引用：

find_package(PoleClientCpp CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE PoleClient::pole-client-cpp)

默认 UDS 为 /var/run/pole/sidecar/bootstrap.sock，仅支持通过 SidecarSessionOptions.socket_path 或 POLE_SIDECAR_SOCKET 覆盖。SDK 不硬编码 任何业务 listener 端口；会话断开后快照立即失效，重连并收到完整首帧后恢复。

Specification 子模块固定在正式集成提交 2642bc29c0a512f4da84ec4eb862b1e1ceee9833（develop，PR #25），该提交已包含 OpenControlSession 契约及官方 C++ 生成方式。

使用

#include <pole/client/sidecar_session.h>
#include <pole/client/target_service.h>

auto session = pole::client::SidecarSession::Connect();
const auto grpc_address = session->ListenerAddress(pole::client::Protocol::kGrpc);

const auto registration_id = session->RegisterLocalService({
    .service_namespace = "default",
    .service = "orders",
    .protocol = pole::client::Protocol::kGrpc,
    .local_port = 50051,
});
session->UnregisterLocalService(registration_id);

const pole::client::TargetService target("default", "orders");
const auto metadata = target.EncodeMetadata();

TargetService v1 只有 namespace 与 service。SDK 去除契约定义的首尾空白、 拒绝 Unicode Cc 控制字符和非法 UTF-8，并执行 canonical UTF-8 %HH 编码。

TrafficContext 在同一 TargetService::EncodeMetadata 装配点写入 W3C baggage。 对象构造后仅暴露只读 getter，非法 UTF-8、控制字符、首尾空白、超长标签和越界 bucket 无法绕过构造校验进入 attach/inject；codec 异常同时提供稳定 diagnostic code。 AttachTrafficContext 默认使用可嵌套的 thread_local scope，析构或 Reset() 后恢复旧值； 跨线程调用必须显式 capture/attach。默认构建不包含任何 OTel 头文件或链接依赖；配置 -DPOLE_CLIENT_WITH_OPENTELEMETRY=ON 后，SDK 链接 opentelemetry-cpp::api 并提供 UseOpenTelemetryTrafficContextStorage()，通过官方 RuntimeContext token 与 Baggage GetBaggage/SetBaggage 保存和恢复标签。应用仍可安装自定义 TrafficContextStorageProvider。 EncodeMetadata(..., &explicit_context) 的显式参数优先，否则读取 current；它覆盖 TargetService 内部键、保留外部 Baggage，并清理旧保留键。 traceparent 不是灰度关联键。自动框架入口 hook 不属于本次范围。