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 <[email protected]> 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 <[email protected]> 于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
> > > ><[email protected]>). 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 <[email protected]> 于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
> > > >> >
> > > >>
> > >
> >
>
