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 dda6295fd659702838886bce7be3ebb243d563de
Author: shuwenwei <[email protected]>
AuthorDate: Thu Nov 12 18:57:47 2026 +0800

    Implement subscription management session
---
 subscription/README.md             |  28 ++-
 subscription/config.go             |   7 +-
 subscription/doc.go                |   6 +-
 subscription/go.mod                |   7 +-
 subscription/session.go            |   3 +-
 subscription/session_config.go     |  88 +++++++++
 subscription/session_connection.go | 363 +++++++++++++++++++++++++++++++++++++
 subscription/session_impl.go       | 302 ++++++++++++++++++++++++++++++
 subscription/session_rows.go       | 134 ++++++++++++++
 subscription/session_sql.go        | 107 +++++++++++
 10 files changed, 1031 insertions(+), 14 deletions(-)

diff --git a/subscription/README.md b/subscription/README.md
index 86c392d..efe7e6c 100644
--- a/subscription/README.md
+++ b/subscription/README.md
@@ -19,7 +19,7 @@ under the License.
 
 # Go subscription 公共接口
 
-当前模块只定义公共接口、配置和数据类型,以及可用 `errors.Is` 
判断的错误哨兵。尚无构造函数、连接、消费者或消息解析实现,不能据此创建可运行的订阅客户端。下面描述的是后续实现必须遵守的接口契约,不代表这些行为已经实现。
+当前已实现 `SubscriptionSession` 的默认配置、构造、普通 Thrift 连接与认证,以及 Topic/Subscription 
管理。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 接口。
 
@@ -31,19 +31,37 @@ Go 使用 `Dialect` 区分树、表模型,管理和消费接口各自共用一
 
 Java 的 `ISubscriptionTreeSession/ISubscriptionTableSession`、树/表 Pull 接口、树/表 
Push 接口各自具有相同的方法签名。因此 Go 分别用 
`SubscriptionSession`、`SubscriptionPullConsumer`、`SubscriptionPushConsumer` 
表达这些共同操作,由配置中的 `Dialect` 选择模型;每个实例对应一个模型。
 
-这里共用的是对外方法契约。后续连接、握手和管理 SQL 必须传递对应模型,记录解析仍需分别处理树模型的设备路径与表模型的数据库、表和 TAG 
身份。相同接口不要求树、表使用同一套内部实现。当前仅有接口声明,尚未实现上述模型选择逻辑。
+这里共用的是对外方法契约。管理 Session 已在连接时传递模型;后续消费握手和记录解析仍需分别处理树模型的设备路径与表模型的数据库、表和 TAG 
身份。相同接口不要求树、表使用同一套内部实现。
 
 | Go 公共类型 | Java 对应 | Go 中的表达方式 |
 | --- | --- | --- |
 | `Dialect`、`TreeDialect`、`TableDialect` | 树、表 Session/Consumer 类型及 SQL 
dialect | 在 `SubscriptionSessionConfig` 或 `SubscriptionConsumerConfig` 中选择模型 |
 | `ConnectionConfig` | Session/Consumer Builder 的节点、认证、连接超时、最大帧配置 | `NodeURLs` 
同时表示单节点和集群种子地址;时间使用 `time.Duration`;明文与加密密码互斥 |
-| `SubscriptionSessionConfig` | 
`SubscriptionTreeSessionBuilder`、`SubscriptionTableSessionBuilder` | 组合连接配置和 
`Dialect`,本步不提供 Builder 或构造函数 |
+| `SubscriptionSessionConfig` | 
`SubscriptionTreeSessionBuilder`、`SubscriptionTableSessionBuilder` | 通过 
`DefaultSubscriptionSessionConfig` 获取默认值,再交给 `NewSubscriptionSession`;构造不建立连接 |
 | `SubscriptionConsumerConfig` | `AbstractSubscriptionConsumerBuilder` | 
公共消费配置,包含消费身份、owner、心跳、端点同步及并行度 |
 | `SubscriptionPullConsumerConfig` | `AbstractSubscriptionPullConsumerBuilder` 
| `AutoCommit == nil` 表示沿用 Java 默认值 `true`,指向 `false` 表示显式手动提交 |
 | `SubscriptionPushConsumerConfig` | `AbstractSubscriptionPushConsumerBuilder` 
| 组合 Handler、ACK 策略及拉取间隔、超时 |
 | `AckStrategy`、`AckAfterConsume`、`AckBeforeConsume` | 
`AckStrategy.AFTER_CONSUME`、`BEFORE_CONSUME` | 零值为消费后确认;消费前确认下,回调失败不导致重新投递 |
 
-`SubscriptionConsumerConfig.OwnerEpoch == nil` 表示未提供 epoch,指向零表示显式 epoch 
0。配置的运行时默认值和校验会在构造函数实现阶段补齐,本步不执行配置校验。
+`SubscriptionConsumerConfig.OwnerEpoch == nil` 表示未提供 epoch,指向零表示显式 epoch 
0。Consumer 的默认值、构造和校验仍待后续实现。
+
+管理 Session 的默认配置为 `localhost:6667`、树模型、root/root、64 MiB 帧和十秒连接及认证超时。Java 管理 
Session 默认不限制连接时长,Go 
入口在这里采用有界超时。构造函数补齐空节点、用户名、模型以及为零的超时和帧大小,校验地址与互斥认证,并复制节点列表。密码始终保留调用方提供的值,包括空字符串;需要
 root/root 默认值时应从默认配置函数开始。使用加密密码时清空 `Password` 后设置 `EncryptedPassword`。
+
+```go
+cfg := subscription.DefaultSubscriptionSessionConfig()
+cfg.Dialect = subscription.TableDialect
+s, err := subscription.NewSubscriptionSession(cfg)
+if err != nil {
+    return err
+}
+if err := s.Open(ctx); err != nil {
+    return err
+}
+defer s.Close()
+topics, err := s.Topics(ctx)
+```
+
+管理连接自行处理查询分页与关闭,复用现有 TsBlock 解码器;不使用会以 `context.Background()` 分页的现有 
SessionDataSet。取消会中断原始连接,后续操作重建连接时继续使用原模型和认证配置。已发送的管理语句不会因连接失败被自动重放;失败后可由调用方查询服务端状态再决定是否重试。管理
 Session 关闭后可以再次打开,这与 Consumer 成功关闭后不可重新打开的契约分开处理。
 
 ## 管理 Session
 
@@ -137,4 +155,4 @@ SubscriptionMessageProcessor 保留消息时必须实现 `BufferingProcessor`,
 
 这些哨兵可以被后续操作错误包装,调用方使用 `errors.Is` 识别。TsFile 不支持错误不得触发连接重试或文件载荷确认。Pull 
本轮返回错误而不交付任何消息,包括并行分支已经取得的记录;本轮记录不得推进位置、进入处理器或自动提交缓存,此前成功交付及提交的状态不回滚。调用方可退订相关 
Topic 后继续拉取。
 
-后续步骤尚需实现构造函数与默认配置、配置校验、连接和协议编解码、管理 SQL、记录解析、Consumer、提交和恢复、后台任务、内置 
Watermark/ColumnAlign Processor,以及示例和行为测试。本步没有编译、运行测试或执行格式工具,不提供运行验证结论。
+后续步骤尚需实现订阅消息协议编解码、记录解析、Consumer 及其默认配置和构造、提交和恢复、后台任务、内置 Watermark/ColumnAlign 
Processor,以及消费示例和行为测试。管理查询复用根模块解码器,本轮不修改其对畸形数据的处理逻辑。当前仅完成静态核对,没有编译、运行测试或执行格式工具,不提供运行验证结论。
diff --git a/subscription/config.go b/subscription/config.go
index f74cbea..cf14793 100644
--- a/subscription/config.go
+++ b/subscription/config.go
@@ -38,6 +38,7 @@ 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.
        NodeURLs []string
        // Username is the IoTDB user used for session and subscription 
authentication.
        Username string
@@ -47,10 +48,12 @@ type ConnectionConfig struct {
        // EncryptedPassword supplies an already encrypted password and must 
not be
        // combined with Password.
        EncryptedPassword string
-       // ConnectTimeout limits connection establishment. The Java consumer 
default
-       // is 10 seconds; default resolution belongs to the future constructors.
+       // 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.
        ConnectTimeout time.Duration
        // MaxFrameSize is the maximum accepted Thrift frame size in bytes.
+       // SubscriptionSession uses 64 MiB for zero and rejects negative values.
        MaxFrameSize int32
 }
 
diff --git a/subscription/doc.go b/subscription/doc.go
index 4232d56..b1a3d1b 100644
--- a/subscription/doc.go
+++ b/subscription/doc.go
@@ -20,9 +20,9 @@
 // Package subscription defines the public contracts for IoTDB tree-model and
 // table-model subscriptions. It is a separate Go module from the Session 
client.
 //
-// This initial module contains interfaces and data types only. Connections,
-// consumers, constructors, protocol decoding, and built-in processors will be
-// implemented in subsequent steps.
+// SubscriptionSession provides topic and subscription management through
+// NewSubscriptionSession. Consumer interfaces, record decoding, and built-in
+// processors are contracts for 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/go.mod b/subscription/go.mod
index 8647ca7..fb9f187 100644
--- a/subscription/go.mod
+++ b/subscription/go.mod
@@ -2,6 +2,7 @@ module github.com/apache/iotdb-client-go/subscription
 
 go 1.25
 
-require github.com/apache/iotdb-client-go/v2 v2.0.0-20260914074454-a25f68aa9681
-
-require github.com/apache/thrift v0.24.0 // indirect
+require (
+       github.com/apache/iotdb-client-go/v2 v2.0.0-20260914074454-a25f68aa9681
+       github.com/apache/thrift v0.24.0
+)
diff --git a/subscription/session.go b/subscription/session.go
index 12d8bc2..2741d55 100644
--- a/subscription/session.go
+++ b/subscription/session.go
@@ -103,7 +103,8 @@ type TopicOwner struct {
        // Epoch is the new monotonically increasing owner epoch.
        Epoch int64
        // LeaseDuration optionally sets the owner's lease. Unlike the Java 
API's
-       // millisecond argument, this field is expressed as a time.Duration.
+       // millisecond argument, this field is expressed as a time.Duration. It 
must
+       // represent a whole number of milliseconds to avoid truncation.
        LeaseDuration *time.Duration
 }
 
diff --git a/subscription/session_config.go b/subscription/session_config.go
new file mode 100644
index 0000000..d8fff7a
--- /dev/null
+++ b/subscription/session_config.go
@@ -0,0 +1,88 @@
+/*
+ * 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"
+       "strconv"
+       "time"
+)
+
+// DefaultSubscriptionSessionConfig returns tree-model settings for 
localhost:6667
+// with root/root authentication and a 64 MiB frame limit. The Go session uses 
a
+// ten-second connection and opening timeout rather than an unbounded open.
+// Each call returns its own endpoint slice.
+func DefaultSubscriptionSessionConfig() SubscriptionSessionConfig {
+       return SubscriptionSessionConfig{
+               Connection: ConnectionConfig{
+                       NodeURLs: []string{"localhost:6667"},
+                       Username: "root",
+                       Password: "root",
+                       ConnectTimeout: 10 * time.Second,
+                       MaxFrameSize: 64 * 1024 * 1024,
+               },
+               Dialect: TreeDialect,
+       }
+}
+
+func normalizeSubscriptionSessionConfig(config SubscriptionSessionConfig) 
(SubscriptionSessionConfig, error) {
+       defaults := DefaultSubscriptionSessionConfig()
+       if config.Dialect == "" {
+               config.Dialect = defaults.Dialect
+       }
+       if config.Dialect != TreeDialect && config.Dialect != TableDialect {
+               return SubscriptionSessionConfig{}, fmt.Errorf("subscription: 
unsupported dialect %q", config.Dialect)
+       }
+       if len(config.Connection.NodeURLs) == 0 {
+               config.Connection.NodeURLs = defaults.Connection.NodeURLs
+       } else {
+               config.Connection.NodeURLs = append([]string(nil), 
config.Connection.NodeURLs...)
+       }
+       for _, address := range config.Connection.NodeURLs {
+               host, port, err := net.SplitHostPort(address)
+               if err != nil || host == "" {
+                       return SubscriptionSessionConfig{}, 
fmt.Errorf("subscription: invalid node address %q: expected host:port", address)
+               }
+               number, err := strconv.Atoi(port)
+               if err != nil || number < 1 || number > 65535 {
+                       return SubscriptionSessionConfig{}, 
fmt.Errorf("subscription: invalid port in node address %q", address)
+               }
+       }
+       if config.Connection.Username == "" {
+               config.Connection.Username = defaults.Connection.Username
+       }
+       if config.Connection.Password != "" && 
config.Connection.EncryptedPassword != "" {
+               return SubscriptionSessionConfig{}, fmt.Errorf("subscription: 
Password and EncryptedPassword are mutually exclusive")
+       }
+       if config.Connection.ConnectTimeout < 0 {
+               return SubscriptionSessionConfig{}, fmt.Errorf("subscription: 
ConnectTimeout must not be negative")
+       }
+       if config.Connection.ConnectTimeout == 0 {
+               config.Connection.ConnectTimeout = 
defaults.Connection.ConnectTimeout
+       }
+       if config.Connection.MaxFrameSize < 0 {
+               return SubscriptionSessionConfig{}, fmt.Errorf("subscription: 
MaxFrameSize must not be negative")
+       }
+       if config.Connection.MaxFrameSize == 0 {
+               config.Connection.MaxFrameSize = 
defaults.Connection.MaxFrameSize
+       }
+       return config, nil
+}
diff --git a/subscription/session_connection.go 
b/subscription/session_connection.go
new file mode 100644
index 0000000..7092389
--- /dev/null
+++ b/subscription/session_connection.go
@@ -0,0 +1,363 @@
+/*
+ * 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"
+       "net"
+       "sync"
+       "sync/atomic"
+       "time"
+
+       "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"
+)
+
+// sessionConnection has one serialized RPC caller. abort may run concurrently
+// with that caller so cancellation and Close can interrupt a blocked socket.
+type sessionConnection struct {
+       network net.Conn
+       client *rpc.IClientRPCServiceClient
+       sessionID int64
+       statementID int64
+       cleanupTimeout time.Duration
+       closed atomic.Bool
+       closeOnce sync.Once
+       closeErr error
+}
+
+func openSubscriptionConnection(ctx context.Context, config 
SubscriptionSessionConfig) (*sessionConnection, error) {
+       var failures []error
+       for _, endpoint := range config.Connection.NodeURLs {
+               if err := ctx.Err(); err != nil {
+                       return nil, err
+               }
+               openingCtx, cancel := context.WithTimeout(ctx, 
config.Connection.ConnectTimeout)
+               connection, err := openSubscriptionEndpoint(openingCtx, 
endpoint, config)
+               cancel()
+               if err == nil {
+                       return connection, nil
+               }
+               failures = append(failures, fmt.Errorf("subscription: open %s: 
%w", endpoint, err))
+       }
+       if err := ctx.Err(); err != nil {
+               return nil, err
+       }
+       return nil, errors.Join(failures...)
+}
+
+func openSubscriptionEndpoint(ctx context.Context, endpoint string, config 
SubscriptionSessionConfig) (_ *sessionConnection, err error) {
+       dialer := net.Dialer{Timeout: config.Connection.ConnectTimeout}
+       network, err := dialer.DialContext(ctx, "tcp", endpoint)
+       if err != nil {
+               return nil, err
+       }
+       thriftConfig := &thrift.TConfiguration{
+               ConnectTimeout: config.Connection.ConnectTimeout,
+               MaxFrameSize: config.Connection.MaxFrameSize,
+               MaxMessageSize: config.Connection.MaxFrameSize,
+       }
+       socket := thrift.NewTSocketFromConnConf(network, thriftConfig)
+       transport := thrift.NewTFramedTransportConf(socket, thriftConfig)
+       protocol := thrift.NewTBinaryProtocolFactoryConf(thriftConfig)
+       connection := &sessionConnection{
+               network: network,
+               client: 
rpc.NewIClientRPCServiceClient(thrift.NewTStandardClient(
+                       protocol.GetProtocol(transport), 
protocol.GetProtocol(transport))),
+               cleanupTimeout: config.Connection.ConnectTimeout,
+       }
+       defer func() {
+               if err != nil {
+                       err = errors.Join(err, connection.abort())
+               }
+       }()
+
+       password := config.Connection.Password
+       attributes := map[string]string{
+               "version": string(client.DEFAULT_VERSION),
+               "sql_dialect": string(config.Dialect),
+       }
+       if config.Connection.EncryptedPassword != "" {
+               password = config.Connection.EncryptedPassword
+               attributes["use_encrypted_password"] = "true"
+       }
+       request := &rpc.TSOpenSessionReq{
+               ClientProtocol: rpc.TSProtocolVersion_IOTDB_SERVICE_PROTOCOL_V3,
+               ZoneId: client.DefaultTimeZone,
+               Username: config.Connection.Username,
+               Password: &password,
+               Configuration: attributes,
+       }
+       var response *rpc.TSOpenSessionResp
+       if err = connection.call(ctx, func() error {
+               var callErr error
+               response, callErr = connection.client.OpenSession(ctx, request)
+               return callErr
+       }); err != nil {
+               return nil, err
+       }
+       if response == nil {
+               return nil, errors.New("subscription: open session returned no 
response")
+       }
+       if err = verifySubscriptionStatus(response.Status); err != nil {
+               return nil, err
+       }
+       if response.SessionId == nil {
+               return nil, errors.New("subscription: open session returned no 
session ID")
+       }
+       if response.ServerProtocolVersion == 0 {
+               return nil, errors.New("subscription: server protocol version 
is not supported")
+       }
+       connection.sessionID = *response.SessionId
+       if err = connection.call(ctx, func() error {
+               var callErr error
+               connection.statementID, callErr = 
connection.client.RequestStatementId(ctx, connection.sessionID)
+               return callErr
+       }); err != nil {
+               return nil, err
+       }
+       return connection, nil
+}
+
+func (c *sessionConnection) isClosed() bool {
+       return c.closed.Load()
+}
+
+func (c *sessionConnection) abort() error {
+       c.closed.Store(true)
+       c.closeOnce.Do(func() {
+               c.closeErr = c.network.Close()
+       })
+       return c.closeErr
+}
+
+// call closes the raw connection on cancellation. A socket deadline alone is
+// insufficient because TSocket sets its own deadline before every read/write.
+// Waiting for a running cancellation callback prevents it from closing a later
+// RPC's connection after this operation has returned.
+func (c *sessionConnection) call(ctx context.Context, invoke func() error) 
error {
+       if err := ctx.Err(); err != nil {
+               return err
+       }
+       if c.isClosed() {
+               return ErrClosed
+       }
+       canceled := make(chan struct{})
+       stop := context.AfterFunc(ctx, func() {
+               _ = c.abort()
+               close(canceled)
+       })
+       err := invoke()
+       if !stop() {
+               <-canceled
+       }
+       if contextErr := ctx.Err(); contextErr != nil {
+               _ = c.abort()
+               return contextErr
+       }
+       if err != nil {
+               _ = c.abort()
+       }
+       return err
+}
+
+func (c *sessionConnection) close(ctx context.Context) (err error) {
+       defer func() {
+               err = errors.Join(err, c.abort())
+       }()
+       if c.isClosed() {
+               return nil
+       }
+       request := &rpc.TSCloseSessionReq{SessionId: c.sessionID}
+       var status *common.TSStatus
+       if err = c.call(ctx, func() error {
+               var callErr error
+               status, callErr = c.client.CloseSession(ctx, request)
+               return callErr
+       }); err != nil {
+               return err
+       }
+       return verifySubscriptionStatus(status)
+}
+
+func (c *sessionConnection) execute(ctx context.Context, sql string) error {
+       request := &rpc.TSExecuteStatementReq{
+               SessionId: c.sessionID,
+               Statement: sql,
+               StatementId: c.statementID,
+       }
+       var response *rpc.TSExecuteStatementResp
+       if err := c.call(ctx, func() error {
+               var callErr error
+               response, callErr = c.client.ExecuteUpdateStatementV2(ctx, 
request)
+               return callErr
+       }); err != nil {
+               return err
+       }
+       if response == nil {
+               return errors.New("subscription: statement returned no 
response")
+       }
+       return verifySubscriptionStatus(response.Status)
+}
+
+func (c *sessionConnection) query(ctx context.Context, sql string, columnCount 
int, allowExtraColumns bool) (rows [][]string, err error) {
+       fetchSize := int32(client.DefaultFetchSize)
+       redirect := false
+       request := &rpc.TSExecuteStatementReq{
+               SessionId: c.sessionID,
+               Statement: sql,
+               StatementId: c.statementID,
+               FetchSize: &fetchSize,
+               Timeout: subscriptionQueryTimeout(ctx),
+               EnableRedirectQuery: &redirect,
+       }
+       var response *rpc.TSExecuteStatementResp
+       if err = c.call(ctx, func() error {
+               var callErr error
+               response, callErr = c.client.ExecuteQueryStatementV2(ctx, 
request)
+               return callErr
+       }); err != nil {
+               return nil, err
+       }
+       if response == nil {
+               return nil, errors.New("subscription: query returned no 
response")
+       }
+       if response.QueryId != nil {
+               defer func() {
+                       if contextErr := ctx.Err(); contextErr != nil {
+                               rows = nil
+                               if !errors.Is(err, contextErr) {
+                                       err = errors.Join(err, contextErr)
+                               }
+                               err = errors.Join(err, c.abort())
+                               return
+                       }
+                       if !c.isClosed() {
+                               err = errors.Join(err, c.closeQuery(ctx, 
*response.QueryId))
+                       }
+               }()
+       }
+       if err = verifySubscriptionStatus(response.Status); err != nil {
+               return nil, err
+       }
+       if response.QueryId == nil {
+               return nil, errors.New("subscription: query returned no query 
ID")
+       }
+       if len(response.Columns) < columnCount || (!allowExtraColumns && 
len(response.Columns) != columnCount) {
+               return nil, fmt.Errorf("subscription: query returned %d 
columns; expected %d", len(response.Columns), columnCount)
+       }
+       rows, err = decodeSubscriptionRows(response.QueryResult_, 
response.DataTypeList, response.ColumnIndex2TsBlockColumnIndexList, columnCount)
+       if err != nil {
+               return nil, err
+       }
+       if err = ctx.Err(); err != nil {
+               return nil, err
+       }
+       moreData := response.GetMoreData()
+       for moreData {
+               fetch := &rpc.TSFetchResultsReq{
+                       SessionId: c.sessionID,
+                       Statement: sql,
+                       FetchSize: fetchSize,
+                       QueryId: *response.QueryId,
+                       IsAlign: true,
+                       Timeout: subscriptionQueryTimeout(ctx),
+                       StatementId: &c.statementID,
+               }
+               var page *rpc.TSFetchResultsResp
+               if err = c.call(ctx, func() error {
+                       var callErr error
+                       page, callErr = c.client.FetchResultsV2(ctx, fetch)
+                       return callErr
+               }); err != nil {
+                       return nil, err
+               }
+               if page == nil {
+                       return nil, errors.New("subscription: fetch results 
returned no response")
+               }
+               if err = verifySubscriptionStatus(page.Status); err != nil {
+                       return nil, err
+               }
+               if !page.HasResultSet {
+                       break
+               }
+               var next [][]string
+               next, err = decodeSubscriptionRows(page.QueryResult_, 
response.DataTypeList, response.ColumnIndex2TsBlockColumnIndexList, columnCount)
+               if err != nil {
+                       return nil, err
+               }
+               if err = ctx.Err(); err != nil {
+                       return nil, err
+               }
+               rows = append(rows, next...)
+               moreData = page.GetMoreData()
+       }
+       return rows, nil
+}
+
+func (c *sessionConnection) closeQuery(ctx context.Context, queryID int64) 
error {
+       cleanupCtx, cancel := context.WithTimeout(ctx, c.cleanupTimeout)
+       defer cancel()
+       request := &rpc.TSCloseOperationReq{
+               SessionId: c.sessionID,
+               QueryId: &queryID,
+               StatementId: &c.statementID,
+       }
+       var status *common.TSStatus
+       if err := c.call(cleanupCtx, func() error {
+               var callErr error
+               status, callErr = c.client.CloseOperation(cleanupCtx, request)
+               return callErr
+       }); err != nil {
+               return err
+       }
+       return verifySubscriptionStatus(status)
+}
+
+func verifySubscriptionStatus(status *common.TSStatus) error {
+       if status == nil {
+               return errors.New("subscription: server returned no status")
+       }
+       if status.Code == client.RedirectionRecommend {
+               return &client.ExecutionError{Code: status.Code, Message: 
status.GetMessage()}
+       }
+       return client.VerifySuccess(status)
+}
+
+func subscriptionQueryTimeout(ctx context.Context) *int64 {
+       deadline, ok := ctx.Deadline()
+       if !ok {
+               return nil
+       }
+       remaining := time.Until(deadline)
+       milliseconds := remaining.Milliseconds()
+       if remaining > 0 && remaining%time.Millisecond != 0 {
+               milliseconds++
+       }
+       if milliseconds < 0 {
+               milliseconds = 0
+       }
+       return &milliseconds
+}
diff --git a/subscription/session_impl.go b/subscription/session_impl.go
new file mode 100644
index 0000000..98852ec
--- /dev/null
+++ b/subscription/session_impl.go
@@ -0,0 +1,302 @@
+/*
+ * 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"
+       "fmt"
+       "strconv"
+       "sync"
+       "time"
+)
+
+// NewSubscriptionSession validates and copies config without opening a network
+// connection. Start with DefaultSubscriptionSessionConfig for root/root 
defaults.
+// An explicitly empty Password is preserved, including when config is 
otherwise
+// zero-valued. Use Open to establish the session and Close to release it.
+func NewSubscriptionSession(config SubscriptionSessionConfig) 
(SubscriptionSession, error) {
+       resolved, err := normalizeSubscriptionSessionConfig(config)
+       if err != nil {
+               return nil, err
+       }
+       return &subscriptionSession{
+               config: resolved,
+               operations: make(chan struct{}, 1),
+       }, nil
+}
+
+type subscriptionSession struct {
+       config SubscriptionSessionConfig
+       operations chan struct{}
+       stateMu sync.Mutex
+       connection *sessionConnection
+       openingCancel context.CancelFunc
+       generation uint64
+       closed bool
+}
+
+func (s *subscriptionSession) acquire(ctx context.Context) error {
+       if ctx == nil {
+               return fmt.Errorf("subscription: context must not be nil")
+       }
+       if err := ctx.Err(); err != nil {
+               return err
+       }
+       select {
+       case s.operations <- struct{}{}:
+               return nil
+       case <-ctx.Done():
+               return ctx.Err()
+       }
+}
+
+func (s *subscriptionSession) connect(ctx context.Context, generation uint64) 
(*sessionConnection, error) {
+       openingCtx, cancel := context.WithCancel(ctx)
+       defer cancel()
+       s.stateMu.Lock()
+       if s.generation != generation {
+               s.stateMu.Unlock()
+               return nil, ErrClosed
+       }
+       s.openingCancel = cancel
+       s.stateMu.Unlock()
+       connection, err := openSubscriptionConnection(openingCtx, s.config)
+       s.stateMu.Lock()
+       defer s.stateMu.Unlock()
+       s.openingCancel = nil
+       if s.generation != generation {
+               if connection != nil {
+                       connection.abort()
+               }
+               return nil, ErrClosed
+       }
+       if err != nil {
+               return nil, err
+       }
+       if err := openingCtx.Err(); err != nil {
+               connection.abort()
+               return nil, err
+       }
+       s.connection = connection
+       s.closed = false
+       return connection, nil
+}
+
+func (s *subscriptionSession) Open(ctx context.Context) error {
+       if err := s.acquire(ctx); err != nil {
+               return err
+       }
+       defer func() { <-s.operations }()
+       s.stateMu.Lock()
+       connection, generation := s.connection, s.generation
+       s.stateMu.Unlock()
+       if connection != nil && !connection.isClosed() {
+               return nil
+       }
+       _, err := s.connect(ctx, generation)
+       return err
+}
+
+func (s *subscriptionSession) Close() error {
+       s.stateMu.Lock()
+       s.generation++
+       if s.openingCancel != nil {
+               s.openingCancel()
+               s.openingCancel = nil
+       }
+       connection := s.connection
+       s.connection = nil
+       s.closed = true
+       s.stateMu.Unlock()
+       if connection == nil {
+               return nil
+       }
+       select {
+       case s.operations <- struct{}{}:
+               defer func() { <-s.operations }()
+               ctx, cancel := context.WithTimeout(context.Background(), 
s.config.Connection.ConnectTimeout)
+               defer cancel()
+               return connection.close(ctx)
+       default:
+               // Interrupt an in-flight RPC instead of waiting for its 
operation lock.
+               return connection.abort()
+       }
+}
+
+func (s *subscriptionSession) withConnection(ctx context.Context, operation 
func(*sessionConnection) error) error {
+       if err := s.acquire(ctx); err != nil {
+               return err
+       }
+       defer func() { <-s.operations }()
+       s.stateMu.Lock()
+       connection, generation, closed := s.connection, s.generation, s.closed
+       s.stateMu.Unlock()
+       if connection == nil {
+               if closed {
+                       return ErrClosed
+               }
+               return ErrNotOpen
+       }
+       if connection.isClosed() {
+               var err error
+               connection, err = s.connect(ctx, generation)
+               if err != nil {
+                       return err
+               }
+       }
+       return operation(connection)
+}
+
+func (s *subscriptionSession) execute(ctx context.Context, statement string) 
error {
+       return s.withConnection(ctx, func(connection *sessionConnection) error {
+               return connection.execute(ctx, statement)
+       })
+}
+
+func (s *subscriptionSession) query(ctx context.Context, statement string, 
columns int, allowExtra bool) ([][]string, error) {
+       var rows [][]string
+       err := s.withConnection(ctx, func(connection *sessionConnection) error {
+               var err error
+               rows, err = connection.query(ctx, statement, columns, 
allowExtra)
+               return err
+       })
+       return rows, err
+}
+
+func (s *subscriptionSession) CreateTopic(ctx context.Context, name string, 
options CreateTopicOptions) error {
+       identifier, err := checkedIdentifier(name)
+       if err != nil {
+               return err
+       }
+       statement := "CREATE TOPIC "
+       if options.IfNotExists {
+               statement += "IF NOT EXISTS "
+       }
+       statement += identifier
+       if len(options.Attributes) != 0 {
+               statement += " WITH " + 
buildTopicAttributesClause(options.Attributes)
+       }
+       return s.execute(ctx, statement)
+}
+
+func (s *subscriptionSession) AlterTopic(ctx context.Context, name string, 
attributes map[string]string) error {
+       return s.alterTopic(ctx, name, attributes, false)
+}
+
+func (s *subscriptionSession) alterTopic(ctx context.Context, name string, 
attributes map[string]string, allowOwner bool) error {
+       identifier, err := checkedIdentifier(name)
+       if err != nil {
+               return err
+       }
+       if err := validateAlterTopicAttributes(attributes, allowOwner); err != 
nil {
+               return err
+       }
+       return s.execute(ctx, "ALTER TOPIC " + identifier + " WITH " + 
buildTopicAttributesClause(attributes))
+}
+
+func (s *subscriptionSession) AlterTopicOwner(ctx context.Context, name 
string, owner TopicOwner) error {
+       if owner.ID == "" {
+               return fmt.Errorf("subscription: topic owner ID must not be 
empty")
+       }
+       attributes := map[string]string{
+               "owner-id": owner.ID,
+               "owner-epoch": strconv.FormatInt(owner.Epoch, 10),
+       }
+       if owner.LeaseDuration != nil {
+               if *owner.LeaseDuration % time.Millisecond != 0 {
+                       return fmt.Errorf("subscription: owner lease duration 
must be a whole number of milliseconds")
+               }
+               attributes["owner-lease-duration-ms"] = 
strconv.FormatInt(owner.LeaseDuration.Milliseconds(), 10)
+       }
+       return s.alterTopic(ctx, name, attributes, true)
+}
+
+func (s *subscriptionSession) DropTopic(ctx context.Context, name string, 
options DropOptions) error {
+       identifier, err := checkedIdentifier(name)
+       if err != nil {
+               return err
+       }
+       statement := "DROP TOPIC "
+       if options.IfExists {
+               statement += "IF EXISTS "
+       }
+       return s.execute(ctx, statement + identifier)
+}
+
+func (s *subscriptionSession) Topics(ctx context.Context) ([]Topic, error) {
+       rows, err := s.query(ctx, "SHOW TOPICS", 2, true)
+       if err != nil {
+               return nil, err
+       }
+       topics := make([]Topic, 0, len(rows))
+       for _, row := range rows {
+               topics = append(topics, Topic{Name: row[0], Attributes: row[1]})
+       }
+       return topics, nil
+}
+
+func (s *subscriptionSession) Topic(ctx context.Context, name string) (Topic, 
bool, error) {
+       identifier, err := checkedIdentifier(name)
+       if err != nil {
+               return Topic{}, false, err
+       }
+       rows, err := s.query(ctx, "SHOW TOPIC " + identifier, 2, true)
+       if err != nil {
+               return Topic{}, false, err
+       }
+       if len(rows) == 0 {
+               return Topic{}, false, nil
+       }
+       return Topic{Name: rows[0][0], Attributes: rows[0][1]}, true, nil
+}
+
+func (s *subscriptionSession) Subscriptions(ctx context.Context, topic string) 
([]Subscription, error) {
+       statement := "SHOW SUBSCRIPTIONS"
+       if topic != "" {
+               identifier, err := checkedIdentifier(topic)
+               if err != nil {
+                       return nil, err
+               }
+               statement += " ON " + identifier
+       }
+       rows, err := s.query(ctx, statement, 4, false)
+       if err != nil {
+               return nil, err
+       }
+       subscriptions := make([]Subscription, 0, len(rows))
+       for _, row := range rows {
+               subscriptions = append(subscriptions, Subscription{
+                       ID: row[0], Topic: row[1], GroupID: row[2], 
ConsumerIDs: row[3],
+               })
+       }
+       return subscriptions, nil
+}
+
+func (s *subscriptionSession) DropSubscription(ctx context.Context, id string, 
options DropOptions) error {
+       identifier, err := checkedIdentifier(id)
+       if err != nil {
+               return err
+       }
+       statement := "DROP SUBSCRIPTION "
+       if options.IfExists {
+               statement += "IF EXISTS "
+       }
+       return s.execute(ctx, statement + identifier)
+}
diff --git a/subscription/session_rows.go b/subscription/session_rows.go
new file mode 100644
index 0000000..950e46a
--- /dev/null
+++ b/subscription/session_rows.go
@@ -0,0 +1,134 @@
+/*
+ * 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"
+
+       "github.com/apache/iotdb-client-go/v2/client"
+)
+
+// decodeSubscriptionRows reads the string fields used by SHOW TOPIC and SHOW
+// SUBSCRIPTIONS. Topic and subscription column-count policies belong to 
callers.
+func decodeSubscriptionRows(buffers [][]byte, dataTypes []string, 
columnMapping []int32, columnCount int) (rows [][]string, err error) {
+       // The shared decoder and column accessors may panic on malformed 
lengths or
+       // indexes. Contain that behavior at this untrusted result-data 
boundary.
+       defer func() {
+               if recovered := recover(); recovered != nil {
+                       rows = nil
+                       err = fmt.Errorf("subscription: invalid SHOW result: 
%v", recovered)
+               }
+       }()
+       if columnCount != 2 && columnCount != 4 {
+               return nil, fmt.Errorf("subscription: unsupported SHOW field 
count %d", columnCount)
+       }
+       if len(dataTypes) < columnCount {
+               return nil, fmt.Errorf("subscription: SHOW result has %d types 
for %d requested fields", len(dataTypes), columnCount)
+       }
+       if len(columnMapping) > 0 && len(columnMapping) < columnCount {
+               return nil, fmt.Errorf("subscription: SHOW result has %d column 
mappings for %d requested fields", len(columnMapping), columnCount)
+       }
+       for logical := 0; logical < columnCount; logical++ {
+               if dataTypes[logical] != "TEXT" && dataTypes[logical] != 
"STRING" {
+                       return nil, fmt.Errorf("subscription: SHOW field %d has 
non-string type %q", logical, dataTypes[logical])
+               }
+               if len(columnMapping) > 0 && columnMapping[logical] < 0 {
+                       return nil, fmt.Errorf("subscription: SHOW field %d 
maps to invalid physical column %d", logical, columnMapping[logical])
+               }
+       }
+
+       for blockIndex, buffer := range buffers {
+               wireTypes, validationErr := validateSubscriptionTsBlock(buffer)
+               if validationErr != nil {
+                       return nil, fmt.Errorf("subscription: invalid SHOW 
block %d: %w", blockIndex, validationErr)
+               }
+               physicalIndexes := make([]int32, columnCount)
+               for logical := range physicalIndexes {
+                       physical := int32(logical)
+                       if len(columnMapping) > 0 {
+                               physical = columnMapping[logical]
+                       }
+                       if physical < 0 || int64(physical) >= 
int64(len(wireTypes)) {
+                               return nil, fmt.Errorf("subscription: SHOW 
field %d maps to invalid physical column %d", logical, physical)
+                       }
+                       dataType := client.TSDataType(wireTypes[physical])
+                       if dataType != client.TEXT && dataType != client.STRING 
{
+                               return nil, fmt.Errorf("subscription: SHOW 
field %d maps to non-string physical column %d", logical, physical)
+                       }
+                       physicalIndexes[logical] = physical
+               }
+
+               block, decodeErr := client.DeserializeTsBlock(buffer)
+               if decodeErr != nil {
+                       return nil, fmt.Errorf("subscription: decode SHOW block 
%d: %w", blockIndex, decodeErr)
+               }
+               if block == nil || block.GetPositionCount() < 0 || 
block.GetValueColumnCount() != int32(len(wireTypes)) {
+                       return nil, fmt.Errorf("subscription: invalid decoded 
SHOW block %d", blockIndex)
+               }
+               columns := make([]client.Column, columnCount)
+               for logical, physical := range physicalIndexes {
+                       column := block.GetColumn(physical)
+                       if column == nil || column.GetPositionCount() != 
block.GetPositionCount() {
+                               return nil, fmt.Errorf("subscription: invalid 
SHOW column %d in block %d", physical, blockIndex)
+                       }
+                       columns[logical] = column
+               }
+               for position := int32(0); position < block.GetPositionCount(); 
position++ {
+                       row := make([]string, columnCount)
+                       for logical, column := range columns {
+                               if column.IsNull(position) {
+                                       // Java Field.getStringValue uses this 
representation for SQL NULL.
+                                       row[logical] = "null"
+                                       continue
+                               }
+                               value, valueErr := column.GetBinary(position)
+                               if valueErr != nil {
+                                       return nil, fmt.Errorf("subscription: 
read SHOW field %d in block %d: %w", logical, blockIndex, valueErr)
+                               }
+                               if value == nil {
+                                       return nil, fmt.Errorf("subscription: 
SHOW field %d in block %d has a nil non-null value", logical, blockIndex)
+                               }
+                               row[logical] = value.GetStringValue()
+                       }
+                       rows = append(rows, row)
+               }
+       }
+       return rows, nil
+}
+
+// validateSubscriptionTsBlock checks the fixed header before handing result 
data
+// to the shared decoder. Value-column decoding remains owned by the client 
module.
+func validateSubscriptionTsBlock(data []byte) ([]byte, error) {
+       if len(data) < 9 {
+               return nil, io.ErrUnexpectedEOF
+       }
+       columnCount := int64(int32(binary.BigEndian.Uint32(data[:4])))
+       if columnCount < 0 || columnCount > (int64(len(data))-9)/2 {
+               return nil, fmt.Errorf("invalid TsBlock value-column count %d", 
columnCount)
+       }
+       typesEnd := 4 + int(columnCount)
+       positionCount := int32(binary.BigEndian.Uint32(data[typesEnd : 
typesEnd+4]))
+       if positionCount < 0 {
+               return nil, fmt.Errorf("invalid TsBlock position count %d", 
positionCount)
+       }
+       return data[4:typesEnd], nil
+}
diff --git a/subscription/session_sql.go b/subscription/session_sql.go
new file mode 100644
index 0000000..4691528
--- /dev/null
+++ b/subscription/session_sql.go
@@ -0,0 +1,107 @@
+/*
+ * 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"
+       "regexp"
+       "sort"
+       "strings"
+)
+
+var (
+       subscriptionIdentifierPattern = 
regexp.MustCompile(`^[a-zA-Z0-9_\x{2E80}-\x{9FFF}]+$`)
+       subscriptionNumericIdentifierPattern = 
regexp.MustCompile(`^[0-9]+([eE][0-9]+)?[fFdD]?$|^[0-9]+[lL]$`)
+)
+
+// checkedIdentifier validates the same identifier forms as Java 
IdentifierUtils
+// while retaining the original SQL spelling, including enclosing backticks.
+func checkedIdentifier(name string) (string, error) {
+       if name == "" {
+               return "", fmt.Errorf("subscription: empty identifier is not 
supported")
+       }
+       if len(name) >= 2 && strings.HasPrefix(name, "`") && 
strings.HasSuffix(name, "`") {
+               return name, nil
+       }
+       if !subscriptionIdentifierPattern.MatchString(name) {
+               return "", fmt.Errorf("subscription: invalid unquoted 
identifier %q", name)
+       }
+
+       // PathVisitor.isRealNumber removes leading zeroes before checking 
numeric
+       // syntax, retaining one zero before an exponent and preserving 
all-zero input.
+       firstNonzero := 0
+       for firstNonzero < len(name) && name[firstNonzero] == '0' {
+               firstNonzero++
+       }
+       numeric := name
+       if firstNonzero > 0 && firstNonzero < len(name) {
+               if name[firstNonzero] == 'e' || name[firstNonzero] == 'E' {
+                       numeric = name[firstNonzero-1:]
+               } else {
+                       numeric = name[firstNonzero:]
+               }
+       }
+       if subscriptionNumericIdentifierPattern.MatchString(numeric) {
+               return "", fmt.Errorf("subscription: numeric identifier %q must 
be enclosed in backticks", name)
+       }
+       return name, nil
+}
+
+// buildTopicAttributesClause quotes attribute names and values for a WITH 
clause.
+// Sorting makes the SQL stable without changing the attributes' spelling.
+func buildTopicAttributesClause(attributes map[string]string) string {
+       keys := make([]string, 0, len(attributes))
+       for key := range attributes {
+               keys = append(keys, key)
+       }
+       sort.Strings(keys)
+
+       var clause strings.Builder
+       clause.WriteByte('(')
+       for index, key := range keys {
+               if index > 0 {
+                       clause.WriteByte(',')
+               }
+               clause.WriteByte('\'')
+               clause.WriteString(strings.ReplaceAll(key, "'", "''"))
+               clause.WriteString("'='")
+               clause.WriteString(strings.ReplaceAll(attributes[key], "'", 
"''"))
+               clause.WriteByte('\'')
+       }
+       clause.WriteByte(')')
+       return clause.String()
+}
+
+func validateAlterTopicAttributes(attributes map[string]string, allowOwner 
bool) error {
+       if len(attributes) == 0 {
+               return fmt.Errorf("subscription: ALTER TOPIC attributes must 
not be empty")
+       }
+       if allowOwner {
+               return nil
+       }
+       // Java's management client checks these exact keys, without trimming or
+       // folding case. Preserve that boundary rather than canonicalizing user 
input.
+       for _, key := range []string{"owner-id", "owner-epoch", 
"max-owner-epoch", "owner-lease-duration-ms"} {
+               if _, exists := attributes[key]; exists {
+                       return fmt.Errorf("subscription: topic owner attributes 
must be changed with AlterTopicOwner")
+               }
+       }
+       return nil
+}

Reply via email to