You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@iotdb.apache.org by 王旋 <cr...@gmail.com> on 2026/07/15 03:50:24 UTC

[DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Hi all,

I'd like to share a Rust client SDK for Apache IoTDB that I've been
developing, and ask for the community's feedback on whether there is
interest in bringing it into the Apache IoTDB ecosystem.

Repository: https://github.com/CritasWang/iotdb-client-rust

Scope & features

Tree model (Session) and table model (TableSession / SQL dialect),
mirroring the API shape of the Java / C# / Node.js clients
Write APIs: insertTablet / insertTablets (multi-tablet batching),
insertRecord(s), insertRecordsOfOneDevice, plus aligned variants
SessionPool and TableSessionPool: RAII checkout, lazy growth, idle
eviction, dead-connection eviction, write-redirection cache (status 400
redirect hints), automatic reconnect with endpoint failover
Full data-type coverage including TIMESTAMP / DATE / BLOB / STRING; TsBlock
decoding with logical-type re-tagging (the TsBlock header carries physical
types — DATE arrives as INT32, BLOB as TEXT)
TLS (feature-gated, incl. client identity) — verified end-to-end against a
real IoTDB with enable_thrift_ssl; RPC compression (compact protocol)
Thrift codegen pipeline sources the IDL from iotdb-protocol/ and uses the
thrift compiler fetched by the IoTDB Maven build, so the stubs stay in
lockstep with the server

Quality

113 unit tests (124 with TLS) + live integration tests that skip gracefully
without a server; CI on GitHub Actions runs fmt / clippy -D warnings /
license checks plus an integration job against an IoTDB 2.0.6 service
container — green
Statistics-aligned benchmark (measurement semantics mirror iot-benchmark:
prep inside the timed span, failures excluded from latency, Result/Latency
Matrix output). On a 16-core server writing 2B points per run (table model,
100 devices x 20 DOUBLE sensors, 1000-row tablets, 20 sessions), the Rust
client sustains ~46-47M points/s — statistically tied with iot-benchmark's
Java Session path on the same box, where the server, not the client, is the
ceiling
Every file carries the ASF Apache 2.0 header

Side effects the community already received

Cross-validating the wire protocol against the Java / C# / Node.js
implementations surfaced two upstream issues in the Node.js client, both
now addressed: the DATE wire-encoding fix (apache/iotdb-client-nodejs#14,
PR #15, merged) and a write-path serialization optimization (+52%
throughput, PR #16, under review).

Questions for the community

Is there interest in an official Rust client under the Apache IoTDB
umbrella (e.g., apache/iotdb-client-rust), following the path of the
Node.js / C# clients?
If so, what would the preferred route be — code donation via the incubator
process for client SDKs, or starting a repo under the existing project and
iterating there?
Any API-surface expectations from the PMC side before such a move (e.g.,
schema-template APIs, session-level query APIs like executeRawDataQuery)?
I'm happy to keep maintaining it either way, and to align the roadmap with
the community's priorities.

大家好

我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入 Apache
IoTDB 生态。

仓库地址:https://github.com/CritasWang/iotdb-client-rust

范围与功能

树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# / Node.js 客户端对齐
写入 API:insertTablet / insertTablets(多 tablet
批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
SessionPool 与 TableSessionPool:RAII 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status 400
重定向提示)、带端点故障转移的自动重连
完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock 解码带逻辑类型重标记(TsBlock
头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB 完成端到端验证;RPC
压缩(compact 协议)
Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven 构建拉取的版本,确保 stub
与服务端严格同步

质量

113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions CI 运行 fmt /
clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service container 的集成
job——全绿
统计口径对齐的基准测试(测量语义对齐 iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency Matrix
输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000 行/tablet、20
会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java Session
路径统计学持平,此时瓶颈在服务端而非客户端
所有文件均带 ASF Apache 2.0 头

社区已经收到的副产品

在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js 客户端的两个上游问题,目前均已处理:DATE
线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐 +52%,PR
#16,评审中)。

想请教社区的问题

社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如 apache/iotdb-client-rust),沿用
Node.js / C# 客户端的路径?
如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery 等会话级查询 API)?
无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。

Best regards,
Xuan Wang

Re: [DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Posted by Yuan Tian <ja...@gmail.com>.
Hi all,

Thank you, Xuan, for providing detailed information about the client’s
compatibility scope, code provenance, dependency licenses, maintenance
plan, and API coverage. Thanks also to Haonan for outlining the proposed
donation path.

Based on the information provided, I support accepting the Rust client as a
code donation to Apache IoTDB and developing it into an official client.
The existing functionality, tests, and CI foundation already demonstrate
its practical value. I also agree that full feature parity with the Java
client should not be a prerequisite for accepting the donation.

I have two suggestions, but I do not consider either of them a blocker for
the donation or the VOTE:

   1.

   Before the first official release, it would be helpful to formalize the
   compatibility and release policy. For example, each crate version could
   document the IoTDB IDL and Thrift compiler versions it uses; CI could
   continuously test against both the oldest supported and latest stable IoTDB
   versions; and the documentation could describe the SemVer policy,
   deprecation policy, and client/server compatibility matrix.
   2.

   After the migration to Apache, I suggest ensuring that the crates.io
   publishing permissions and release process are managed by the project
   community, with reproducible release steps and review by multiple
   maintainers. This would reduce the risks associated with relying on a
   single maintainer and help grow the maintainer community over time.

These items can be tracked as public issues or roadmap tasks after the code
is accepted. Based on the information currently available, I do not see any
issue preventing the proposal from moving forward. I support starting the
formal VOTE after leaving the DISCUSS thread open for a short feedback
period.


Best regards,

Yuan Tian

On Wed, Jul 15, 2026 at 11:50 AM 王旋 <cr...@gmail.com> wrote:

> Hi all,
>
> I'd like to share a Rust client SDK for Apache IoTDB that I've been
> developing, and ask for the community's feedback on whether there is
> interest in bringing it into the Apache IoTDB ecosystem.
>
> Repository: https://github.com/CritasWang/iotdb-client-rust
>
> Scope & features
>
> Tree model (Session) and table model (TableSession / SQL dialect),
> mirroring the API shape of the Java / C# / Node.js clients
> Write APIs: insertTablet / insertTablets (multi-tablet batching),
> insertRecord(s), insertRecordsOfOneDevice, plus aligned variants
> SessionPool and TableSessionPool: RAII checkout, lazy growth, idle
> eviction, dead-connection eviction, write-redirection cache (status 400
> redirect hints), automatic reconnect with endpoint failover
> Full data-type coverage including TIMESTAMP / DATE / BLOB / STRING; TsBlock
> decoding with logical-type re-tagging (the TsBlock header carries physical
> types — DATE arrives as INT32, BLOB as TEXT)
> TLS (feature-gated, incl. client identity) — verified end-to-end against a
> real IoTDB with enable_thrift_ssl; RPC compression (compact protocol)
> Thrift codegen pipeline sources the IDL from iotdb-protocol/ and uses the
> thrift compiler fetched by the IoTDB Maven build, so the stubs stay in
> lockstep with the server
>
> Quality
>
> 113 unit tests (124 with TLS) + live integration tests that skip gracefully
> without a server; CI on GitHub Actions runs fmt / clippy -D warnings /
> license checks plus an integration job against an IoTDB 2.0.6 service
> container — green
> Statistics-aligned benchmark (measurement semantics mirror iot-benchmark:
> prep inside the timed span, failures excluded from latency, Result/Latency
> Matrix output). On a 16-core server writing 2B points per run (table model,
> 100 devices x 20 DOUBLE sensors, 1000-row tablets, 20 sessions), the Rust
> client sustains ~46-47M points/s — statistically tied with iot-benchmark's
> Java Session path on the same box, where the server, not the client, is the
> ceiling
> Every file carries the ASF Apache 2.0 header
>
> Side effects the community already received
>
> Cross-validating the wire protocol against the Java / C# / Node.js
> implementations surfaced two upstream issues in the Node.js client, both
> now addressed: the DATE wire-encoding fix (apache/iotdb-client-nodejs#14,
> PR #15, merged) and a write-path serialization optimization (+52%
> throughput, PR #16, under review).
>
> Questions for the community
>
> Is there interest in an official Rust client under the Apache IoTDB
> umbrella (e.g., apache/iotdb-client-rust), following the path of the
> Node.js / C# clients?
> If so, what would the preferred route be — code donation via the incubator
> process for client SDKs, or starting a repo under the existing project and
> iterating there?
> Any API-surface expectations from the PMC side before such a move (e.g.,
> schema-template APIs, session-level query APIs like executeRawDataQuery)?
> I'm happy to keep maintaining it either way, and to align the roadmap with
> the community's priorities.
>
> 大家好
>
> 我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入 Apache
> IoTDB 生态。
>
> 仓库地址:https://github.com/CritasWang/iotdb-client-rust
>
> 范围与功能
>
> 树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# / Node.js 客户端对齐
> 写入 API:insertTablet / insertTablets(多 tablet
> 批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
> SessionPool 与 TableSessionPool:RAII 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status 400
> 重定向提示)、带端点故障转移的自动重连
> 完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock 解码带逻辑类型重标记(TsBlock
> 头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
> TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB 完成端到端验证;RPC
> 压缩(compact 协议)
> Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven 构建拉取的版本,确保 stub
> 与服务端严格同步
>
> 质量
>
> 113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions CI 运行 fmt /
> clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service container 的集成
> job——全绿
> 统计口径对齐的基准测试(测量语义对齐 iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency Matrix
> 输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000 行/tablet、20
> 会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java Session
> 路径统计学持平,此时瓶颈在服务端而非客户端
> 所有文件均带 ASF Apache 2.0 头
>
> 社区已经收到的副产品
>
> 在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js 客户端的两个上游问题,目前均已处理:DATE
> 线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐 +52%,PR
> #16,评审中)。
>
> 想请教社区的问题
>
> 社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如 apache/iotdb-client-rust),沿用
> Node.js / C# 客户端的路径?
> 如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
> 在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery 等会话级查询 API)?
> 无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。
>
> Best regards,
> Xuan Wang
>

Re: [DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Posted by Haonan Hou <ha...@apache.org>.
Hi Xuan,

Thank you for the detailed response. This addresses the questions I raised
and provides a clear picture of the client’s compatibility scope,
provenance, dependencies, maintenance plan, and current API coverage.

From my perspective as a PMC member, I do not see any obvious blocker to
moving this proposal toward a formal vote.

I suggest leaving this DISCUSS thread open for a short period so that other
community and PMC members can provide feedback. If no major concerns are
raised, I will start a separate [VOTE] thread to accept the code donation and
create the apache/iotdb-client-rust repository.

Thanks again for preparing all the requested information.

Best regards,
Haonan

On 2026/07/15 07:31:35 王旋 wrote:
> Hi,
> 
> Thank you very much for the supportive and detailed reply. The suggested
> route (code donation to the existing TLP + ASF IP clearance, rather than
> incubation) makes sense to me, and I'm glad full Java-parity is not a
> prerequisite — an incremental, roadmap-tracked approach matches how the
> client was built.
> 
> Below are the five items requested before a vote.
> 
> ## 1. Supported IoTDB version matrix
> 
> | IoTDB version | Status | Evidence |
> |---|---|---|
> | 2.0.6 | Supported | CI integration job runs the full live test suite + 3
> examples against apache/iotdb:2.0.6-standalone on every push |
> | 2.0.10 | Supported | Full benchmark + data-correctness verification (all
> 10 data types, tree & table, nulls) against a 2.0.10 standalone deployment |
> | 2.0.x (general) | Expected to work | Thrift IDL is synced from
> iotdb-protocol/ master; protocol version V3; no version-specific branching
> in the client |
> | 1.x | Not targeted | Table model and several data types
> (TIMESTAMP/DATE/BLOB/STRING) assume 2.x; no plan to support 1.x |
> 
> TLS was verified end-to-end against 2.0.6 with enable_thrift_ssl (TLSv1.3,
> full certificate verification). RPC compression (compact protocol) verified
> against a server with dn_rpc_thrift_compression_enable=true.
> 
> ## 2. Contributors and provenance
> 
> The entire git history has a single author — myself (Wang Xuan / CritasWang
> <cr...@outlook.com>). I am an existing Apache IoTDB committer with an ICLA
> already on file, and I hold full ownership of this work, so the provenance
> chain is straightforward. Two categories of code in the repo:
> 
> - Hand-written code: 100% original work, written for this project,
> Apache-2.0 headers on every file.
> - Generated code (src/protocol/): produced by the Apache Thrift compiler
> from the Apache IoTDB project's own IDL files (iotdb-protocol/, ALv2); the
> generation pipeline (tools/generate-thrift.sh) is documented and
> reproducible.
> 
> No code was copied from other client SDKs; the Java/C#/Node.js clients were
> used as behavioral references only (wire-protocol semantics), which is also
> how the cross-client protocol issues (e.g. the Node.js DATE encoding bug)
> were found.
> 
> ## 3. Dependency and license inventory
> 
> Runtime dependencies (4 + 1 optional):
> 
> | Crate | Version | License | Purpose |
> |---|---|---|---|
> | thrift | 0.23 | Apache-2.0 | RPC (matches the compiler version pinned by
> the IoTDB pom) |
> | byteorder | 1.5 | Unlicense OR MIT | Big-endian encoding |
> | chrono | 0.4 | MIT OR Apache-2.0 | DATE handling |
> | log | 0.4 | MIT OR Apache-2.0 | Logging facade |
> | native-tls (optional, feature "tls") | 0.2 | MIT OR Apache-2.0 | TLS |
> 
> Dev-dependency: env_logger (MIT OR Apache-2.0). Full transitive closure: 74
> packages, machine-checked — every one is MIT / Apache-2.0 / Unlicense / BSD
> / Zlib dual-or-multi licensed, i.e. 100% ASF Category-A. Zero Category-B/X,
> zero unknown-license packages. The full inventory (cargo metadata) can be
> attached to the IP-clearance checklist.
> 
> ## 4. Proposed initial maintainers and maintenance plan
> 
> - Initial maintainer: myself (CritasWang — existing IoTDB committer). I
> commit to maintaining the client — issue triage, protocol-sync with
> iotdb-protocol changes, and regular releases through the normal IoTDB
> community process — and to growing co-maintainers from the community;
> review bandwidth from other committers/PMC members on client-facing changes
> would be welcome.
> - The repo already carries the practices expected for handover: CI (fmt /
> clippy -D warnings / license check / unit tests / live integration against
> a service container), bilingual READMEs, runnable examples, a
> statistics-aligned benchmark, and a documented codegen pipeline. Nothing
> depends on my personal infrastructure.
> 
> ## 5. API support matrix (vs Java client) and near-term roadmap
> 
> Supported today (feature → Java-client equivalent):
> 
> | Area | Rust today | Java client |
> |---|---|---|
> | Session lifecycle, multi-node URLs, failover, auto-reconnect | ✅ | ✅ |
> | insertTablet / insertTablets | ✅ | ✅ |
> | insertRecord(s) / insertRecordsOfOneDevice (+ aligned variants) | ✅ | ✅ |
> | Table model (TableSession/Pool, TAG/FIELD/ATTRIBUTE) | ✅ | ✅ |
> | SessionPool / TableSessionPool (idle eviction, redirection cache) | ✅ | ✅
> |
> | Query + paging iteration (TsBlock, fetchResultsV2) | ✅ | ✅ |
> | All data types incl. TIMESTAMP/DATE/BLOB/STRING | ✅ | ✅ |
> | TLS (incl. client identity) / RPC compression | ✅ | ✅ |
> | deleteData / deleteTimeseries / DDL helpers | SQL only | ✅ dedicated APIs
> |
> | Schema templates | ❌ | ✅ |
> | executeRawDataQuery / executeLastDataQuery / aggregation APIs | ❌ | ✅ |
> | Per-type encoding tuning (RPC compression V2) | ❌ | ✅ |
> 
> Near-term roadmap (order negotiable with the community):
> 
> 1. async (tokio) API layer — most-requested Rust-ecosystem feature, kept
> out of v0.1 to keep the sync core small
> 2. crates.io releases under the Apache project
> 
> I'll keep this thread open for feedback on maintenance ownership and API
> scope as suggested. Since I'm an existing committer with an ICLA on file
> and the sole author, the IP-clearance paperwork should be light — I'm happy
> to prepare whatever the PMC deems necessary (software grant if required for
> the pre-existing external history, plus the dependency inventory above)
> whenever the community feels ready to move to a VOTE.
> 
> Best regards,
> Xuan Wang
> 
> Haonan Hou <ha...@apache.org> 于2026年7月15日周三 15:06写道:
> 
> > Hi Xuan,
> >
> > Thank you for sharing this work. The implementation already covers a
> > substantial part of the client functionality, and the test coverage, live
> > integration testing, CI setup, and benchmark results are all encouraging.
> >
> > The protocol issues and performance improvements discovered while
> > validating
> > against the other clients are also a good indication that this work can
> > benefit the broader IoTDB client ecosystem.
> >
> > As a member of the IoTDB PMC, I support bringing a well-maintained Rust
> > client
> > into the Apache IoTDB project. Based on what you have presented, I believe
> > this
> > repository is a strong candidate for donation and for becoming an official
> > IoTDB client.
> >
> > Since IoTDB is already an Apache top-level project, the appropriate route
> > should be a code donation to the existing project, followed by the ASF IP
> > clearance process, rather than incubation as a separate project.
> >
> > I suggest the following next steps:
> >
> > 1. Continue this DISCUSS thread to collect feedback from the community,
> >    especially regarding maintenance ownership and the initial API scope.
> > 2. Prepare a concise compatibility and API-support matrix against the Java
> >    client, together with a near-term roadmap.
> > 3. If there are no major concerns, start a formal PMC VOTE to accept the
> > code
> >    donation and create the apache/iotdb-client-rust repository.
> > 4. Complete the software grant, code provenance, dependency/license review,
> >    and ASF IP clearance.
> > 5. Move the code to the Apache repository and continue development and
> >    releases through the normal IoTDB community process.
> >
> > I do not think complete Java client API parity needs to be a prerequisite
> > for
> > the donation. The current functionality appears sufficient to establish a
> > useful official client. APIs such as schema-template operations and
> > additional
> > session-level query methods can be added incrementally and tracked through
> > a
> > public roadmap.
> >
> > Before moving to a vote, it would be helpful to provide:
> >
> > - The supported IoTDB version matrix.
> > - A list of contributors and confirmation of the code’s
> > ownership/provenance.
> > - A dependency and license inventory.
> > - The proposed initial maintainers and long-term maintenance plan.
> > - An API support matrix and near-term roadmap.
> >
> > Overall, I am supportive of this proposal and am willing to help move the
> > discussion and donation process forward.
> >
> > Best regards,
> > Haonan Hou
> >
> > On 2026/07/15 03:50:24 王旋 wrote:
> > > Hi all,
> > >
> > > I'd like to share a Rust client SDK for Apache IoTDB that I've been
> > > developing, and ask for the community's feedback on whether there is
> > > interest in bringing it into the Apache IoTDB ecosystem.
> > >
> > > Repository: https://github.com/CritasWang/iotdb-client-rust
> > >
> > > Scope & features
> > >
> > > Tree model (Session) and table model (TableSession / SQL dialect),
> > > mirroring the API shape of the Java / C# / Node.js clients
> > > Write APIs: insertTablet / insertTablets (multi-tablet batching),
> > > insertRecord(s), insertRecordsOfOneDevice, plus aligned variants
> > > SessionPool and TableSessionPool: RAII checkout, lazy growth, idle
> > > eviction, dead-connection eviction, write-redirection cache (status 400
> > > redirect hints), automatic reconnect with endpoint failover
> > > Full data-type coverage including TIMESTAMP / DATE / BLOB / STRING;
> > TsBlock
> > > decoding with logical-type re-tagging (the TsBlock header carries
> > physical
> > > types — DATE arrives as INT32, BLOB as TEXT)
> > > TLS (feature-gated, incl. client identity) — verified end-to-end against
> > a
> > > real IoTDB with enable_thrift_ssl; RPC compression (compact protocol)
> > > Thrift codegen pipeline sources the IDL from iotdb-protocol/ and uses the
> > > thrift compiler fetched by the IoTDB Maven build, so the stubs stay in
> > > lockstep with the server
> > >
> > > Quality
> > >
> > > 113 unit tests (124 with TLS) + live integration tests that skip
> > gracefully
> > > without a server; CI on GitHub Actions runs fmt / clippy -D warnings /
> > > license checks plus an integration job against an IoTDB 2.0.6 service
> > > container — green
> > > Statistics-aligned benchmark (measurement semantics mirror iot-benchmark:
> > > prep inside the timed span, failures excluded from latency,
> > Result/Latency
> > > Matrix output). On a 16-core server writing 2B points per run (table
> > model,
> > > 100 devices x 20 DOUBLE sensors, 1000-row tablets, 20 sessions), the Rust
> > > client sustains ~46-47M points/s — statistically tied with
> > iot-benchmark's
> > > Java Session path on the same box, where the server, not the client, is
> > the
> > > ceiling
> > > Every file carries the ASF Apache 2.0 header
> > >
> > > Side effects the community already received
> > >
> > > Cross-validating the wire protocol against the Java / C# / Node.js
> > > implementations surfaced two upstream issues in the Node.js client, both
> > > now addressed: the DATE wire-encoding fix (apache/iotdb-client-nodejs#14,
> > > PR #15, merged) and a write-path serialization optimization (+52%
> > > throughput, PR #16, under review).
> > >
> > > Questions for the community
> > >
> > > Is there interest in an official Rust client under the Apache IoTDB
> > > umbrella (e.g., apache/iotdb-client-rust), following the path of the
> > > Node.js / C# clients?
> > > If so, what would the preferred route be — code donation via the
> > incubator
> > > process for client SDKs, or starting a repo under the existing project
> > and
> > > iterating there?
> > > Any API-surface expectations from the PMC side before such a move (e.g.,
> > > schema-template APIs, session-level query APIs like executeRawDataQuery)?
> > > I'm happy to keep maintaining it either way, and to align the roadmap
> > with
> > > the community's priorities.
> > >
> > > 大家好
> > >
> > > 我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入 Apache
> > > IoTDB 生态。
> > >
> > > 仓库地址:https://github.com/CritasWang/iotdb-client-rust
> > >
> > > 范围与功能
> > >
> > > 树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# / Node.js 客户端对齐
> > > 写入 API:insertTablet / insertTablets(多 tablet
> > > 批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
> > > SessionPool 与 TableSessionPool:RAII 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status 400
> > > 重定向提示)、带端点故障转移的自动重连
> > > 完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock 解码带逻辑类型重标记(TsBlock
> > > 头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
> > > TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB 完成端到端验证;RPC
> > > 压缩(compact 协议)
> > > Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven 构建拉取的版本,确保 stub
> > > 与服务端严格同步
> > >
> > > 质量
> > >
> > > 113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions CI 运行 fmt /
> > > clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service container 的集成
> > > job——全绿
> > > 统计口径对齐的基准测试(测量语义对齐 iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency Matrix
> > > 输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000 行/tablet、20
> > > 会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java Session
> > > 路径统计学持平,此时瓶颈在服务端而非客户端
> > > 所有文件均带 ASF Apache 2.0 头
> > >
> > > 社区已经收到的副产品
> > >
> > > 在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js 客户端的两个上游问题,目前均已处理:DATE
> > > 线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐 +52%,PR
> > > #16,评审中)。
> > >
> > > 想请教社区的问题
> > >
> > > 社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如 apache/iotdb-client-rust),沿用
> > > Node.js / C# 客户端的路径?
> > > 如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
> > > 在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery 等会话级查询 API)?
> > > 无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。
> > >
> > > Best regards,
> > > Xuan Wang
> > >
> >
> 

Re: [DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Posted by 王旋 <cr...@gmail.com>.
Hi Zihan,

PR is https://github.com/apache/iotdb-client-rust/pull/11

Welcome to review

Best regards,
Xuan Wang

王旋 <cr...@gmail.com> 于2026年8月7日周五 12:28写道:

> Hi Zihan,
>
> Thank you — this is an extremely thorough review, and I've verified every
> claim against the tree. To answer your opening question first: the review
> commit faff2de is the current HEAD, so nothing here is stale. I reproduced
> the structure of all thirteen findings in source, and your mechanism
> descriptions hold line-for-line.
>
> F1 is the root cause and it's real. connect_timeout was intended to bound
> only the TCP handshake — the doc comment on
> ConnectionOptions.connect_timeout says exactly that — and per-RPC deadlines
> were simply never wired up. That intent doesn't survive contact with
> reality: a wedged read is unbounded, auto-reconnect can't fire (it only
> reacts to Error::Thrift), and drop hangs forever. I consider this a defect,
> not a contract. Plan: add a socket_timeout to ConnectionOptions applied as
> set_read_timeout/set_write_timeout on the stream in Connection::open, set a
> deadline before the TLS handshake (which will make the currently-dead
> WouldBlock arm reachable — good catch on the consequences), and make sure
> it covers the whole lifetime including sweeps and the pool-closed teardown
> path.
>
> F2 — your read is right. The RPC-on-drop was deliberate, to match the
> C#/Node SDKs' best-effort close, but with F1 present it is non-recoverable
> rather than best-effort, and I hadn't fully appreciated that a wedged
> destructor also strands the other seven sessions in a pool close and hangs
> an unwind. Once socket_timeout exists, the drop path becomes bounded, which
> I think is the right fix rather than dropping the transport without a
> closeSession — but I'm open to the alternative if you have reasons.
>
> F4–F7 — all accepted, all real. authenticate running outside the endpoint
> loop is an oversight (reconnect does the right thing; open should too).
> F5's budget-less growth failure and F6's lost-Condvar-notification are both
> legitimate; I'll fix the accounting so live is only touched under the lock.
> On F7: the acquire-side eviction loop is defensive — with
> enable_auto_reconnect = false it's the only place a dead session gets
> caught on the hot path — but you're right that it's hard to reach in
> production today; I'd rather make is_open reflect socket state than lean on
> it.
>
> F8–F13 — accepted. F8's hold-the-slot-while-reconnecting is worth fixing;
> F9 contradicts its own doc comment; F10's frame cap matches Go/C# so it's
> not a regression, but I'll look at making it configurable and draining the
> body before rejecting; F11/F12 (host-string equality,
> queue-position-not-recency) I'll fix — preferring the newest hint is
> strictly better given RedirectCache already tracks seq. F13's Duration::MAX
> panic is a fair catch; I'll saturate instead of overflowing.
>
> The two smaller observations: the fixed TTL/max_entries should become
> SessionConfig knobs — agreed, and the reason they're fixed is simply that
> they predate the config plumbing. TableSessionPool missing
> acquire_for_device is an omission, not deliberate; I'll add it so
> table-mode hints have a consumer.
>
> The "checked, nothing found" section was as valuable as the findings —
> thank you for recording it. I'll open the F1–F7 items as GitHub issues in
> the next few days and start on the socket timeout.
>
> Best regards,
> Xuan Wang
>
> Zh D <dz...@gmail.com> 于2026年8月4日周二 23:14写道:
>
>> Hi Xuan, all,
>>
>> A review of the session pool, connection lifecycle and redirect
>> handling in apache/iotdb-client-rust, at faff2de.
>>
>> I previously reviewed the Node.js client along the same axes -- pool
>> acquire/release, connection lifecycle, redirect handling -- and
>> applied the same method to the Rust implementation. Everything below
>> was read in the source and, where noted, reproduced locally against
>> a throwaway fake Thrift server (handshake answered normally, then
>> silent) or a blackhole listener. Where I only traced statically, I
>> say so.
>>
>>
>> There is no client-side time bound after the TCP handshake
>> ----------------------------------------------------------
>>
>> This is the one finding I would put first. F1, F2 and F3 below are
>> three fix points for it, kept separate because they are fixed in
>> different places, but they are one root cause.
>>
>> connect_stream (connection/mod.rs:246-261) applies connect_timeout
>> to TcpStream::connect_timeout only, which covers the TCP
>> handshake. After that, open (:180-181) sets only set_nodelay(true).
>> There is no set_read_timeout / set_write_timeout anywhere in the
>> crate and no socket2 dependency, so every Thrift read after the
>> handshake is an unbounded blocking read. ConnectionOptions
>> (:87-106) has no field for one. SessionConfig::query_timeout_ms
>> (session.rs:61-62) is a request-body field carried in
>> TSExecuteStatementReq (:840) and TSFetchResultsReq (:484) -- it is
>> enforced server-side, gives no client-side bound, and does not
>> cover openSession or closeSession. Rust's TcpStream does not enable
>> SO_KEEPALIVE by default either, so if the peer's kernel never sends
>> FIN/RST the block is unbounded in the literal sense.
>>
>> F1. Ordinary RPCs. Against a listener that completes the TCP
>> handshake and then never replies -- equivalent to a long JVM GC
>> pause, a stateful firewall silently dropping return traffic, or an
>> LB that accepts but does not forward:
>>
>> - Session::open() with connect_timeout = 200ms was still blocked
>> after 12s; the block is in the openSession read (session.rs:278),
>> past the connect timeout's scope.
>> - With a fake server that answers openSession + requestStatementId
>> normally and then goes silent, execute_non_query blocked for >8s
>> with enable_auto_reconnect = true and max_reconnect_attempts = 3.
>> The reconnect path never fired, because a wedged read produces no
>> Error::Thrift and with_retry (session.rs:349-357) only reacts to
>> errors. So auto-reconnect does not help against the one failure it
>> looks like it should cover.
>> - Control: with the port closed, the same call returned in 176us.
>> The hang is specific to "handshake succeeded, peer silent".
>>
>> Reachability is the default configuration through the public API:
>> Session::open, any RPC, TableSession::build, SessionPool::new (which
>> calls open_session() at pool.rs:150 inside the constructor when
>> min_size > 0), SessionPool::acquire. There is no escape hatch for a
>> user outside the library -- Connection's only public constructor is
>> open, and the TcpStream is never exposed.
>>
>> Question. Is the intended contract that connect_timeout bounds only
>> the TCP handshake and that per-RPC deadlines are out of scope for
>> now, or was a socket-level read timeout intended and simply not
>> wired up? Asking because several of the findings below are
>> amplifications of this one and would collapse if a socket_timeout
>> existed.
>>
>> F2. Drop, where the caller has no recourse. Three destructors send
>> RPCs that wait for a response: Drop for Session (session.rs:847) ->
>> close() (:822) -> close_session (:825); Drop for SessionPool
>> (pool.rs:392) -> close() (:307) -> serial entry.session.close() for
>> every idle session (:314-316); Drop for SessionDataSet
>> (dataset.rs:213) -> close() (:202) -> Session::close_query
>> (session.rs:500) -> close_operation. Drop for PooledSession
>> (pool.rs:427-433) is indirect: release() only issues RPCs on the
>> pool-closed branch (:370) or when the sweep expires entries
>> (:373-377); the normal return path (:372) just pushes to the idle
>> queue.
>>
>> A destructor cannot return an error, cannot be cancelled, and
>> cannot be given a timeout by the caller. The failures are also
>> swallowed (session.rs:826, pool.rs:315, :370, :376 are all let _ =
>> or log::debug!), so a wedged teardown produces neither an error nor
>> a warning. Reproduced against the same silent server:
>>
>> 1. Session::open() succeeds -- the server log shows ["openSession",
>> "requestStatementId", "closeSession"], i.e. closeSession was
>> written -- then drop(s) blocked >12s and will not return.
>> 2. SessionPool::new(min_size = 1) then drop(pool): blocked >12s at
>> pool.rs:314-316. With max_size = 8 idle sessions, the first one
>> blocks, the other seven are never attempted, and notify_all() at
>> :317 is never reached.
>> 3. pool.close() followed by a guard going out of scope: blocked
>> over 12s on the release() closed-branch at :370.
>> 4. If a panic unwind passes through a bare Session or a
>> SessionPool, the unwind never completes.
>>
>> A secondary effect on waiters, which is latency only: in close(),
>> closed = true is set inside the lock (:310) and the lock is
>> released at :312 before the blocking loop, so waiters are not stuck
>> on the mutex -- good. But notify_all() is at :317, after the
>> blocking closes. With two or more waiters parked in wait_timeout
>> (:254), the one not woken by the earlier notify_one() in release()
>> (:379) sleeps out its full acquire_timeout. Measured with
>> acquire_timeout = 4s: one waiter returned in 305ms, the other in
>> 4.004s. Both got the correct "session pool is closed" error.
>>
>> Question. Would you consider a teardown path that drops the
>> transport without waiting for closeSession, or is the best-effort
>> RPC-on-drop deliberate (matching the C#/Node SDKs)? It reads
>> deliberate -- I mostly want to flag that with F1 present it is
>> non-recoverable rather than best-effort.
>>
>> F3. TLS, where a one-line misconfiguration hangs instead of
>> erroring. Severity is lower because tls is a non-default feature.
>> At connection/mod.rs:185 the stream handed to tls_handshake is a
>> blocking socket with no read timeout, so connector.connect(domain,
>> stream) at :310 has no time bound. The comment at :312 ("Blocking
>> sockets never yield the mid-handshake variant") confirms the
>> blocking socket is intentional, which is precisely why a deadline
>> would have to be set before :310. The doc comment at :176-178 says
>> the TCP connect is bounded by connect_timeout and does not claim
>> the TLS step is, so this is an undocumented unbounded step rather
>> than a contradiction.
>>
>> Reproduced with use_ssl = true, connect_timeout = 200ms, pointed at
>> a non-TLS IoTDB RPC port. The client sends ClientHello and waits
>> for ServerHello; the server's framed transport reads the first four
>> bytes 16 03 03 00 as a frame length of 369,296,128 and waits for a
>> 369MB body. Neither side closes. Session::open() was still blocked
>> after 15s. Control: the same silent peer with tls: None returned in
>> 200.5us, so the non-TLS path is genuinely bounded and the TLS path
>> is not. The multi-endpoint failover loop in Session::open
>> (session.rs:238-247) never reaches the second endpoint, and
>> reconnect's max_reconnect_attempts / retry_interval are equally
>> never reached.
>>
>> The existing TLS tests do not cover this shape:
>> tls_dispatch_sends_client_hello (connection/mod.rs:621-643) and
>> tls_option_selects_stack_against_plain_endpoint (:646-676) both use
>> listeners that close the connection, so the client escapes on EOF
>> with Err(Error::Tls(_)). One consequence for whoever fixes this:
>> once a read timeout exists, the currently dead
>> HandshakeError::WouldBlock arm at :313-315 becomes reachable and
>> the comment at :312 stops being true.
>>
>>
>> Other findings, in brief
>> ------------------------
>>
>> Each of these was reproduced or traced the same way; I have kept
>> them to a line each rather than expanding the mechanism. Happy to
>> open any of them as separate GitHub issues if that is easier to
>> track.
>>
>> F4 (medium) session.rs:238-252, contrast :313-337 -- Session::open
>> fails over only at the TCP layer: authenticate runs outside the
>> endpoint loop, so a handshake failure returns instead of trying the
>> remaining nodes. reconnect() does the opposite. With a 3-node
>> cluster where one node accepts TCP but fails openSession, roughly
>> one open() in three fails while 2 of 3 nodes are healthy.
>>
>> F5 (medium) pool.rs:235-242, :335-343 -- acquire() spends none of
>> its acquire_timeout budget when the growth branch fails (measured
>> 198us against a 5s budget; 4136 of 4800 acquires failed instantly
>> under stress while the pool had sessions circulating), and a failed
>> USE replay in hand_out discards the remaining idle candidates.
>>
>> F6 (medium, latency only) pool.rs:238-239, :339-340, :355-356 --
>> live is decremented outside the state lock at five sites; at the
>> three above, the decremented value is exactly the predicate a parked
>> waiter re-evaluates, so a Condvar notification can be lost. The
>> comment at :121-122 no longer matches the code. Measured stalls
>> track acquire_timeout exactly (300ms -> 305ms, 1000ms -> 1.005s).
>>
>> F7 (medium, gated on enable_auto_reconnect = false)
>> session.rs:368-370, pool.rs:223-228 -- is_open() is
>> connection.is_some(), not socket state. With auto-reconnect off, a
>> dead session is reused indefinitely under load. Separately, I could
>> not construct a production path where the acquire-side eviction
>> loop evicts anything; is it defensive, or have I missed a writer?
>>
>> F8 (low-medium) session.rs:299-340, sleep at :315 -- reconnect()
>> sleeps and walks all endpoints while still holding its pool slot;
>> worst case with defaults is ~92s for three endpoints. Concurrent
>> callers get "pool exhausted", which points away from the cause.
>>
>> F9 (low) connection/mod.rs:246-256 -- connect_timeout is applied
>> per resolved address, not per endpoint, contradicting both doc
>> comments; a dual-address host multiplies every bound (measured
>> 2.0011s for two blackhole addresses at 1s each).
>>
>> F10 (low/informational) connection/mod.rs:231 -- the frame cap is
>> thrift-rs's default 16,384,000 bytes, which a conforming IoTDB
>> server can legitimately exceed. Go and C# use the same number, so
>> this is not a Rust-specific regression; the part worth attention is
>> that rejection happens before the body is drained, leaving the
>> connection desynchronized, and fetch_results does not go through
>> with_retry.
>>
>> F11 (low) pool.rs:284-286 -- redirect endpoint matching is exact
>> host-string equality with no normalization, so hostname-vs-IP
>> spelling silently disables the optimization on multi-DataNode
>> clusters. No log line, so it is invisible from outside.
>>
>> F12 (low) pool.rs:279-282 -- when idle sessions hold conflicting
>> hints for one device, the winner is queue position, not recency.
>> Within documented behaviour (:266-268 says "any idle session"), but
>> RedirectCache already tracks seq/inserted -- was preferring the
>> newest hint considered?
>>
>> F13 (low) pool.rs:207 -- acquire_timeout = Duration::MAX panics on
>> Instant + Duration overflow before the lock is taken. Narrow (100
>> years and 1000 years both work), and it matters only because there
>> is no "never time out" option and Duration::MAX is the natural way
>> to ask for one.
>>
>> Two smaller observations: RedirectCache's TTL and max_entries are
>> fixed at construction with no SessionConfig knob, which becomes
>> measurable only on large batch inserts; and TableSessionPool
>> exposes acquire() but not acquire_for_device(), so table-mode users
>> accumulate hints no pool API can consume -- deliberate?
>>
>>
>> What this implementation gets right
>> -----------------------------------
>>
>> These are the specific failure modes that bit the Node.js client,
>> absent here by construction rather than by discipline.
>>
>> The redirect design structurally avoids the Node.js endpoint-session
>> bug. Outside the generated Thrift code there is exactly one HashMap
>> -- the device-to-endpoint hint cache (redirect.rs:68). There is no
>> endPointToSession map, and Connection::open has exactly two
>> non-test call sites (session.rs:240, session.rs:319), both of which
>> only iterate config.endpoints. The client never opens a connection
>> because of a redirect. Combined with move semantics in the pool
>> (pop_front at pool.rs:223, remove(pos) at :288, push_back only
>> after the guard yields ownership at :429-431), a session cannot
>> simultaneously be in an endpoint map and in the general idle queue.
>> The comment at pool.rs:270-272 states the trade-off honestly. This
>> is the single most important thing this client does differently.
>>
>> No lock is ever held across blocking I/O. I checked every non-test
>> lock() in pool.rs: new() :151 (open is at :150, outside), acquire()
>> :208 (drops at :215 before closing swept sessions, :226/:234 before
>> hand_out), acquire_for_device() :275 (drops at :289), close() :309
>> (scope ends :312, blocking closes at :314-316), release() :365
>> (drops at :374), open_session() :324, hand_out() :334. The one
>> Session destructor that runs under the lock (:228) is a no-op
>> because connection is already None. sweep_idle being #[must_use]
>> and returning expired sessions for the caller to close outside the
>> lock (:173-176) is a deliberate, correct design.
>>
>> The borrow checker is doing real work. PooledSession<'a> borrows
>> the pool, so a guard cannot outlive it; SessionDataSet<'a> borrows
>> &mut Session, so a result set cannot outlive its session or be used
>> concurrently with another RPC; every RPC takes &mut self, which
>> makes interleaved Thrift sequence numbers on one channel impossible
>> without a runtime lock. Zero unsafe in the crate.
>>
>>
>> Checked, nothing found
>> ----------------------
>>
>> Recording these because a clean result is information too: async
>> and cancellation issues (the crate is fully synchronous -- zero
>> async fn / .await / tokio across src, tests and examples, so the
>> Node.js-shaped hypotheses are vacuous); RefCell misuse (the two
>> occurrences are unused generator imports); waiters removed on
>> timeout but still notified (no explicit waiter list exists); two
>> callers receiving the same idle session (stress-verified, 16
>> threads x 300 acquire/release, zero failures); stale-index
>> remove/pop after dropping the lock; live accounting drift and usize
>> underflow (three increments and seven decrements reconcile); mutex
>> poisoning cascades (no reachable first panic found, though the
>> chain is fragile); double closeSession / closeOperation; dangling
>> PooledSession after the pool is dropped; oversized allocation from
>> a bogus peer; min_size / max_size boundaries; spurious condvar
>> wakeups; Thrift sequence-number interleaving; Endpoint::parse edge
>> cases; and redirect interaction with reconnect.
>>
>>
>> Happy to go deeper on any of these, or to re-check a scenario if
>> you think one is a misread.
>>
>> Best regards,
>> Zihan Dai
>> GitHub: PDGGK
>>
>> On Mon, Jul 20, 2026 12:40 PM, Haonan Hou <ha...@apache.org> wrote:
>>
>> > Hi Xuan,
>> >
>> > The vote passed and the repo has been created.
>> > https://github.com/apache/iotdb-client-rust
>> >
>> > Thanks,
>> > Haonan
>> >
>> > On 2026/07/17 03:57:02 王旋 wrote:
>> > > Hi Yuan,
>> > >
>> > > Thank you for the suggestions. Status on both:
>> > >
>> > > 1. Compatibility & release policy -- now landed in the repository as
>> > > COMPATIBILITY.md <http://compatibility.md/> [1]:
>> > >
>> > > - IoTDB server compatibility matrix: 2.0.1-2.0.8, 2.0.10 and master
>> are
>> > >   listed; 2.0.6 and 2.0.10 are tested (CI live suite / full benchmark
>> +
>> > >   data-correctness verification respectively), the other versions are
>> > >   explicitly marked as untested.
>> > > - A per-release protocol toolchain table recording, for each crate
>> > >   version, the exact IDL source (currently apache/iotdb master,
>> > >   iotdb-protocol/ @ 2fedd8a395) and the Thrift compiler version
>> (0.23.0,
>> > >   as pinned by the IoTDB pom), plus the thrift crate version.
>> > > - A SemVer policy (Cargo semantics, 0.x pre-1.0 rules), a deprecation
>> > >   policy (#[deprecated] for at least one minor release before
>> removal),
>> > >   and a release checklist that updates the toolchain table on every
>> > >   release.
>> > >
>> > > CI now runs the live integration suite and examples against both the
>> > > oldest tested and the latest stable IoTDB (2.0.6 and 2.0.10) as a
>> build
>> > > matrix [2].
>> > >
>> > > 2. crates.io publishing permissions and a community-managed release
>> > > process -- fully agreed. Since this depends on the Apache repository
>> and
>> > > community processes existing first, I will file it as a roadmap issue
>> in
>> > > apache/iotdb-client-rust once the repository is created, covering
>> > > community-owned crates.io ownership, reproducible release steps, and
>> > > review by multiple maintainers.
>> > >
>> > > [1]
>> > >
>> >
>> https://github.com/CritasWang/iotdb-client-rust/blob/main/COMPATIBILITY.md
>> > > [2]
>> > >
>> >
>> https://github.com/CritasWang/iotdb-client-rust/blob/main/.github/workflows/ci.yml
>> > >
>> > > Best regards,
>> > > Xuan Wang
>> > >
>> > > zerolbsony <ze...@163.com> 于2026年7月16日周四 20:58写道:
>> > >
>> > > > Hi, Xuan Wang
>> > > > It’s hard to believe that Rust has overtaken Go and become so
>> popular.
>> > > > The top 10 programming languages in the July 2026 TIOBE rankings
>> are as
>> > > > follows:
>> > > > Python – 18.94%
>> > > > C – 10.86%
>> > > > C++ – 9.12%
>> > > > Java – 8.03%
>> > > > C# – 4.49%
>> > > > JavaScript – 2.72%
>> > > > Visual Basic – 2.48%
>> > > > SQL – 1.71%
>> > > > R – 1.69%
>> > > > Rust – 1.34%
>> > > >
>> > > >
>> > > > I’ve noticed that starting from 2024, the Linux kernel has allowed
>> > certain
>> > > > modules, primarily device drivers, to be written in Rust.
>> > > >
>> > > >
>> > > > Rust can be used to write Linux kernel modules, which means you can
>> run
>> > > > Rust code directly at the kernel level. This is extremely useful for
>> > > > scenarios that demand high performance and low-level hardware
>> > operations.
>> > > > Have you considered invoking certain IoTDB functionalities directly
>> > via the
>> > > > Linux kernel to boost performance?
>> > > > Best regards,
>> > > > Bo Li
>> > > >
>> > > >
>> > > > >Hi,
>> > > > >
>> > > > >Thank you very much for the supportive and detailed reply. The
>> > suggested
>> > > > >route (code donation to the existing TLP + ASF IP clearance, rather
>> > than
>> > > > >incubation) makes sense to me, and I'm glad full Java-parity is
>> not a
>> > > > >prerequisite — an incremental, roadmap-tracked approach matches how
>> > the
>> > > > >client was built.
>> > > > >
>> > > > >Below are the five items requested before a vote.
>> > > > >
>> > > > >## 1. Supported IoTDB version matrix
>> > > > >
>> > > > >| IoTDB version | Status | Evidence |
>> > > > >|---|---|---|
>> > > > >| 2.0.6 | Supported | CI integration job runs the full live test
>> > suite + 3
>> > > > >examples against apache/iotdb:2.0.6-standalone on every push |
>> > > > >| 2.0.10 | Supported | Full benchmark + data-correctness
>> verification
>> > (all
>> > > > >10 data types, tree & table, nulls) against a 2.0.10 standalone
>> > > > deployment |
>> > > > >| 2.0.x (general) | Expected to work | Thrift IDL is synced from
>> > > > >iotdb-protocol/ master; protocol version V3; no version-specific
>> > branching
>> > > > >in the client |
>> > > > >| 1.x | Not targeted | Table model and several data types
>> > > > >(TIMESTAMP/DATE/BLOB/STRING) assume 2.x; no plan to support 1.x |
>> > > > >
>> > > > >TLS was verified end-to-end against 2.0.6 with enable_thrift_ssl
>> > (TLSv1.3,
>> > > > >full certificate verification). RPC compression (compact protocol)
>> > > > verified
>> > > > >against a server with dn_rpc_thrift_compression_enable=true.
>> > > > >
>> > > > >## 2. Contributors and provenance
>> > > > >
>> > > > >The entire git history has a single author — myself (Wang Xuan /
>> > > > CritasWang
>> > > > ><cr...@outlook.com>). I am an existing Apache IoTDB committer
>> with
>> > an
>> > > > ICLA
>> > > > >already on file, and I hold full ownership of this work, so the
>> > provenance
>> > > > >chain is straightforward. Two categories of code in the repo:
>> > > > >
>> > > > >- Hand-written code: 100% original work, written for this project,
>> > > > >Apache-2.0 headers on every file.
>> > > > >- Generated code (src/protocol/): produced by the Apache Thrift
>> > compiler
>> > > > >from the Apache IoTDB project's own IDL files (iotdb-protocol/,
>> > ALv2); the
>> > > > >generation pipeline (tools/generate-thrift.sh) is documented and
>> > > > >reproducible.
>> > > > >
>> > > > >No code was copied from other client SDKs; the Java/C#/Node.js
>> clients
>> > > > were
>> > > > >used as behavioral references only (wire-protocol semantics),
>> which is
>> > > > also
>> > > > >how the cross-client protocol issues (e.g. the Node.js DATE
>> encoding
>> > bug)
>> > > > >were found.
>> > > > >
>> > > > >## 3. Dependency and license inventory
>> > > > >
>> > > > >Runtime dependencies (4 + 1 optional):
>> > > > >
>> > > > >| Crate | Version | License | Purpose |
>> > > > >|---|---|---|---|
>> > > > >| thrift | 0.23 | Apache-2.0 | RPC (matches the compiler version
>> > pinned by
>> > > > >the IoTDB pom) |
>> > > > >| byteorder | 1.5 | Unlicense OR MIT | Big-endian encoding |
>> > > > >| chrono | 0.4 | MIT OR Apache-2.0 | DATE handling |
>> > > > >| log | 0.4 | MIT OR Apache-2.0 | Logging facade |
>> > > > >| native-tls (optional, feature "tls") | 0.2 | MIT OR Apache-2.0 |
>> > TLS |
>> > > > >
>> > > > >Dev-dependency: env_logger (MIT OR Apache-2.0). Full transitive
>> > closure:
>> > > > 74
>> > > > >packages, machine-checked — every one is MIT / Apache-2.0 /
>> Unlicense
>> > /
>> > > > BSD
>> > > > >/ Zlib dual-or-multi licensed, i.e. 100% ASF Category-A. Zero
>> > > > Category-B/X,
>> > > > >zero unknown-license packages. The full inventory (cargo metadata)
>> > can be
>> > > > >attached to the IP-clearance checklist.
>> > > > >
>> > > > >## 4. Proposed initial maintainers and maintenance plan
>> > > > >
>> > > > >- Initial maintainer: myself (CritasWang — existing IoTDB
>> committer).
>> > I
>> > > > >commit to maintaining the client — issue triage, protocol-sync with
>> > > > >iotdb-protocol changes, and regular releases through the normal
>> IoTDB
>> > > > >community process — and to growing co-maintainers from the
>> community;
>> > > > >review bandwidth from other committers/PMC members on client-facing
>> > > > changes
>> > > > >would be welcome.
>> > > > >- The repo already carries the practices expected for handover: CI
>> > (fmt /
>> > > > >clippy -D warnings / license check / unit tests / live integration
>> > against
>> > > > >a service container), bilingual READMEs, runnable examples, a
>> > > > >statistics-aligned benchmark, and a documented codegen pipeline.
>> > Nothing
>> > > > >depends on my personal infrastructure.
>> > > > >
>> > > > >## 5. API support matrix (vs Java client) and near-term roadmap
>> > > > >
>> > > > >Supported today (feature → Java-client equivalent):
>> > > > >
>> > > > >| Area | Rust today | Java client |
>> > > > >|---|---|---|
>> > > > >| Session lifecycle, multi-node URLs, failover, auto-reconnect | ✅
>> |
>> > ✅ |
>> > > > >| insertTablet / insertTablets | ✅ | ✅ |
>> > > > >| insertRecord(s) / insertRecordsOfOneDevice (+ aligned variants)
>> | ✅
>> > | ✅
>> > > > |
>> > > > >| Table model (TableSession/Pool, TAG/FIELD/ATTRIBUTE) | ✅ | ✅ |
>> > > > >| SessionPool / TableSessionPool (idle eviction, redirection
>> cache) |
>> > ✅ |
>> > > > ✅
>> > > > >|
>> > > > >| Query + paging iteration (TsBlock, fetchResultsV2) | ✅ | ✅ |
>> > > > >| All data types incl. TIMESTAMP/DATE/BLOB/STRING | ✅ | ✅ |
>> > > > >| TLS (incl. client identity) / RPC compression | ✅ | ✅ |
>> > > > >| deleteData / deleteTimeseries / DDL helpers | SQL only | ✅
>> dedicated
>> > > > APIs
>> > > > >|
>> > > > >| Schema templates | ❌ | ✅ |
>> > > > >| executeRawDataQuery / executeLastDataQuery / aggregation APIs |
>> ❌ |
>> > ✅ |
>> > > > >| Per-type encoding tuning (RPC compression V2) | ❌ | ✅ |
>> > > > >
>> > > > >Near-term roadmap (order negotiable with the community):
>> > > > >
>> > > > >1. async (tokio) API layer — most-requested Rust-ecosystem feature,
>> > kept
>> > > > >out of v0.1 to keep the sync core small
>> > > > >2. crates.io releases under the Apache project
>> > > > >
>> > > > >I'll keep this thread open for feedback on maintenance ownership
>> and
>> > API
>> > > > >scope as suggested. Since I'm an existing committer with an ICLA on
>> > file
>> > > > >and the sole author, the IP-clearance paperwork should be light —
>> I'm
>> > > > happy
>> > > > >to prepare whatever the PMC deems necessary (software grant if
>> > required
>> > > > for
>> > > > >the pre-existing external history, plus the dependency inventory
>> > above)
>> > > > >whenever the community feels ready to move to a VOTE.
>> > > > >
>> > > > >Best regards,
>> > > > >Xuan Wang
>> > > > >
>> > > > >Haonan Hou <ha...@apache.org> 于2026年7月15日周三 15:06写道:
>> > > > >
>> > > > >> Hi Xuan,
>> > > > >>
>> > > > >> Thank you for sharing this work. The implementation already
>> covers a
>> > > > >> substantial part of the client functionality, and the test
>> coverage,
>> > > > live
>> > > > >> integration testing, CI setup, and benchmark results are all
>> > > > encouraging.
>> > > > >>
>> > > > >> The protocol issues and performance improvements discovered while
>> > > > >> validating
>> > > > >> against the other clients are also a good indication that this
>> work
>> > can
>> > > > >> benefit the broader IoTDB client ecosystem.
>> > > > >>
>> > > > >> As a member of the IoTDB PMC, I support bringing a
>> well-maintained
>> > Rust
>> > > > >> client
>> > > > >> into the Apache IoTDB project. Based on what you have presented,
>> I
>> > > > believe
>> > > > >> this
>> > > > >> repository is a strong candidate for donation and for becoming an
>> > > > official
>> > > > >> IoTDB client.
>> > > > >>
>> > > > >> Since IoTDB is already an Apache top-level project, the
>> appropriate
>> > > > route
>> > > > >> should be a code donation to the existing project, followed by
>> the
>> > ASF
>> > > > IP
>> > > > >> clearance process, rather than incubation as a separate project.
>> > > > >>
>> > > > >> I suggest the following next steps:
>> > > > >>
>> > > > >> 1. Continue this DISCUSS thread to collect feedback from the
>> > community,
>> > > > >>    especially regarding maintenance ownership and the initial API
>> > scope.
>> > > > >> 2. Prepare a concise compatibility and API-support matrix against
>> > the
>> > > > Java
>> > > > >>    client, together with a near-term roadmap.
>> > > > >> 3. If there are no major concerns, start a formal PMC VOTE to
>> > accept the
>> > > > >> code
>> > > > >>    donation and create the apache/iotdb-client-rust repository.
>> > > > >> 4. Complete the software grant, code provenance,
>> dependency/license
>> > > > review,
>> > > > >>    and ASF IP clearance.
>> > > > >> 5. Move the code to the Apache repository and continue
>> development
>> > and
>> > > > >>    releases through the normal IoTDB community process.
>> > > > >>
>> > > > >> I do not think complete Java client API parity needs to be a
>> > > > prerequisite
>> > > > >> for
>> > > > >> the donation. The current functionality appears sufficient to
>> > establish
>> > > > a
>> > > > >> useful official client. APIs such as schema-template operations
>> and
>> > > > >> additional
>> > > > >> session-level query methods can be added incrementally and
>> tracked
>> > > > through
>> > > > >> a
>> > > > >> public roadmap.
>> > > > >>
>> > > > >> Before moving to a vote, it would be helpful to provide:
>> > > > >>
>> > > > >> - The supported IoTDB version matrix.
>> > > > >> - A list of contributors and confirmation of the code’s
>> > > > >> ownership/provenance.
>> > > > >> - A dependency and license inventory.
>> > > > >> - The proposed initial maintainers and long-term maintenance
>> plan.
>> > > > >> - An API support matrix and near-term roadmap.
>> > > > >>
>> > > > >> Overall, I am supportive of this proposal and am willing to help
>> > move
>> > > > the
>> > > > >> discussion and donation process forward.
>> > > > >>
>> > > > >> Best regards,
>> > > > >> Haonan Hou
>> > > > >>
>> > > > >> On 2026/07/15 03:50:24 王旋 wrote:
>> > > > >> > Hi all,
>> > > > >> >
>> > > > >> > I'd like to share a Rust client SDK for Apache IoTDB that I've
>> > been
>> > > > >> > developing, and ask for the community's feedback on whether
>> there
>> > is
>> > > > >> > interest in bringing it into the Apache IoTDB ecosystem.
>> > > > >> >
>> > > > >> > Repository: https://github.com/CritasWang/iotdb-client-rust
>> > > > >> >
>> > > > >> > Scope & features
>> > > > >> >
>> > > > >> > Tree model (Session) and table model (TableSession / SQL
>> dialect),
>> > > > >> > mirroring the API shape of the Java / C# / Node.js clients
>> > > > >> > Write APIs: insertTablet / insertTablets (multi-tablet
>> batching),
>> > > > >> > insertRecord(s), insertRecordsOfOneDevice, plus aligned
>> variants
>> > > > >> > SessionPool and TableSessionPool: RAII checkout, lazy growth,
>> idle
>> > > > >> > eviction, dead-connection eviction, write-redirection cache
>> > (status
>> > > > 400
>> > > > >> > redirect hints), automatic reconnect with endpoint failover
>> > > > >> > Full data-type coverage including TIMESTAMP / DATE / BLOB /
>> > STRING;
>> > > > >> TsBlock
>> > > > >> > decoding with logical-type re-tagging (the TsBlock header
>> carries
>> > > > >> physical
>> > > > >> > types — DATE arrives as INT32, BLOB as TEXT)
>> > > > >> > TLS (feature-gated, incl. client identity) — verified
>> end-to-end
>> > > > against
>> > > > >> a
>> > > > >> > real IoTDB with enable_thrift_ssl; RPC compression (compact
>> > protocol)
>> > > > >> > Thrift codegen pipeline sources the IDL from iotdb-protocol/
>> and
>> > uses
>> > > > the
>> > > > >> > thrift compiler fetched by the IoTDB Maven build, so the stubs
>> > stay in
>> > > > >> > lockstep with the server
>> > > > >> >
>> > > > >> > Quality
>> > > > >> >
>> > > > >> > 113 unit tests (124 with TLS) + live integration tests that
>> skip
>> > > > >> gracefully
>> > > > >> > without a server; CI on GitHub Actions runs fmt / clippy -D
>> > warnings /
>> > > > >> > license checks plus an integration job against an IoTDB 2.0.6
>> > service
>> > > > >> > container — green
>> > > > >> > Statistics-aligned benchmark (measurement semantics mirror
>> > > > iot-benchmark:
>> > > > >> > prep inside the timed span, failures excluded from latency,
>> > > > >> Result/Latency
>> > > > >> > Matrix output). On a 16-core server writing 2B points per run
>> > (table
>> > > > >> model,
>> > > > >> > 100 devices x 20 DOUBLE sensors, 1000-row tablets, 20
>> sessions),
>> > the
>> > > > Rust
>> > > > >> > client sustains ~46-47M points/s — statistically tied with
>> > > > >> iot-benchmark's
>> > > > >> > Java Session path on the same box, where the server, not the
>> > client,
>> > > > is
>> > > > >> the
>> > > > >> > ceiling
>> > > > >> > Every file carries the ASF Apache 2.0 header
>> > > > >> >
>> > > > >> > Side effects the community already received
>> > > > >> >
>> > > > >> > Cross-validating the wire protocol against the Java / C# /
>> Node.js
>> > > > >> > implementations surfaced two upstream issues in the Node.js
>> > client,
>> > > > both
>> > > > >> > now addressed: the DATE wire-encoding fix
>> > > > (apache/iotdb-client-nodejs#14,
>> > > > >> > PR #15, merged) and a write-path serialization optimization
>> (+52%
>> > > > >> > throughput, PR #16, under review).
>> > > > >> >
>> > > > >> > Questions for the community
>> > > > >> >
>> > > > >> > Is there interest in an official Rust client under the Apache
>> > IoTDB
>> > > > >> > umbrella (e.g., apache/iotdb-client-rust), following the path
>> of
>> > the
>> > > > >> > Node.js / C# clients?
>> > > > >> > If so, what would the preferred route be — code donation via
>> the
>> > > > >> incubator
>> > > > >> > process for client SDKs, or starting a repo under the existing
>> > project
>> > > > >> and
>> > > > >> > iterating there?
>> > > > >> > Any API-surface expectations from the PMC side before such a
>> move
>> > > > (e.g.,
>> > > > >> > schema-template APIs, session-level query APIs like
>> > > > executeRawDataQuery)?
>> > > > >> > I'm happy to keep maintaining it either way, and to align the
>> > roadmap
>> > > > >> with
>> > > > >> > the community's priorities.
>> > > > >> >
>> > > > >> > 大家好
>> > > > >> >
>> > > > >> > 我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入
>> > Apache
>> > > > >> > IoTDB 生态。
>> > > > >> >
>> > > > >> > 仓库地址:https://github.com/CritasWang/iotdb-client-rust
>> > > > >> >
>> > > > >> > 范围与功能
>> > > > >> >
>> > > > >> > 树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# /
>> > Node.js
>> > > > 客户端对齐
>> > > > >> > 写入 API:insertTablet / insertTablets(多 tablet
>> > > > >> > 批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
>> > > > >> > SessionPool 与 TableSessionPool:RAII
>> > 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status
>> > > > 400
>> > > > >> > 重定向提示)、带端点故障转移的自动重连
>> > > > >> > 完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock
>> > > > 解码带逻辑类型重标记(TsBlock
>> > > > >> > 头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
>> > > > >> > TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB
>> > 完成端到端验证;RPC
>> > > > >> > 压缩(compact 协议)
>> > > > >> > Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven
>> 构建拉取的版本,确保
>> > > > stub
>> > > > >> > 与服务端严格同步
>> > > > >> >
>> > > > >> > 质量
>> > > > >> >
>> > > > >> > 113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions
>> CI
>> > 运行
>> > > > fmt /
>> > > > >> > clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service
>> > container 的集成
>> > > > >> > job——全绿
>> > > > >> > 统计口径对齐的基准测试(测量语义对齐
>> iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency
>> > > > Matrix
>> > > > >> > 输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000
>> > 行/tablet、20
>> > > > >> > 会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java
>> Session
>> > > > >> > 路径统计学持平,此时瓶颈在服务端而非客户端
>> > > > >> > 所有文件均带 ASF Apache 2.0 头
>> > > > >> >
>> > > > >> > 社区已经收到的副产品
>> > > > >> >
>> > > > >> > 在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js
>> > > > 客户端的两个上游问题,目前均已处理:DATE
>> > > > >> > 线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐
>> > +52%,PR
>> > > > >> > #16,评审中)。
>> > > > >> >
>> > > > >> > 想请教社区的问题
>> > > > >> >
>> > > > >> > 社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如
>> > apache/iotdb-client-rust),沿用
>> > > > >> > Node.js / C# 客户端的路径?
>> > > > >> > 如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
>> > > > >> > 在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery
>> > 等会话级查询
>> > > > API)?
>> > > > >> > 无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。
>> > > > >> >
>> > > > >> > Best regards,
>> > > > >> > Xuan Wang
>> > > > >> >
>> > > > >>
>> > > >
>> > >
>> >
>>
>

Re: [DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Posted by 王旋 <cr...@gmail.com>.
Hi Zihan,

Thank you — this is an extremely thorough review, and I've verified every
claim against the tree. To answer your opening question first: the review
commit faff2de is the current HEAD, so nothing here is stale. I reproduced
the structure of all thirteen findings in source, and your mechanism
descriptions hold line-for-line.

F1 is the root cause and it's real. connect_timeout was intended to bound
only the TCP handshake — the doc comment on
ConnectionOptions.connect_timeout says exactly that — and per-RPC deadlines
were simply never wired up. That intent doesn't survive contact with
reality: a wedged read is unbounded, auto-reconnect can't fire (it only
reacts to Error::Thrift), and drop hangs forever. I consider this a defect,
not a contract. Plan: add a socket_timeout to ConnectionOptions applied as
set_read_timeout/set_write_timeout on the stream in Connection::open, set a
deadline before the TLS handshake (which will make the currently-dead
WouldBlock arm reachable — good catch on the consequences), and make sure
it covers the whole lifetime including sweeps and the pool-closed teardown
path.

F2 — your read is right. The RPC-on-drop was deliberate, to match the
C#/Node SDKs' best-effort close, but with F1 present it is non-recoverable
rather than best-effort, and I hadn't fully appreciated that a wedged
destructor also strands the other seven sessions in a pool close and hangs
an unwind. Once socket_timeout exists, the drop path becomes bounded, which
I think is the right fix rather than dropping the transport without a
closeSession — but I'm open to the alternative if you have reasons.

F4–F7 — all accepted, all real. authenticate running outside the endpoint
loop is an oversight (reconnect does the right thing; open should too).
F5's budget-less growth failure and F6's lost-Condvar-notification are both
legitimate; I'll fix the accounting so live is only touched under the lock.
On F7: the acquire-side eviction loop is defensive — with
enable_auto_reconnect = false it's the only place a dead session gets
caught on the hot path — but you're right that it's hard to reach in
production today; I'd rather make is_open reflect socket state than lean on
it.

F8–F13 — accepted. F8's hold-the-slot-while-reconnecting is worth fixing;
F9 contradicts its own doc comment; F10's frame cap matches Go/C# so it's
not a regression, but I'll look at making it configurable and draining the
body before rejecting; F11/F12 (host-string equality,
queue-position-not-recency) I'll fix — preferring the newest hint is
strictly better given RedirectCache already tracks seq. F13's Duration::MAX
panic is a fair catch; I'll saturate instead of overflowing.

The two smaller observations: the fixed TTL/max_entries should become
SessionConfig knobs — agreed, and the reason they're fixed is simply that
they predate the config plumbing. TableSessionPool missing
acquire_for_device is an omission, not deliberate; I'll add it so
table-mode hints have a consumer.

The "checked, nothing found" section was as valuable as the findings —
thank you for recording it. I'll open the F1–F7 items as GitHub issues in
the next few days and start on the socket timeout.

Best regards,
Xuan Wang

Zh D <dz...@gmail.com> 于2026年8月4日周二 23:14写道:

> Hi Xuan, all,
>
> A review of the session pool, connection lifecycle and redirect
> handling in apache/iotdb-client-rust, at faff2de.
>
> I previously reviewed the Node.js client along the same axes -- pool
> acquire/release, connection lifecycle, redirect handling -- and
> applied the same method to the Rust implementation. Everything below
> was read in the source and, where noted, reproduced locally against
> a throwaway fake Thrift server (handshake answered normally, then
> silent) or a blackhole listener. Where I only traced statically, I
> say so.
>
>
> There is no client-side time bound after the TCP handshake
> ----------------------------------------------------------
>
> This is the one finding I would put first. F1, F2 and F3 below are
> three fix points for it, kept separate because they are fixed in
> different places, but they are one root cause.
>
> connect_stream (connection/mod.rs:246-261) applies connect_timeout
> to TcpStream::connect_timeout only, which covers the TCP
> handshake. After that, open (:180-181) sets only set_nodelay(true).
> There is no set_read_timeout / set_write_timeout anywhere in the
> crate and no socket2 dependency, so every Thrift read after the
> handshake is an unbounded blocking read. ConnectionOptions
> (:87-106) has no field for one. SessionConfig::query_timeout_ms
> (session.rs:61-62) is a request-body field carried in
> TSExecuteStatementReq (:840) and TSFetchResultsReq (:484) -- it is
> enforced server-side, gives no client-side bound, and does not
> cover openSession or closeSession. Rust's TcpStream does not enable
> SO_KEEPALIVE by default either, so if the peer's kernel never sends
> FIN/RST the block is unbounded in the literal sense.
>
> F1. Ordinary RPCs. Against a listener that completes the TCP
> handshake and then never replies -- equivalent to a long JVM GC
> pause, a stateful firewall silently dropping return traffic, or an
> LB that accepts but does not forward:
>
> - Session::open() with connect_timeout = 200ms was still blocked
> after 12s; the block is in the openSession read (session.rs:278),
> past the connect timeout's scope.
> - With a fake server that answers openSession + requestStatementId
> normally and then goes silent, execute_non_query blocked for >8s
> with enable_auto_reconnect = true and max_reconnect_attempts = 3.
> The reconnect path never fired, because a wedged read produces no
> Error::Thrift and with_retry (session.rs:349-357) only reacts to
> errors. So auto-reconnect does not help against the one failure it
> looks like it should cover.
> - Control: with the port closed, the same call returned in 176us.
> The hang is specific to "handshake succeeded, peer silent".
>
> Reachability is the default configuration through the public API:
> Session::open, any RPC, TableSession::build, SessionPool::new (which
> calls open_session() at pool.rs:150 inside the constructor when
> min_size > 0), SessionPool::acquire. There is no escape hatch for a
> user outside the library -- Connection's only public constructor is
> open, and the TcpStream is never exposed.
>
> Question. Is the intended contract that connect_timeout bounds only
> the TCP handshake and that per-RPC deadlines are out of scope for
> now, or was a socket-level read timeout intended and simply not
> wired up? Asking because several of the findings below are
> amplifications of this one and would collapse if a socket_timeout
> existed.
>
> F2. Drop, where the caller has no recourse. Three destructors send
> RPCs that wait for a response: Drop for Session (session.rs:847) ->
> close() (:822) -> close_session (:825); Drop for SessionPool
> (pool.rs:392) -> close() (:307) -> serial entry.session.close() for
> every idle session (:314-316); Drop for SessionDataSet
> (dataset.rs:213) -> close() (:202) -> Session::close_query
> (session.rs:500) -> close_operation. Drop for PooledSession
> (pool.rs:427-433) is indirect: release() only issues RPCs on the
> pool-closed branch (:370) or when the sweep expires entries
> (:373-377); the normal return path (:372) just pushes to the idle
> queue.
>
> A destructor cannot return an error, cannot be cancelled, and
> cannot be given a timeout by the caller. The failures are also
> swallowed (session.rs:826, pool.rs:315, :370, :376 are all let _ =
> or log::debug!), so a wedged teardown produces neither an error nor
> a warning. Reproduced against the same silent server:
>
> 1. Session::open() succeeds -- the server log shows ["openSession",
> "requestStatementId", "closeSession"], i.e. closeSession was
> written -- then drop(s) blocked >12s and will not return.
> 2. SessionPool::new(min_size = 1) then drop(pool): blocked >12s at
> pool.rs:314-316. With max_size = 8 idle sessions, the first one
> blocks, the other seven are never attempted, and notify_all() at
> :317 is never reached.
> 3. pool.close() followed by a guard going out of scope: blocked
> over 12s on the release() closed-branch at :370.
> 4. If a panic unwind passes through a bare Session or a
> SessionPool, the unwind never completes.
>
> A secondary effect on waiters, which is latency only: in close(),
> closed = true is set inside the lock (:310) and the lock is
> released at :312 before the blocking loop, so waiters are not stuck
> on the mutex -- good. But notify_all() is at :317, after the
> blocking closes. With two or more waiters parked in wait_timeout
> (:254), the one not woken by the earlier notify_one() in release()
> (:379) sleeps out its full acquire_timeout. Measured with
> acquire_timeout = 4s: one waiter returned in 305ms, the other in
> 4.004s. Both got the correct "session pool is closed" error.
>
> Question. Would you consider a teardown path that drops the
> transport without waiting for closeSession, or is the best-effort
> RPC-on-drop deliberate (matching the C#/Node SDKs)? It reads
> deliberate -- I mostly want to flag that with F1 present it is
> non-recoverable rather than best-effort.
>
> F3. TLS, where a one-line misconfiguration hangs instead of
> erroring. Severity is lower because tls is a non-default feature.
> At connection/mod.rs:185 the stream handed to tls_handshake is a
> blocking socket with no read timeout, so connector.connect(domain,
> stream) at :310 has no time bound. The comment at :312 ("Blocking
> sockets never yield the mid-handshake variant") confirms the
> blocking socket is intentional, which is precisely why a deadline
> would have to be set before :310. The doc comment at :176-178 says
> the TCP connect is bounded by connect_timeout and does not claim
> the TLS step is, so this is an undocumented unbounded step rather
> than a contradiction.
>
> Reproduced with use_ssl = true, connect_timeout = 200ms, pointed at
> a non-TLS IoTDB RPC port. The client sends ClientHello and waits
> for ServerHello; the server's framed transport reads the first four
> bytes 16 03 03 00 as a frame length of 369,296,128 and waits for a
> 369MB body. Neither side closes. Session::open() was still blocked
> after 15s. Control: the same silent peer with tls: None returned in
> 200.5us, so the non-TLS path is genuinely bounded and the TLS path
> is not. The multi-endpoint failover loop in Session::open
> (session.rs:238-247) never reaches the second endpoint, and
> reconnect's max_reconnect_attempts / retry_interval are equally
> never reached.
>
> The existing TLS tests do not cover this shape:
> tls_dispatch_sends_client_hello (connection/mod.rs:621-643) and
> tls_option_selects_stack_against_plain_endpoint (:646-676) both use
> listeners that close the connection, so the client escapes on EOF
> with Err(Error::Tls(_)). One consequence for whoever fixes this:
> once a read timeout exists, the currently dead
> HandshakeError::WouldBlock arm at :313-315 becomes reachable and
> the comment at :312 stops being true.
>
>
> Other findings, in brief
> ------------------------
>
> Each of these was reproduced or traced the same way; I have kept
> them to a line each rather than expanding the mechanism. Happy to
> open any of them as separate GitHub issues if that is easier to
> track.
>
> F4 (medium) session.rs:238-252, contrast :313-337 -- Session::open
> fails over only at the TCP layer: authenticate runs outside the
> endpoint loop, so a handshake failure returns instead of trying the
> remaining nodes. reconnect() does the opposite. With a 3-node
> cluster where one node accepts TCP but fails openSession, roughly
> one open() in three fails while 2 of 3 nodes are healthy.
>
> F5 (medium) pool.rs:235-242, :335-343 -- acquire() spends none of
> its acquire_timeout budget when the growth branch fails (measured
> 198us against a 5s budget; 4136 of 4800 acquires failed instantly
> under stress while the pool had sessions circulating), and a failed
> USE replay in hand_out discards the remaining idle candidates.
>
> F6 (medium, latency only) pool.rs:238-239, :339-340, :355-356 --
> live is decremented outside the state lock at five sites; at the
> three above, the decremented value is exactly the predicate a parked
> waiter re-evaluates, so a Condvar notification can be lost. The
> comment at :121-122 no longer matches the code. Measured stalls
> track acquire_timeout exactly (300ms -> 305ms, 1000ms -> 1.005s).
>
> F7 (medium, gated on enable_auto_reconnect = false)
> session.rs:368-370, pool.rs:223-228 -- is_open() is
> connection.is_some(), not socket state. With auto-reconnect off, a
> dead session is reused indefinitely under load. Separately, I could
> not construct a production path where the acquire-side eviction
> loop evicts anything; is it defensive, or have I missed a writer?
>
> F8 (low-medium) session.rs:299-340, sleep at :315 -- reconnect()
> sleeps and walks all endpoints while still holding its pool slot;
> worst case with defaults is ~92s for three endpoints. Concurrent
> callers get "pool exhausted", which points away from the cause.
>
> F9 (low) connection/mod.rs:246-256 -- connect_timeout is applied
> per resolved address, not per endpoint, contradicting both doc
> comments; a dual-address host multiplies every bound (measured
> 2.0011s for two blackhole addresses at 1s each).
>
> F10 (low/informational) connection/mod.rs:231 -- the frame cap is
> thrift-rs's default 16,384,000 bytes, which a conforming IoTDB
> server can legitimately exceed. Go and C# use the same number, so
> this is not a Rust-specific regression; the part worth attention is
> that rejection happens before the body is drained, leaving the
> connection desynchronized, and fetch_results does not go through
> with_retry.
>
> F11 (low) pool.rs:284-286 -- redirect endpoint matching is exact
> host-string equality with no normalization, so hostname-vs-IP
> spelling silently disables the optimization on multi-DataNode
> clusters. No log line, so it is invisible from outside.
>
> F12 (low) pool.rs:279-282 -- when idle sessions hold conflicting
> hints for one device, the winner is queue position, not recency.
> Within documented behaviour (:266-268 says "any idle session"), but
> RedirectCache already tracks seq/inserted -- was preferring the
> newest hint considered?
>
> F13 (low) pool.rs:207 -- acquire_timeout = Duration::MAX panics on
> Instant + Duration overflow before the lock is taken. Narrow (100
> years and 1000 years both work), and it matters only because there
> is no "never time out" option and Duration::MAX is the natural way
> to ask for one.
>
> Two smaller observations: RedirectCache's TTL and max_entries are
> fixed at construction with no SessionConfig knob, which becomes
> measurable only on large batch inserts; and TableSessionPool
> exposes acquire() but not acquire_for_device(), so table-mode users
> accumulate hints no pool API can consume -- deliberate?
>
>
> What this implementation gets right
> -----------------------------------
>
> These are the specific failure modes that bit the Node.js client,
> absent here by construction rather than by discipline.
>
> The redirect design structurally avoids the Node.js endpoint-session
> bug. Outside the generated Thrift code there is exactly one HashMap
> -- the device-to-endpoint hint cache (redirect.rs:68). There is no
> endPointToSession map, and Connection::open has exactly two
> non-test call sites (session.rs:240, session.rs:319), both of which
> only iterate config.endpoints. The client never opens a connection
> because of a redirect. Combined with move semantics in the pool
> (pop_front at pool.rs:223, remove(pos) at :288, push_back only
> after the guard yields ownership at :429-431), a session cannot
> simultaneously be in an endpoint map and in the general idle queue.
> The comment at pool.rs:270-272 states the trade-off honestly. This
> is the single most important thing this client does differently.
>
> No lock is ever held across blocking I/O. I checked every non-test
> lock() in pool.rs: new() :151 (open is at :150, outside), acquire()
> :208 (drops at :215 before closing swept sessions, :226/:234 before
> hand_out), acquire_for_device() :275 (drops at :289), close() :309
> (scope ends :312, blocking closes at :314-316), release() :365
> (drops at :374), open_session() :324, hand_out() :334. The one
> Session destructor that runs under the lock (:228) is a no-op
> because connection is already None. sweep_idle being #[must_use]
> and returning expired sessions for the caller to close outside the
> lock (:173-176) is a deliberate, correct design.
>
> The borrow checker is doing real work. PooledSession<'a> borrows
> the pool, so a guard cannot outlive it; SessionDataSet<'a> borrows
> &mut Session, so a result set cannot outlive its session or be used
> concurrently with another RPC; every RPC takes &mut self, which
> makes interleaved Thrift sequence numbers on one channel impossible
> without a runtime lock. Zero unsafe in the crate.
>
>
> Checked, nothing found
> ----------------------
>
> Recording these because a clean result is information too: async
> and cancellation issues (the crate is fully synchronous -- zero
> async fn / .await / tokio across src, tests and examples, so the
> Node.js-shaped hypotheses are vacuous); RefCell misuse (the two
> occurrences are unused generator imports); waiters removed on
> timeout but still notified (no explicit waiter list exists); two
> callers receiving the same idle session (stress-verified, 16
> threads x 300 acquire/release, zero failures); stale-index
> remove/pop after dropping the lock; live accounting drift and usize
> underflow (three increments and seven decrements reconcile); mutex
> poisoning cascades (no reachable first panic found, though the
> chain is fragile); double closeSession / closeOperation; dangling
> PooledSession after the pool is dropped; oversized allocation from
> a bogus peer; min_size / max_size boundaries; spurious condvar
> wakeups; Thrift sequence-number interleaving; Endpoint::parse edge
> cases; and redirect interaction with reconnect.
>
>
> Happy to go deeper on any of these, or to re-check a scenario if
> you think one is a misread.
>
> Best regards,
> Zihan Dai
> GitHub: PDGGK
>
> On Mon, Jul 20, 2026 12:40 PM, Haonan Hou <ha...@apache.org> wrote:
>
> > Hi Xuan,
> >
> > The vote passed and the repo has been created.
> > https://github.com/apache/iotdb-client-rust
> >
> > Thanks,
> > Haonan
> >
> > On 2026/07/17 03:57:02 王旋 wrote:
> > > Hi Yuan,
> > >
> > > Thank you for the suggestions. Status on both:
> > >
> > > 1. Compatibility & release policy -- now landed in the repository as
> > > COMPATIBILITY.md <http://compatibility.md/> [1]:
> > >
> > > - IoTDB server compatibility matrix: 2.0.1-2.0.8, 2.0.10 and master are
> > >   listed; 2.0.6 and 2.0.10 are tested (CI live suite / full benchmark +
> > >   data-correctness verification respectively), the other versions are
> > >   explicitly marked as untested.
> > > - A per-release protocol toolchain table recording, for each crate
> > >   version, the exact IDL source (currently apache/iotdb master,
> > >   iotdb-protocol/ @ 2fedd8a395) and the Thrift compiler version
> (0.23.0,
> > >   as pinned by the IoTDB pom), plus the thrift crate version.
> > > - A SemVer policy (Cargo semantics, 0.x pre-1.0 rules), a deprecation
> > >   policy (#[deprecated] for at least one minor release before removal),
> > >   and a release checklist that updates the toolchain table on every
> > >   release.
> > >
> > > CI now runs the live integration suite and examples against both the
> > > oldest tested and the latest stable IoTDB (2.0.6 and 2.0.10) as a build
> > > matrix [2].
> > >
> > > 2. crates.io publishing permissions and a community-managed release
> > > process -- fully agreed. Since this depends on the Apache repository
> and
> > > community processes existing first, I will file it as a roadmap issue
> in
> > > apache/iotdb-client-rust once the repository is created, covering
> > > community-owned crates.io ownership, reproducible release steps, and
> > > review by multiple maintainers.
> > >
> > > [1]
> > >
> >
> https://github.com/CritasWang/iotdb-client-rust/blob/main/COMPATIBILITY.md
> > > [2]
> > >
> >
> https://github.com/CritasWang/iotdb-client-rust/blob/main/.github/workflows/ci.yml
> > >
> > > Best regards,
> > > Xuan Wang
> > >
> > > zerolbsony <ze...@163.com> 于2026年7月16日周四 20:58写道:
> > >
> > > > Hi, Xuan Wang
> > > > It’s hard to believe that Rust has overtaken Go and become so
> popular.
> > > > The top 10 programming languages in the July 2026 TIOBE rankings are
> as
> > > > follows:
> > > > Python – 18.94%
> > > > C – 10.86%
> > > > C++ – 9.12%
> > > > Java – 8.03%
> > > > C# – 4.49%
> > > > JavaScript – 2.72%
> > > > Visual Basic – 2.48%
> > > > SQL – 1.71%
> > > > R – 1.69%
> > > > Rust – 1.34%
> > > >
> > > >
> > > > I’ve noticed that starting from 2024, the Linux kernel has allowed
> > certain
> > > > modules, primarily device drivers, to be written in Rust.
> > > >
> > > >
> > > > Rust can be used to write Linux kernel modules, which means you can
> run
> > > > Rust code directly at the kernel level. This is extremely useful for
> > > > scenarios that demand high performance and low-level hardware
> > operations.
> > > > Have you considered invoking certain IoTDB functionalities directly
> > via the
> > > > Linux kernel to boost performance?
> > > > Best regards,
> > > > Bo Li
> > > >
> > > >
> > > > >Hi,
> > > > >
> > > > >Thank you very much for the supportive and detailed reply. The
> > suggested
> > > > >route (code donation to the existing TLP + ASF IP clearance, rather
> > than
> > > > >incubation) makes sense to me, and I'm glad full Java-parity is not
> a
> > > > >prerequisite — an incremental, roadmap-tracked approach matches how
> > the
> > > > >client was built.
> > > > >
> > > > >Below are the five items requested before a vote.
> > > > >
> > > > >## 1. Supported IoTDB version matrix
> > > > >
> > > > >| IoTDB version | Status | Evidence |
> > > > >|---|---|---|
> > > > >| 2.0.6 | Supported | CI integration job runs the full live test
> > suite + 3
> > > > >examples against apache/iotdb:2.0.6-standalone on every push |
> > > > >| 2.0.10 | Supported | Full benchmark + data-correctness
> verification
> > (all
> > > > >10 data types, tree & table, nulls) against a 2.0.10 standalone
> > > > deployment |
> > > > >| 2.0.x (general) | Expected to work | Thrift IDL is synced from
> > > > >iotdb-protocol/ master; protocol version V3; no version-specific
> > branching
> > > > >in the client |
> > > > >| 1.x | Not targeted | Table model and several data types
> > > > >(TIMESTAMP/DATE/BLOB/STRING) assume 2.x; no plan to support 1.x |
> > > > >
> > > > >TLS was verified end-to-end against 2.0.6 with enable_thrift_ssl
> > (TLSv1.3,
> > > > >full certificate verification). RPC compression (compact protocol)
> > > > verified
> > > > >against a server with dn_rpc_thrift_compression_enable=true.
> > > > >
> > > > >## 2. Contributors and provenance
> > > > >
> > > > >The entire git history has a single author — myself (Wang Xuan /
> > > > CritasWang
> > > > ><cr...@outlook.com>). I am an existing Apache IoTDB committer with
> > an
> > > > ICLA
> > > > >already on file, and I hold full ownership of this work, so the
> > provenance
> > > > >chain is straightforward. Two categories of code in the repo:
> > > > >
> > > > >- Hand-written code: 100% original work, written for this project,
> > > > >Apache-2.0 headers on every file.
> > > > >- Generated code (src/protocol/): produced by the Apache Thrift
> > compiler
> > > > >from the Apache IoTDB project's own IDL files (iotdb-protocol/,
> > ALv2); the
> > > > >generation pipeline (tools/generate-thrift.sh) is documented and
> > > > >reproducible.
> > > > >
> > > > >No code was copied from other client SDKs; the Java/C#/Node.js
> clients
> > > > were
> > > > >used as behavioral references only (wire-protocol semantics), which
> is
> > > > also
> > > > >how the cross-client protocol issues (e.g. the Node.js DATE encoding
> > bug)
> > > > >were found.
> > > > >
> > > > >## 3. Dependency and license inventory
> > > > >
> > > > >Runtime dependencies (4 + 1 optional):
> > > > >
> > > > >| Crate | Version | License | Purpose |
> > > > >|---|---|---|---|
> > > > >| thrift | 0.23 | Apache-2.0 | RPC (matches the compiler version
> > pinned by
> > > > >the IoTDB pom) |
> > > > >| byteorder | 1.5 | Unlicense OR MIT | Big-endian encoding |
> > > > >| chrono | 0.4 | MIT OR Apache-2.0 | DATE handling |
> > > > >| log | 0.4 | MIT OR Apache-2.0 | Logging facade |
> > > > >| native-tls (optional, feature "tls") | 0.2 | MIT OR Apache-2.0 |
> > TLS |
> > > > >
> > > > >Dev-dependency: env_logger (MIT OR Apache-2.0). Full transitive
> > closure:
> > > > 74
> > > > >packages, machine-checked — every one is MIT / Apache-2.0 /
> Unlicense
> > /
> > > > BSD
> > > > >/ Zlib dual-or-multi licensed, i.e. 100% ASF Category-A. Zero
> > > > Category-B/X,
> > > > >zero unknown-license packages. The full inventory (cargo metadata)
> > can be
> > > > >attached to the IP-clearance checklist.
> > > > >
> > > > >## 4. Proposed initial maintainers and maintenance plan
> > > > >
> > > > >- Initial maintainer: myself (CritasWang — existing IoTDB
> committer).
> > I
> > > > >commit to maintaining the client — issue triage, protocol-sync with
> > > > >iotdb-protocol changes, and regular releases through the normal
> IoTDB
> > > > >community process — and to growing co-maintainers from the
> community;
> > > > >review bandwidth from other committers/PMC members on client-facing
> > > > changes
> > > > >would be welcome.
> > > > >- The repo already carries the practices expected for handover: CI
> > (fmt /
> > > > >clippy -D warnings / license check / unit tests / live integration
> > against
> > > > >a service container), bilingual READMEs, runnable examples, a
> > > > >statistics-aligned benchmark, and a documented codegen pipeline.
> > Nothing
> > > > >depends on my personal infrastructure.
> > > > >
> > > > >## 5. API support matrix (vs Java client) and near-term roadmap
> > > > >
> > > > >Supported today (feature → Java-client equivalent):
> > > > >
> > > > >| Area | Rust today | Java client |
> > > > >|---|---|---|
> > > > >| Session lifecycle, multi-node URLs, failover, auto-reconnect | ✅ |
> > ✅ |
> > > > >| insertTablet / insertTablets | ✅ | ✅ |
> > > > >| insertRecord(s) / insertRecordsOfOneDevice (+ aligned variants) |
> ✅
> > | ✅
> > > > |
> > > > >| Table model (TableSession/Pool, TAG/FIELD/ATTRIBUTE) | ✅ | ✅ |
> > > > >| SessionPool / TableSessionPool (idle eviction, redirection cache)
> |
> > ✅ |
> > > > ✅
> > > > >|
> > > > >| Query + paging iteration (TsBlock, fetchResultsV2) | ✅ | ✅ |
> > > > >| All data types incl. TIMESTAMP/DATE/BLOB/STRING | ✅ | ✅ |
> > > > >| TLS (incl. client identity) / RPC compression | ✅ | ✅ |
> > > > >| deleteData / deleteTimeseries / DDL helpers | SQL only | ✅
> dedicated
> > > > APIs
> > > > >|
> > > > >| Schema templates | ❌ | ✅ |
> > > > >| executeRawDataQuery / executeLastDataQuery / aggregation APIs | ❌
> |
> > ✅ |
> > > > >| Per-type encoding tuning (RPC compression V2) | ❌ | ✅ |
> > > > >
> > > > >Near-term roadmap (order negotiable with the community):
> > > > >
> > > > >1. async (tokio) API layer — most-requested Rust-ecosystem feature,
> > kept
> > > > >out of v0.1 to keep the sync core small
> > > > >2. crates.io releases under the Apache project
> > > > >
> > > > >I'll keep this thread open for feedback on maintenance ownership and
> > API
> > > > >scope as suggested. Since I'm an existing committer with an ICLA on
> > file
> > > > >and the sole author, the IP-clearance paperwork should be light —
> I'm
> > > > happy
> > > > >to prepare whatever the PMC deems necessary (software grant if
> > required
> > > > for
> > > > >the pre-existing external history, plus the dependency inventory
> > above)
> > > > >whenever the community feels ready to move to a VOTE.
> > > > >
> > > > >Best regards,
> > > > >Xuan Wang
> > > > >
> > > > >Haonan Hou <ha...@apache.org> 于2026年7月15日周三 15:06写道:
> > > > >
> > > > >> Hi Xuan,
> > > > >>
> > > > >> Thank you for sharing this work. The implementation already
> covers a
> > > > >> substantial part of the client functionality, and the test
> coverage,
> > > > live
> > > > >> integration testing, CI setup, and benchmark results are all
> > > > encouraging.
> > > > >>
> > > > >> The protocol issues and performance improvements discovered while
> > > > >> validating
> > > > >> against the other clients are also a good indication that this
> work
> > can
> > > > >> benefit the broader IoTDB client ecosystem.
> > > > >>
> > > > >> As a member of the IoTDB PMC, I support bringing a well-maintained
> > Rust
> > > > >> client
> > > > >> into the Apache IoTDB project. Based on what you have presented, I
> > > > believe
> > > > >> this
> > > > >> repository is a strong candidate for donation and for becoming an
> > > > official
> > > > >> IoTDB client.
> > > > >>
> > > > >> Since IoTDB is already an Apache top-level project, the
> appropriate
> > > > route
> > > > >> should be a code donation to the existing project, followed by the
> > ASF
> > > > IP
> > > > >> clearance process, rather than incubation as a separate project.
> > > > >>
> > > > >> I suggest the following next steps:
> > > > >>
> > > > >> 1. Continue this DISCUSS thread to collect feedback from the
> > community,
> > > > >>    especially regarding maintenance ownership and the initial API
> > scope.
> > > > >> 2. Prepare a concise compatibility and API-support matrix against
> > the
> > > > Java
> > > > >>    client, together with a near-term roadmap.
> > > > >> 3. If there are no major concerns, start a formal PMC VOTE to
> > accept the
> > > > >> code
> > > > >>    donation and create the apache/iotdb-client-rust repository.
> > > > >> 4. Complete the software grant, code provenance,
> dependency/license
> > > > review,
> > > > >>    and ASF IP clearance.
> > > > >> 5. Move the code to the Apache repository and continue development
> > and
> > > > >>    releases through the normal IoTDB community process.
> > > > >>
> > > > >> I do not think complete Java client API parity needs to be a
> > > > prerequisite
> > > > >> for
> > > > >> the donation. The current functionality appears sufficient to
> > establish
> > > > a
> > > > >> useful official client. APIs such as schema-template operations
> and
> > > > >> additional
> > > > >> session-level query methods can be added incrementally and tracked
> > > > through
> > > > >> a
> > > > >> public roadmap.
> > > > >>
> > > > >> Before moving to a vote, it would be helpful to provide:
> > > > >>
> > > > >> - The supported IoTDB version matrix.
> > > > >> - A list of contributors and confirmation of the code’s
> > > > >> ownership/provenance.
> > > > >> - A dependency and license inventory.
> > > > >> - The proposed initial maintainers and long-term maintenance plan.
> > > > >> - An API support matrix and near-term roadmap.
> > > > >>
> > > > >> Overall, I am supportive of this proposal and am willing to help
> > move
> > > > the
> > > > >> discussion and donation process forward.
> > > > >>
> > > > >> Best regards,
> > > > >> Haonan Hou
> > > > >>
> > > > >> On 2026/07/15 03:50:24 王旋 wrote:
> > > > >> > Hi all,
> > > > >> >
> > > > >> > I'd like to share a Rust client SDK for Apache IoTDB that I've
> > been
> > > > >> > developing, and ask for the community's feedback on whether
> there
> > is
> > > > >> > interest in bringing it into the Apache IoTDB ecosystem.
> > > > >> >
> > > > >> > Repository: https://github.com/CritasWang/iotdb-client-rust
> > > > >> >
> > > > >> > Scope & features
> > > > >> >
> > > > >> > Tree model (Session) and table model (TableSession / SQL
> dialect),
> > > > >> > mirroring the API shape of the Java / C# / Node.js clients
> > > > >> > Write APIs: insertTablet / insertTablets (multi-tablet
> batching),
> > > > >> > insertRecord(s), insertRecordsOfOneDevice, plus aligned variants
> > > > >> > SessionPool and TableSessionPool: RAII checkout, lazy growth,
> idle
> > > > >> > eviction, dead-connection eviction, write-redirection cache
> > (status
> > > > 400
> > > > >> > redirect hints), automatic reconnect with endpoint failover
> > > > >> > Full data-type coverage including TIMESTAMP / DATE / BLOB /
> > STRING;
> > > > >> TsBlock
> > > > >> > decoding with logical-type re-tagging (the TsBlock header
> carries
> > > > >> physical
> > > > >> > types — DATE arrives as INT32, BLOB as TEXT)
> > > > >> > TLS (feature-gated, incl. client identity) — verified end-to-end
> > > > against
> > > > >> a
> > > > >> > real IoTDB with enable_thrift_ssl; RPC compression (compact
> > protocol)
> > > > >> > Thrift codegen pipeline sources the IDL from iotdb-protocol/ and
> > uses
> > > > the
> > > > >> > thrift compiler fetched by the IoTDB Maven build, so the stubs
> > stay in
> > > > >> > lockstep with the server
> > > > >> >
> > > > >> > Quality
> > > > >> >
> > > > >> > 113 unit tests (124 with TLS) + live integration tests that skip
> > > > >> gracefully
> > > > >> > without a server; CI on GitHub Actions runs fmt / clippy -D
> > warnings /
> > > > >> > license checks plus an integration job against an IoTDB 2.0.6
> > service
> > > > >> > container — green
> > > > >> > Statistics-aligned benchmark (measurement semantics mirror
> > > > iot-benchmark:
> > > > >> > prep inside the timed span, failures excluded from latency,
> > > > >> Result/Latency
> > > > >> > Matrix output). On a 16-core server writing 2B points per run
> > (table
> > > > >> model,
> > > > >> > 100 devices x 20 DOUBLE sensors, 1000-row tablets, 20 sessions),
> > the
> > > > Rust
> > > > >> > client sustains ~46-47M points/s — statistically tied with
> > > > >> iot-benchmark's
> > > > >> > Java Session path on the same box, where the server, not the
> > client,
> > > > is
> > > > >> the
> > > > >> > ceiling
> > > > >> > Every file carries the ASF Apache 2.0 header
> > > > >> >
> > > > >> > Side effects the community already received
> > > > >> >
> > > > >> > Cross-validating the wire protocol against the Java / C# /
> Node.js
> > > > >> > implementations surfaced two upstream issues in the Node.js
> > client,
> > > > both
> > > > >> > now addressed: the DATE wire-encoding fix
> > > > (apache/iotdb-client-nodejs#14,
> > > > >> > PR #15, merged) and a write-path serialization optimization
> (+52%
> > > > >> > throughput, PR #16, under review).
> > > > >> >
> > > > >> > Questions for the community
> > > > >> >
> > > > >> > Is there interest in an official Rust client under the Apache
> > IoTDB
> > > > >> > umbrella (e.g., apache/iotdb-client-rust), following the path of
> > the
> > > > >> > Node.js / C# clients?
> > > > >> > If so, what would the preferred route be — code donation via the
> > > > >> incubator
> > > > >> > process for client SDKs, or starting a repo under the existing
> > project
> > > > >> and
> > > > >> > iterating there?
> > > > >> > Any API-surface expectations from the PMC side before such a
> move
> > > > (e.g.,
> > > > >> > schema-template APIs, session-level query APIs like
> > > > executeRawDataQuery)?
> > > > >> > I'm happy to keep maintaining it either way, and to align the
> > roadmap
> > > > >> with
> > > > >> > the community's priorities.
> > > > >> >
> > > > >> > 大家好
> > > > >> >
> > > > >> > 我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入
> > Apache
> > > > >> > IoTDB 生态。
> > > > >> >
> > > > >> > 仓库地址:https://github.com/CritasWang/iotdb-client-rust
> > > > >> >
> > > > >> > 范围与功能
> > > > >> >
> > > > >> > 树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# /
> > Node.js
> > > > 客户端对齐
> > > > >> > 写入 API:insertTablet / insertTablets(多 tablet
> > > > >> > 批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
> > > > >> > SessionPool 与 TableSessionPool:RAII
> > 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status
> > > > 400
> > > > >> > 重定向提示)、带端点故障转移的自动重连
> > > > >> > 完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock
> > > > 解码带逻辑类型重标记(TsBlock
> > > > >> > 头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
> > > > >> > TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB
> > 完成端到端验证;RPC
> > > > >> > 压缩(compact 协议)
> > > > >> > Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven
> 构建拉取的版本,确保
> > > > stub
> > > > >> > 与服务端严格同步
> > > > >> >
> > > > >> > 质量
> > > > >> >
> > > > >> > 113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions CI
> > 运行
> > > > fmt /
> > > > >> > clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service
> > container 的集成
> > > > >> > job——全绿
> > > > >> > 统计口径对齐的基准测试(测量语义对齐 iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency
> > > > Matrix
> > > > >> > 输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000
> > 行/tablet、20
> > > > >> > 会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java
> Session
> > > > >> > 路径统计学持平,此时瓶颈在服务端而非客户端
> > > > >> > 所有文件均带 ASF Apache 2.0 头
> > > > >> >
> > > > >> > 社区已经收到的副产品
> > > > >> >
> > > > >> > 在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js
> > > > 客户端的两个上游问题,目前均已处理:DATE
> > > > >> > 线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐
> > +52%,PR
> > > > >> > #16,评审中)。
> > > > >> >
> > > > >> > 想请教社区的问题
> > > > >> >
> > > > >> > 社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如
> > apache/iotdb-client-rust),沿用
> > > > >> > Node.js / C# 客户端的路径?
> > > > >> > 如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
> > > > >> > 在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery
> > 等会话级查询
> > > > API)?
> > > > >> > 无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。
> > > > >> >
> > > > >> > Best regards,
> > > > >> > Xuan Wang
> > > > >> >
> > > > >>
> > > >
> > >
> >
>

Re: [DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Posted by Zh D <dz...@gmail.com>.
Hi Xuan, all,

A review of the session pool, connection lifecycle and redirect
handling in apache/iotdb-client-rust, at faff2de.

I previously reviewed the Node.js client along the same axes -- pool
acquire/release, connection lifecycle, redirect handling -- and
applied the same method to the Rust implementation. Everything below
was read in the source and, where noted, reproduced locally against
a throwaway fake Thrift server (handshake answered normally, then
silent) or a blackhole listener. Where I only traced statically, I
say so.


There is no client-side time bound after the TCP handshake
----------------------------------------------------------

This is the one finding I would put first. F1, F2 and F3 below are
three fix points for it, kept separate because they are fixed in
different places, but they are one root cause.

connect_stream (connection/mod.rs:246-261) applies connect_timeout
to TcpStream::connect_timeout only, which covers the TCP
handshake. After that, open (:180-181) sets only set_nodelay(true).
There is no set_read_timeout / set_write_timeout anywhere in the
crate and no socket2 dependency, so every Thrift read after the
handshake is an unbounded blocking read. ConnectionOptions
(:87-106) has no field for one. SessionConfig::query_timeout_ms
(session.rs:61-62) is a request-body field carried in
TSExecuteStatementReq (:840) and TSFetchResultsReq (:484) -- it is
enforced server-side, gives no client-side bound, and does not
cover openSession or closeSession. Rust's TcpStream does not enable
SO_KEEPALIVE by default either, so if the peer's kernel never sends
FIN/RST the block is unbounded in the literal sense.

F1. Ordinary RPCs. Against a listener that completes the TCP
handshake and then never replies -- equivalent to a long JVM GC
pause, a stateful firewall silently dropping return traffic, or an
LB that accepts but does not forward:

- Session::open() with connect_timeout = 200ms was still blocked
after 12s; the block is in the openSession read (session.rs:278),
past the connect timeout's scope.
- With a fake server that answers openSession + requestStatementId
normally and then goes silent, execute_non_query blocked for >8s
with enable_auto_reconnect = true and max_reconnect_attempts = 3.
The reconnect path never fired, because a wedged read produces no
Error::Thrift and with_retry (session.rs:349-357) only reacts to
errors. So auto-reconnect does not help against the one failure it
looks like it should cover.
- Control: with the port closed, the same call returned in 176us.
The hang is specific to "handshake succeeded, peer silent".

Reachability is the default configuration through the public API:
Session::open, any RPC, TableSession::build, SessionPool::new (which
calls open_session() at pool.rs:150 inside the constructor when
min_size > 0), SessionPool::acquire. There is no escape hatch for a
user outside the library -- Connection's only public constructor is
open, and the TcpStream is never exposed.

Question. Is the intended contract that connect_timeout bounds only
the TCP handshake and that per-RPC deadlines are out of scope for
now, or was a socket-level read timeout intended and simply not
wired up? Asking because several of the findings below are
amplifications of this one and would collapse if a socket_timeout
existed.

F2. Drop, where the caller has no recourse. Three destructors send
RPCs that wait for a response: Drop for Session (session.rs:847) ->
close() (:822) -> close_session (:825); Drop for SessionPool
(pool.rs:392) -> close() (:307) -> serial entry.session.close() for
every idle session (:314-316); Drop for SessionDataSet
(dataset.rs:213) -> close() (:202) -> Session::close_query
(session.rs:500) -> close_operation. Drop for PooledSession
(pool.rs:427-433) is indirect: release() only issues RPCs on the
pool-closed branch (:370) or when the sweep expires entries
(:373-377); the normal return path (:372) just pushes to the idle
queue.

A destructor cannot return an error, cannot be cancelled, and
cannot be given a timeout by the caller. The failures are also
swallowed (session.rs:826, pool.rs:315, :370, :376 are all let _ =
or log::debug!), so a wedged teardown produces neither an error nor
a warning. Reproduced against the same silent server:

1. Session::open() succeeds -- the server log shows ["openSession",
"requestStatementId", "closeSession"], i.e. closeSession was
written -- then drop(s) blocked >12s and will not return.
2. SessionPool::new(min_size = 1) then drop(pool): blocked >12s at
pool.rs:314-316. With max_size = 8 idle sessions, the first one
blocks, the other seven are never attempted, and notify_all() at
:317 is never reached.
3. pool.close() followed by a guard going out of scope: blocked
over 12s on the release() closed-branch at :370.
4. If a panic unwind passes through a bare Session or a
SessionPool, the unwind never completes.

A secondary effect on waiters, which is latency only: in close(),
closed = true is set inside the lock (:310) and the lock is
released at :312 before the blocking loop, so waiters are not stuck
on the mutex -- good. But notify_all() is at :317, after the
blocking closes. With two or more waiters parked in wait_timeout
(:254), the one not woken by the earlier notify_one() in release()
(:379) sleeps out its full acquire_timeout. Measured with
acquire_timeout = 4s: one waiter returned in 305ms, the other in
4.004s. Both got the correct "session pool is closed" error.

Question. Would you consider a teardown path that drops the
transport without waiting for closeSession, or is the best-effort
RPC-on-drop deliberate (matching the C#/Node SDKs)? It reads
deliberate -- I mostly want to flag that with F1 present it is
non-recoverable rather than best-effort.

F3. TLS, where a one-line misconfiguration hangs instead of
erroring. Severity is lower because tls is a non-default feature.
At connection/mod.rs:185 the stream handed to tls_handshake is a
blocking socket with no read timeout, so connector.connect(domain,
stream) at :310 has no time bound. The comment at :312 ("Blocking
sockets never yield the mid-handshake variant") confirms the
blocking socket is intentional, which is precisely why a deadline
would have to be set before :310. The doc comment at :176-178 says
the TCP connect is bounded by connect_timeout and does not claim
the TLS step is, so this is an undocumented unbounded step rather
than a contradiction.

Reproduced with use_ssl = true, connect_timeout = 200ms, pointed at
a non-TLS IoTDB RPC port. The client sends ClientHello and waits
for ServerHello; the server's framed transport reads the first four
bytes 16 03 03 00 as a frame length of 369,296,128 and waits for a
369MB body. Neither side closes. Session::open() was still blocked
after 15s. Control: the same silent peer with tls: None returned in
200.5us, so the non-TLS path is genuinely bounded and the TLS path
is not. The multi-endpoint failover loop in Session::open
(session.rs:238-247) never reaches the second endpoint, and
reconnect's max_reconnect_attempts / retry_interval are equally
never reached.

The existing TLS tests do not cover this shape:
tls_dispatch_sends_client_hello (connection/mod.rs:621-643) and
tls_option_selects_stack_against_plain_endpoint (:646-676) both use
listeners that close the connection, so the client escapes on EOF
with Err(Error::Tls(_)). One consequence for whoever fixes this:
once a read timeout exists, the currently dead
HandshakeError::WouldBlock arm at :313-315 becomes reachable and
the comment at :312 stops being true.


Other findings, in brief
------------------------

Each of these was reproduced or traced the same way; I have kept
them to a line each rather than expanding the mechanism. Happy to
open any of them as separate GitHub issues if that is easier to
track.

F4 (medium) session.rs:238-252, contrast :313-337 -- Session::open
fails over only at the TCP layer: authenticate runs outside the
endpoint loop, so a handshake failure returns instead of trying the
remaining nodes. reconnect() does the opposite. With a 3-node
cluster where one node accepts TCP but fails openSession, roughly
one open() in three fails while 2 of 3 nodes are healthy.

F5 (medium) pool.rs:235-242, :335-343 -- acquire() spends none of
its acquire_timeout budget when the growth branch fails (measured
198us against a 5s budget; 4136 of 4800 acquires failed instantly
under stress while the pool had sessions circulating), and a failed
USE replay in hand_out discards the remaining idle candidates.

F6 (medium, latency only) pool.rs:238-239, :339-340, :355-356 --
live is decremented outside the state lock at five sites; at the
three above, the decremented value is exactly the predicate a parked
waiter re-evaluates, so a Condvar notification can be lost. The
comment at :121-122 no longer matches the code. Measured stalls
track acquire_timeout exactly (300ms -> 305ms, 1000ms -> 1.005s).

F7 (medium, gated on enable_auto_reconnect = false)
session.rs:368-370, pool.rs:223-228 -- is_open() is
connection.is_some(), not socket state. With auto-reconnect off, a
dead session is reused indefinitely under load. Separately, I could
not construct a production path where the acquire-side eviction
loop evicts anything; is it defensive, or have I missed a writer?

F8 (low-medium) session.rs:299-340, sleep at :315 -- reconnect()
sleeps and walks all endpoints while still holding its pool slot;
worst case with defaults is ~92s for three endpoints. Concurrent
callers get "pool exhausted", which points away from the cause.

F9 (low) connection/mod.rs:246-256 -- connect_timeout is applied
per resolved address, not per endpoint, contradicting both doc
comments; a dual-address host multiplies every bound (measured
2.0011s for two blackhole addresses at 1s each).

F10 (low/informational) connection/mod.rs:231 -- the frame cap is
thrift-rs's default 16,384,000 bytes, which a conforming IoTDB
server can legitimately exceed. Go and C# use the same number, so
this is not a Rust-specific regression; the part worth attention is
that rejection happens before the body is drained, leaving the
connection desynchronized, and fetch_results does not go through
with_retry.

F11 (low) pool.rs:284-286 -- redirect endpoint matching is exact
host-string equality with no normalization, so hostname-vs-IP
spelling silently disables the optimization on multi-DataNode
clusters. No log line, so it is invisible from outside.

F12 (low) pool.rs:279-282 -- when idle sessions hold conflicting
hints for one device, the winner is queue position, not recency.
Within documented behaviour (:266-268 says "any idle session"), but
RedirectCache already tracks seq/inserted -- was preferring the
newest hint considered?

F13 (low) pool.rs:207 -- acquire_timeout = Duration::MAX panics on
Instant + Duration overflow before the lock is taken. Narrow (100
years and 1000 years both work), and it matters only because there
is no "never time out" option and Duration::MAX is the natural way
to ask for one.

Two smaller observations: RedirectCache's TTL and max_entries are
fixed at construction with no SessionConfig knob, which becomes
measurable only on large batch inserts; and TableSessionPool
exposes acquire() but not acquire_for_device(), so table-mode users
accumulate hints no pool API can consume -- deliberate?


What this implementation gets right
-----------------------------------

These are the specific failure modes that bit the Node.js client,
absent here by construction rather than by discipline.

The redirect design structurally avoids the Node.js endpoint-session
bug. Outside the generated Thrift code there is exactly one HashMap
-- the device-to-endpoint hint cache (redirect.rs:68). There is no
endPointToSession map, and Connection::open has exactly two
non-test call sites (session.rs:240, session.rs:319), both of which
only iterate config.endpoints. The client never opens a connection
because of a redirect. Combined with move semantics in the pool
(pop_front at pool.rs:223, remove(pos) at :288, push_back only
after the guard yields ownership at :429-431), a session cannot
simultaneously be in an endpoint map and in the general idle queue.
The comment at pool.rs:270-272 states the trade-off honestly. This
is the single most important thing this client does differently.

No lock is ever held across blocking I/O. I checked every non-test
lock() in pool.rs: new() :151 (open is at :150, outside), acquire()
:208 (drops at :215 before closing swept sessions, :226/:234 before
hand_out), acquire_for_device() :275 (drops at :289), close() :309
(scope ends :312, blocking closes at :314-316), release() :365
(drops at :374), open_session() :324, hand_out() :334. The one
Session destructor that runs under the lock (:228) is a no-op
because connection is already None. sweep_idle being #[must_use]
and returning expired sessions for the caller to close outside the
lock (:173-176) is a deliberate, correct design.

The borrow checker is doing real work. PooledSession<'a> borrows
the pool, so a guard cannot outlive it; SessionDataSet<'a> borrows
&mut Session, so a result set cannot outlive its session or be used
concurrently with another RPC; every RPC takes &mut self, which
makes interleaved Thrift sequence numbers on one channel impossible
without a runtime lock. Zero unsafe in the crate.


Checked, nothing found
----------------------

Recording these because a clean result is information too: async
and cancellation issues (the crate is fully synchronous -- zero
async fn / .await / tokio across src, tests and examples, so the
Node.js-shaped hypotheses are vacuous); RefCell misuse (the two
occurrences are unused generator imports); waiters removed on
timeout but still notified (no explicit waiter list exists); two
callers receiving the same idle session (stress-verified, 16
threads x 300 acquire/release, zero failures); stale-index
remove/pop after dropping the lock; live accounting drift and usize
underflow (three increments and seven decrements reconcile); mutex
poisoning cascades (no reachable first panic found, though the
chain is fragile); double closeSession / closeOperation; dangling
PooledSession after the pool is dropped; oversized allocation from
a bogus peer; min_size / max_size boundaries; spurious condvar
wakeups; Thrift sequence-number interleaving; Endpoint::parse edge
cases; and redirect interaction with reconnect.


Happy to go deeper on any of these, or to re-check a scenario if
you think one is a misread.

Best regards,
Zihan Dai
GitHub: PDGGK

On Mon, Jul 20, 2026 12:40 PM, Haonan Hou <ha...@apache.org> wrote:

> Hi Xuan,
>
> The vote passed and the repo has been created.
> https://github.com/apache/iotdb-client-rust
>
> Thanks,
> Haonan
>
> On 2026/07/17 03:57:02 王旋 wrote:
> > Hi Yuan,
> >
> > Thank you for the suggestions. Status on both:
> >
> > 1. Compatibility & release policy -- now landed in the repository as
> > COMPATIBILITY.md <http://compatibility.md/> [1]:
> >
> > - IoTDB server compatibility matrix: 2.0.1-2.0.8, 2.0.10 and master are
> >   listed; 2.0.6 and 2.0.10 are tested (CI live suite / full benchmark +
> >   data-correctness verification respectively), the other versions are
> >   explicitly marked as untested.
> > - A per-release protocol toolchain table recording, for each crate
> >   version, the exact IDL source (currently apache/iotdb master,
> >   iotdb-protocol/ @ 2fedd8a395) and the Thrift compiler version (0.23.0,
> >   as pinned by the IoTDB pom), plus the thrift crate version.
> > - A SemVer policy (Cargo semantics, 0.x pre-1.0 rules), a deprecation
> >   policy (#[deprecated] for at least one minor release before removal),
> >   and a release checklist that updates the toolchain table on every
> >   release.
> >
> > CI now runs the live integration suite and examples against both the
> > oldest tested and the latest stable IoTDB (2.0.6 and 2.0.10) as a build
> > matrix [2].
> >
> > 2. crates.io publishing permissions and a community-managed release
> > process -- fully agreed. Since this depends on the Apache repository and
> > community processes existing first, I will file it as a roadmap issue in
> > apache/iotdb-client-rust once the repository is created, covering
> > community-owned crates.io ownership, reproducible release steps, and
> > review by multiple maintainers.
> >
> > [1]
> >
> https://github.com/CritasWang/iotdb-client-rust/blob/main/COMPATIBILITY.md
> > [2]
> >
> https://github.com/CritasWang/iotdb-client-rust/blob/main/.github/workflows/ci.yml
> >
> > Best regards,
> > Xuan Wang
> >
> > zerolbsony <ze...@163.com> 于2026年7月16日周四 20:58写道:
> >
> > > Hi, Xuan Wang
> > > It’s hard to believe that Rust has overtaken Go and become so popular.
> > > The top 10 programming languages in the July 2026 TIOBE rankings are as
> > > follows:
> > > Python – 18.94%
> > > C – 10.86%
> > > C++ – 9.12%
> > > Java – 8.03%
> > > C# – 4.49%
> > > JavaScript – 2.72%
> > > Visual Basic – 2.48%
> > > SQL – 1.71%
> > > R – 1.69%
> > > Rust – 1.34%
> > >
> > >
> > > I’ve noticed that starting from 2024, the Linux kernel has allowed
> certain
> > > modules, primarily device drivers, to be written in Rust.
> > >
> > >
> > > Rust can be used to write Linux kernel modules, which means you can run
> > > Rust code directly at the kernel level. This is extremely useful for
> > > scenarios that demand high performance and low-level hardware
> operations.
> > > Have you considered invoking certain IoTDB functionalities directly
> via the
> > > Linux kernel to boost performance?
> > > Best regards,
> > > Bo Li
> > >
> > >
> > > >Hi,
> > > >
> > > >Thank you very much for the supportive and detailed reply. The
> suggested
> > > >route (code donation to the existing TLP + ASF IP clearance, rather
> than
> > > >incubation) makes sense to me, and I'm glad full Java-parity is not a
> > > >prerequisite — an incremental, roadmap-tracked approach matches how
> the
> > > >client was built.
> > > >
> > > >Below are the five items requested before a vote.
> > > >
> > > >## 1. Supported IoTDB version matrix
> > > >
> > > >| IoTDB version | Status | Evidence |
> > > >|---|---|---|
> > > >| 2.0.6 | Supported | CI integration job runs the full live test
> suite + 3
> > > >examples against apache/iotdb:2.0.6-standalone on every push |
> > > >| 2.0.10 | Supported | Full benchmark + data-correctness verification
> (all
> > > >10 data types, tree & table, nulls) against a 2.0.10 standalone
> > > deployment |
> > > >| 2.0.x (general) | Expected to work | Thrift IDL is synced from
> > > >iotdb-protocol/ master; protocol version V3; no version-specific
> branching
> > > >in the client |
> > > >| 1.x | Not targeted | Table model and several data types
> > > >(TIMESTAMP/DATE/BLOB/STRING) assume 2.x; no plan to support 1.x |
> > > >
> > > >TLS was verified end-to-end against 2.0.6 with enable_thrift_ssl
> (TLSv1.3,
> > > >full certificate verification). RPC compression (compact protocol)
> > > verified
> > > >against a server with dn_rpc_thrift_compression_enable=true.
> > > >
> > > >## 2. Contributors and provenance
> > > >
> > > >The entire git history has a single author — myself (Wang Xuan /
> > > CritasWang
> > > ><cr...@outlook.com>). I am an existing Apache IoTDB committer with
> an
> > > ICLA
> > > >already on file, and I hold full ownership of this work, so the
> provenance
> > > >chain is straightforward. Two categories of code in the repo:
> > > >
> > > >- Hand-written code: 100% original work, written for this project,
> > > >Apache-2.0 headers on every file.
> > > >- Generated code (src/protocol/): produced by the Apache Thrift
> compiler
> > > >from the Apache IoTDB project's own IDL files (iotdb-protocol/,
> ALv2); the
> > > >generation pipeline (tools/generate-thrift.sh) is documented and
> > > >reproducible.
> > > >
> > > >No code was copied from other client SDKs; the Java/C#/Node.js clients
> > > were
> > > >used as behavioral references only (wire-protocol semantics), which is
> > > also
> > > >how the cross-client protocol issues (e.g. the Node.js DATE encoding
> bug)
> > > >were found.
> > > >
> > > >## 3. Dependency and license inventory
> > > >
> > > >Runtime dependencies (4 + 1 optional):
> > > >
> > > >| Crate | Version | License | Purpose |
> > > >|---|---|---|---|
> > > >| thrift | 0.23 | Apache-2.0 | RPC (matches the compiler version
> pinned by
> > > >the IoTDB pom) |
> > > >| byteorder | 1.5 | Unlicense OR MIT | Big-endian encoding |
> > > >| chrono | 0.4 | MIT OR Apache-2.0 | DATE handling |
> > > >| log | 0.4 | MIT OR Apache-2.0 | Logging facade |
> > > >| native-tls (optional, feature "tls") | 0.2 | MIT OR Apache-2.0 |
> TLS |
> > > >
> > > >Dev-dependency: env_logger (MIT OR Apache-2.0). Full transitive
> closure:
> > > 74
> > > >packages, machine-checked — every one is MIT / Apache-2.0 / Unlicense
> /
> > > BSD
> > > >/ Zlib dual-or-multi licensed, i.e. 100% ASF Category-A. Zero
> > > Category-B/X,
> > > >zero unknown-license packages. The full inventory (cargo metadata)
> can be
> > > >attached to the IP-clearance checklist.
> > > >
> > > >## 4. Proposed initial maintainers and maintenance plan
> > > >
> > > >- Initial maintainer: myself (CritasWang — existing IoTDB committer).
> I
> > > >commit to maintaining the client — issue triage, protocol-sync with
> > > >iotdb-protocol changes, and regular releases through the normal IoTDB
> > > >community process — and to growing co-maintainers from the community;
> > > >review bandwidth from other committers/PMC members on client-facing
> > > changes
> > > >would be welcome.
> > > >- The repo already carries the practices expected for handover: CI
> (fmt /
> > > >clippy -D warnings / license check / unit tests / live integration
> against
> > > >a service container), bilingual READMEs, runnable examples, a
> > > >statistics-aligned benchmark, and a documented codegen pipeline.
> Nothing
> > > >depends on my personal infrastructure.
> > > >
> > > >## 5. API support matrix (vs Java client) and near-term roadmap
> > > >
> > > >Supported today (feature → Java-client equivalent):
> > > >
> > > >| Area | Rust today | Java client |
> > > >|---|---|---|
> > > >| Session lifecycle, multi-node URLs, failover, auto-reconnect | ✅ |
> ✅ |
> > > >| insertTablet / insertTablets | ✅ | ✅ |
> > > >| insertRecord(s) / insertRecordsOfOneDevice (+ aligned variants) | ✅
> | ✅
> > > |
> > > >| Table model (TableSession/Pool, TAG/FIELD/ATTRIBUTE) | ✅ | ✅ |
> > > >| SessionPool / TableSessionPool (idle eviction, redirection cache) |
> ✅ |
> > > ✅
> > > >|
> > > >| Query + paging iteration (TsBlock, fetchResultsV2) | ✅ | ✅ |
> > > >| All data types incl. TIMESTAMP/DATE/BLOB/STRING | ✅ | ✅ |
> > > >| TLS (incl. client identity) / RPC compression | ✅ | ✅ |
> > > >| deleteData / deleteTimeseries / DDL helpers | SQL only | ✅ dedicated
> > > APIs
> > > >|
> > > >| Schema templates | ❌ | ✅ |
> > > >| executeRawDataQuery / executeLastDataQuery / aggregation APIs | ❌ |
> ✅ |
> > > >| Per-type encoding tuning (RPC compression V2) | ❌ | ✅ |
> > > >
> > > >Near-term roadmap (order negotiable with the community):
> > > >
> > > >1. async (tokio) API layer — most-requested Rust-ecosystem feature,
> kept
> > > >out of v0.1 to keep the sync core small
> > > >2. crates.io releases under the Apache project
> > > >
> > > >I'll keep this thread open for feedback on maintenance ownership and
> API
> > > >scope as suggested. Since I'm an existing committer with an ICLA on
> file
> > > >and the sole author, the IP-clearance paperwork should be light — I'm
> > > happy
> > > >to prepare whatever the PMC deems necessary (software grant if
> required
> > > for
> > > >the pre-existing external history, plus the dependency inventory
> above)
> > > >whenever the community feels ready to move to a VOTE.
> > > >
> > > >Best regards,
> > > >Xuan Wang
> > > >
> > > >Haonan Hou <ha...@apache.org> 于2026年7月15日周三 15:06写道:
> > > >
> > > >> Hi Xuan,
> > > >>
> > > >> Thank you for sharing this work. The implementation already covers a
> > > >> substantial part of the client functionality, and the test coverage,
> > > live
> > > >> integration testing, CI setup, and benchmark results are all
> > > encouraging.
> > > >>
> > > >> The protocol issues and performance improvements discovered while
> > > >> validating
> > > >> against the other clients are also a good indication that this work
> can
> > > >> benefit the broader IoTDB client ecosystem.
> > > >>
> > > >> As a member of the IoTDB PMC, I support bringing a well-maintained
> Rust
> > > >> client
> > > >> into the Apache IoTDB project. Based on what you have presented, I
> > > believe
> > > >> this
> > > >> repository is a strong candidate for donation and for becoming an
> > > official
> > > >> IoTDB client.
> > > >>
> > > >> Since IoTDB is already an Apache top-level project, the appropriate
> > > route
> > > >> should be a code donation to the existing project, followed by the
> ASF
> > > IP
> > > >> clearance process, rather than incubation as a separate project.
> > > >>
> > > >> I suggest the following next steps:
> > > >>
> > > >> 1. Continue this DISCUSS thread to collect feedback from the
> community,
> > > >>    especially regarding maintenance ownership and the initial API
> scope.
> > > >> 2. Prepare a concise compatibility and API-support matrix against
> the
> > > Java
> > > >>    client, together with a near-term roadmap.
> > > >> 3. If there are no major concerns, start a formal PMC VOTE to
> accept the
> > > >> code
> > > >>    donation and create the apache/iotdb-client-rust repository.
> > > >> 4. Complete the software grant, code provenance, dependency/license
> > > review,
> > > >>    and ASF IP clearance.
> > > >> 5. Move the code to the Apache repository and continue development
> and
> > > >>    releases through the normal IoTDB community process.
> > > >>
> > > >> I do not think complete Java client API parity needs to be a
> > > prerequisite
> > > >> for
> > > >> the donation. The current functionality appears sufficient to
> establish
> > > a
> > > >> useful official client. APIs such as schema-template operations and
> > > >> additional
> > > >> session-level query methods can be added incrementally and tracked
> > > through
> > > >> a
> > > >> public roadmap.
> > > >>
> > > >> Before moving to a vote, it would be helpful to provide:
> > > >>
> > > >> - The supported IoTDB version matrix.
> > > >> - A list of contributors and confirmation of the code’s
> > > >> ownership/provenance.
> > > >> - A dependency and license inventory.
> > > >> - The proposed initial maintainers and long-term maintenance plan.
> > > >> - An API support matrix and near-term roadmap.
> > > >>
> > > >> Overall, I am supportive of this proposal and am willing to help
> move
> > > the
> > > >> discussion and donation process forward.
> > > >>
> > > >> Best regards,
> > > >> Haonan Hou
> > > >>
> > > >> On 2026/07/15 03:50:24 王旋 wrote:
> > > >> > Hi all,
> > > >> >
> > > >> > I'd like to share a Rust client SDK for Apache IoTDB that I've
> been
> > > >> > developing, and ask for the community's feedback on whether there
> is
> > > >> > interest in bringing it into the Apache IoTDB ecosystem.
> > > >> >
> > > >> > Repository: https://github.com/CritasWang/iotdb-client-rust
> > > >> >
> > > >> > Scope & features
> > > >> >
> > > >> > Tree model (Session) and table model (TableSession / SQL dialect),
> > > >> > mirroring the API shape of the Java / C# / Node.js clients
> > > >> > Write APIs: insertTablet / insertTablets (multi-tablet batching),
> > > >> > insertRecord(s), insertRecordsOfOneDevice, plus aligned variants
> > > >> > SessionPool and TableSessionPool: RAII checkout, lazy growth, idle
> > > >> > eviction, dead-connection eviction, write-redirection cache
> (status
> > > 400
> > > >> > redirect hints), automatic reconnect with endpoint failover
> > > >> > Full data-type coverage including TIMESTAMP / DATE / BLOB /
> STRING;
> > > >> TsBlock
> > > >> > decoding with logical-type re-tagging (the TsBlock header carries
> > > >> physical
> > > >> > types — DATE arrives as INT32, BLOB as TEXT)
> > > >> > TLS (feature-gated, incl. client identity) — verified end-to-end
> > > against
> > > >> a
> > > >> > real IoTDB with enable_thrift_ssl; RPC compression (compact
> protocol)
> > > >> > Thrift codegen pipeline sources the IDL from iotdb-protocol/ and
> uses
> > > the
> > > >> > thrift compiler fetched by the IoTDB Maven build, so the stubs
> stay in
> > > >> > lockstep with the server
> > > >> >
> > > >> > Quality
> > > >> >
> > > >> > 113 unit tests (124 with TLS) + live integration tests that skip
> > > >> gracefully
> > > >> > without a server; CI on GitHub Actions runs fmt / clippy -D
> warnings /
> > > >> > license checks plus an integration job against an IoTDB 2.0.6
> service
> > > >> > container — green
> > > >> > Statistics-aligned benchmark (measurement semantics mirror
> > > iot-benchmark:
> > > >> > prep inside the timed span, failures excluded from latency,
> > > >> Result/Latency
> > > >> > Matrix output). On a 16-core server writing 2B points per run
> (table
> > > >> model,
> > > >> > 100 devices x 20 DOUBLE sensors, 1000-row tablets, 20 sessions),
> the
> > > Rust
> > > >> > client sustains ~46-47M points/s — statistically tied with
> > > >> iot-benchmark's
> > > >> > Java Session path on the same box, where the server, not the
> client,
> > > is
> > > >> the
> > > >> > ceiling
> > > >> > Every file carries the ASF Apache 2.0 header
> > > >> >
> > > >> > Side effects the community already received
> > > >> >
> > > >> > Cross-validating the wire protocol against the Java / C# / Node.js
> > > >> > implementations surfaced two upstream issues in the Node.js
> client,
> > > both
> > > >> > now addressed: the DATE wire-encoding fix
> > > (apache/iotdb-client-nodejs#14,
> > > >> > PR #15, merged) and a write-path serialization optimization (+52%
> > > >> > throughput, PR #16, under review).
> > > >> >
> > > >> > Questions for the community
> > > >> >
> > > >> > Is there interest in an official Rust client under the Apache
> IoTDB
> > > >> > umbrella (e.g., apache/iotdb-client-rust), following the path of
> the
> > > >> > Node.js / C# clients?
> > > >> > If so, what would the preferred route be — code donation via the
> > > >> incubator
> > > >> > process for client SDKs, or starting a repo under the existing
> project
> > > >> and
> > > >> > iterating there?
> > > >> > Any API-surface expectations from the PMC side before such a move
> > > (e.g.,
> > > >> > schema-template APIs, session-level query APIs like
> > > executeRawDataQuery)?
> > > >> > I'm happy to keep maintaining it either way, and to align the
> roadmap
> > > >> with
> > > >> > the community's priorities.
> > > >> >
> > > >> > 大家好
> > > >> >
> > > >> > 我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入
> Apache
> > > >> > IoTDB 生态。
> > > >> >
> > > >> > 仓库地址:https://github.com/CritasWang/iotdb-client-rust
> > > >> >
> > > >> > 范围与功能
> > > >> >
> > > >> > 树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# /
> Node.js
> > > 客户端对齐
> > > >> > 写入 API:insertTablet / insertTablets(多 tablet
> > > >> > 批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
> > > >> > SessionPool 与 TableSessionPool:RAII
> 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status
> > > 400
> > > >> > 重定向提示)、带端点故障转移的自动重连
> > > >> > 完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock
> > > 解码带逻辑类型重标记(TsBlock
> > > >> > 头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
> > > >> > TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB
> 完成端到端验证;RPC
> > > >> > 压缩(compact 协议)
> > > >> > Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven 构建拉取的版本,确保
> > > stub
> > > >> > 与服务端严格同步
> > > >> >
> > > >> > 质量
> > > >> >
> > > >> > 113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions CI
> 运行
> > > fmt /
> > > >> > clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service
> container 的集成
> > > >> > job——全绿
> > > >> > 统计口径对齐的基准测试(测量语义对齐 iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency
> > > Matrix
> > > >> > 输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000
> 行/tablet、20
> > > >> > 会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java Session
> > > >> > 路径统计学持平,此时瓶颈在服务端而非客户端
> > > >> > 所有文件均带 ASF Apache 2.0 头
> > > >> >
> > > >> > 社区已经收到的副产品
> > > >> >
> > > >> > 在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js
> > > 客户端的两个上游问题,目前均已处理:DATE
> > > >> > 线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐
> +52%,PR
> > > >> > #16,评审中)。
> > > >> >
> > > >> > 想请教社区的问题
> > > >> >
> > > >> > 社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如
> apache/iotdb-client-rust),沿用
> > > >> > Node.js / C# 客户端的路径?
> > > >> > 如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
> > > >> > 在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery
> 等会话级查询
> > > API)?
> > > >> > 无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。
> > > >> >
> > > >> > Best regards,
> > > >> > Xuan Wang
> > > >> >
> > > >>
> > >
> >
>

Re: Re: [DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Posted by Haonan Hou <ha...@apache.org>.
Hi Xuan,

The vote passed and the repo has been created. 
https://github.com/apache/iotdb-client-rust

Thanks,
Haonan

On 2026/07/17 03:57:02 王旋 wrote:
> Hi Yuan,
> 
> Thank you for the suggestions. Status on both:
> 
> 1. Compatibility & release policy -- now landed in the repository as
> COMPATIBILITY.md <http://compatibility.md/> [1]:
> 
> - IoTDB server compatibility matrix: 2.0.1-2.0.8, 2.0.10 and master are
>   listed; 2.0.6 and 2.0.10 are tested (CI live suite / full benchmark +
>   data-correctness verification respectively), the other versions are
>   explicitly marked as untested.
> - A per-release protocol toolchain table recording, for each crate
>   version, the exact IDL source (currently apache/iotdb master,
>   iotdb-protocol/ @ 2fedd8a395) and the Thrift compiler version (0.23.0,
>   as pinned by the IoTDB pom), plus the thrift crate version.
> - A SemVer policy (Cargo semantics, 0.x pre-1.0 rules), a deprecation
>   policy (#[deprecated] for at least one minor release before removal),
>   and a release checklist that updates the toolchain table on every
>   release.
> 
> CI now runs the live integration suite and examples against both the
> oldest tested and the latest stable IoTDB (2.0.6 and 2.0.10) as a build
> matrix [2].
> 
> 2. crates.io publishing permissions and a community-managed release
> process -- fully agreed. Since this depends on the Apache repository and
> community processes existing first, I will file it as a roadmap issue in
> apache/iotdb-client-rust once the repository is created, covering
> community-owned crates.io ownership, reproducible release steps, and
> review by multiple maintainers.
> 
> [1]
> https://github.com/CritasWang/iotdb-client-rust/blob/main/COMPATIBILITY.md
> [2]
> https://github.com/CritasWang/iotdb-client-rust/blob/main/.github/workflows/ci.yml
> 
> Best regards,
> Xuan Wang
> 
> zerolbsony <ze...@163.com> 于2026年7月16日周四 20:58写道:
> 
> > Hi, Xuan Wang
> > It’s hard to believe that Rust has overtaken Go and become so popular.
> > The top 10 programming languages in the July 2026 TIOBE rankings are as
> > follows:
> > Python – 18.94%
> > C – 10.86%
> > C++ – 9.12%
> > Java – 8.03%
> > C# – 4.49%
> > JavaScript – 2.72%
> > Visual Basic – 2.48%
> > SQL – 1.71%
> > R – 1.69%
> > Rust – 1.34%
> >
> >
> > I’ve noticed that starting from 2024, the Linux kernel has allowed certain
> > modules, primarily device drivers, to be written in Rust.
> >
> >
> > Rust can be used to write Linux kernel modules, which means you can run
> > Rust code directly at the kernel level. This is extremely useful for
> > scenarios that demand high performance and low-level hardware operations.
> > Have you considered invoking certain IoTDB functionalities directly via the
> > Linux kernel to boost performance?
> > Best regards,
> > Bo Li
> >
> >
> > >Hi,
> > >
> > >Thank you very much for the supportive and detailed reply. The suggested
> > >route (code donation to the existing TLP + ASF IP clearance, rather than
> > >incubation) makes sense to me, and I'm glad full Java-parity is not a
> > >prerequisite — an incremental, roadmap-tracked approach matches how the
> > >client was built.
> > >
> > >Below are the five items requested before a vote.
> > >
> > >## 1. Supported IoTDB version matrix
> > >
> > >| IoTDB version | Status | Evidence |
> > >|---|---|---|
> > >| 2.0.6 | Supported | CI integration job runs the full live test suite + 3
> > >examples against apache/iotdb:2.0.6-standalone on every push |
> > >| 2.0.10 | Supported | Full benchmark + data-correctness verification (all
> > >10 data types, tree & table, nulls) against a 2.0.10 standalone
> > deployment |
> > >| 2.0.x (general) | Expected to work | Thrift IDL is synced from
> > >iotdb-protocol/ master; protocol version V3; no version-specific branching
> > >in the client |
> > >| 1.x | Not targeted | Table model and several data types
> > >(TIMESTAMP/DATE/BLOB/STRING) assume 2.x; no plan to support 1.x |
> > >
> > >TLS was verified end-to-end against 2.0.6 with enable_thrift_ssl (TLSv1.3,
> > >full certificate verification). RPC compression (compact protocol)
> > verified
> > >against a server with dn_rpc_thrift_compression_enable=true.
> > >
> > >## 2. Contributors and provenance
> > >
> > >The entire git history has a single author — myself (Wang Xuan /
> > CritasWang
> > ><cr...@outlook.com>). I am an existing Apache IoTDB committer with an
> > ICLA
> > >already on file, and I hold full ownership of this work, so the provenance
> > >chain is straightforward. Two categories of code in the repo:
> > >
> > >- Hand-written code: 100% original work, written for this project,
> > >Apache-2.0 headers on every file.
> > >- Generated code (src/protocol/): produced by the Apache Thrift compiler
> > >from the Apache IoTDB project's own IDL files (iotdb-protocol/, ALv2); the
> > >generation pipeline (tools/generate-thrift.sh) is documented and
> > >reproducible.
> > >
> > >No code was copied from other client SDKs; the Java/C#/Node.js clients
> > were
> > >used as behavioral references only (wire-protocol semantics), which is
> > also
> > >how the cross-client protocol issues (e.g. the Node.js DATE encoding bug)
> > >were found.
> > >
> > >## 3. Dependency and license inventory
> > >
> > >Runtime dependencies (4 + 1 optional):
> > >
> > >| Crate | Version | License | Purpose |
> > >|---|---|---|---|
> > >| thrift | 0.23 | Apache-2.0 | RPC (matches the compiler version pinned by
> > >the IoTDB pom) |
> > >| byteorder | 1.5 | Unlicense OR MIT | Big-endian encoding |
> > >| chrono | 0.4 | MIT OR Apache-2.0 | DATE handling |
> > >| log | 0.4 | MIT OR Apache-2.0 | Logging facade |
> > >| native-tls (optional, feature "tls") | 0.2 | MIT OR Apache-2.0 | TLS |
> > >
> > >Dev-dependency: env_logger (MIT OR Apache-2.0). Full transitive closure:
> > 74
> > >packages, machine-checked — every one is MIT / Apache-2.0 / Unlicense /
> > BSD
> > >/ Zlib dual-or-multi licensed, i.e. 100% ASF Category-A. Zero
> > Category-B/X,
> > >zero unknown-license packages. The full inventory (cargo metadata) can be
> > >attached to the IP-clearance checklist.
> > >
> > >## 4. Proposed initial maintainers and maintenance plan
> > >
> > >- Initial maintainer: myself (CritasWang — existing IoTDB committer). I
> > >commit to maintaining the client — issue triage, protocol-sync with
> > >iotdb-protocol changes, and regular releases through the normal IoTDB
> > >community process — and to growing co-maintainers from the community;
> > >review bandwidth from other committers/PMC members on client-facing
> > changes
> > >would be welcome.
> > >- The repo already carries the practices expected for handover: CI (fmt /
> > >clippy -D warnings / license check / unit tests / live integration against
> > >a service container), bilingual READMEs, runnable examples, a
> > >statistics-aligned benchmark, and a documented codegen pipeline. Nothing
> > >depends on my personal infrastructure.
> > >
> > >## 5. API support matrix (vs Java client) and near-term roadmap
> > >
> > >Supported today (feature → Java-client equivalent):
> > >
> > >| Area | Rust today | Java client |
> > >|---|---|---|
> > >| Session lifecycle, multi-node URLs, failover, auto-reconnect | ✅ | ✅ |
> > >| insertTablet / insertTablets | ✅ | ✅ |
> > >| insertRecord(s) / insertRecordsOfOneDevice (+ aligned variants) | ✅ | ✅
> > |
> > >| Table model (TableSession/Pool, TAG/FIELD/ATTRIBUTE) | ✅ | ✅ |
> > >| SessionPool / TableSessionPool (idle eviction, redirection cache) | ✅ |
> > ✅
> > >|
> > >| Query + paging iteration (TsBlock, fetchResultsV2) | ✅ | ✅ |
> > >| All data types incl. TIMESTAMP/DATE/BLOB/STRING | ✅ | ✅ |
> > >| TLS (incl. client identity) / RPC compression | ✅ | ✅ |
> > >| deleteData / deleteTimeseries / DDL helpers | SQL only | ✅ dedicated
> > APIs
> > >|
> > >| Schema templates | ❌ | ✅ |
> > >| executeRawDataQuery / executeLastDataQuery / aggregation APIs | ❌ | ✅ |
> > >| Per-type encoding tuning (RPC compression V2) | ❌ | ✅ |
> > >
> > >Near-term roadmap (order negotiable with the community):
> > >
> > >1. async (tokio) API layer — most-requested Rust-ecosystem feature, kept
> > >out of v0.1 to keep the sync core small
> > >2. crates.io releases under the Apache project
> > >
> > >I'll keep this thread open for feedback on maintenance ownership and API
> > >scope as suggested. Since I'm an existing committer with an ICLA on file
> > >and the sole author, the IP-clearance paperwork should be light — I'm
> > happy
> > >to prepare whatever the PMC deems necessary (software grant if required
> > for
> > >the pre-existing external history, plus the dependency inventory above)
> > >whenever the community feels ready to move to a VOTE.
> > >
> > >Best regards,
> > >Xuan Wang
> > >
> > >Haonan Hou <ha...@apache.org> 于2026年7月15日周三 15:06写道:
> > >
> > >> Hi Xuan,
> > >>
> > >> Thank you for sharing this work. The implementation already covers a
> > >> substantial part of the client functionality, and the test coverage,
> > live
> > >> integration testing, CI setup, and benchmark results are all
> > encouraging.
> > >>
> > >> The protocol issues and performance improvements discovered while
> > >> validating
> > >> against the other clients are also a good indication that this work can
> > >> benefit the broader IoTDB client ecosystem.
> > >>
> > >> As a member of the IoTDB PMC, I support bringing a well-maintained Rust
> > >> client
> > >> into the Apache IoTDB project. Based on what you have presented, I
> > believe
> > >> this
> > >> repository is a strong candidate for donation and for becoming an
> > official
> > >> IoTDB client.
> > >>
> > >> Since IoTDB is already an Apache top-level project, the appropriate
> > route
> > >> should be a code donation to the existing project, followed by the ASF
> > IP
> > >> clearance process, rather than incubation as a separate project.
> > >>
> > >> I suggest the following next steps:
> > >>
> > >> 1. Continue this DISCUSS thread to collect feedback from the community,
> > >>    especially regarding maintenance ownership and the initial API scope.
> > >> 2. Prepare a concise compatibility and API-support matrix against the
> > Java
> > >>    client, together with a near-term roadmap.
> > >> 3. If there are no major concerns, start a formal PMC VOTE to accept the
> > >> code
> > >>    donation and create the apache/iotdb-client-rust repository.
> > >> 4. Complete the software grant, code provenance, dependency/license
> > review,
> > >>    and ASF IP clearance.
> > >> 5. Move the code to the Apache repository and continue development and
> > >>    releases through the normal IoTDB community process.
> > >>
> > >> I do not think complete Java client API parity needs to be a
> > prerequisite
> > >> for
> > >> the donation. The current functionality appears sufficient to establish
> > a
> > >> useful official client. APIs such as schema-template operations and
> > >> additional
> > >> session-level query methods can be added incrementally and tracked
> > through
> > >> a
> > >> public roadmap.
> > >>
> > >> Before moving to a vote, it would be helpful to provide:
> > >>
> > >> - The supported IoTDB version matrix.
> > >> - A list of contributors and confirmation of the code’s
> > >> ownership/provenance.
> > >> - A dependency and license inventory.
> > >> - The proposed initial maintainers and long-term maintenance plan.
> > >> - An API support matrix and near-term roadmap.
> > >>
> > >> Overall, I am supportive of this proposal and am willing to help move
> > the
> > >> discussion and donation process forward.
> > >>
> > >> Best regards,
> > >> Haonan Hou
> > >>
> > >> On 2026/07/15 03:50:24 王旋 wrote:
> > >> > Hi all,
> > >> >
> > >> > I'd like to share a Rust client SDK for Apache IoTDB that I've been
> > >> > developing, and ask for the community's feedback on whether there is
> > >> > interest in bringing it into the Apache IoTDB ecosystem.
> > >> >
> > >> > Repository: https://github.com/CritasWang/iotdb-client-rust
> > >> >
> > >> > Scope & features
> > >> >
> > >> > Tree model (Session) and table model (TableSession / SQL dialect),
> > >> > mirroring the API shape of the Java / C# / Node.js clients
> > >> > Write APIs: insertTablet / insertTablets (multi-tablet batching),
> > >> > insertRecord(s), insertRecordsOfOneDevice, plus aligned variants
> > >> > SessionPool and TableSessionPool: RAII checkout, lazy growth, idle
> > >> > eviction, dead-connection eviction, write-redirection cache (status
> > 400
> > >> > redirect hints), automatic reconnect with endpoint failover
> > >> > Full data-type coverage including TIMESTAMP / DATE / BLOB / STRING;
> > >> TsBlock
> > >> > decoding with logical-type re-tagging (the TsBlock header carries
> > >> physical
> > >> > types — DATE arrives as INT32, BLOB as TEXT)
> > >> > TLS (feature-gated, incl. client identity) — verified end-to-end
> > against
> > >> a
> > >> > real IoTDB with enable_thrift_ssl; RPC compression (compact protocol)
> > >> > Thrift codegen pipeline sources the IDL from iotdb-protocol/ and uses
> > the
> > >> > thrift compiler fetched by the IoTDB Maven build, so the stubs stay in
> > >> > lockstep with the server
> > >> >
> > >> > Quality
> > >> >
> > >> > 113 unit tests (124 with TLS) + live integration tests that skip
> > >> gracefully
> > >> > without a server; CI on GitHub Actions runs fmt / clippy -D warnings /
> > >> > license checks plus an integration job against an IoTDB 2.0.6 service
> > >> > container — green
> > >> > Statistics-aligned benchmark (measurement semantics mirror
> > iot-benchmark:
> > >> > prep inside the timed span, failures excluded from latency,
> > >> Result/Latency
> > >> > Matrix output). On a 16-core server writing 2B points per run (table
> > >> model,
> > >> > 100 devices x 20 DOUBLE sensors, 1000-row tablets, 20 sessions), the
> > Rust
> > >> > client sustains ~46-47M points/s — statistically tied with
> > >> iot-benchmark's
> > >> > Java Session path on the same box, where the server, not the client,
> > is
> > >> the
> > >> > ceiling
> > >> > Every file carries the ASF Apache 2.0 header
> > >> >
> > >> > Side effects the community already received
> > >> >
> > >> > Cross-validating the wire protocol against the Java / C# / Node.js
> > >> > implementations surfaced two upstream issues in the Node.js client,
> > both
> > >> > now addressed: the DATE wire-encoding fix
> > (apache/iotdb-client-nodejs#14,
> > >> > PR #15, merged) and a write-path serialization optimization (+52%
> > >> > throughput, PR #16, under review).
> > >> >
> > >> > Questions for the community
> > >> >
> > >> > Is there interest in an official Rust client under the Apache IoTDB
> > >> > umbrella (e.g., apache/iotdb-client-rust), following the path of the
> > >> > Node.js / C# clients?
> > >> > If so, what would the preferred route be — code donation via the
> > >> incubator
> > >> > process for client SDKs, or starting a repo under the existing project
> > >> and
> > >> > iterating there?
> > >> > Any API-surface expectations from the PMC side before such a move
> > (e.g.,
> > >> > schema-template APIs, session-level query APIs like
> > executeRawDataQuery)?
> > >> > I'm happy to keep maintaining it either way, and to align the roadmap
> > >> with
> > >> > the community's priorities.
> > >> >
> > >> > 大家好
> > >> >
> > >> > 我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入 Apache
> > >> > IoTDB 生态。
> > >> >
> > >> > 仓库地址:https://github.com/CritasWang/iotdb-client-rust
> > >> >
> > >> > 范围与功能
> > >> >
> > >> > 树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# / Node.js
> > 客户端对齐
> > >> > 写入 API:insertTablet / insertTablets(多 tablet
> > >> > 批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
> > >> > SessionPool 与 TableSessionPool:RAII 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status
> > 400
> > >> > 重定向提示)、带端点故障转移的自动重连
> > >> > 完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock
> > 解码带逻辑类型重标记(TsBlock
> > >> > 头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
> > >> > TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB 完成端到端验证;RPC
> > >> > 压缩(compact 协议)
> > >> > Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven 构建拉取的版本,确保
> > stub
> > >> > 与服务端严格同步
> > >> >
> > >> > 质量
> > >> >
> > >> > 113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions CI 运行
> > fmt /
> > >> > clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service container 的集成
> > >> > job——全绿
> > >> > 统计口径对齐的基准测试(测量语义对齐 iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency
> > Matrix
> > >> > 输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000 行/tablet、20
> > >> > 会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java Session
> > >> > 路径统计学持平,此时瓶颈在服务端而非客户端
> > >> > 所有文件均带 ASF Apache 2.0 头
> > >> >
> > >> > 社区已经收到的副产品
> > >> >
> > >> > 在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js
> > 客户端的两个上游问题,目前均已处理:DATE
> > >> > 线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐 +52%,PR
> > >> > #16,评审中)。
> > >> >
> > >> > 想请教社区的问题
> > >> >
> > >> > 社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如 apache/iotdb-client-rust),沿用
> > >> > Node.js / C# 客户端的路径?
> > >> > 如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
> > >> > 在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery 等会话级查询
> > API)?
> > >> > 无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。
> > >> >
> > >> > Best regards,
> > >> > Xuan Wang
> > >> >
> > >>
> >
> 

Re: Re: [DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Posted by 王旋 <cr...@gmail.com>.
Hi Yuan,

Thank you for the suggestions. Status on both:

1. Compatibility & release policy -- now landed in the repository as
COMPATIBILITY.md <http://compatibility.md/> [1]:

- IoTDB server compatibility matrix: 2.0.1-2.0.8, 2.0.10 and master are
  listed; 2.0.6 and 2.0.10 are tested (CI live suite / full benchmark +
  data-correctness verification respectively), the other versions are
  explicitly marked as untested.
- A per-release protocol toolchain table recording, for each crate
  version, the exact IDL source (currently apache/iotdb master,
  iotdb-protocol/ @ 2fedd8a395) and the Thrift compiler version (0.23.0,
  as pinned by the IoTDB pom), plus the thrift crate version.
- A SemVer policy (Cargo semantics, 0.x pre-1.0 rules), a deprecation
  policy (#[deprecated] for at least one minor release before removal),
  and a release checklist that updates the toolchain table on every
  release.

CI now runs the live integration suite and examples against both the
oldest tested and the latest stable IoTDB (2.0.6 and 2.0.10) as a build
matrix [2].

2. crates.io publishing permissions and a community-managed release
process -- fully agreed. Since this depends on the Apache repository and
community processes existing first, I will file it as a roadmap issue in
apache/iotdb-client-rust once the repository is created, covering
community-owned crates.io ownership, reproducible release steps, and
review by multiple maintainers.

[1]
https://github.com/CritasWang/iotdb-client-rust/blob/main/COMPATIBILITY.md
[2]
https://github.com/CritasWang/iotdb-client-rust/blob/main/.github/workflows/ci.yml

Best regards,
Xuan Wang

zerolbsony <ze...@163.com> 于2026年7月16日周四 20:58写道:

> Hi, Xuan Wang
> It’s hard to believe that Rust has overtaken Go and become so popular.
> The top 10 programming languages in the July 2026 TIOBE rankings are as
> follows:
> Python – 18.94%
> C – 10.86%
> C++ – 9.12%
> Java – 8.03%
> C# – 4.49%
> JavaScript – 2.72%
> Visual Basic – 2.48%
> SQL – 1.71%
> R – 1.69%
> Rust – 1.34%
>
>
> I’ve noticed that starting from 2024, the Linux kernel has allowed certain
> modules, primarily device drivers, to be written in Rust.
>
>
> Rust can be used to write Linux kernel modules, which means you can run
> Rust code directly at the kernel level. This is extremely useful for
> scenarios that demand high performance and low-level hardware operations.
> Have you considered invoking certain IoTDB functionalities directly via the
> Linux kernel to boost performance?
> Best regards,
> Bo Li
>
>
> >Hi,
> >
> >Thank you very much for the supportive and detailed reply. The suggested
> >route (code donation to the existing TLP + ASF IP clearance, rather than
> >incubation) makes sense to me, and I'm glad full Java-parity is not a
> >prerequisite — an incremental, roadmap-tracked approach matches how the
> >client was built.
> >
> >Below are the five items requested before a vote.
> >
> >## 1. Supported IoTDB version matrix
> >
> >| IoTDB version | Status | Evidence |
> >|---|---|---|
> >| 2.0.6 | Supported | CI integration job runs the full live test suite + 3
> >examples against apache/iotdb:2.0.6-standalone on every push |
> >| 2.0.10 | Supported | Full benchmark + data-correctness verification (all
> >10 data types, tree & table, nulls) against a 2.0.10 standalone
> deployment |
> >| 2.0.x (general) | Expected to work | Thrift IDL is synced from
> >iotdb-protocol/ master; protocol version V3; no version-specific branching
> >in the client |
> >| 1.x | Not targeted | Table model and several data types
> >(TIMESTAMP/DATE/BLOB/STRING) assume 2.x; no plan to support 1.x |
> >
> >TLS was verified end-to-end against 2.0.6 with enable_thrift_ssl (TLSv1.3,
> >full certificate verification). RPC compression (compact protocol)
> verified
> >against a server with dn_rpc_thrift_compression_enable=true.
> >
> >## 2. Contributors and provenance
> >
> >The entire git history has a single author — myself (Wang Xuan /
> CritasWang
> ><cr...@outlook.com>). I am an existing Apache IoTDB committer with an
> ICLA
> >already on file, and I hold full ownership of this work, so the provenance
> >chain is straightforward. Two categories of code in the repo:
> >
> >- Hand-written code: 100% original work, written for this project,
> >Apache-2.0 headers on every file.
> >- Generated code (src/protocol/): produced by the Apache Thrift compiler
> >from the Apache IoTDB project's own IDL files (iotdb-protocol/, ALv2); the
> >generation pipeline (tools/generate-thrift.sh) is documented and
> >reproducible.
> >
> >No code was copied from other client SDKs; the Java/C#/Node.js clients
> were
> >used as behavioral references only (wire-protocol semantics), which is
> also
> >how the cross-client protocol issues (e.g. the Node.js DATE encoding bug)
> >were found.
> >
> >## 3. Dependency and license inventory
> >
> >Runtime dependencies (4 + 1 optional):
> >
> >| Crate | Version | License | Purpose |
> >|---|---|---|---|
> >| thrift | 0.23 | Apache-2.0 | RPC (matches the compiler version pinned by
> >the IoTDB pom) |
> >| byteorder | 1.5 | Unlicense OR MIT | Big-endian encoding |
> >| chrono | 0.4 | MIT OR Apache-2.0 | DATE handling |
> >| log | 0.4 | MIT OR Apache-2.0 | Logging facade |
> >| native-tls (optional, feature "tls") | 0.2 | MIT OR Apache-2.0 | TLS |
> >
> >Dev-dependency: env_logger (MIT OR Apache-2.0). Full transitive closure:
> 74
> >packages, machine-checked — every one is MIT / Apache-2.0 / Unlicense /
> BSD
> >/ Zlib dual-or-multi licensed, i.e. 100% ASF Category-A. Zero
> Category-B/X,
> >zero unknown-license packages. The full inventory (cargo metadata) can be
> >attached to the IP-clearance checklist.
> >
> >## 4. Proposed initial maintainers and maintenance plan
> >
> >- Initial maintainer: myself (CritasWang — existing IoTDB committer). I
> >commit to maintaining the client — issue triage, protocol-sync with
> >iotdb-protocol changes, and regular releases through the normal IoTDB
> >community process — and to growing co-maintainers from the community;
> >review bandwidth from other committers/PMC members on client-facing
> changes
> >would be welcome.
> >- The repo already carries the practices expected for handover: CI (fmt /
> >clippy -D warnings / license check / unit tests / live integration against
> >a service container), bilingual READMEs, runnable examples, a
> >statistics-aligned benchmark, and a documented codegen pipeline. Nothing
> >depends on my personal infrastructure.
> >
> >## 5. API support matrix (vs Java client) and near-term roadmap
> >
> >Supported today (feature → Java-client equivalent):
> >
> >| Area | Rust today | Java client |
> >|---|---|---|
> >| Session lifecycle, multi-node URLs, failover, auto-reconnect | ✅ | ✅ |
> >| insertTablet / insertTablets | ✅ | ✅ |
> >| insertRecord(s) / insertRecordsOfOneDevice (+ aligned variants) | ✅ | ✅
> |
> >| Table model (TableSession/Pool, TAG/FIELD/ATTRIBUTE) | ✅ | ✅ |
> >| SessionPool / TableSessionPool (idle eviction, redirection cache) | ✅ |
> ✅
> >|
> >| Query + paging iteration (TsBlock, fetchResultsV2) | ✅ | ✅ |
> >| All data types incl. TIMESTAMP/DATE/BLOB/STRING | ✅ | ✅ |
> >| TLS (incl. client identity) / RPC compression | ✅ | ✅ |
> >| deleteData / deleteTimeseries / DDL helpers | SQL only | ✅ dedicated
> APIs
> >|
> >| Schema templates | ❌ | ✅ |
> >| executeRawDataQuery / executeLastDataQuery / aggregation APIs | ❌ | ✅ |
> >| Per-type encoding tuning (RPC compression V2) | ❌ | ✅ |
> >
> >Near-term roadmap (order negotiable with the community):
> >
> >1. async (tokio) API layer — most-requested Rust-ecosystem feature, kept
> >out of v0.1 to keep the sync core small
> >2. crates.io releases under the Apache project
> >
> >I'll keep this thread open for feedback on maintenance ownership and API
> >scope as suggested. Since I'm an existing committer with an ICLA on file
> >and the sole author, the IP-clearance paperwork should be light — I'm
> happy
> >to prepare whatever the PMC deems necessary (software grant if required
> for
> >the pre-existing external history, plus the dependency inventory above)
> >whenever the community feels ready to move to a VOTE.
> >
> >Best regards,
> >Xuan Wang
> >
> >Haonan Hou <ha...@apache.org> 于2026年7月15日周三 15:06写道:
> >
> >> Hi Xuan,
> >>
> >> Thank you for sharing this work. The implementation already covers a
> >> substantial part of the client functionality, and the test coverage,
> live
> >> integration testing, CI setup, and benchmark results are all
> encouraging.
> >>
> >> The protocol issues and performance improvements discovered while
> >> validating
> >> against the other clients are also a good indication that this work can
> >> benefit the broader IoTDB client ecosystem.
> >>
> >> As a member of the IoTDB PMC, I support bringing a well-maintained Rust
> >> client
> >> into the Apache IoTDB project. Based on what you have presented, I
> believe
> >> this
> >> repository is a strong candidate for donation and for becoming an
> official
> >> IoTDB client.
> >>
> >> Since IoTDB is already an Apache top-level project, the appropriate
> route
> >> should be a code donation to the existing project, followed by the ASF
> IP
> >> clearance process, rather than incubation as a separate project.
> >>
> >> I suggest the following next steps:
> >>
> >> 1. Continue this DISCUSS thread to collect feedback from the community,
> >>    especially regarding maintenance ownership and the initial API scope.
> >> 2. Prepare a concise compatibility and API-support matrix against the
> Java
> >>    client, together with a near-term roadmap.
> >> 3. If there are no major concerns, start a formal PMC VOTE to accept the
> >> code
> >>    donation and create the apache/iotdb-client-rust repository.
> >> 4. Complete the software grant, code provenance, dependency/license
> review,
> >>    and ASF IP clearance.
> >> 5. Move the code to the Apache repository and continue development and
> >>    releases through the normal IoTDB community process.
> >>
> >> I do not think complete Java client API parity needs to be a
> prerequisite
> >> for
> >> the donation. The current functionality appears sufficient to establish
> a
> >> useful official client. APIs such as schema-template operations and
> >> additional
> >> session-level query methods can be added incrementally and tracked
> through
> >> a
> >> public roadmap.
> >>
> >> Before moving to a vote, it would be helpful to provide:
> >>
> >> - The supported IoTDB version matrix.
> >> - A list of contributors and confirmation of the code’s
> >> ownership/provenance.
> >> - A dependency and license inventory.
> >> - The proposed initial maintainers and long-term maintenance plan.
> >> - An API support matrix and near-term roadmap.
> >>
> >> Overall, I am supportive of this proposal and am willing to help move
> the
> >> discussion and donation process forward.
> >>
> >> Best regards,
> >> Haonan Hou
> >>
> >> On 2026/07/15 03:50:24 王旋 wrote:
> >> > Hi all,
> >> >
> >> > I'd like to share a Rust client SDK for Apache IoTDB that I've been
> >> > developing, and ask for the community's feedback on whether there is
> >> > interest in bringing it into the Apache IoTDB ecosystem.
> >> >
> >> > Repository: https://github.com/CritasWang/iotdb-client-rust
> >> >
> >> > Scope & features
> >> >
> >> > Tree model (Session) and table model (TableSession / SQL dialect),
> >> > mirroring the API shape of the Java / C# / Node.js clients
> >> > Write APIs: insertTablet / insertTablets (multi-tablet batching),
> >> > insertRecord(s), insertRecordsOfOneDevice, plus aligned variants
> >> > SessionPool and TableSessionPool: RAII checkout, lazy growth, idle
> >> > eviction, dead-connection eviction, write-redirection cache (status
> 400
> >> > redirect hints), automatic reconnect with endpoint failover
> >> > Full data-type coverage including TIMESTAMP / DATE / BLOB / STRING;
> >> TsBlock
> >> > decoding with logical-type re-tagging (the TsBlock header carries
> >> physical
> >> > types — DATE arrives as INT32, BLOB as TEXT)
> >> > TLS (feature-gated, incl. client identity) — verified end-to-end
> against
> >> a
> >> > real IoTDB with enable_thrift_ssl; RPC compression (compact protocol)
> >> > Thrift codegen pipeline sources the IDL from iotdb-protocol/ and uses
> the
> >> > thrift compiler fetched by the IoTDB Maven build, so the stubs stay in
> >> > lockstep with the server
> >> >
> >> > Quality
> >> >
> >> > 113 unit tests (124 with TLS) + live integration tests that skip
> >> gracefully
> >> > without a server; CI on GitHub Actions runs fmt / clippy -D warnings /
> >> > license checks plus an integration job against an IoTDB 2.0.6 service
> >> > container — green
> >> > Statistics-aligned benchmark (measurement semantics mirror
> iot-benchmark:
> >> > prep inside the timed span, failures excluded from latency,
> >> Result/Latency
> >> > Matrix output). On a 16-core server writing 2B points per run (table
> >> model,
> >> > 100 devices x 20 DOUBLE sensors, 1000-row tablets, 20 sessions), the
> Rust
> >> > client sustains ~46-47M points/s — statistically tied with
> >> iot-benchmark's
> >> > Java Session path on the same box, where the server, not the client,
> is
> >> the
> >> > ceiling
> >> > Every file carries the ASF Apache 2.0 header
> >> >
> >> > Side effects the community already received
> >> >
> >> > Cross-validating the wire protocol against the Java / C# / Node.js
> >> > implementations surfaced two upstream issues in the Node.js client,
> both
> >> > now addressed: the DATE wire-encoding fix
> (apache/iotdb-client-nodejs#14,
> >> > PR #15, merged) and a write-path serialization optimization (+52%
> >> > throughput, PR #16, under review).
> >> >
> >> > Questions for the community
> >> >
> >> > Is there interest in an official Rust client under the Apache IoTDB
> >> > umbrella (e.g., apache/iotdb-client-rust), following the path of the
> >> > Node.js / C# clients?
> >> > If so, what would the preferred route be — code donation via the
> >> incubator
> >> > process for client SDKs, or starting a repo under the existing project
> >> and
> >> > iterating there?
> >> > Any API-surface expectations from the PMC side before such a move
> (e.g.,
> >> > schema-template APIs, session-level query APIs like
> executeRawDataQuery)?
> >> > I'm happy to keep maintaining it either way, and to align the roadmap
> >> with
> >> > the community's priorities.
> >> >
> >> > 大家好
> >> >
> >> > 我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入 Apache
> >> > IoTDB 生态。
> >> >
> >> > 仓库地址:https://github.com/CritasWang/iotdb-client-rust
> >> >
> >> > 范围与功能
> >> >
> >> > 树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# / Node.js
> 客户端对齐
> >> > 写入 API:insertTablet / insertTablets(多 tablet
> >> > 批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
> >> > SessionPool 与 TableSessionPool:RAII 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status
> 400
> >> > 重定向提示)、带端点故障转移的自动重连
> >> > 完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock
> 解码带逻辑类型重标记(TsBlock
> >> > 头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
> >> > TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB 完成端到端验证;RPC
> >> > 压缩(compact 协议)
> >> > Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven 构建拉取的版本,确保
> stub
> >> > 与服务端严格同步
> >> >
> >> > 质量
> >> >
> >> > 113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions CI 运行
> fmt /
> >> > clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service container 的集成
> >> > job——全绿
> >> > 统计口径对齐的基准测试(测量语义对齐 iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency
> Matrix
> >> > 输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000 行/tablet、20
> >> > 会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java Session
> >> > 路径统计学持平,此时瓶颈在服务端而非客户端
> >> > 所有文件均带 ASF Apache 2.0 头
> >> >
> >> > 社区已经收到的副产品
> >> >
> >> > 在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js
> 客户端的两个上游问题,目前均已处理:DATE
> >> > 线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐 +52%,PR
> >> > #16,评审中)。
> >> >
> >> > 想请教社区的问题
> >> >
> >> > 社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如 apache/iotdb-client-rust),沿用
> >> > Node.js / C# 客户端的路径?
> >> > 如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
> >> > 在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery 等会话级查询
> API)?
> >> > 无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。
> >> >
> >> > Best regards,
> >> > Xuan Wang
> >> >
> >>
>

Re:Re: [DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Posted by zerolbsony <ze...@163.com>.
Hi, Xuan Wang
It’s hard to believe that Rust has overtaken Go and become so popular.
The top 10 programming languages in the July 2026 TIOBE rankings are as follows:
Python – 18.94%
C – 10.86%
C++ – 9.12%
Java – 8.03%
C# – 4.49%
JavaScript – 2.72%
Visual Basic – 2.48%
SQL – 1.71%
R – 1.69%
Rust – 1.34%


I’ve noticed that starting from 2024, the Linux kernel has allowed certain modules, primarily device drivers, to be written in Rust.


Rust can be used to write Linux kernel modules, which means you can run Rust code directly at the kernel level. This is extremely useful for scenarios that demand high performance and low-level hardware operations. Have you considered invoking certain IoTDB functionalities directly via the Linux kernel to boost performance?
Best regards,
Bo Li


>Hi,
>
>Thank you very much for the supportive and detailed reply. The suggested
>route (code donation to the existing TLP + ASF IP clearance, rather than
>incubation) makes sense to me, and I'm glad full Java-parity is not a
>prerequisite — an incremental, roadmap-tracked approach matches how the
>client was built.
>
>Below are the five items requested before a vote.
>
>## 1. Supported IoTDB version matrix
>
>| IoTDB version | Status | Evidence |
>|---|---|---|
>| 2.0.6 | Supported | CI integration job runs the full live test suite + 3
>examples against apache/iotdb:2.0.6-standalone on every push |
>| 2.0.10 | Supported | Full benchmark + data-correctness verification (all
>10 data types, tree & table, nulls) against a 2.0.10 standalone deployment |
>| 2.0.x (general) | Expected to work | Thrift IDL is synced from
>iotdb-protocol/ master; protocol version V3; no version-specific branching
>in the client |
>| 1.x | Not targeted | Table model and several data types
>(TIMESTAMP/DATE/BLOB/STRING) assume 2.x; no plan to support 1.x |
>
>TLS was verified end-to-end against 2.0.6 with enable_thrift_ssl (TLSv1.3,
>full certificate verification). RPC compression (compact protocol) verified
>against a server with dn_rpc_thrift_compression_enable=true.
>
>## 2. Contributors and provenance
>
>The entire git history has a single author — myself (Wang Xuan / CritasWang
><cr...@outlook.com>). I am an existing Apache IoTDB committer with an ICLA
>already on file, and I hold full ownership of this work, so the provenance
>chain is straightforward. Two categories of code in the repo:
>
>- Hand-written code: 100% original work, written for this project,
>Apache-2.0 headers on every file.
>- Generated code (src/protocol/): produced by the Apache Thrift compiler
>from the Apache IoTDB project's own IDL files (iotdb-protocol/, ALv2); the
>generation pipeline (tools/generate-thrift.sh) is documented and
>reproducible.
>
>No code was copied from other client SDKs; the Java/C#/Node.js clients were
>used as behavioral references only (wire-protocol semantics), which is also
>how the cross-client protocol issues (e.g. the Node.js DATE encoding bug)
>were found.
>
>## 3. Dependency and license inventory
>
>Runtime dependencies (4 + 1 optional):
>
>| Crate | Version | License | Purpose |
>|---|---|---|---|
>| thrift | 0.23 | Apache-2.0 | RPC (matches the compiler version pinned by
>the IoTDB pom) |
>| byteorder | 1.5 | Unlicense OR MIT | Big-endian encoding |
>| chrono | 0.4 | MIT OR Apache-2.0 | DATE handling |
>| log | 0.4 | MIT OR Apache-2.0 | Logging facade |
>| native-tls (optional, feature "tls") | 0.2 | MIT OR Apache-2.0 | TLS |
>
>Dev-dependency: env_logger (MIT OR Apache-2.0). Full transitive closure: 74
>packages, machine-checked — every one is MIT / Apache-2.0 / Unlicense / BSD
>/ Zlib dual-or-multi licensed, i.e. 100% ASF Category-A. Zero Category-B/X,
>zero unknown-license packages. The full inventory (cargo metadata) can be
>attached to the IP-clearance checklist.
>
>## 4. Proposed initial maintainers and maintenance plan
>
>- Initial maintainer: myself (CritasWang — existing IoTDB committer). I
>commit to maintaining the client — issue triage, protocol-sync with
>iotdb-protocol changes, and regular releases through the normal IoTDB
>community process — and to growing co-maintainers from the community;
>review bandwidth from other committers/PMC members on client-facing changes
>would be welcome.
>- The repo already carries the practices expected for handover: CI (fmt /
>clippy -D warnings / license check / unit tests / live integration against
>a service container), bilingual READMEs, runnable examples, a
>statistics-aligned benchmark, and a documented codegen pipeline. Nothing
>depends on my personal infrastructure.
>
>## 5. API support matrix (vs Java client) and near-term roadmap
>
>Supported today (feature → Java-client equivalent):
>
>| Area | Rust today | Java client |
>|---|---|---|
>| Session lifecycle, multi-node URLs, failover, auto-reconnect | ✅ | ✅ |
>| insertTablet / insertTablets | ✅ | ✅ |
>| insertRecord(s) / insertRecordsOfOneDevice (+ aligned variants) | ✅ | ✅ |
>| Table model (TableSession/Pool, TAG/FIELD/ATTRIBUTE) | ✅ | ✅ |
>| SessionPool / TableSessionPool (idle eviction, redirection cache) | ✅ | ✅
>|
>| Query + paging iteration (TsBlock, fetchResultsV2) | ✅ | ✅ |
>| All data types incl. TIMESTAMP/DATE/BLOB/STRING | ✅ | ✅ |
>| TLS (incl. client identity) / RPC compression | ✅ | ✅ |
>| deleteData / deleteTimeseries / DDL helpers | SQL only | ✅ dedicated APIs
>|
>| Schema templates | ❌ | ✅ |
>| executeRawDataQuery / executeLastDataQuery / aggregation APIs | ❌ | ✅ |
>| Per-type encoding tuning (RPC compression V2) | ❌ | ✅ |
>
>Near-term roadmap (order negotiable with the community):
>
>1. async (tokio) API layer — most-requested Rust-ecosystem feature, kept
>out of v0.1 to keep the sync core small
>2. crates.io releases under the Apache project
>
>I'll keep this thread open for feedback on maintenance ownership and API
>scope as suggested. Since I'm an existing committer with an ICLA on file
>and the sole author, the IP-clearance paperwork should be light — I'm happy
>to prepare whatever the PMC deems necessary (software grant if required for
>the pre-existing external history, plus the dependency inventory above)
>whenever the community feels ready to move to a VOTE.
>
>Best regards,
>Xuan Wang
>
>Haonan Hou <ha...@apache.org> 于2026年7月15日周三 15:06写道:
>
>> Hi Xuan,
>>
>> Thank you for sharing this work. The implementation already covers a
>> substantial part of the client functionality, and the test coverage, live
>> integration testing, CI setup, and benchmark results are all encouraging.
>>
>> The protocol issues and performance improvements discovered while
>> validating
>> against the other clients are also a good indication that this work can
>> benefit the broader IoTDB client ecosystem.
>>
>> As a member of the IoTDB PMC, I support bringing a well-maintained Rust
>> client
>> into the Apache IoTDB project. Based on what you have presented, I believe
>> this
>> repository is a strong candidate for donation and for becoming an official
>> IoTDB client.
>>
>> Since IoTDB is already an Apache top-level project, the appropriate route
>> should be a code donation to the existing project, followed by the ASF IP
>> clearance process, rather than incubation as a separate project.
>>
>> I suggest the following next steps:
>>
>> 1. Continue this DISCUSS thread to collect feedback from the community,
>>    especially regarding maintenance ownership and the initial API scope.
>> 2. Prepare a concise compatibility and API-support matrix against the Java
>>    client, together with a near-term roadmap.
>> 3. If there are no major concerns, start a formal PMC VOTE to accept the
>> code
>>    donation and create the apache/iotdb-client-rust repository.
>> 4. Complete the software grant, code provenance, dependency/license review,
>>    and ASF IP clearance.
>> 5. Move the code to the Apache repository and continue development and
>>    releases through the normal IoTDB community process.
>>
>> I do not think complete Java client API parity needs to be a prerequisite
>> for
>> the donation. The current functionality appears sufficient to establish a
>> useful official client. APIs such as schema-template operations and
>> additional
>> session-level query methods can be added incrementally and tracked through
>> a
>> public roadmap.
>>
>> Before moving to a vote, it would be helpful to provide:
>>
>> - The supported IoTDB version matrix.
>> - A list of contributors and confirmation of the code’s
>> ownership/provenance.
>> - A dependency and license inventory.
>> - The proposed initial maintainers and long-term maintenance plan.
>> - An API support matrix and near-term roadmap.
>>
>> Overall, I am supportive of this proposal and am willing to help move the
>> discussion and donation process forward.
>>
>> Best regards,
>> Haonan Hou
>>
>> On 2026/07/15 03:50:24 王旋 wrote:
>> > Hi all,
>> >
>> > I'd like to share a Rust client SDK for Apache IoTDB that I've been
>> > developing, and ask for the community's feedback on whether there is
>> > interest in bringing it into the Apache IoTDB ecosystem.
>> >
>> > Repository: https://github.com/CritasWang/iotdb-client-rust
>> >
>> > Scope & features
>> >
>> > Tree model (Session) and table model (TableSession / SQL dialect),
>> > mirroring the API shape of the Java / C# / Node.js clients
>> > Write APIs: insertTablet / insertTablets (multi-tablet batching),
>> > insertRecord(s), insertRecordsOfOneDevice, plus aligned variants
>> > SessionPool and TableSessionPool: RAII checkout, lazy growth, idle
>> > eviction, dead-connection eviction, write-redirection cache (status 400
>> > redirect hints), automatic reconnect with endpoint failover
>> > Full data-type coverage including TIMESTAMP / DATE / BLOB / STRING;
>> TsBlock
>> > decoding with logical-type re-tagging (the TsBlock header carries
>> physical
>> > types — DATE arrives as INT32, BLOB as TEXT)
>> > TLS (feature-gated, incl. client identity) — verified end-to-end against
>> a
>> > real IoTDB with enable_thrift_ssl; RPC compression (compact protocol)
>> > Thrift codegen pipeline sources the IDL from iotdb-protocol/ and uses the
>> > thrift compiler fetched by the IoTDB Maven build, so the stubs stay in
>> > lockstep with the server
>> >
>> > Quality
>> >
>> > 113 unit tests (124 with TLS) + live integration tests that skip
>> gracefully
>> > without a server; CI on GitHub Actions runs fmt / clippy -D warnings /
>> > license checks plus an integration job against an IoTDB 2.0.6 service
>> > container — green
>> > Statistics-aligned benchmark (measurement semantics mirror iot-benchmark:
>> > prep inside the timed span, failures excluded from latency,
>> Result/Latency
>> > Matrix output). On a 16-core server writing 2B points per run (table
>> model,
>> > 100 devices x 20 DOUBLE sensors, 1000-row tablets, 20 sessions), the Rust
>> > client sustains ~46-47M points/s — statistically tied with
>> iot-benchmark's
>> > Java Session path on the same box, where the server, not the client, is
>> the
>> > ceiling
>> > Every file carries the ASF Apache 2.0 header
>> >
>> > Side effects the community already received
>> >
>> > Cross-validating the wire protocol against the Java / C# / Node.js
>> > implementations surfaced two upstream issues in the Node.js client, both
>> > now addressed: the DATE wire-encoding fix (apache/iotdb-client-nodejs#14,
>> > PR #15, merged) and a write-path serialization optimization (+52%
>> > throughput, PR #16, under review).
>> >
>> > Questions for the community
>> >
>> > Is there interest in an official Rust client under the Apache IoTDB
>> > umbrella (e.g., apache/iotdb-client-rust), following the path of the
>> > Node.js / C# clients?
>> > If so, what would the preferred route be — code donation via the
>> incubator
>> > process for client SDKs, or starting a repo under the existing project
>> and
>> > iterating there?
>> > Any API-surface expectations from the PMC side before such a move (e.g.,
>> > schema-template APIs, session-level query APIs like executeRawDataQuery)?
>> > I'm happy to keep maintaining it either way, and to align the roadmap
>> with
>> > the community's priorities.
>> >
>> > 大家好
>> >
>> > 我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入 Apache
>> > IoTDB 生态。
>> >
>> > 仓库地址:https://github.com/CritasWang/iotdb-client-rust
>> >
>> > 范围与功能
>> >
>> > 树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# / Node.js 客户端对齐
>> > 写入 API:insertTablet / insertTablets(多 tablet
>> > 批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
>> > SessionPool 与 TableSessionPool:RAII 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status 400
>> > 重定向提示)、带端点故障转移的自动重连
>> > 完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock 解码带逻辑类型重标记(TsBlock
>> > 头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
>> > TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB 完成端到端验证;RPC
>> > 压缩(compact 协议)
>> > Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven 构建拉取的版本,确保 stub
>> > 与服务端严格同步
>> >
>> > 质量
>> >
>> > 113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions CI 运行 fmt /
>> > clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service container 的集成
>> > job——全绿
>> > 统计口径对齐的基准测试(测量语义对齐 iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency Matrix
>> > 输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000 行/tablet、20
>> > 会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java Session
>> > 路径统计学持平,此时瓶颈在服务端而非客户端
>> > 所有文件均带 ASF Apache 2.0 头
>> >
>> > 社区已经收到的副产品
>> >
>> > 在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js 客户端的两个上游问题,目前均已处理:DATE
>> > 线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐 +52%,PR
>> > #16,评审中)。
>> >
>> > 想请教社区的问题
>> >
>> > 社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如 apache/iotdb-client-rust),沿用
>> > Node.js / C# 客户端的路径?
>> > 如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
>> > 在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery 等会话级查询 API)?
>> > 无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。
>> >
>> > Best regards,
>> > Xuan Wang
>> >
>>

Re: [DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Posted by 王旋 <cr...@gmail.com>.
Hi,

Thank you very much for the supportive and detailed reply. The suggested
route (code donation to the existing TLP + ASF IP clearance, rather than
incubation) makes sense to me, and I'm glad full Java-parity is not a
prerequisite — an incremental, roadmap-tracked approach matches how the
client was built.

Below are the five items requested before a vote.

## 1. Supported IoTDB version matrix

| IoTDB version | Status | Evidence |
|---|---|---|
| 2.0.6 | Supported | CI integration job runs the full live test suite + 3
examples against apache/iotdb:2.0.6-standalone on every push |
| 2.0.10 | Supported | Full benchmark + data-correctness verification (all
10 data types, tree & table, nulls) against a 2.0.10 standalone deployment |
| 2.0.x (general) | Expected to work | Thrift IDL is synced from
iotdb-protocol/ master; protocol version V3; no version-specific branching
in the client |
| 1.x | Not targeted | Table model and several data types
(TIMESTAMP/DATE/BLOB/STRING) assume 2.x; no plan to support 1.x |

TLS was verified end-to-end against 2.0.6 with enable_thrift_ssl (TLSv1.3,
full certificate verification). RPC compression (compact protocol) verified
against a server with dn_rpc_thrift_compression_enable=true.

## 2. Contributors and provenance

The entire git history has a single author — myself (Wang Xuan / CritasWang
<cr...@outlook.com>). I am an existing Apache IoTDB committer with an ICLA
already on file, and I hold full ownership of this work, so the provenance
chain is straightforward. Two categories of code in the repo:

- Hand-written code: 100% original work, written for this project,
Apache-2.0 headers on every file.
- Generated code (src/protocol/): produced by the Apache Thrift compiler
from the Apache IoTDB project's own IDL files (iotdb-protocol/, ALv2); the
generation pipeline (tools/generate-thrift.sh) is documented and
reproducible.

No code was copied from other client SDKs; the Java/C#/Node.js clients were
used as behavioral references only (wire-protocol semantics), which is also
how the cross-client protocol issues (e.g. the Node.js DATE encoding bug)
were found.

## 3. Dependency and license inventory

Runtime dependencies (4 + 1 optional):

| Crate | Version | License | Purpose |
|---|---|---|---|
| thrift | 0.23 | Apache-2.0 | RPC (matches the compiler version pinned by
the IoTDB pom) |
| byteorder | 1.5 | Unlicense OR MIT | Big-endian encoding |
| chrono | 0.4 | MIT OR Apache-2.0 | DATE handling |
| log | 0.4 | MIT OR Apache-2.0 | Logging facade |
| native-tls (optional, feature "tls") | 0.2 | MIT OR Apache-2.0 | TLS |

Dev-dependency: env_logger (MIT OR Apache-2.0). Full transitive closure: 74
packages, machine-checked — every one is MIT / Apache-2.0 / Unlicense / BSD
/ Zlib dual-or-multi licensed, i.e. 100% ASF Category-A. Zero Category-B/X,
zero unknown-license packages. The full inventory (cargo metadata) can be
attached to the IP-clearance checklist.

## 4. Proposed initial maintainers and maintenance plan

- Initial maintainer: myself (CritasWang — existing IoTDB committer). I
commit to maintaining the client — issue triage, protocol-sync with
iotdb-protocol changes, and regular releases through the normal IoTDB
community process — and to growing co-maintainers from the community;
review bandwidth from other committers/PMC members on client-facing changes
would be welcome.
- The repo already carries the practices expected for handover: CI (fmt /
clippy -D warnings / license check / unit tests / live integration against
a service container), bilingual READMEs, runnable examples, a
statistics-aligned benchmark, and a documented codegen pipeline. Nothing
depends on my personal infrastructure.

## 5. API support matrix (vs Java client) and near-term roadmap

Supported today (feature → Java-client equivalent):

| Area | Rust today | Java client |
|---|---|---|
| Session lifecycle, multi-node URLs, failover, auto-reconnect | ✅ | ✅ |
| insertTablet / insertTablets | ✅ | ✅ |
| insertRecord(s) / insertRecordsOfOneDevice (+ aligned variants) | ✅ | ✅ |
| Table model (TableSession/Pool, TAG/FIELD/ATTRIBUTE) | ✅ | ✅ |
| SessionPool / TableSessionPool (idle eviction, redirection cache) | ✅ | ✅
|
| Query + paging iteration (TsBlock, fetchResultsV2) | ✅ | ✅ |
| All data types incl. TIMESTAMP/DATE/BLOB/STRING | ✅ | ✅ |
| TLS (incl. client identity) / RPC compression | ✅ | ✅ |
| deleteData / deleteTimeseries / DDL helpers | SQL only | ✅ dedicated APIs
|
| Schema templates | ❌ | ✅ |
| executeRawDataQuery / executeLastDataQuery / aggregation APIs | ❌ | ✅ |
| Per-type encoding tuning (RPC compression V2) | ❌ | ✅ |

Near-term roadmap (order negotiable with the community):

1. async (tokio) API layer — most-requested Rust-ecosystem feature, kept
out of v0.1 to keep the sync core small
2. crates.io releases under the Apache project

I'll keep this thread open for feedback on maintenance ownership and API
scope as suggested. Since I'm an existing committer with an ICLA on file
and the sole author, the IP-clearance paperwork should be light — I'm happy
to prepare whatever the PMC deems necessary (software grant if required for
the pre-existing external history, plus the dependency inventory above)
whenever the community feels ready to move to a VOTE.

Best regards,
Xuan Wang

Haonan Hou <ha...@apache.org> 于2026年7月15日周三 15:06写道:

> Hi Xuan,
>
> Thank you for sharing this work. The implementation already covers a
> substantial part of the client functionality, and the test coverage, live
> integration testing, CI setup, and benchmark results are all encouraging.
>
> The protocol issues and performance improvements discovered while
> validating
> against the other clients are also a good indication that this work can
> benefit the broader IoTDB client ecosystem.
>
> As a member of the IoTDB PMC, I support bringing a well-maintained Rust
> client
> into the Apache IoTDB project. Based on what you have presented, I believe
> this
> repository is a strong candidate for donation and for becoming an official
> IoTDB client.
>
> Since IoTDB is already an Apache top-level project, the appropriate route
> should be a code donation to the existing project, followed by the ASF IP
> clearance process, rather than incubation as a separate project.
>
> I suggest the following next steps:
>
> 1. Continue this DISCUSS thread to collect feedback from the community,
>    especially regarding maintenance ownership and the initial API scope.
> 2. Prepare a concise compatibility and API-support matrix against the Java
>    client, together with a near-term roadmap.
> 3. If there are no major concerns, start a formal PMC VOTE to accept the
> code
>    donation and create the apache/iotdb-client-rust repository.
> 4. Complete the software grant, code provenance, dependency/license review,
>    and ASF IP clearance.
> 5. Move the code to the Apache repository and continue development and
>    releases through the normal IoTDB community process.
>
> I do not think complete Java client API parity needs to be a prerequisite
> for
> the donation. The current functionality appears sufficient to establish a
> useful official client. APIs such as schema-template operations and
> additional
> session-level query methods can be added incrementally and tracked through
> a
> public roadmap.
>
> Before moving to a vote, it would be helpful to provide:
>
> - The supported IoTDB version matrix.
> - A list of contributors and confirmation of the code’s
> ownership/provenance.
> - A dependency and license inventory.
> - The proposed initial maintainers and long-term maintenance plan.
> - An API support matrix and near-term roadmap.
>
> Overall, I am supportive of this proposal and am willing to help move the
> discussion and donation process forward.
>
> Best regards,
> Haonan Hou
>
> On 2026/07/15 03:50:24 王旋 wrote:
> > Hi all,
> >
> > I'd like to share a Rust client SDK for Apache IoTDB that I've been
> > developing, and ask for the community's feedback on whether there is
> > interest in bringing it into the Apache IoTDB ecosystem.
> >
> > Repository: https://github.com/CritasWang/iotdb-client-rust
> >
> > Scope & features
> >
> > Tree model (Session) and table model (TableSession / SQL dialect),
> > mirroring the API shape of the Java / C# / Node.js clients
> > Write APIs: insertTablet / insertTablets (multi-tablet batching),
> > insertRecord(s), insertRecordsOfOneDevice, plus aligned variants
> > SessionPool and TableSessionPool: RAII checkout, lazy growth, idle
> > eviction, dead-connection eviction, write-redirection cache (status 400
> > redirect hints), automatic reconnect with endpoint failover
> > Full data-type coverage including TIMESTAMP / DATE / BLOB / STRING;
> TsBlock
> > decoding with logical-type re-tagging (the TsBlock header carries
> physical
> > types — DATE arrives as INT32, BLOB as TEXT)
> > TLS (feature-gated, incl. client identity) — verified end-to-end against
> a
> > real IoTDB with enable_thrift_ssl; RPC compression (compact protocol)
> > Thrift codegen pipeline sources the IDL from iotdb-protocol/ and uses the
> > thrift compiler fetched by the IoTDB Maven build, so the stubs stay in
> > lockstep with the server
> >
> > Quality
> >
> > 113 unit tests (124 with TLS) + live integration tests that skip
> gracefully
> > without a server; CI on GitHub Actions runs fmt / clippy -D warnings /
> > license checks plus an integration job against an IoTDB 2.0.6 service
> > container — green
> > Statistics-aligned benchmark (measurement semantics mirror iot-benchmark:
> > prep inside the timed span, failures excluded from latency,
> Result/Latency
> > Matrix output). On a 16-core server writing 2B points per run (table
> model,
> > 100 devices x 20 DOUBLE sensors, 1000-row tablets, 20 sessions), the Rust
> > client sustains ~46-47M points/s — statistically tied with
> iot-benchmark's
> > Java Session path on the same box, where the server, not the client, is
> the
> > ceiling
> > Every file carries the ASF Apache 2.0 header
> >
> > Side effects the community already received
> >
> > Cross-validating the wire protocol against the Java / C# / Node.js
> > implementations surfaced two upstream issues in the Node.js client, both
> > now addressed: the DATE wire-encoding fix (apache/iotdb-client-nodejs#14,
> > PR #15, merged) and a write-path serialization optimization (+52%
> > throughput, PR #16, under review).
> >
> > Questions for the community
> >
> > Is there interest in an official Rust client under the Apache IoTDB
> > umbrella (e.g., apache/iotdb-client-rust), following the path of the
> > Node.js / C# clients?
> > If so, what would the preferred route be — code donation via the
> incubator
> > process for client SDKs, or starting a repo under the existing project
> and
> > iterating there?
> > Any API-surface expectations from the PMC side before such a move (e.g.,
> > schema-template APIs, session-level query APIs like executeRawDataQuery)?
> > I'm happy to keep maintaining it either way, and to align the roadmap
> with
> > the community's priorities.
> >
> > 大家好
> >
> > 我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入 Apache
> > IoTDB 生态。
> >
> > 仓库地址:https://github.com/CritasWang/iotdb-client-rust
> >
> > 范围与功能
> >
> > 树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# / Node.js 客户端对齐
> > 写入 API:insertTablet / insertTablets(多 tablet
> > 批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
> > SessionPool 与 TableSessionPool:RAII 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status 400
> > 重定向提示)、带端点故障转移的自动重连
> > 完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock 解码带逻辑类型重标记(TsBlock
> > 头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
> > TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB 完成端到端验证;RPC
> > 压缩(compact 协议)
> > Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven 构建拉取的版本,确保 stub
> > 与服务端严格同步
> >
> > 质量
> >
> > 113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions CI 运行 fmt /
> > clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service container 的集成
> > job——全绿
> > 统计口径对齐的基准测试(测量语义对齐 iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency Matrix
> > 输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000 行/tablet、20
> > 会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java Session
> > 路径统计学持平,此时瓶颈在服务端而非客户端
> > 所有文件均带 ASF Apache 2.0 头
> >
> > 社区已经收到的副产品
> >
> > 在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js 客户端的两个上游问题,目前均已处理:DATE
> > 线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐 +52%,PR
> > #16,评审中)。
> >
> > 想请教社区的问题
> >
> > 社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如 apache/iotdb-client-rust),沿用
> > Node.js / C# 客户端的路径?
> > 如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
> > 在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery 等会话级查询 API)?
> > 无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。
> >
> > Best regards,
> > Xuan Wang
> >
>

Re: [DISCUSS] A Rust client SDK for Apache IoTDB — seeking feedback and contribution path

Posted by Haonan Hou <ha...@apache.org>.
Hi Xuan,

Thank you for sharing this work. The implementation already covers a
substantial part of the client functionality, and the test coverage, live
integration testing, CI setup, and benchmark results are all encouraging.

The protocol issues and performance improvements discovered while validating
against the other clients are also a good indication that this work can
benefit the broader IoTDB client ecosystem.

As a member of the IoTDB PMC, I support bringing a well-maintained Rust client
into the Apache IoTDB project. Based on what you have presented, I believe this
repository is a strong candidate for donation and for becoming an official
IoTDB client.

Since IoTDB is already an Apache top-level project, the appropriate route
should be a code donation to the existing project, followed by the ASF IP
clearance process, rather than incubation as a separate project.

I suggest the following next steps:

1. Continue this DISCUSS thread to collect feedback from the community,
   especially regarding maintenance ownership and the initial API scope.
2. Prepare a concise compatibility and API-support matrix against the Java
   client, together with a near-term roadmap.
3. If there are no major concerns, start a formal PMC VOTE to accept the code
   donation and create the apache/iotdb-client-rust repository.
4. Complete the software grant, code provenance, dependency/license review,
   and ASF IP clearance.
5. Move the code to the Apache repository and continue development and
   releases through the normal IoTDB community process.

I do not think complete Java client API parity needs to be a prerequisite for
the donation. The current functionality appears sufficient to establish a
useful official client. APIs such as schema-template operations and additional
session-level query methods can be added incrementally and tracked through a
public roadmap.

Before moving to a vote, it would be helpful to provide:

- The supported IoTDB version matrix.
- A list of contributors and confirmation of the code’s ownership/provenance.
- A dependency and license inventory.
- The proposed initial maintainers and long-term maintenance plan.
- An API support matrix and near-term roadmap.

Overall, I am supportive of this proposal and am willing to help move the
discussion and donation process forward.

Best regards,
Haonan Hou

On 2026/07/15 03:50:24 王旋 wrote:
> Hi all,
> 
> I'd like to share a Rust client SDK for Apache IoTDB that I've been
> developing, and ask for the community's feedback on whether there is
> interest in bringing it into the Apache IoTDB ecosystem.
> 
> Repository: https://github.com/CritasWang/iotdb-client-rust
> 
> Scope & features
> 
> Tree model (Session) and table model (TableSession / SQL dialect),
> mirroring the API shape of the Java / C# / Node.js clients
> Write APIs: insertTablet / insertTablets (multi-tablet batching),
> insertRecord(s), insertRecordsOfOneDevice, plus aligned variants
> SessionPool and TableSessionPool: RAII checkout, lazy growth, idle
> eviction, dead-connection eviction, write-redirection cache (status 400
> redirect hints), automatic reconnect with endpoint failover
> Full data-type coverage including TIMESTAMP / DATE / BLOB / STRING; TsBlock
> decoding with logical-type re-tagging (the TsBlock header carries physical
> types — DATE arrives as INT32, BLOB as TEXT)
> TLS (feature-gated, incl. client identity) — verified end-to-end against a
> real IoTDB with enable_thrift_ssl; RPC compression (compact protocol)
> Thrift codegen pipeline sources the IDL from iotdb-protocol/ and uses the
> thrift compiler fetched by the IoTDB Maven build, so the stubs stay in
> lockstep with the server
> 
> Quality
> 
> 113 unit tests (124 with TLS) + live integration tests that skip gracefully
> without a server; CI on GitHub Actions runs fmt / clippy -D warnings /
> license checks plus an integration job against an IoTDB 2.0.6 service
> container — green
> Statistics-aligned benchmark (measurement semantics mirror iot-benchmark:
> prep inside the timed span, failures excluded from latency, Result/Latency
> Matrix output). On a 16-core server writing 2B points per run (table model,
> 100 devices x 20 DOUBLE sensors, 1000-row tablets, 20 sessions), the Rust
> client sustains ~46-47M points/s — statistically tied with iot-benchmark's
> Java Session path on the same box, where the server, not the client, is the
> ceiling
> Every file carries the ASF Apache 2.0 header
> 
> Side effects the community already received
> 
> Cross-validating the wire protocol against the Java / C# / Node.js
> implementations surfaced two upstream issues in the Node.js client, both
> now addressed: the DATE wire-encoding fix (apache/iotdb-client-nodejs#14,
> PR #15, merged) and a write-path serialization optimization (+52%
> throughput, PR #16, under review).
> 
> Questions for the community
> 
> Is there interest in an official Rust client under the Apache IoTDB
> umbrella (e.g., apache/iotdb-client-rust), following the path of the
> Node.js / C# clients?
> If so, what would the preferred route be — code donation via the incubator
> process for client SDKs, or starting a repo under the existing project and
> iterating there?
> Any API-surface expectations from the PMC side before such a move (e.g.,
> schema-template APIs, session-level query APIs like executeRawDataQuery)?
> I'm happy to keep maintaining it either way, and to align the roadmap with
> the community's priorities.
> 
> 大家好
> 
> 我想向社区分享一个我一直在开发的 Apache IoTDB Rust 客户端 SDK,并征求大家的意见:社区是否有兴趣将它纳入 Apache
> IoTDB 生态。
> 
> 仓库地址:https://github.com/CritasWang/iotdb-client-rust
> 
> 范围与功能
> 
> 树模型(Session)与表模型(TableSession / SQL 方言),API 形态与 Java / C# / Node.js 客户端对齐
> 写入 API:insertTablet / insertTablets(多 tablet
> 批量)、insertRecord(s)、insertRecordsOfOneDevice,以及 aligned 变体
> SessionPool 与 TableSessionPool:RAII 借还、惰性增长、空闲回收、死连接剔除、写重定向缓存(status 400
> 重定向提示)、带端点故障转移的自动重连
> 完整数据类型覆盖,包括 TIMESTAMP / DATE / BLOB / STRING;TsBlock 解码带逻辑类型重标记(TsBlock
> 头携带的是物理类型——DATE 以 INT32 到达、BLOB 以 TEXT 到达)
> TLS(feature 门控,含客户端证书)——已对开启 enable_thrift_ssl 的真实 IoTDB 完成端到端验证;RPC
> 压缩(compact 协议)
> Thrift 代码生成流水线:IDL 取自 iotdb-protocol/,编译器使用 IoTDB Maven 构建拉取的版本,确保 stub
> 与服务端严格同步
> 
> 质量
> 
> 113 个单元测试(含 TLS 为 124 个)+ 无服务器时优雅跳过的 live 集成测试;GitHub Actions CI 运行 fmt /
> clippy -D warnings / license 检查,另有针对 IoTDB 2.0.6 service container 的集成
> job——全绿
> 统计口径对齐的基准测试(测量语义对齐 iot-benchmark:批准备计入计时段、失败不计入延迟、Result/Latency Matrix
> 输出)。在 16 核服务器上每轮写入 20 亿点(表模型、100 设备 x 20 个 DOUBLE 测点、1000 行/tablet、20
> 会话),Rust 客户端持续吞吐约 4600-4700 万点/秒——与同机 iot-benchmark 的 Java Session
> 路径统计学持平,此时瓶颈在服务端而非客户端
> 所有文件均带 ASF Apache 2.0 头
> 
> 社区已经收到的副产品
> 
> 在与 Java / C# / Node.js 实现交叉验证线上协议的过程中,发现了 Node.js 客户端的两个上游问题,目前均已处理:DATE
> 线上编码修复(apache/iotdb-client-nodejs#14,PR #15,已合并)以及写路径序列化优化(吞吐 +52%,PR
> #16,评审中)。
> 
> 想请教社区的问题
> 
> 社区是否有兴趣在 Apache IoTDB 旗下提供官方 Rust 客户端(例如 apache/iotdb-client-rust),沿用
> Node.js / C# 客户端的路径?
> 如果有,倾向的路线是什么——通过客户端 SDK 的代码捐赠流程,还是先在现有项目下建仓库迭代?
> 在此之前,PMC 对 API 面是否有预期要求(例如 schema 模板 API、executeRawDataQuery 等会话级查询 API)?
> 无论结果如何,我都会继续维护它,并愿意将路线图与社区的优先级对齐。
> 
> Best regards,
> Xuan Wang
>