This is an automated email from the ASF dual-hosted git repository.

shuwenwei pushed a commit to branch supports_subscription
in repository https://gitbox.apache.org/repos/asf/iotdb-client-go.git

commit 701e79dc4cfc32840662a92b2782162e936b5510
Author: shuwenwei <[email protected]>
AuthorDate: Fri Nov 13 09:58:29 2026 +0800

    Add subscription control protocol and provider support
---
 subscription/README.md             |  18 +-
 subscription/config.go             |  15 +-
 subscription/consumer_config.go    | 189 ++++++++++++++++
 subscription/doc.go                |   5 +-
 subscription/provider.go           | 452 +++++++++++++++++++++++++++++++++++++
 subscription/session_connection.go |   7 +-
 subscription/wire_codec.go         | 403 +++++++++++++++++++++++++++++++++
 subscription/wire_control.go       | 369 ++++++++++++++++++++++++++++++
 8 files changed, 1446 insertions(+), 12 deletions(-)

diff --git a/subscription/README.md b/subscription/README.md
index efe7e6c..8a78bd0 100644
--- a/subscription/README.md
+++ b/subscription/README.md
@@ -19,7 +19,7 @@ under the License.
 
 # Go subscription 公共接口
 
-当前已实现 `SubscriptionSession` 的默认配置、构造、普通 Thrift 连接与认证,以及 Topic/Subscription 
管理。Consumer、记录解析和处理器仍只有公共接口,没有可运行的消费实现。下文对应表同时列出已实现的管理能力和后续消费实现需要遵守的契约。
+当前已实现 `SubscriptionSession` 的默认配置、构造、普通 Thrift 连接与认证,以及 Topic/Subscription 
管理;Consumer 默认配置、内部控制协议和单节点 Provider 也已补齐。公共 
Consumer、记录解析和处理器仍没有可运行的消费实现。下文对应表同时列出已实现能力和后续消费实现需要遵守的契约。
 
 模块路径为 `github.com/apache/iotdb-client-go/subscription`,使用 Go 1.25,与现有 
`github.com/apache/iotdb-client-go/v2` Session 模块分别维护依赖和版本。当前仅依赖现有模块,以复用 
`TSDataType` 和 `ColumnCategory`;没有 TsFile、cgo 或 TLS 依赖,也没有改动现有 Session 接口。
 
@@ -43,7 +43,7 @@ Java 的 
`ISubscriptionTreeSession/ISubscriptionTableSession`、树/表 Pull 接
 | `SubscriptionPushConsumerConfig` | `AbstractSubscriptionPushConsumerBuilder` 
| 组合 Handler、ACK 策略及拉取间隔、超时 |
 | `AckStrategy`、`AckAfterConsume`、`AckBeforeConsume` | 
`AckStrategy.AFTER_CONSUME`、`BEFORE_CONSUME` | 零值为消费后确认;消费前确认下,回调失败不导致重新投递 |
 
-`SubscriptionConsumerConfig.OwnerEpoch == nil` 表示未提供 epoch,指向零表示显式 epoch 
0。Consumer 的默认值、构造和校验仍待后续实现。
+`SubscriptionConsumerConfig.OwnerEpoch == nil` 表示未提供 epoch,指向零表示显式 epoch 0。已提供 
`DefaultSubscriptionConsumerConfig`、`DefaultSubscriptionPullConsumerConfig`、`DefaultSubscriptionPushConsumerConfig`。Push
 默认配置的 Handler 保持 nil,调用方需设置实际处理函数。内部归一化会复制节点列表及可选指针;时长零值使用默认值,负值报错,低于 Java 
正数下限的配置提升到对应下限。Consumer 构造函数尚未提供。
 
 管理 Session 的默认配置为 `localhost:6667`、树模型、root/root、64 MiB 帧和十秒连接及认证超时。Java 管理 
Session 默认不限制连接时长,Go 
入口在这里采用有界超时。构造函数补齐空节点、用户名、模型以及为零的超时和帧大小,校验地址与互斥认证,并复制节点列表。密码始终保留调用方提供的值,包括空字符串;需要
 root/root 默认值时应从默认配置函数开始。使用加密密码时清空 `Password` 后设置 `EncryptedPassword`。
 
@@ -63,6 +63,18 @@ topics, err := s.Topics(ctx)
 
 管理连接自行处理查询分页与关闭,复用现有 TsBlock 解码器;不使用会以 `context.Background()` 分页的现有 
SessionDataSet。取消会中断原始连接,后续操作重建连接时继续使用原模型和认证配置。已发送的管理语句不会因连接失败被自动重放;失败后可由调用方查询服务端状态再决定是否重试。管理
 Session 关闭后可以再次打开,这与 Consumer 成功关闭后不可重新打开的契约分开处理。
 
+## 内部订阅协议与 Provider
+
+当前内部实现覆盖握手、心跳、订阅/退订、关闭、提交、seek、Poll 请求与 Tablet 续取请求,以及超大请求分片。它们尚未接入公共 
Consumer,不能仅凭这一层直接消费记录。
+
+- 基础编解码采用 Java 的 big-endian 布局。提交上下文使用版本 2,保留旧式提交字段及可选 Writer 
身份和进度;Topic/Region/Writer 进度按原协议结构编码。
+- 订阅和 Poll 的 Topic 集合使用 Java ObjectSet 字符串标记,不与心跳退订列表的普通 StringList 
混用。集合编码稳定排序;null 字符串在现有 Go string 字段中映射为空串。
+- 每个 Provider 自持普通 Thrift 连接和串行 RPC 
通道,打开阶段包含认证、帧协商和订阅握手,均受打开超时约束。服务端分配的消费身份保留在 Provider 中,实例身份与 owner 信息通过握手传递。
+- 帧限制取本地与服务端较小值并预留协议空间;旧服务端没有属性字段或不支持属性探测 RPC 时回退本地限制。可分片请求的所有片段保持同一连接、顺序和批次身份。
+- 心跳按报文大小分批发送缓存上下文;提交预留响应空间分批,后续批次失败时仍返回先前已接受的上下文和进度。没有响应 body 
时保留空结果,不推断整批提交成功。
+- 状态码保留普通错误、owner fencing、consumer fencing、连接替换和致命错误的区别。Poll 返回消费组 Broker 
丢失诊断时使旧连接失效,供后续 Consumer 重建;失效连接不会被旧响应重新启用。
+- 本轮只编码记录拉取请求,不解析其响应,也不实现文件拉取。TsFile 在解析时报错的契约保留,实际分派与记录解码在后续阶段接入。
+
 ## 管理 Session
 
 `SubscriptionSession` 对应 Java 的 `ISubscriptionTreeSession` 和 
`ISubscriptionTableSession`。方法接收显式 `context.Context`,存在性条件通过参数结构表达。
@@ -155,4 +167,4 @@ SubscriptionMessageProcessor 保留消息时必须实现 `BufferingProcessor`,
 
 这些哨兵可以被后续操作错误包装,调用方使用 `errors.Is` 识别。TsFile 不支持错误不得触发连接重试或文件载荷确认。Pull 
本轮返回错误而不交付任何消息,包括并行分支已经取得的记录;本轮记录不得推进位置、进入处理器或自动提交缓存,此前成功交付及提交的状态不回滚。调用方可退订相关 
Topic 后继续拉取。
 
-后续步骤尚需实现订阅消息协议编解码、记录解析、Consumer 及其默认配置和构造、提交和恢复、后台任务、内置 Watermark/ColumnAlign 
Processor,以及消费示例和行为测试。管理查询复用根模块解码器,本轮不修改其对畸形数据的处理逻辑。当前仅完成静态核对,没有编译、运行测试或执行格式工具,不提供运行验证结论。
+后续步骤尚需实现记录及 Poll 响应解析、公共 Consumer 和构造、多节点协调、提交进度与恢复、后台任务、内置 
Watermark/ColumnAlign Processor,以及消费示例和行为测试。内部 Provider 已有提交 RPC,但尚未实现公共 
Consumer 
的交付和确认链。管理查询复用根模块解码器,本轮不修改其对畸形数据的处理逻辑。当前仅完成静态核对,没有编译、运行测试或执行格式工具,不提供运行验证结论。
diff --git a/subscription/config.go b/subscription/config.go
index cf14793..9039c4c 100644
--- a/subscription/config.go
+++ b/subscription/config.go
@@ -38,7 +38,8 @@ const (
 type ConnectionConfig struct {
        // NodeURLs lists host:port endpoints to use when establishing 
connections.
        // A single entry selects a single seed; multiple entries provide 
alternatives.
-       // SubscriptionSession uses localhost:6667 when the list is empty.
+       // SubscriptionSession and consumer config normalization use 
localhost:6667
+       // when the list is empty.
        NodeURLs []string
        // Username is the IoTDB user used for session and subscription 
authentication.
        Username string
@@ -49,11 +50,13 @@ type ConnectionConfig struct {
        // combined with Password.
        EncryptedPassword string
        // ConnectTimeout limits connection establishment and authentication 
for each
-       // seed endpoint. SubscriptionSession uses ten seconds for zero and 
rejects
-       // negative values. Java consumers also default to ten seconds.
+       // seed endpoint. SubscriptionSession and consumer config normalization 
use
+       // ten seconds for zero and reject negative values. Java consumers also
+       // default to ten seconds.
        ConnectTimeout time.Duration
        // MaxFrameSize is the maximum accepted Thrift frame size in bytes.
-       // SubscriptionSession uses 64 MiB for zero and rejects negative values.
+       // SubscriptionSession and consumer config normalization use 64 MiB for 
zero
+       // and reject negative values.
        MaxFrameSize int32
 }
 
@@ -96,8 +99,8 @@ type SubscriptionConsumerConfig struct {
 }
 
 // SubscriptionPullConsumerConfig adds automatic commit settings. A nil 
AutoCommit selects the Java
-// default, true; an explicit false selects manual commit. Timing defaults will
-// follow the Java consumer defaults when constructors are implemented.
+// default, true; an explicit false selects manual commit. Use
+// DefaultSubscriptionPullConsumerConfig to obtain explicit timing defaults.
 type SubscriptionPullConsumerConfig struct {
        // Consumer contains the shared connection, identity, and polling 
settings.
        Consumer SubscriptionConsumerConfig
diff --git a/subscription/consumer_config.go b/subscription/consumer_config.go
new file mode 100644
index 0000000..4b91869
--- /dev/null
+++ b/subscription/consumer_config.go
@@ -0,0 +1,189 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package subscription
+
+import (
+       "fmt"
+       "strings"
+       "time"
+)
+
+// DefaultSubscriptionConsumerConfig returns tree-model settings with the same
+// connection defaults as DefaultSubscriptionSessionConfig, a 30-second 
heartbeat,
+// two-minute endpoint synchronization, and polling parallelism of one. Empty
+// consumer and group IDs request assigned identities. Each call owns its 
endpoint
+// slice and does not establish a connection.
+func DefaultSubscriptionConsumerConfig() SubscriptionConsumerConfig {
+       session := DefaultSubscriptionSessionConfig()
+       return SubscriptionConsumerConfig{
+               Connection: session.Connection,
+               Dialect: session.Dialect,
+               HeartbeatInterval: 30 * time.Second,
+               EndpointsSyncInterval: 2 * time.Minute,
+               MaxPollParallelism: 1,
+       }
+}
+
+// DefaultSubscriptionPullConsumerConfig enables automatic commit with a
+// five-second interval and uses DefaultSubscriptionConsumerConfig for shared
+// settings. Each call returns its own AutoCommit pointer and endpoint slice.
+func DefaultSubscriptionPullConsumerConfig() SubscriptionPullConsumerConfig {
+       autoCommit := true
+       return SubscriptionPullConsumerConfig{
+               Consumer: DefaultSubscriptionConsumerConfig(),
+               AutoCommit: &autoCommit,
+               AutoCommitInterval: 5 * time.Second,
+       }
+}
+
+// DefaultSubscriptionPushConsumerConfig selects acknowledgment after 
successful
+// consumption, a 100-millisecond polling interval, and a ten-second poll 
timeout.
+// Shared settings come from DefaultSubscriptionConsumerConfig. Handler remains
+// nil: callers must supply their own handler before the configuration is 
usable.
+func DefaultSubscriptionPushConsumerConfig() SubscriptionPushConsumerConfig {
+       return SubscriptionPushConsumerConfig{
+               Consumer: DefaultSubscriptionConsumerConfig(),
+               AckStrategy: AckAfterConsume,
+               PollInterval: 100 * time.Millisecond,
+               PollTimeout: 10 * time.Second,
+       }
+}
+
+// normalizeSubscriptionConsumerConfig copies caller-owned connection and epoch
+// data, resolves defaults, and parses consumer identities for protocol use.
+// Unlike management SQL identifiers, protocol identities have their 
surrounding
+// backticks removed and doubled backticks unescaped.
+func normalizeSubscriptionConsumerConfig(config SubscriptionConsumerConfig) 
(SubscriptionConsumerConfig, error) {
+       session, err := 
normalizeSubscriptionSessionConfig(SubscriptionSessionConfig{
+               Connection: config.Connection,
+               Dialect: config.Dialect,
+       })
+       if err != nil {
+               return SubscriptionConsumerConfig{}, err
+       }
+       config.Connection = session.Connection
+       config.Dialect = session.Dialect
+       if config.ConsumerID != "" {
+               config.ConsumerID, err = 
parseSubscriptionIdentifier(config.ConsumerID)
+               if err != nil {
+                       return SubscriptionConsumerConfig{}, 
fmt.Errorf("subscription: ConsumerID: %w", err)
+               }
+       }
+       if config.GroupID != "" {
+               config.GroupID, err = 
parseSubscriptionIdentifier(config.GroupID)
+               if err != nil {
+                       return SubscriptionConsumerConfig{}, 
fmt.Errorf("subscription: GroupID: %w", err)
+               }
+       }
+       if config.OwnerEpoch != nil {
+               epoch := *config.OwnerEpoch
+               config.OwnerEpoch = &epoch
+       }
+       defaults := DefaultSubscriptionConsumerConfig()
+       config.HeartbeatInterval, err = 
normalizeConsumerInterval("HeartbeatInterval", config.HeartbeatInterval, 
defaults.HeartbeatInterval, time.Second)
+       if err != nil {
+               return SubscriptionConsumerConfig{}, err
+       }
+       config.EndpointsSyncInterval, err = 
normalizeConsumerInterval("EndpointsSyncInterval", 
config.EndpointsSyncInterval, defaults.EndpointsSyncInterval, 5 * time.Second)
+       if err != nil {
+               return SubscriptionConsumerConfig{}, err
+       }
+       if config.MaxPollParallelism < 0 {
+               return SubscriptionConsumerConfig{}, fmt.Errorf("subscription: 
MaxPollParallelism must not be negative")
+       }
+       if config.MaxPollParallelism == 0 {
+               config.MaxPollParallelism = defaults.MaxPollParallelism
+       }
+       return config, nil
+}
+
+// normalizeSubscriptionPullConsumerConfig preserves an explicit manual-commit
+// choice, copies AutoCommit, and clamps a positive interval below Java's 
minimum.
+func normalizeSubscriptionPullConsumerConfig(config 
SubscriptionPullConsumerConfig) (SubscriptionPullConsumerConfig, error) {
+       consumer, err := normalizeSubscriptionConsumerConfig(config.Consumer)
+       if err != nil {
+               return SubscriptionPullConsumerConfig{}, err
+       }
+       config.Consumer = consumer
+       autoCommit := true
+       if config.AutoCommit != nil {
+               autoCommit = *config.AutoCommit
+       }
+       config.AutoCommit = &autoCommit
+       defaults := DefaultSubscriptionPullConsumerConfig()
+       config.AutoCommitInterval, err = 
normalizeConsumerInterval("AutoCommitInterval", config.AutoCommitInterval, 
defaults.AutoCommitInterval, 500 * time.Millisecond)
+       if err != nil {
+               return SubscriptionPullConsumerConfig{}, err
+       }
+       return config, nil
+}
+
+// normalizeSubscriptionPushConsumerConfig requires a real handler and a known
+// acknowledgment strategy. Zero intervals select defaults; positive intervals
+// below the Java minimum are clamped and negative intervals are rejected.
+func normalizeSubscriptionPushConsumerConfig(config 
SubscriptionPushConsumerConfig) (SubscriptionPushConsumerConfig, error) {
+       consumer, err := normalizeSubscriptionConsumerConfig(config.Consumer)
+       if err != nil {
+               return SubscriptionPushConsumerConfig{}, err
+       }
+       config.Consumer = consumer
+       if config.AckStrategy != AckAfterConsume && config.AckStrategy != 
AckBeforeConsume {
+               return SubscriptionPushConsumerConfig{}, 
fmt.Errorf("subscription: unsupported acknowledgment strategy %d", 
config.AckStrategy)
+       }
+       if config.Handler == nil {
+               return SubscriptionPushConsumerConfig{}, 
fmt.Errorf("subscription: push consumer Handler must not be nil")
+       }
+       defaults := DefaultSubscriptionPushConsumerConfig()
+       config.PollInterval, err = normalizeConsumerInterval("PollInterval", 
config.PollInterval, defaults.PollInterval, time.Millisecond)
+       if err != nil {
+               return SubscriptionPushConsumerConfig{}, err
+       }
+       config.PollTimeout, err = normalizeConsumerInterval("PollTimeout", 
config.PollTimeout, defaults.PollTimeout, time.Second)
+       if err != nil {
+               return SubscriptionPushConsumerConfig{}, err
+       }
+       return config, nil
+}
+
+func normalizeConsumerInterval(name string, value, fallback, minimum 
time.Duration) (time.Duration, error) {
+       if value < 0 {
+               return 0, fmt.Errorf("subscription: %s must not be negative", 
name)
+       }
+       if value == 0 {
+               return fallback, nil
+       }
+       if value < minimum {
+               return minimum, nil
+       }
+       return value, nil
+}
+
+// parseSubscriptionIdentifier returns the unquoted identifier used in protocol
+// payloads, while checkedIdentifier retains SQL spelling for management calls.
+func parseSubscriptionIdentifier(value string) (string, error) {
+       identifier, err := checkedIdentifier(value)
+       if err != nil {
+               return "", err
+       }
+       if len(identifier) >= 2 && strings.HasPrefix(identifier, "`") && 
strings.HasSuffix(identifier, "`") {
+               return strings.ReplaceAll(identifier[1:len(identifier)-1], 
"``", "`"), nil
+       }
+       return identifier, nil
+}
diff --git a/subscription/doc.go b/subscription/doc.go
index b1a3d1b..8f1dece 100644
--- a/subscription/doc.go
+++ b/subscription/doc.go
@@ -21,8 +21,9 @@
 // table-model subscriptions. It is a separate Go module from the Session 
client.
 //
 // SubscriptionSession provides topic and subscription management through
-// NewSubscriptionSession. Consumer interfaces, record decoding, and built-in
-// processors are contracts for subsequent implementation steps.
+// NewSubscriptionSession. Consumer configuration defaults and internal control
+// protocol/provider support are available. Public consumer implementations,
+// record decoding, and built-in processors remain subsequent implementation 
steps.
 //
 // Record messages are the supported payload format. Topic management and
 // subscription do not reject TsFile topics; decoding a TsFile payload must 
return
diff --git a/subscription/provider.go b/subscription/provider.go
new file mode 100644
index 0000000..472652a
--- /dev/null
+++ b/subscription/provider.go
@@ -0,0 +1,452 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package subscription
+
+import (
+       "context"
+       "errors"
+       "fmt"
+       "strconv"
+       "strings"
+       "sync/atomic"
+
+       "github.com/apache/thrift/lib/go/thrift"
+
+       "github.com/apache/iotdb-client-go/v2/client"
+       "github.com/apache/iotdb-client-go/v2/common"
+       "github.com/apache/iotdb-client-go/v2/rpc"
+)
+
+const subscriptionFrameReserve = 1024
+
+var subscriptionSliceOrder atomic.Int32
+
+// subscriptionProvider owns one handshaken connection. Its operation gate 
keeps
+// normal RPCs and every slice of a logical request on the same serialized 
stream.
+// Recovery creates a new provider; an old response cannot revive a failed one.
+type subscriptionProvider struct {
+       connection *sessionConnection
+       endpoint string
+       dataNodeID int32
+       consumerID string
+       groupID string
+       bodyLimit int
+       operations chan struct{}
+}
+
+func openSubscriptionProvider(ctx context.Context, config 
SubscriptionConsumerConfig, endpoint, instanceID string) (_ 
*subscriptionProvider, err error) {
+       if ctx == nil {
+               return nil, errors.New("subscription: context must not be nil")
+       }
+       if instanceID == "" {
+               return nil, errors.New("subscription: consumer instance ID must 
not be empty")
+       }
+       openingCtx, cancel := context.WithTimeout(ctx, 
config.Connection.ConnectTimeout)
+       defer cancel()
+       sessionConfig := SubscriptionSessionConfig{Connection: 
config.Connection, Dialect: config.Dialect}
+       sessionConfig.Connection.NodeURLs = []string{endpoint}
+       connection, err := openSubscriptionConnection(openingCtx, sessionConfig)
+       if err != nil {
+               return nil, err
+       }
+       provider := &subscriptionProvider{
+               connection: connection,
+               endpoint: endpoint,
+               bodyLimit: int(config.Connection.MaxFrameSize) - 
subscriptionFrameReserve,
+               operations: make(chan struct{}, 1),
+       }
+       defer func() {
+               if err != nil {
+                       _ = connection.abort()
+               }
+       }()
+       if err = provider.negotiateFrameLimit(openingCtx); err != nil {
+               return nil, err
+       }
+       attributes := map[string]string{
+               "username": config.Connection.Username,
+               "password": config.Connection.Password,
+               "sql-dialect": string(config.Dialect),
+               "consumer-instance-id": instanceID,
+               "heartbeat-interval-ms": 
strconv.FormatInt(config.HeartbeatInterval.Milliseconds(), 10),
+               "connection-timeout-ms": 
strconv.FormatInt(config.Connection.ConnectTimeout.Milliseconds(), 10),
+       }
+       if config.ConsumerID != "" {
+               attributes["consumer-id"] = config.ConsumerID
+       }
+       if config.GroupID != "" {
+               attributes["group-id"] = config.GroupID
+       }
+       if config.OwnerID != "" {
+               attributes["owner-id"] = config.OwnerID
+       }
+       if config.OwnerEpoch != nil {
+               attributes["owner-epoch"] = 
strconv.FormatInt(*config.OwnerEpoch, 10)
+       }
+       if config.Connection.EncryptedPassword != "" {
+               attributes["encrypted-password"] = 
config.Connection.EncryptedPassword
+       }
+       request, err := encodeSubscriptionHandshake(attributes)
+       if err != nil {
+               return nil, err
+       }
+       response, err := provider.sendLocked(openingCtx, request)
+       if err != nil {
+               return nil, err
+       }
+       identity, err := decodeSubscriptionHandshake(response)
+       if err != nil {
+               return nil, err
+       }
+       if identity.ConsumerID == "" || identity.GroupID == "" {
+               return nil, errors.New("subscription: handshake returned no 
consumer or group identity")
+       }
+       provider.dataNodeID = identity.DataNodeID
+       provider.consumerID = identity.ConsumerID
+       provider.groupID = identity.GroupID
+       return provider, nil
+}
+
+func (p *subscriptionProvider) negotiateFrameLimit(ctx context.Context) error {
+       var properties *rpc.ServerProperties
+       err := p.connection.call(ctx, func() error {
+               var callErr error
+               properties, callErr = p.connection.client.GetProperties(ctx)
+               return callErr
+       })
+       if err != nil {
+               var applicationError thrift.TApplicationException
+               if !errors.As(err, &applicationError) || 
applicationError.TypeId() != thrift.UNKNOWN_METHOD {
+                       return err
+               }
+       }
+       if properties != nil && properties.IsSetThriftMaxFrameSize() {
+               serverLimit := int(properties.GetThriftMaxFrameSize()) - 
subscriptionFrameReserve
+               if properties.GetThriftMaxFrameSize() > 0 && serverLimit < 
p.bodyLimit {
+                       p.bodyLimit = serverLimit
+               }
+       }
+       if p.bodyLimit <= 0 {
+               return errors.New("subscription: negotiated frame size cannot 
hold a subscription request")
+       }
+       return nil
+}
+
+func (p *subscriptionProvider) acquire(ctx context.Context) error {
+       if ctx == nil {
+               return errors.New("subscription: context must not be nil")
+       }
+       if err := ctx.Err(); err != nil {
+               return err
+       }
+       select {
+       case p.operations <- struct{}{}:
+               if p.connection.isClosed() {
+                       <-p.operations
+                       return ErrClosed
+               }
+               return nil
+       case <-ctx.Done():
+               return ctx.Err()
+       }
+}
+
+func (p *subscriptionProvider) call(ctx context.Context, request 
*rpc.TPipeSubscribeReq) (*rpc.TPipeSubscribeResp, error) {
+       if err := p.acquire(ctx); err != nil {
+               return nil, err
+       }
+       defer func() { <-p.operations }()
+       return p.sendLocked(ctx, request)
+}
+
+func (p *subscriptionProvider) sendLocked(ctx context.Context, request 
*rpc.TPipeSubscribeReq) (*rpc.TPipeSubscribeResp, error) {
+       if request == nil {
+               return nil, errors.New("subscription: request must not be nil")
+       }
+       if len(request.Body) <= p.bodyLimit {
+               return p.sendOne(ctx, request)
+       }
+       if request.Version != subscriptionRequestVersion || request.Type <= 
subscriptionRequestHandshake || request.Type >= subscriptionRequestSlice || 
request.Type == subscriptionRequestClose {
+               return nil, errors.New("subscription: request exceeds the 
negotiated frame limit and cannot be sliced")
+       }
+       if len(request.Body) > int(^uint32(0)>>1) {
+               return nil, errors.New("subscription: request body exceeds the 
protocol length limit")
+       }
+       count := (len(request.Body)-1)/p.bodyLimit + 1
+       orderID := subscriptionSliceOrder.Add(1)
+       var response *rpc.TPipeSubscribeResp
+       for index := 0; index < count; index++ {
+               start := index*p.bodyLimit
+               end := start + min(p.bodyLimit, len(request.Body)-start)
+               slice, err := encodeSubscriptionSlice(request, orderID, 
int32(index), int32(count), request.Body[start:end])
+               if err != nil {
+                       return nil, err
+               }
+               response, err = p.sendOne(ctx, slice)
+               if err != nil {
+                       return nil, err
+               }
+       }
+       return response, nil
+}
+
+func (p *subscriptionProvider) sendOne(ctx context.Context, request 
*rpc.TPipeSubscribeReq) (*rpc.TPipeSubscribeResp, error) {
+       var response *rpc.TPipeSubscribeResp
+       if err := p.connection.call(ctx, func() error {
+               var callErr error
+               response, callErr = p.connection.client.PipeSubscribe(ctx, 
request)
+               return callErr
+       }); err != nil {
+               return nil, err
+       }
+       if response == nil {
+               _ = p.connection.abort()
+               return nil, errors.New("subscription: server returned no 
subscription response")
+       }
+       if response.Status == nil {
+               _ = p.connection.abort()
+               return nil, errors.New("subscription: server returned no 
subscription status")
+       }
+       if err := verifySubscriptionProviderStatus(response.Status); err != nil 
{
+               var statusErr *subscriptionStatusError
+               if errors.As(err, &statusErr) && statusErr.Code == 1920 {
+                       _ = p.connection.abort()
+               }
+               return nil, err
+       }
+       if err := validateSubscriptionResponse(response); err != nil {
+               _ = p.connection.abort()
+               return nil, err
+       }
+       return response, nil
+}
+
+func (p *subscriptionProvider) subscribe(ctx context.Context, topics []string, 
unsubscribe bool) (map[string]map[string]string, error) {
+       request, err := encodeSubscriptionSubscribe(topics, unsubscribe)
+       if err != nil {
+               return nil, err
+       }
+       response, err := p.call(ctx, request)
+       if err != nil {
+               return nil, err
+       }
+       return decodeSubscriptionTopics(response)
+}
+
+func (p *subscriptionProvider) heartbeat(ctx context.Context, buffered 
[]CommitContext) (subscriptionHeartbeat, error) {
+       if err := p.acquire(ctx); err != nil {
+               return subscriptionHeartbeat{}, err
+       }
+       defer func() { <-p.operations }()
+       batches, err := partitionSubscriptionContexts(buffered, p.bodyLimit, 4)
+       if err != nil {
+               return subscriptionHeartbeat{}, err
+       }
+       var result subscriptionHeartbeat
+       var terminated []string
+       seen := make(map[string]bool)
+       for _, batch := range batches {
+               request, err := encodeSubscriptionHeartbeat(batch)
+               if err != nil {
+                       return result, err
+               }
+               response, err := p.sendLocked(ctx, request)
+               if err != nil {
+                       return result, err
+               }
+               result, err = decodeSubscriptionHeartbeat(response)
+               if err != nil {
+                       return result, err
+               }
+               for _, topic := range result.Unsubscribe {
+                       if !seen[topic] {
+                               seen[topic] = true
+                               terminated = append(terminated, topic)
+                       }
+               }
+       }
+       result.Unsubscribe = terminated
+       return result, nil
+}
+
+// commit returns every accepted result even when a later batch fails. The
+// consumer must apply that progress before retrying or reporting the error.
+func (p *subscriptionProvider) commit(ctx context.Context, contexts 
[]CommitContext, nack bool) (subscriptionCommitResult, error) {
+       result := subscriptionCommitResult{Progress: 
make(map[string]TopicProgress)}
+       if err := p.acquire(ctx); err != nil {
+               return result, err
+       }
+       defer func() { <-p.operations }()
+       limit := p.bodyLimit/3
+       if limit < 1 {
+               limit = 1
+       }
+       batches, err := partitionSubscriptionContexts(contexts, limit, 5)
+       if err != nil {
+               return result, err
+       }
+       for _, batch := range batches {
+               request, err := encodeSubscriptionCommit(batch, nack)
+               if err != nil {
+                       return result, err
+               }
+               response, err := p.sendLocked(ctx, request)
+               if err != nil {
+                       return result, err
+               }
+               completed, err := decodeSubscriptionCommit(response)
+               if err != nil {
+                       return result, err
+               }
+               result.Accepted = append(result.Accepted, completed.Accepted...)
+               for topic, progress := range completed.Progress {
+                       if result.Progress[topic] == nil {
+                               result.Progress[topic] = make(TopicProgress)
+                       }
+                       for region, writers := range progress {
+                               result.Progress[topic][region] = writers
+                       }
+               }
+       }
+       return result, nil
+}
+
+func (p *subscriptionProvider) seek(ctx context.Context, topic string, kind 
int16, progress TopicProgress) error {
+       request, err := encodeSubscriptionSeek(topic, kind, 0, progress)
+       if err != nil {
+               return err
+       }
+       _, err = p.call(ctx, request)
+       return err
+}
+
+func (p *subscriptionProvider) poll(ctx context.Context, topics []string, 
timeoutMs, maxBytes int64, progress map[string]TopicProgress) ([][]byte, error) 
{
+       request, err := encodeSubscriptionPoll(topics, timeoutMs, maxBytes, 
progress)
+       if err != nil {
+               return nil, err
+       }
+       return p.pollPayloads(ctx, request)
+}
+
+func (p *subscriptionProvider) pollTablets(ctx context.Context, commitContext 
CommitContext, offset int32, timeoutMs, maxBytes int64) ([][]byte, error) {
+       request, err := encodeSubscriptionPollTablets(commitContext, offset, 
timeoutMs, maxBytes)
+       if err != nil {
+               return nil, err
+       }
+       return p.pollPayloads(ctx, request)
+}
+
+func (p *subscriptionProvider) pollPayloads(ctx context.Context, request 
*rpc.TPipeSubscribeReq) ([][]byte, error) {
+       response, err := p.call(ctx, request)
+       if err != nil {
+               var statusErr *subscriptionStatusError
+               if errors.As(err, &statusErr) && statusErr.Code == 1904 {
+                       // Broker loss is a server-reported connection failure. 
Rebuilding the
+                       // provider and handshaking again is required before 
another poll.
+                       group := "[" + p.groupID + "]"
+                       if strings.Contains(statusErr.Message, "no broker bound 
to consumer group " + group) ||
+                               strings.Contains(statusErr.Message, "broker 
bound to consumer group " + group + " does not exist") ||
+                               strings.Contains(statusErr.Message, "绑定到消费者组 " 
+ group + " 的 Broker 不存在") {
+                               _ = p.connection.abort()
+                       }
+               }
+               return nil, err
+       }
+       return response.Body, nil
+}
+
+// close preserves subscriptions during fenced/recovery teardown. A regular 
close
+// sends the subscription CLOSE before closing the authenticated session.
+func (p *subscriptionProvider) close(ctx context.Context, 
preserveSubscriptions bool) error {
+       if preserveSubscriptions {
+               return p.connection.abort()
+       }
+       if p.connection.isClosed() {
+               return nil
+       }
+       select {
+       case p.operations <- struct{}{}:
+               defer func() { <-p.operations }()
+       default:
+               return p.connection.abort()
+       }
+       _, requestErr := p.sendLocked(ctx, encodeSubscriptionClose())
+       return errors.Join(requestErr, p.connection.close(ctx))
+}
+
+func partitionSubscriptionContexts(contexts []CommitContext, limit, fixed int) 
([][]CommitContext, error) {
+       if len(contexts) == 0 {
+               return [][]CommitContext{nil}, nil
+       }
+       var batches [][]CommitContext
+       start, size := 0, fixed
+       for index, commitContext := range contexts {
+               writer := &subscriptionWireWriter{}
+               writeSubscriptionCommitContext(writer, commitContext)
+               body, err := writer.bytes()
+               if err != nil {
+                       return nil, err
+               }
+               if index > start && size + len(body) > limit {
+                       batches = append(batches, contexts[start:index])
+                       start, size = index, fixed
+               }
+               size += len(body)
+       }
+       return append(batches, contexts[start:]), nil
+}
+
+// subscriptionStatusError retains server status and its retry classification
+// without expanding the public error API before Consumer error handling 
exists.
+type subscriptionStatusError struct {
+       Code int32
+       Message string
+       Critical bool
+       cause error
+}
+
+func (e *subscriptionStatusError) Error() string {
+       return fmt.Sprintf("subscription: server status %d: %s", e.Code, 
e.Message)
+}
+
+func (e *subscriptionStatusError) Unwrap() error {
+       return e.cause
+}
+
+func verifySubscriptionProviderStatus(status *common.TSStatus) error {
+       if status == nil {
+               return errors.New("subscription: server returned no status")
+       }
+       if status.Code == client.SuccessStatus {
+               return nil
+       }
+       failure := &subscriptionStatusError{Code: status.Code, Message: 
status.GetMessage()}
+       switch status.Code {
+       case 1902, 1903, 1904, 1905, 1906, 1907, 1908, 1911, 1913, 1920:
+       case 1914, 1915, 1916, 1917, 1918:
+               failure.cause = ErrOwnerFenced
+       case 1919:
+               failure.cause = ErrConsumerFenced
+               failure.Critical = true
+       default:
+               failure.Critical = true
+       }
+       return failure
+}
diff --git a/subscription/session_connection.go 
b/subscription/session_connection.go
index 7092389..09006f5 100644
--- a/subscription/session_connection.go
+++ b/subscription/session_connection.go
@@ -178,7 +178,12 @@ func (c *sessionConnection) call(ctx context.Context, 
invoke func() error) error
                return contextErr
        }
        if err != nil {
-               _ = c.abort()
+               // An older server can reject an optional RPC without 
corrupting the
+               // stream. Keep that connection usable for the caller's 
fallback.
+               var applicationError thrift.TApplicationException
+               if !errors.As(err, &applicationError) || 
applicationError.TypeId() != thrift.UNKNOWN_METHOD {
+                       _ = c.abort()
+               }
        }
        return err
 }
diff --git a/subscription/wire_codec.go b/subscription/wire_codec.go
new file mode 100644
index 0000000..70b18e9
--- /dev/null
+++ b/subscription/wire_codec.go
@@ -0,0 +1,403 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package subscription
+
+import (
+       "encoding/binary"
+       "fmt"
+       "io"
+       "sort"
+)
+
+const (
+       subscriptionCommitContextVersion int8 = 2
+       maxSubscriptionWireLength = 1<<31 - 1
+)
+
+// subscriptionWireWriter matches the big-endian primitives used by Java
+// ReadWriteIOUtils. Its zero value is ready to use, and the first error is 
sticky.
+type subscriptionWireWriter struct {
+       data []byte
+       err error
+}
+
+func (w *subscriptionWireWriter) writeByte(value int8) {
+       if w.err == nil {
+               w.data = append(w.data, byte(value))
+       }
+}
+
+func (w *subscriptionWireWriter) writeInt16(value int16) {
+       if w.err == nil {
+               w.data = binary.BigEndian.AppendUint16(w.data, uint16(value))
+       }
+}
+
+func (w *subscriptionWireWriter) writeInt32(value int32) {
+       if w.err == nil {
+               w.data = binary.BigEndian.AppendUint32(w.data, uint32(value))
+       }
+}
+
+func (w *subscriptionWireWriter) writeInt64(value int64) {
+       if w.err == nil {
+               w.data = binary.BigEndian.AppendUint64(w.data, uint64(value))
+       }
+}
+
+func (w *subscriptionWireWriter) writeBool(value bool) {
+       if value {
+               w.writeByte(1)
+       } else {
+               w.writeByte(0)
+       }
+}
+
+// writeString always emits a non-null string; an empty string has length zero.
+func (w *subscriptionWireWriter) writeString(value string) {
+       if w.err != nil {
+               return
+       }
+       if len(value) > maxSubscriptionWireLength {
+               w.err = fmt.Errorf("subscription: string length %d exceeds 
int32", len(value))
+               return
+       }
+       w.writeInt32(int32(len(value)))
+       w.data = append(w.data, value...)
+}
+
+func (w *subscriptionWireWriter) writeStringMap(values map[string]string) {
+       if w.err != nil {
+               return
+       }
+       if values == nil {
+               w.writeInt32(-1)
+               return
+       }
+       if len(values) > maxSubscriptionWireLength {
+               w.err = fmt.Errorf("subscription: map size %d exceeds int32", 
len(values))
+               return
+       }
+       keys := make([]string, 0, len(values))
+       for key := range values {
+               keys = append(keys, key)
+       }
+       sort.Strings(keys)
+       w.writeInt32(int32(len(keys)))
+       for _, key := range keys {
+               w.writeString(key)
+               w.writeString(values[key])
+       }
+}
+
+// writeStrings encodes a string list, not the tagged writeObjectSet format.
+// List order is preserved and the caller's slice is never reordered.
+func (w *subscriptionWireWriter) writeStrings(values []string) {
+       if w.err != nil {
+               return
+       }
+       if values == nil {
+               w.writeInt32(-1)
+               return
+       }
+       if len(values) > maxSubscriptionWireLength {
+               w.err = fmt.Errorf("subscription: string list size %d exceeds 
int32", len(values))
+               return
+       }
+       w.writeInt32(int32(len(values)))
+       for _, value := range values {
+               w.writeString(value)
+       }
+}
+
+func (w *subscriptionWireWriter) bytes() ([]byte, error) {
+       if w.err != nil {
+               return nil, w.err
+       }
+       return w.data, nil
+}
+
+// subscriptionWireReader borrows the payload and records the first decoding
+// error. Failed reads do not advance the offset or allocate from invalid 
lengths.
+type subscriptionWireReader struct {
+       data []byte
+       offset int
+       err error
+}
+
+func newSubscriptionWireReader(data []byte) *subscriptionWireReader {
+       return &subscriptionWireReader{data: data}
+}
+
+func (r *subscriptionWireReader) remaining() int {
+       if r.offset < 0 || r.offset > len(r.data) {
+               return 0
+       }
+       return len(r.data) - r.offset
+}
+
+func (r *subscriptionWireReader) take(count int) []byte {
+       if r.err != nil {
+               return nil
+       }
+       if count < 0 || r.offset < 0 || r.offset > len(r.data) {
+               r.err = fmt.Errorf("subscription: invalid payload read of %d 
bytes at offset %d", count, r.offset)
+               return nil
+       }
+       if count > len(r.data)-r.offset {
+               r.err = io.ErrUnexpectedEOF
+               return nil
+       }
+       value := r.data[r.offset : r.offset+count]
+       r.offset += count
+       return value
+}
+
+func (r *subscriptionWireReader) readByte() int8 {
+       value := r.take(1)
+       if r.err != nil {
+               return 0
+       }
+       return int8(value[0])
+}
+
+func (r *subscriptionWireReader) readInt16() int16 {
+       value := r.take(2)
+       if r.err != nil {
+               return 0
+       }
+       return int16(binary.BigEndian.Uint16(value))
+}
+
+func (r *subscriptionWireReader) readInt32() int32 {
+       value := r.take(4)
+       if r.err != nil {
+               return 0
+       }
+       return int32(binary.BigEndian.Uint32(value))
+}
+
+func (r *subscriptionWireReader) readInt64() int64 {
+       value := r.take(8)
+       if r.err != nil {
+               return 0
+       }
+       return int64(binary.BigEndian.Uint64(value))
+}
+
+func (r *subscriptionWireReader) readBool() bool {
+       return r.readByte() == 1
+}
+
+// readString maps Java's null marker to the Go string zero value. Other 
negative
+// lengths are invalid; writeString distinguishes only empty and nonempty 
values.
+func (r *subscriptionWireReader) readString() string {
+       length := r.readInt32()
+       if r.err != nil || length == -1 {
+               return ""
+       }
+       if length < -1 {
+               r.err = fmt.Errorf("subscription: invalid string length %d", 
length)
+               return ""
+       }
+       return string(r.take(int(length)))
+}
+
+// readCount bounds iterations by the minimum encoded size of each entry 
without
+// allocating a collection from an unchecked wire count.
+func (r *subscriptionWireReader) readCount(minimumEntryBytes int, allowNull 
bool) int32 {
+       count := r.readInt32()
+       if r.err != nil || (allowNull && count == -1) {
+               return count
+       }
+       if count < 0 {
+               r.err = fmt.Errorf("subscription: invalid collection size %d", 
count)
+               return 0
+       }
+       if int64(count) > int64(r.remaining()/minimumEntryBytes) {
+               r.err = fmt.Errorf("subscription: collection size %d exceeds 
remaining payload: %w", count, io.ErrUnexpectedEOF)
+               return 0
+       }
+       return count
+}
+
+func (r *subscriptionWireReader) readStringMap() map[string]string {
+       count := r.readCount(8, true)
+       if r.err != nil || count == -1 {
+               return nil
+       }
+       values := make(map[string]string)
+       for index := int32(0); index < count && r.err == nil; index++ {
+               key := r.readString()
+               value := r.readString()
+               if r.err == nil {
+                       values[key] = value
+               }
+       }
+       if r.err != nil {
+               return nil
+       }
+       return values
+}
+
+func (r *subscriptionWireReader) readStrings() []string {
+       count := r.readCount(4, true)
+       if r.err != nil || count == -1 {
+               return nil
+       }
+       values := make([]string, 0)
+       for index := int32(0); index < count && r.err == nil; index++ {
+               value := r.readString()
+               if r.err == nil {
+                       values = append(values, value)
+               }
+       }
+       if r.err != nil {
+               return nil
+       }
+       return values
+}
+
+func writeSubscriptionCommitContext(w *subscriptionWireWriter, context 
CommitContext) {
+       w.writeByte(subscriptionCommitContextVersion)
+       w.writeInt32(context.DataNodeID)
+       w.writeInt32(context.RebootTimes)
+       w.writeString(context.Topic)
+       w.writeString(context.GroupID)
+       w.writeInt64(context.CommitID)
+       w.writeInt64(context.SeekGeneration)
+       w.writeString(context.RegionID)
+       w.writeInt64(context.PhysicalTime)
+       w.writeBool(context.Writer != nil)
+       if context.Writer != nil {
+               writeSubscriptionWriterPosition(w, *context.Writer)
+       }
+}
+
+func readSubscriptionCommitContext(r *subscriptionWireReader) CommitContext {
+       version := r.readByte()
+       if r.err != nil {
+               return CommitContext{}
+       }
+       if version != subscriptionCommitContextVersion {
+               r.err = fmt.Errorf("subscription: unsupported commit-context 
version %d", version)
+               return CommitContext{}
+       }
+       context := CommitContext{
+               DataNodeID: r.readInt32(),
+               RebootTimes: r.readInt32(),
+               Topic: r.readString(),
+               GroupID: r.readString(),
+               CommitID: r.readInt64(),
+               SeekGeneration: r.readInt64(),
+               RegionID: r.readString(),
+               PhysicalTime: r.readInt64(),
+       }
+       // Java reads this presence marker as a byte, not 
ReadWriteIOUtils.readBool.
+       if r.readByte() != 0 {
+               position := readSubscriptionWriterPosition(r)
+               context.Writer = &position
+       }
+       if r.err != nil {
+               return CommitContext{}
+       }
+       return context
+}
+
+func writeSubscriptionTopicProgress(w *subscriptionWireWriter, progress 
TopicProgress) {
+       if w.err != nil {
+               return
+       }
+       if len(progress) > maxSubscriptionWireLength {
+               w.err = fmt.Errorf("subscription: region count %d exceeds 
int32", len(progress))
+               return
+       }
+       regions := make([]string, 0, len(progress))
+       for region := range progress {
+               regions = append(regions, region)
+       }
+       sort.Strings(regions)
+       w.writeInt32(int32(len(regions)))
+       for _, region := range regions {
+               w.writeString(region)
+               if w.err != nil {
+                       return
+               }
+               positions := progress[region]
+               if len(positions) > maxSubscriptionWireLength {
+                       w.err = fmt.Errorf("subscription: writer count %d 
exceeds int32", len(positions))
+                       return
+               }
+               writers := make([]WriterID, 0, len(positions))
+               for writer := range positions {
+                       writers = append(writers, writer)
+               }
+               sort.Slice(writers, func(i, j int) bool {
+                       if writers[i].RegionID != writers[j].RegionID {
+                               return writers[i].RegionID < writers[j].RegionID
+                       }
+                       return writers[i].NodeID < writers[j].NodeID
+               })
+               w.writeInt32(int32(len(writers)))
+               for _, writer := range writers {
+                       writeSubscriptionWriterPosition(w, WriterPosition{ID: 
writer, Progress: positions[writer]})
+               }
+       }
+}
+
+func readSubscriptionTopicProgress(r *subscriptionWireReader) TopicProgress {
+       regionCount := r.readCount(8, false)
+       if r.err != nil {
+               return nil
+       }
+       progress := make(TopicProgress)
+       for regionIndex := int32(0); regionIndex < regionCount && r.err == nil; 
regionIndex++ {
+               region := r.readString()
+               writerCount := r.readCount(24, false)
+               positions := make(RegionProgress)
+               for writerIndex := int32(0); writerIndex < writerCount && r.err 
== nil; writerIndex++ {
+                       position := readSubscriptionWriterPosition(r)
+                       if r.err == nil {
+                               positions[position.ID] = position.Progress
+                       }
+               }
+               if r.err == nil {
+                       progress[region] = positions
+               }
+       }
+       if r.err != nil {
+               return nil
+       }
+       return progress
+}
+
+func writeSubscriptionWriterPosition(w *subscriptionWireWriter, position 
WriterPosition) {
+       w.writeString(position.ID.RegionID)
+       w.writeInt32(position.ID.NodeID)
+       w.writeInt64(position.Progress.PhysicalTime)
+       w.writeInt64(position.Progress.LocalSeq)
+}
+
+func readSubscriptionWriterPosition(r *subscriptionWireReader) WriterPosition {
+       return WriterPosition{
+               ID: WriterID{RegionID: r.readString(), NodeID: r.readInt32()},
+               Progress: WriterProgress{PhysicalTime: r.readInt64(), LocalSeq: 
r.readInt64()},
+       }
+}
diff --git a/subscription/wire_control.go b/subscription/wire_control.go
new file mode 100644
index 0000000..9643bcb
--- /dev/null
+++ b/subscription/wire_control.go
@@ -0,0 +1,369 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package subscription
+
+import (
+       "fmt"
+       "net"
+       "sort"
+       "strconv"
+
+       "github.com/apache/iotdb-client-go/v2/rpc"
+)
+
+const subscriptionRequestVersion int8 = 1
+
+const (
+       subscriptionRequestHandshake int16 = iota
+       subscriptionRequestHeartbeat
+       subscriptionRequestPoll
+       subscriptionRequestCommit
+       subscriptionRequestClose
+       subscriptionRequestSubscribe
+       subscriptionRequestUnsubscribe
+       subscriptionRequestSeek
+       subscriptionRequestSlice
+)
+
+const (
+       subscriptionSeekBeginning int16 = iota + 1
+       subscriptionSeekEnd
+       subscriptionSeekTimestamp
+       subscriptionSeekProgress
+       subscriptionSeekAfterProgress
+)
+
+const (
+       subscriptionResponseVersion int8 = 1
+       subscriptionResponseAck int16 = 0
+       subscriptionStringObjectTag int8 = 6
+       subscriptionPollInitial int16 = 0
+       subscriptionPollNextTablets int16 = 2
+)
+
+type subscriptionHandshake struct {
+       DataNodeID int32
+       ConsumerID string
+       GroupID string
+}
+
+type subscriptionHeartbeat struct {
+       Topics map[string]map[string]string
+       Endpoints map[int32]string
+       Unsubscribe []string
+}
+
+type subscriptionCommitResult struct {
+       Accepted []CommitContext
+       Progress map[string]TopicProgress
+}
+
+// validateSubscriptionResponse checks the envelope only. Providers interpret 
the
+// status before decoding, including responses that carry partial commit 
results.
+func validateSubscriptionResponse(response *rpc.TPipeSubscribeResp) error {
+       if response == nil {
+               return fmt.Errorf("subscription: no subscription response")
+       }
+       if response.Version != subscriptionResponseVersion {
+               return fmt.Errorf("subscription: unsupported response version 
%d", response.Version)
+       }
+       if response.Type != subscriptionResponseAck {
+               return fmt.Errorf("subscription: unsupported response type %d", 
response.Type)
+       }
+       return nil
+}
+
+func encodeSubscriptionHandshake(attributes map[string]string) 
(*rpc.TPipeSubscribeReq, error) {
+       if attributes == nil {
+               attributes = map[string]string{}
+       }
+       var writer subscriptionWireWriter
+       writer.writeStringMap(attributes)
+       return subscriptionControlRequest(subscriptionRequestHandshake, &writer)
+}
+
+func decodeSubscriptionHandshake(response *rpc.TPipeSubscribeResp) 
(subscriptionHandshake, error) {
+       var result subscriptionHandshake
+       if err := validateSubscriptionResponse(response); err != nil {
+               return result, err
+       }
+       if body := subscriptionControlBody(response); body != nil {
+               reader := newSubscriptionWireReader(body)
+               result.DataNodeID = reader.readInt32()
+               result.ConsumerID = reader.readString()
+               result.GroupID = reader.readString()
+               if reader.err != nil {
+                       return subscriptionHandshake{}, 
fmt.Errorf("subscription: decode handshake response: %w", reader.err)
+               }
+       }
+       return result, nil
+}
+
+func encodeSubscriptionHeartbeat(contexts []CommitContext) 
(*rpc.TPipeSubscribeReq, error) {
+       var writer subscriptionWireWriter
+       writeSubscriptionControlCount(&writer, len(contexts))
+       for _, commitContext := range contexts {
+               writeSubscriptionCommitContext(&writer, commitContext)
+       }
+       return subscriptionControlRequest(subscriptionRequestHeartbeat, &writer)
+}
+
+func decodeSubscriptionHeartbeat(response *rpc.TPipeSubscribeResp) 
(subscriptionHeartbeat, error) {
+       result := subscriptionHeartbeat{
+               Topics: make(map[string]map[string]string),
+               Endpoints: make(map[int32]string),
+       }
+       if err := validateSubscriptionResponse(response); err != nil {
+               return result, err
+       }
+       if body := subscriptionControlBody(response); body != nil {
+               reader := newSubscriptionWireReader(body)
+               result.Topics = readSubscriptionTopics(reader)
+               count := readSubscriptionControlCount(reader, 12)
+               for index := 0; index < count && reader.err == nil; index++ {
+                       nodeID := reader.readInt32()
+                       host := reader.readString()
+                       port := reader.readInt32()
+                       result.Endpoints[nodeID] = net.JoinHostPort(host, 
strconv.FormatInt(int64(port), 10))
+               }
+               result.Unsubscribe = reader.readStrings()
+               if reader.err != nil {
+                       return subscriptionHeartbeat{}, 
fmt.Errorf("subscription: decode heartbeat response: %w", reader.err)
+               }
+       }
+       return result, nil
+}
+
+func encodeSubscriptionSubscribe(topics []string, unsubscribe bool) 
(*rpc.TPipeSubscribeReq, error) {
+       var writer subscriptionWireWriter
+       writeSubscriptionTopicSet(&writer, topics)
+       requestType := subscriptionRequestSubscribe
+       if unsubscribe {
+               requestType = subscriptionRequestUnsubscribe
+       }
+       return subscriptionControlRequest(requestType, &writer)
+}
+
+func decodeSubscriptionTopics(response *rpc.TPipeSubscribeResp) 
(map[string]map[string]string, error) {
+       if err := validateSubscriptionResponse(response); err != nil {
+               return nil, err
+       }
+       if body := subscriptionControlBody(response); body != nil {
+               reader := newSubscriptionWireReader(body)
+               topics := readSubscriptionTopics(reader)
+               if reader.err != nil {
+                       return nil, fmt.Errorf("subscription: decode topic 
response: %w", reader.err)
+               }
+               return topics, nil
+       }
+       return make(map[string]map[string]string), nil
+}
+
+func encodeSubscriptionClose() *rpc.TPipeSubscribeReq {
+       return &rpc.TPipeSubscribeReq{
+               Version: subscriptionRequestVersion,
+               Type: subscriptionRequestClose,
+       }
+}
+
+func encodeSubscriptionCommit(contexts []CommitContext, nack bool) 
(*rpc.TPipeSubscribeReq, error) {
+       var writer subscriptionWireWriter
+       writeSubscriptionControlCount(&writer, len(contexts))
+       for _, commitContext := range contexts {
+               writeSubscriptionCommitContext(&writer, commitContext)
+       }
+       writer.writeBool(nack)
+       return subscriptionControlRequest(subscriptionRequestCommit, &writer)
+}
+
+func decodeSubscriptionCommit(response *rpc.TPipeSubscribeResp) 
(subscriptionCommitResult, error) {
+       result := subscriptionCommitResult{Progress: 
make(map[string]TopicProgress)}
+       if err := validateSubscriptionResponse(response); err != nil {
+               return result, err
+       }
+       if body := subscriptionControlBody(response); body != nil {
+               reader := newSubscriptionWireReader(body)
+               count := readSubscriptionControlCount(reader, 1)
+               for index := 0; index < count && reader.err == nil; index++ {
+                       result.Accepted = append(result.Accepted, 
readSubscriptionCommitContext(reader))
+               }
+               count = readSubscriptionControlCount(reader, 8)
+               for index := 0; index < count && reader.err == nil; index++ {
+                       topic := reader.readString()
+                       result.Progress[topic] = 
readSubscriptionTopicProgress(reader)
+               }
+               if reader.err != nil {
+                       return subscriptionCommitResult{}, 
fmt.Errorf("subscription: decode commit response: %w", reader.err)
+               }
+       }
+       // A response without a body has no explicit acceptance or progress. Do 
not
+       // infer that every requested context was accepted from the status 
alone.
+       return result, nil
+}
+
+func encodeSubscriptionSeek(topic string, kind int16, timestamp int64, 
progress TopicProgress) (*rpc.TPipeSubscribeReq, error) {
+       var writer subscriptionWireWriter
+       writer.writeString(topic)
+       writer.writeInt16(kind)
+       switch kind {
+       case subscriptionSeekBeginning, subscriptionSeekEnd:
+       case subscriptionSeekTimestamp:
+               writer.writeInt64(timestamp)
+       case subscriptionSeekProgress, subscriptionSeekAfterProgress:
+               writeSubscriptionTopicProgress(&writer, progress)
+       default:
+               return nil, fmt.Errorf("subscription: unsupported seek type 
%d", kind)
+       }
+       return subscriptionControlRequest(subscriptionRequestSeek, &writer)
+}
+
+func encodeSubscriptionPoll(topics []string, timeoutMs, maxBytes int64, 
progress map[string]TopicProgress) (*rpc.TPipeSubscribeReq, error) {
+       var writer subscriptionWireWriter
+       writer.writeInt16(subscriptionPollInitial)
+       writeSubscriptionTopicSet(&writer, topics)
+       writeSubscriptionPollLimits(&writer, timeoutMs, maxBytes, progress)
+       return subscriptionControlRequest(subscriptionRequestPoll, &writer)
+}
+
+func encodeSubscriptionPollTablets(commitContext CommitContext, offset int32, 
timeoutMs, maxBytes int64) (*rpc.TPipeSubscribeReq, error) {
+       var writer subscriptionWireWriter
+       writer.writeInt16(subscriptionPollNextTablets)
+       writeSubscriptionCommitContext(&writer, commitContext)
+       writer.writeInt32(offset)
+       writeSubscriptionPollLimits(&writer, timeoutMs, maxBytes, nil)
+       return subscriptionControlRequest(subscriptionRequestPoll, &writer)
+}
+
+func encodeSubscriptionSlice(request *rpc.TPipeSubscribeReq, orderID int32, 
index, count int32, piece []byte) (*rpc.TPipeSubscribeReq, error) {
+       if request == nil {
+               return nil, fmt.Errorf("subscription: cannot slice a nil 
request")
+       }
+       if count <= 0 || index < 0 || index >= count {
+               return nil, fmt.Errorf("subscription: invalid slice index %d 
for %d slices", index, count)
+       }
+       if int64(len(request.Body)) > 1<<31-1 || len(piece) > len(request.Body) 
{
+               return nil, fmt.Errorf("subscription: invalid subscription 
slice body size")
+       }
+       var writer subscriptionWireWriter
+       writer.writeInt32(orderID)
+       writer.writeByte(request.Version)
+       writer.writeInt16(request.Type)
+       writer.writeInt32(int32(len(request.Body)))
+       writer.writeInt32(index)
+       writer.writeInt32(count)
+       writer.writeInt32(int32(len(piece)))
+       body, err := writer.bytes()
+       if err != nil {
+               return nil, err
+       }
+       return &rpc.TPipeSubscribeReq{
+               Version: subscriptionRequestVersion,
+               Type: subscriptionRequestSlice,
+               Body: append(body, piece...),
+       }, nil
+}
+
+func subscriptionControlRequest(requestType int16, writer 
*subscriptionWireWriter) (*rpc.TPipeSubscribeReq, error) {
+       body, err := writer.bytes()
+       if err != nil {
+               return nil, err
+       }
+       return &rpc.TPipeSubscribeReq{
+               Version: subscriptionRequestVersion,
+               Type: requestType,
+               Body: body,
+       }, nil
+}
+
+// Java reads the first nonempty response body and ignores later entries.
+func subscriptionControlBody(response *rpc.TPipeSubscribeResp) []byte {
+       for _, body := range response.Body {
+               if len(body) != 0 {
+                       return body
+               }
+       }
+       return nil
+}
+
+func readSubscriptionTopics(reader *subscriptionWireReader) 
map[string]map[string]string {
+       topics := make(map[string]map[string]string)
+       count := readSubscriptionControlCount(reader, 8)
+       for index := 0; index < count && reader.err == nil; index++ {
+               topic := reader.readString()
+               topics[topic] = reader.readStringMap()
+       }
+       return topics
+}
+
+// Subscribe and Poll use writeObjectSet, whose string entries carry an object
+// type tag. This is different from the untagged StringList used by heartbeat.
+func writeSubscriptionTopicSet(writer *subscriptionWireWriter, topics 
[]string) {
+       unique := make(map[string]struct{}, len(topics))
+       for _, topic := range topics {
+               unique[topic] = struct{}{}
+       }
+       names := make([]string, 0, len(unique))
+       for topic := range unique {
+               names = append(names, topic)
+       }
+       sort.Strings(names)
+       writeSubscriptionControlCount(writer, len(names))
+       for _, topic := range names {
+               writer.writeByte(subscriptionStringObjectTag)
+               writer.writeString(topic)
+       }
+}
+
+func writeSubscriptionPollLimits(writer *subscriptionWireWriter, timeoutMs, 
maxBytes int64, progress map[string]TopicProgress) {
+       writer.writeInt64(timeoutMs)
+       writer.writeInt64(maxBytes)
+       topics := make([]string, 0, len(progress))
+       for topic := range progress {
+               topics = append(topics, topic)
+       }
+       sort.Strings(topics)
+       writeSubscriptionControlCount(writer, len(topics))
+       for _, topic := range topics {
+               writer.writeString(topic)
+               writeSubscriptionTopicProgress(writer, progress[topic])
+       }
+}
+
+func writeSubscriptionControlCount(writer *subscriptionWireWriter, count int) {
+       if int64(count) > 1<<31-1 {
+               if writer.err == nil {
+                       writer.err = fmt.Errorf("subscription: collection is 
too large for the wire format")
+               }
+               return
+       }
+       writer.writeInt32(int32(count))
+}
+
+func readSubscriptionControlCount(reader *subscriptionWireReader, minimumBytes 
int) int {
+       count := reader.readInt32()
+       if reader.err != nil {
+               return 0
+       }
+       if count < 0 || int64(count)*int64(minimumBytes) > 
int64(reader.remaining()) {
+               reader.err = fmt.Errorf("subscription: invalid collection count 
%d", count)
+               return 0
+       }
+       return int(count)
+}

Reply via email to