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 7e8fe2b611fac7392311f589c122f86758ebcd40
Author: shuwenwei <[email protected]>
AuthorDate: Fri Nov 13 11:13:01 2026 +0800

    Implement subscription pull consumer
---
 subscription/README.md         | 293 +++++++++-------
 subscription/consumer.go       |  10 +-
 subscription/doc.go            |   5 +-
 subscription/pull_consumer.go  | 513 ++++++++++++++++++++++++++++
 subscription/pull_flow.go      | 739 +++++++++++++++++++++++++++++++++++++++++
 subscription/pull_progress.go  | 594 +++++++++++++++++++++++++++++++++
 subscription/pull_providers.go | 404 ++++++++++++++++++++++
 7 files changed, 2432 insertions(+), 126 deletions(-)

diff --git a/subscription/README.md b/subscription/README.md
index af8a373..f470148 100644
--- a/subscription/README.md
+++ b/subscription/README.md
@@ -17,35 +17,35 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Go subscription 公共接口
+# Go Subscription API
 
-当前已实现 `SubscriptionSession` 的默认配置、构造、普通 Thrift 连接与认证,以及 Topic/Subscription 
管理;Consumer 默认配置、内部控制协议和单节点 Provider、Poll 响应与记录解析、消息及记录访问实现也已补齐。公共 Consumer 
和处理器仍没有可运行的消费实现。下文对应表同时列出已实现能力和后续消费实现需要遵守的契约。
+The module implements `SubscriptionSession` management and the configuration, 
construction, subscription management, record polling, commits, progress, seek, 
processor pipeline, and background connection coordination of 
`SubscriptionPullConsumer`. Poll response decoding, record decoding, and 
message release are also connected. Push consumers and built-in processors 
remain for subsequent steps. These implementations have not been compiled or 
exercised at runtime; this document describes t [...]
 
-模块路径为 `github.com/apache/iotdb-client-go/subscription`,使用 Go 1.25,与现有 
`github.com/apache/iotdb-client-go/v2` Session 模块分别维护依赖和版本。当前仅依赖现有模块,以复用 
`TSDataType` 和 `ColumnCategory`;没有 TsFile、cgo 或 TLS 依赖,也没有改动现有 Session 接口。
+The module path is `github.com/apache/iotdb-client-go/subscription`. It uses 
Go 1.25 and maintains dependencies and versions separately from the existing 
`github.com/apache/iotdb-client-go/v2` Session module. Its direct dependencies 
are `github.com/apache/iotdb-client-go/v2` at 
`v2.0.0-20260914074454-a25f68aa9681`, which provides existing types such as 
`TSDataType` and `ColumnCategory`, and `github.com/apache/thrift` at `v0.24.0`, 
which provides the RPC transport and protocol. It adds no [...]
 
-Java 对照基线为 IoTDB `d9122d837610` 的 `iotdb-client/subscription`。本次支持范围是记录消息:不定义 
TsFile handler、下载、文件操作或 Reader API。Topic 管理和 `Subscribe` 不预先拒绝 TsFile 
Topic;后续解析分派到文件载荷时必须返回 `ErrUnsupportedTsFile`,不能交付或确认该载荷。
+The Java reference is `iotdb-client/subscription` at IoTDB commit 
`d9122d837610`. The supported payload format is records: this module defines no 
TsFile handler, download, file-management, or Reader API. Topic management and 
`Subscribe` do not reject TsFile topics in advance. Dispatching a file payload 
during decoding returns `ErrUnsupportedTsFile`; that payload must not be 
delivered or acknowledged.
 
-## 配置与模型选择
+## Configuration and Data Model Selection
 
-Go 使用 `Dialect` 区分树、表模型,管理和消费接口各自共用一份契约,避免复制 Java 的树、表类型及 Builder 层次。
+Go uses `Dialect` to distinguish the tree and table models. Management and 
consumption each share a contract rather than duplicating Java's tree/table 
types and Builder hierarchy.
 
-Java 的 `ISubscriptionTreeSession/ISubscriptionTableSession`、树/表 Pull 接口、树/表 
Push 接口各自具有相同的方法签名。因此 Go 分别用 
`SubscriptionSession`、`SubscriptionPullConsumer`、`SubscriptionPushConsumer` 
表达这些共同操作,由配置中的 `Dialect` 选择模型;每个实例对应一个模型。
+Java's `ISubscriptionTreeSession/ISubscriptionTableSession`, tree/table Pull 
interfaces, and tree/table Push interfaces have identical method signatures 
within each pair. Go therefore uses `SubscriptionSession`, 
`SubscriptionPullConsumer`, and `SubscriptionPushConsumer` for those common 
operations. Configuration selects the model through `Dialect`; each instance 
uses one model.
 
-这里共用的是对外方法契约。管理 Session 已在连接时传递模型;后续消费握手和记录解析仍需分别处理树模型的设备路径与表模型的数据库、表和 TAG 
身份。相同接口不要求树、表使用同一套内部实现。
+Only the public method contract is shared. Management sessions pass the model 
when connecting. Consumer handshakes carry the selected model, and record 
decoding distinguishes tree device paths from table databases, tables, and TAG 
identities. Sharing an interface does not require the two models to use the 
same internal implementation.
 
-| Go 公共类型 | Java 对应 | Go 中的表达方式 |
+| Public Go type | Java counterpart | Go representation |
 | --- | --- | --- |
-| `Dialect`、`TreeDialect`、`TableDialect` | 树、表 Session/Consumer 类型及 SQL 
dialect | 在 `SubscriptionSessionConfig` 或 `SubscriptionConsumerConfig` 中选择模型 |
-| `ConnectionConfig` | Session/Consumer Builder 的节点、认证、连接超时、最大帧配置 | `NodeURLs` 
同时表示单节点和集群种子地址;时间使用 `time.Duration`;明文与加密密码互斥 |
-| `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` | 零值为消费后确认;消费前确认下,回调失败不导致重新投递 |
+| `Dialect`, `TreeDialect`, `TableDialect` | Tree/table Session and Consumer 
types, SQL dialect | Select the model in `SubscriptionSessionConfig` or 
`SubscriptionConsumerConfig` |
+| `ConnectionConfig` | Session/Consumer Builder settings for nodes, 
authentication, connection timeout, and maximum frame size | `NodeURLs` 
represents either a single node or cluster seed addresses; durations use 
`time.Duration`; plaintext and encrypted passwords are mutually exclusive |
+| `SubscriptionSessionConfig` | `SubscriptionTreeSessionBuilder`, 
`SubscriptionTableSessionBuilder` | Obtain defaults through 
`DefaultSubscriptionSessionConfig`, then pass them to `NewSubscriptionSession`; 
construction does not connect |
+| `SubscriptionConsumerConfig` | `AbstractSubscriptionConsumerBuilder` | 
Shared configuration for consumer identity, ownership, heartbeats, endpoint 
synchronization, and parallelism |
+| `SubscriptionPullConsumerConfig` | `AbstractSubscriptionPullConsumerBuilder` 
| `AutoCommit == nil` selects Java's default, `true`; a pointer to `false` 
explicitly selects manual commits |
+| `SubscriptionPushConsumerConfig` | `AbstractSubscriptionPushConsumerBuilder` 
| Combines a Handler, ACK strategy, and polling interval and timeout |
+| `AckStrategy`, `AckAfterConsume`, `AckBeforeConsume` | 
`AckStrategy.AFTER_CONSUME`, `BEFORE_CONSUME` | The zero value acknowledges 
after consumption; callback failure does not cause redelivery when 
acknowledgment precedes consumption |
 
-`SubscriptionConsumerConfig.OwnerEpoch == nil` 表示未提供 epoch,指向零表示显式 epoch 0。已提供 
`DefaultSubscriptionConsumerConfig`、`DefaultSubscriptionPullConsumerConfig`、`DefaultSubscriptionPushConsumerConfig`。Push
 默认配置的 Handler 保持 nil,调用方需设置实际处理函数。内部归一化会复制节点列表及可选指针;时长零值使用默认值,负值报错,低于 Java 
正数下限的配置提升到对应下限。Consumer 构造函数尚未提供。
+`SubscriptionConsumerConfig.OwnerEpoch == nil` means that no epoch was 
supplied; a pointer to zero explicitly supplies epoch 0. 
`DefaultSubscriptionConsumerConfig`, `DefaultSubscriptionPullConsumerConfig`, 
and `DefaultSubscriptionPushConsumerConfig` are available. The default Push 
Handler remains nil, so callers must supply a real handler. Internal 
normalization copies endpoint slices and optional pointers. Zero durations 
select defaults, negative durations return errors, and positive va [...]
 
-管理 Session 的默认配置为 `localhost:6667`、树模型、root/root、64 MiB 帧和十秒连接及认证超时。Java 管理 
Session 默认不限制连接时长,Go 
入口在这里采用有界超时。构造函数补齐空节点、用户名、模型以及为零的超时和帧大小,校验地址与互斥认证,并复制节点列表。密码始终保留调用方提供的值,包括空字符串;需要
 root/root 默认值时应从默认配置函数开始。使用加密密码时清空 `Password` 后设置 `EncryptedPassword`。
+The management session defaults are `localhost:6667`, the tree model, 
root/root authentication, a 64 MiB frame limit, and a ten-second connection and 
authentication timeout. Java management sessions do not limit connection time 
by default; the Go entry point uses a bounded timeout here. The constructor 
fills empty endpoints, username, and dialect, as well as zero timeout and frame 
size, validates addresses and mutually exclusive authentication, and copies the 
endpoint slice. Passwords ar [...]
 
 ```go
 cfg := subscription.DefaultSubscriptionSessionConfig()
@@ -61,122 +61,171 @@ defer s.Close()
 topics, err := s.Topics(ctx)
 ```
 
-管理连接自行处理查询分页与关闭,复用现有 TsBlock 解码器;不使用会以 `context.Background()` 分页的现有 
SessionDataSet。取消会中断原始连接,后续操作重建连接时继续使用原模型和认证配置。已发送的管理语句不会因连接失败被自动重放;失败后可由调用方查询服务端状态再决定是否重试。管理
 Session 关闭后可以再次打开,这与 Consumer 成功关闭后不可重新打开的契约分开处理。
+Management connections own query pagination and closing while reusing the 
existing TsBlock decoder. They do not use the existing SessionDataSet, whose 
pagination uses `context.Background()`. Cancellation interrupts the underlying 
connection. Later operations rebuild a failed connection with the same model 
and authentication settings. Already-sent management statements are not 
automatically replayed after a connection failure; callers can query server 
state before deciding whether to retr [...]
 
-## 内部订阅协议与 Provider
+## Internal Subscription Protocol and Providers
 
-当前内部实现覆盖握手、心跳、订阅/退订、关闭、提交、seek、Poll 请求与 Tablet 续取请求,以及超大请求分片。它们尚未接入公共 
Consumer,不能仅凭这一层直接消费记录。
+The internal implementation covers handshakes, heartbeats, 
subscribe/unsubscribe, close, commits, seek, Poll and Tablet-continuation 
requests, and oversized-request slicing. These are connected to the public Pull 
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 重建;失效连接不会被旧响应重新启用。
-- Provider 现在解析全部非空 Poll 响应 body,保留记录、错误、终止和水位线事件。文件响应在类型分派处返回 
`ErrUnsupportedTsFile`;混合响应不会返回已经解析的部分记录,不实现文件拉取。
+- Primitive encoding uses Java's big-endian layout. Commit contexts use 
version 2 and retain legacy commit fields plus optional Writer identity and 
progress. Topic/Region/Writer progress follows the original protocol structure.
+- Topic sets in subscribe and Poll requests use Java ObjectSet string tags, 
separately from the ordinary StringList used by heartbeat unsubscribe lists. 
Set encoding is sorted for stability. Null strings map to empty strings in 
existing Go string fields.
+- Each Provider owns a plain Thrift connection and a serialized RPC channel. 
Opening includes authentication, frame negotiation, and the subscription 
handshake, all bounded by the opening timeout. The Provider retains 
server-assigned consumer identities and sends instance identity and ownership 
information in the handshake.
+- The frame limit is the smaller of the local and server limits, with protocol 
space reserved. Older servers without the property field or property-probe RPC 
fall back to the local limit. All slices of a sliceable request retain the same 
connection, order, and batch identity.
+- Heartbeats batch buffered commit contexts by message size. Commits reserve 
response space and send batches; a later batch failure still returns earlier 
accepted contexts and progress. A response without a body retains an empty 
result rather than implying that the entire batch succeeded.
+- Status handling distinguishes ordinary errors, owner fencing, consumer 
fencing, connection replacement, and critical errors. A Poll diagnostic 
reporting a missing consumer-group Broker invalidates the old connection for 
Consumer recovery. Late responses cannot reactivate an invalidated connection.
+- Providers decode every nonempty Poll response body and retain record, error, 
termination, and watermark events. File responses return `ErrUnsupportedTsFile` 
during type dispatch. Mixed responses do not return partially decoded records, 
and file polling is not implemented.
 
-## 记录消息与解析
+## Record Messages and Decoding
 
-记录数据采用 Java 当前依赖的 `2.5.1-261023-SNAPSHOT` Tablet 序列化格式,与写入 RPC 和查询 TsBlock 
格式分开处理,不依赖 TsFile Go 或原生库。
+Records use the Tablet serialization format of Java's current 
`2.5.1-261023-SNAPSHOT` dependency, separately from insert RPC and query 
TsBlock formats. They do not depend on TsFile Go or native libraries.
 
-- 支持 BOOLEAN、INT32、INT64、FLOAT、DOUBLE、TEXT、STRING、TIMESTAMP、DATE、BLOB 和 
OBJECT,保留 TAG/FIELD/ATTRIBUTE 类别。TEXT/STRING 暴露为 string,BLOB/OBJECT 为 
`[]byte`,DATE 为 UTC 零点的 `time.Time`。
-- NULL 由 Bitmap 和缺失值列决定。Binary 的缺省标记先恢复为空内容,再应用 Bitmap;不把空字符串或空 BLOB 自动变成 
NULL。日期按 Java 的日期整数规则读取。
-- 原始行号用于 `Timestamp/Value`;`Rows()` 
通过独立的稳定排序视图按时间递增遍历,相同时间戳保持原始顺序。行值切片不在迭代间复用,调用用户的迭代函数时不持内部锁。
-- 树模型始终显示时间戳;表模型优先采用按数据库、表指定的时间投影,未指定时回退消息级标志。旧响应缺少投影尾部时保持 Java 的默认选择时间行为。
-- 消息释放幂等并清理记录缓存;提交上下文及其可选 Writer 元数据仍以独立快照返回,水位线和消息类型继续可访问。已借用的批次在释放后数据访问报错。
-- 记录续取组装校验完整提交上下文,逐页合并数据和时间投影;最终数量按 Tablet 个数核对,不按行数核对。该组装能力尚未接入 Consumer 
的实际续取循环。
-- 空记录交付和终止事件在解析层保留上下文,不自动 ACK 或退订;服务端 ERROR 保留严重级别,水位线可转为处理器消息。消费循环中的处理仍待下一步实现。
+- Supported types are BOOLEAN, INT32, INT64, FLOAT, DOUBLE, TEXT, STRING, 
TIMESTAMP, DATE, BLOB, and OBJECT, preserving TAG/FIELD/ATTRIBUTE categories. 
TEXT/STRING values are strings, BLOB/OBJECT values are `[]byte`, and DATE 
values are `time.Time` at midnight UTC.
+- Bitmaps and absent value columns determine NULL values. A Binary absence 
marker first becomes empty content, after which the Bitmap is applied. Empty 
strings and empty BLOBs are not automatically converted to NULL. Dates follow 
Java's integer date representation.
+- `Timestamp/Value` use original row indexes. `Rows()` iterates a separate 
stable view in ascending timestamp order, retaining original order for equal 
timestamps. Row value slices are not reused between iterations, and internal 
locks are not held while invoking the caller's iteration function.
+- Tree records always expose timestamps. Table records first use 
database/table-specific time projection, falling back to the message-level 
flag. Older responses without the projection suffix retain Java's default of 
selecting time.
+- Message release is idempotent and clears record buffers. Commit contexts and 
their optional Writer metadata remain available as independent snapshots, as do 
watermark and message kind. Accessing data through previously borrowed batches 
after release returns an error.
+- Record continuation uses the original DataNode Provider, checks the complete 
commit context, and merges data and time projections across pages. The final 
count is checked against the number of Tablets, not rows. Outdated or 
unavailable partial deliveries are not exposed.
+- Empty-record deliveries and termination events retain their contexts at the 
decoding layer. Pull handles empty-message ACKs and termination unsubscribe 
only after confirming that the entire poll round has no TsFile or fencing 
error. Server ERROR payloads retain their severity, and watermarks can become 
processor messages.
 
-## 管理 Session
+## Pull Consumption
 
-`SubscriptionSession` 对应 Java 的 `ISubscriptionTreeSession` 和 
`ISubscriptionTableSession`。方法接收显式 `context.Context`,存在性条件通过参数结构表达。
+`NewSubscriptionPullConsumer` copies and validates configuration without 
connecting. `Open(ctx)` opens seed connections and discovers other nodes. 
Background lifetime is independent of the opening context. 
`Subscribe/Unsubscribe` update subscriptions, and `AddProcessor` adds 
processors in order.
 
-| Go 方法或类型 | Java 对应 | 合并方式 |
+```go
+cfg := subscription.DefaultSubscriptionPullConsumerConfig()
+cfg.Consumer.Dialect = subscription.TableDialect
+autoCommit := false
+cfg.AutoCommit = &autoCommit
+consumer, err := subscription.NewSubscriptionPullConsumer(cfg)
+if err != nil {
+    return err
+}
+if err := consumer.Open(ctx); err != nil {
+    return err
+}
+defer consumer.Close()
+if err := consumer.Subscribe(ctx, "measurements"); err != nil {
+    return err
+}
+messages, err := consumer.Poll(ctx, 5*time.Second)
+if err != nil {
+    return err
+}
+for _, message := range messages {
+    batches, err := message.Records()
+    if err != nil {
+        return err
+    }
+    for _, batch := range batches {
+        for row, err := range batch.Rows() {
+            if err != nil {
+                return err
+            }
+            fmt.Println(row.Timestamp, row.Values)
+        }
+    }
+    message.Release()
+}
+return consumer.Commit(ctx, messages...)
+```
+
+- A positive Poll timeout starts at entry and covers waiting for the 
serialized foreground gate and the network budget. Processor callbacks must 
return promptly. Negative timeouts return argument errors. A zero timeout does 
not wait for a busy foreground gate or perform synchronous provider recovery; 
it sends one round of requests to available Providers with server timeout 0. 
Network I/O can still wait and is bounded by the caller's context. Caller 
context cancellation always returns an error.
+- Multiple topics are partitioned according to `MaxPollParallelism`. When only 
Poll's own budget expires, already completed healthy partitions may still be 
delivered while incomplete sibling results are discarded. TsFile or 
current-consumer fencing makes the entire round fail, without passing records 
to processors, automatic commit tracking, or fetch positions. Custom processor 
code must still avoid blocking indefinitely.
+- Heartbeats renew records buffered by Pull processors. Automatic commits 
track only records delivered to the caller and wait at least one configured 
interval. Manual `Commit` can run concurrently with Poll; `CommitAsync` reports 
its result once through a buffered channel.
+- Commit and seek server requests and local progress updates are mutually 
exclusive. Partial acceptance is applied first and accepted contexts leave the 
pending queue; only the remainder is retried. NACKs are not replayed. A writer 
ACK pending after node loss is redirected only after the same Topic/Region 
reappears through a healthy node.
+- Heartbeats are scheduled independently per Provider. Endpoint 
synchronization and connection failure trigger recovery. Background recovery 
attempts are at least five seconds apart. Late old-connection responses cannot 
reactivate an old Provider or incorrectly fence the replacement connection's 
Consumer.
+- `Close` interrupts blocked polling and stops background work. In manual 
mode, buffered processor messages make closing return an error while preserving 
the drain path. Call `DrainBufferedMessages`, process and commit its records, 
then close again. Automatic mode makes a best-effort commit of delivered and 
drained records during closing. Commit failures return errors; a successful 
close does not imply that all historical messages were processed.
+
+## Management Sessions
+
+`SubscriptionSession` corresponds to Java's `ISubscriptionTreeSession` and 
`ISubscriptionTableSession`. Methods take an explicit `context.Context`, while 
parameter structures express existence conditions.
+
+| Go method or type | Java counterpart | Consolidation |
 | --- | --- | --- |
-| `Open(ctx)`、`Close()` | `open()`、`AutoCloseable.close()` | 
打开操作可取消;关闭统一负责释放资源 |
-| `CreateTopic(ctx, name, options)`、`CreateTopicOptions` | 四个 
`createTopic/createTopicIfNotExists` 重载 | `Attributes` 表示可选属性,`IfNotExists` 
表示条件创建 |
-| `AlterTopic(ctx, name, attributes)` | `alterTopic(name, properties)` | 属性用 
`map[string]string` |
-| `AlterTopicOwner(ctx, name, owner)`、`TopicOwner` | 两个 `alterTopicOwner` 重载 | 
`LeaseDuration` 指针表达可选租约时长 |
-| `DropTopic(ctx, name, options)`、`DropOptions` | 
`dropTopic/dropTopicIfExists` | `IfExists` 表示条件删除 |
-| `Topics(ctx)`、`Topic(ctx, name)` | `getTopics()`、`getTopic(name)` | 集合用 
slice;单 Topic 不存在时返回 `found == false` |
-| `Subscriptions(ctx, topic)` | `getSubscriptions()`、`getSubscriptions(topic)` 
| `topic == ""` 表示查询全部 |
-| `DropSubscription(ctx, id, options)` | 
`dropSubscription/dropSubscriptionIfExists` | 复用 `DropOptions` |
-| `Topic` | `model.Topic` | 保留服务端返回的属性原始文本,不假定其可直接解析为 map |
-| `Subscription` | `model.Subscription` | 保留服务端的 `ConsumerIDs` 原始文本,不假定其是 CSV |
-
-## Consumer、提交与进度
-
-`SubscriptionConsumer` 是 Pull 和 Push 的共同接口。它包含 `Positioner`,因此两类消费者共用进度与 seek 
契约;这也覆盖 Java 具体 Consumer 从基类继承的公开能力。
-
-| Go 方法或类型 | Java 对应 | 合并方式 |
+| `Open(ctx)`, `Close()` | `open()`, `AutoCloseable.close()` | Opening is 
cancelable; closing owns resource release |
+| `CreateTopic(ctx, name, options)`, `CreateTopicOptions` | Four 
`createTopic/createTopicIfNotExists` overloads | `Attributes` carries optional 
properties; `IfNotExists` requests conditional creation |
+| `AlterTopic(ctx, name, attributes)` | `alterTopic(name, properties)` | 
Attributes use `map[string]string` |
+| `AlterTopicOwner(ctx, name, owner)`, `TopicOwner` | Two `alterTopicOwner` 
overloads | A `LeaseDuration` pointer represents an optional lease duration |
+| `DropTopic(ctx, name, options)`, `DropOptions` | 
`dropTopic/dropTopicIfExists` | `IfExists` requests conditional deletion |
+| `Topics(ctx)`, `Topic(ctx, name)` | `getTopics()`, `getTopic(name)` | 
Collections are slices; an absent single topic returns `found == false` |
+| `Subscriptions(ctx, topic)` | `getSubscriptions()`, 
`getSubscriptions(topic)` | `topic == ""` lists all subscriptions |
+| `DropSubscription(ctx, id, options)` | 
`dropSubscription/dropSubscriptionIfExists` | Reuses `DropOptions` |
+| `Topic` | `model.Topic` | Retains the server's raw attribute text rather 
than assuming it is directly parseable as a map |
+| `Subscription` | `model.Subscription` | Retains the server's raw 
`ConsumerIDs` text rather than assuming it is CSV |
+
+## Consumers, Commits, and Progress
+
+`SubscriptionConsumer` is the common interface for Pull and Push. It embeds 
`Positioner`, so both share progress and seek contracts, including public 
methods inherited by Java's concrete consumers from their base class.
+
+| Go method or type | Java counterpart | Consolidation |
 | --- | --- | --- |
-| `SubscriptionConsumer.Open(ctx)`、`Close()` | 各 Consumer 的 `open/close` | 
共用生命周期接口 |
-| `Subscribe(ctx, topics...)`、`Unsubscribe(ctx, topics...)` | 单个、数组、集合重载 | 统一为 
variadic Topic 名称 |
-| `Info()`、`SubscriptionConsumerInfo` | 
`getConsumerId/getConsumerGroupId/getOwnerId/getOwnerEpoch` | 
一次返回不含凭据的身份快照,包含服务端分配的 ID |
-| `LatestWatermark()` | `getLatestWatermarkTimestamp()` | 额外返回 
`ok`,区分尚无水位线与有效时间值 |
-| `AllConsumed()` | `allTopicMessagesHaveBeenConsumed()` | 无订阅时为 true;活跃的无界 
Topic 阻止完成 |
-| `SubscriptionPullConsumer.Poll(ctx, timeout, topics...)` | 四个 `poll` 重载 | 
`time.Duration` 替代毫秒和 Java Duration 重载;不传 Topic 表示当前全部订阅 |
-| `PollWithInfo(ctx, timeout, topics...)`、`PollResult` | 具体 Pull 类的 
`pollWithInfo`、`payload.PollResult` | 一并返回消息、缓存条数及处理器水位线 |
-| `DrainBufferedMessages(ctx)` | `drainBufferedMessages()` | 显式排空处理器或待交付缓存 |
-| `Commit(ctx, messages...)` | 单条/批量 `commitSync` | 同步提交统一为 variadic 消息 |
-| `CommitAsync(ctx, messages...)` | `CompletableFuture` 及 
`AsyncCommitCallback` 重载 | 返回 `<-chan error`;调用方可直接等待,或用 goroutine 等待后执行回调 |
-| `AddProcessor(processor)` | 具体 Pull 类的 `addProcessor` | 按调用顺序添加处理阶段,返回错误而非链式 
Builder |
-| `ConsumeFunc`、`SubscriptionPushConsumerConfig.Handler` | 
`ConsumeListener.onReceive`、`ConsumeResult` | `func(ctx, message) error`,nil 
表示成功,非 nil 表示消费失败 |
-| `SubscriptionPushConsumer.Errors()` | Java 自动拉取异常路径的 Go 显式错误出口 | 
首次终止性后台错误通知一次;普通 Handler 失败不视为终止错误 |
-| `Positioner.Positions(topic)` | `positions(topic)` | 返回当前已拉取位置的深快照 |
-| `CommittedPositions(topic)` | `committedPositions(topic)` | 单独保留已确认、可恢复的位置 |
-| `SeekToBeginning(ctx, topic)`、`SeekToEnd(ctx, topic)` | 同名 Java 方法 | 
保留两种定位行为 |
-| `Seek(ctx, topic, progress)`、`SeekAfter(ctx, topic, progress)` | 
`seek/seekAfter` | 分别从指定进度重放和从其后继续 |
-| `TopicProgress`、`RegionProgress` | 同名 Java 类 | Topic → Region → Writer 的 
map,不合并成单 offset |
-| `WriterID`、`WriterProgress` | `WriterId`、`WriterProgress` | 可比较 Writer ID 作为 
map key;进度保留物理时间和本地序号 |
-| `WriterPosition`、`CommitContext`、`InvalidCommitID` | 
`SubscriptionCommitContext` 的可选 writer 进度及旧式 commit 元数据 | writer 
身份与进度成对保留,同时保留路由、重启和 seek-generation 信息 |
-
-`CommitAsync` 的返回 channel 容量为 1,只发送一次结果(成功时为 nil)后关闭。调用方不读取结果不能阻塞清理。取消 context 
不撤回服务端已接受的提交;同步或异步提交报错也不代表整批都失败。
-
-`SubscriptionPushConsumer.Errors()` 的 channel 至少缓冲一个错误。TsFile 
解析错误必须先停止自动拉取再报告,失败轮次不能进入 Handler 或 ACK;channel 关闭由统一生命周期管理,避免与后台发送竞争。
-
-## 消息、记录与 Processor
-
-| Go 方法或类型 | Java 对应 | Go 中的表达方式 |
+| `SubscriptionConsumer.Open(ctx)`, `Close()` | Each Consumer's `open/close` | 
Shared lifecycle interface |
+| `Subscribe(ctx, topics...)`, `Unsubscribe(ctx, topics...)` | Single-topic, 
array, and collection overloads | Variadic topic names |
+| `Info()`, `SubscriptionConsumerInfo` | 
`getConsumerId/getConsumerGroupId/getOwnerId/getOwnerEpoch` | Returns a 
credential-free identity snapshot, including server-assigned IDs |
+| `LatestWatermark()` | `getLatestWatermarkTimestamp()` | An additional `ok` 
distinguishes an unavailable watermark from a valid timestamp |
+| `AllConsumed()` | `allTopicMessagesHaveBeenConsumed()` | True without 
subscriptions; an active unbounded topic prevents completion |
+| `SubscriptionPullConsumer.Poll(ctx, timeout, topics...)` | Four `poll` 
overloads | `time.Duration` replaces millisecond and Java Duration overloads; 
omitted topics mean all current subscriptions |
+| `PollWithInfo(ctx, timeout, topics...)`, `PollResult` | Concrete Pull 
classes' `pollWithInfo`, `payload.PollResult` | Returns messages, buffered 
count, and processor watermark together |
+| `DrainBufferedMessages(ctx)` | `drainBufferedMessages()` | Explicitly drains 
processors or pending delivery buffers |
+| `Commit(ctx, messages...)` | Single/batch `commitSync` | Variadic messages 
for synchronous commits |
+| `CommitAsync(ctx, messages...)` | `CompletableFuture` and 
`AsyncCommitCallback` overloads | Returns `<-chan error`; callers can wait 
directly or wait in a goroutine before invoking a callback |
+| `AddProcessor(processor)` | Concrete Pull classes' `addProcessor` | Adds 
processing stages in order and returns an error rather than a chained Builder |
+| `ConsumeFunc`, `SubscriptionPushConsumerConfig.Handler` | 
`ConsumeListener.onReceive`, `ConsumeResult` | `func(ctx, message) error`; nil 
means success and a non-nil error means failure |
+| `SubscriptionPushConsumer.Errors()` | Explicit Go error outlet for Java's 
automatic-poll exception path | Reports the first terminal background error 
once; ordinary Handler failures are not terminal |
+| `Positioner.Positions(topic)` | `positions(topic)` | Returns a deep snapshot 
of current fetch positions |
+| `CommittedPositions(topic)` | `committedPositions(topic)` | Separately 
retains confirmed, recoverable positions |
+| `SeekToBeginning(ctx, topic)`, `SeekToEnd(ctx, topic)` | Methods with the 
same names | Retains both positioning operations |
+| `Seek(ctx, topic, progress)`, `SeekAfter(ctx, topic, progress)` | 
`seek/seekAfter` | Replays from progress or resumes after it, respectively |
+| `TopicProgress`, `RegionProgress` | Classes with the same names | Topic → 
Region → Writer maps rather than a single offset |
+| `WriterID`, `WriterProgress` | `WriterId`, `WriterProgress` | Comparable 
Writer IDs serve as map keys; progress retains physical time and local sequence 
|
+| `WriterPosition`, `CommitContext`, `InvalidCommitID` | Optional writer 
progress and legacy commit metadata in `SubscriptionCommitContext` | Preserves 
paired writer identity and progress, routing, restart, and seek-generation 
information |
+
+`CommitAsync` returns a channel with capacity 1. It sends one result, nil on 
success, then closes. An unread result cannot block cleanup. Canceling the 
context does not undo commits accepted by the server, and a synchronous or 
asynchronous commit error does not mean that the whole batch failed.
+
+The `SubscriptionPushConsumer.Errors()` channel buffers at least one error. A 
TsFile decoding error must stop automatic polling before notification; the 
failed round cannot enter the Handler or ACK path. The lifecycle owner closes 
the channel after coordinating background senders.
+
+## Messages, Records, and Processors
+
+| Go method or type | Java counterpart | Go representation |
 | --- | --- | --- |
-| 
`SubscriptionMessage`、`SubscriptionMessageKind`、`RecordMessage`、`WatermarkMessage`
 | `SubscriptionMessage`、记录和水位线消息类型 | 公共消息种类与协议数字解耦;Pull 和 Push 只交付记录,Processor 
可接收水位线 |
-| `SubscriptionMessage.Kind()`、`CommitContext()` | 
`getMessageType/getCommitContext` | 方法返回公开种类和提交上下文快照 |
-| `SubscriptionMessage.Records()` | 
`getResultSets/getRecordTabletIterator`、`SubscriptionRecordHandler` | 返回多数据库、多 
Tablet 的 `[]RecordBatch`,不复制 Java ResultSet 继承层次 |
-| `SubscriptionMessage.Watermark()` | `getWatermarkTimestamp()` | 用 `ok` 
标识是否为水位线消息 |
-| `EstimatedSize()`、`Release()` | `estimateSize/removeUserData` | 
释放记录缓存后保留消息类型与提交身份,仍可提交 |
-| `RecordBatch` | `SubscriptionRecordHandler.SubscriptionResultSet` 和底层 Tablet 
视图 | 提供模型、数据库、目标、列信息、时间投影、行数和按索引访问 |
-| `Column` | measurement schema、列类型与类别 | 复用现有 
`client.TSDataType/ColumnCategory`;时间列单独表示 |
-| `RecordBatch.Rows()`、`Row` | `ResultSet`、`RowRecord`、`TSRecord` 的遍历视图 | 使用 
`iter.Seq2[Row, error]`;索引从 0 开始 |
-| `RecordBatch.TimeSelected()`、`Row.Timestamp` | 消息和表级时间列选择信息 | 
每个批次独立保留投影;未选择时间列时 `Row.Timestamp == nil` |
-| `RecordBatch.Timestamp(row)` | 底层 Tablet 的时间戳访问 | 即使不投影时间列,处理器仍可读取原始时间戳 |
-| `SubscriptionMessageProcessor.Process/Flush/Reset` | 
`SubscriptionMessageProcessor` 的同名能力 | 处理和排空显式返回 error;consumer 串行调用每个 
Processor |
-| `BufferingProcessor.Buffered()`、`ProcessorBuffer` | 
`getBufferedCount/getBufferedCommitContexts` | 缓存能力用可选接口表达,同时报告条数和全部可续租上下文 |
-| `TopicResetter.ResetTopic(topic)` | `supportsTopicScopedReset/reset(topic)` 
| 是否实现接口代替 Java 的能力布尔值 |
-| `WatermarkReporter.Watermark()` | `WatermarkProcessor.getWatermark()` | 
可选暴露处理器计算的排序水位线;不等同于 Consumer 最新服务端水位线 |
-
-SubscriptionMessageProcessor 保留消息时必须实现 
`BufferingProcessor`,让后续心跳实现能够续租未交付记录。seek 只清理目标 Topic;同时订阅多个 Topic 时,未实现 
`TopicResetter` 的 Processor 会使 seek 在修改服务端位置前失败;单 Topic 场景允许回退到 
`Reset()`。`Flush` 返回的消息经后续处理阶段继续处理,Processor 不得再保留或修改已移交的消息。
-
-## 数据所有权与 context 契约
-
-- Session 查询集合、Consumer 身份、提交上下文和进度返回调用方拥有的快照;进度 map 为深快照。seek 复制输入,不长期借用调用方的 
map。
-- `SubscriptionMessage.Records()` 的批次、列和行数据是借用的只读视图,有效期到所属消息 
`Release()`。需要跨越该有效期保留数据时,调用方负责复制值和字节数组。
-- `Release()` 幂等。释放后不再使用已借用的批次、列和行数据;`Records()` 返回 
`ErrDataReleased`,消息类型、提交上下文和水位线仍可访问。
-- `Row.Values` 的 nil 表示 SQL NULL;DATE 使用 `time.Time`;TIMESTAMP 和记录时间戳使用服务端精度的 
`int64`;BLOB/OBJECT 使用 `[]byte`。
-- Push Handler 不得释放收到的消息;回调返回后若仍需记录数据,必须先复制。回调 context 随消费交付停止而取消。
-- `Open(ctx)` 的 context 只限制打开操作,不持有后台任务生命周期;后台任务随 `Close()` 停止。其他操作 context 
仅限制对应操作。
-- Pull 超时受 `timeout` 和 context deadline 中较早者约束。操作超时使用 
`time.Duration`,不改变消息中的时间戳单位。
-- 已打开时重复 `Open`、已关闭时重复 `Close` 无副作用。成功关闭后不能重新打开;要求先排空缓存的关闭失败仍保留排空和提交的恢复路径。
-
-## 错误与当前未实现内容
-
-| Go 错误哨兵 | Java 对应或行为 |
+| `SubscriptionMessage`, `SubscriptionMessageKind`, `RecordMessage`, 
`WatermarkMessage` | `SubscriptionMessage`, record and watermark message kinds 
| Public kinds are independent of numeric wire types; Pull and Push deliver 
records only, while processors can receive watermarks |
+| `SubscriptionMessage.Kind()`, `CommitContext()` | 
`getMessageType/getCommitContext` | Returns the public kind and a 
commit-context snapshot |
+| `SubscriptionMessage.Records()` | `getResultSets/getRecordTabletIterator`, 
`SubscriptionRecordHandler` | Returns `[]RecordBatch` across databases and 
Tablets without reproducing Java's ResultSet hierarchy |
+| `SubscriptionMessage.Watermark()` | `getWatermarkTimestamp()` | `ok` 
identifies a watermark message |
+| `EstimatedSize()`, `Release()` | `estimateSize/removeUserData` | Releases 
record buffers while retaining kind and commit identity, allowing a later 
commit |
+| `RecordBatch` | `SubscriptionRecordHandler.SubscriptionResultSet` and its 
Tablet view | Exposes model, database, target, column metadata, time 
projection, row count, and indexed access |
+| `Column` | Measurement schema, column type, and category | Reuses 
`client.TSDataType/ColumnCategory`; time is represented separately |
+| `RecordBatch.Rows()`, `Row` | Iteration views of `ResultSet`, `RowRecord`, 
and `TSRecord` | Uses `iter.Seq2[Row, error]` with zero-based indexes |
+| `RecordBatch.TimeSelected()`, `Row.Timestamp` | Message-level and per-table 
time-selection metadata | Each batch retains its projection; `Row.Timestamp == 
nil` when time is not selected |
+| `RecordBatch.Timestamp(row)` | Raw Tablet timestamp access | Processors can 
read raw timestamps even when time is not projected |
+| `SubscriptionMessageProcessor.Process/Flush/Reset` | Methods with the same 
roles in `SubscriptionMessageProcessor` | Processing and flushing explicitly 
return errors; consumers invoke each processor serially |
+| `BufferingProcessor.Buffered()`, `ProcessorBuffer` | 
`getBufferedCount/getBufferedCommitContexts` | An optional buffering interface 
reports both the count and all renewable contexts |
+| `TopicResetter.ResetTopic(topic)` | `supportsTopicScopedReset/reset(topic)` 
| Interface implementation replaces Java's capability flag |
+| `WatermarkReporter.Watermark()` | `WatermarkProcessor.getWatermark()` | 
Optionally exposes a processor's ordering watermark, distinct from the 
Consumer's latest server watermark |
+
+A `SubscriptionMessageProcessor` that retains messages must implement 
`BufferingProcessor` so heartbeats can renew undelivered records. Seek clears 
only its target topic. With multiple subscribed topics, a processor without 
`TopicResetter` makes seek fail before server positions change. A single-topic 
consumer can fall back to `Reset()`. Messages returned by `Flush` pass through 
subsequent stages; the processor must not retain or modify messages after 
transferring them.
+
+## Data Ownership and Context Contracts
+
+- Session query collections, Consumer identity, commit contexts, and progress 
are caller-owned snapshots; progress maps are deep snapshots. Seek copies its 
input rather than retaining the caller's maps.
+- Batches, columns, and row data from `SubscriptionMessage.Records()` are 
borrowed, read-only views valid until the message's `Release()`. Callers must 
copy values and byte slices that need to outlive that point.
+- `Release()` is idempotent. Do not reuse borrowed batch, column, or row data 
after release. `Records()` returns `ErrDataReleased`, while kind, commit 
context, and watermark remain available.
+- Nil in `Row.Values` means SQL NULL. DATE uses `time.Time`; TIMESTAMP and 
record timestamps use `int64` in server precision; BLOB/OBJECT use `[]byte`.
+- A Push Handler must not release its message. Copy record data before 
returning if it is needed afterward. The callback context is canceled when 
delivery stops.
+- The `Open(ctx)` context bounds opening only, not the background lifetime. 
Background work stops with `Close()`. Other operation contexts bound their 
corresponding operations only.
+- A positive Pull timeout bounds foreground queue waiting and network polling, 
subject to an earlier context deadline. Zero has the single-round behavior 
described above; processor callbacks must return promptly. Operation timeouts 
use `time.Duration` without changing message timestamp units.
+- Repeated Consumer `Open` while open and repeated `Close` after closing are 
harmless. A successfully closed Consumer cannot reopen. A failed close 
requiring buffered data to be drained preserves the drain-and-commit recovery 
path.
+
+## Errors and Remaining Work
+
+| Go sentinel error | Java counterpart or behavior |
 | --- | --- |
-| `ErrUnsupportedTsFile` | 本轮明确排除的 TsFile handler;仅解析文件载荷时返回,管理及订阅不提前拒绝 |
-| `ErrClosed`、`ErrNotOpen` | Consumer 生命周期检查 |
-| `ErrDataReleased` | 记录数据已释放后的访问 |
-| `ErrIncompatibleMessage` | `SubscriptionIncompatibleHandlerException` 
所表达的消息访问不匹配 |
-| `ErrConsumerFenced`、`ErrOwnerFenced` | 
`SubscriptionConsumerFencedException`、`SubscriptionOwnerFencedException` |
+| `ErrUnsupportedTsFile` | The excluded TsFile handler; returned only while 
decoding a file payload, not during management or subscribe |
+| `ErrClosed`, `ErrNotOpen` | Consumer lifecycle checks |
+| `ErrDataReleased` | Record access after user data release |
+| `ErrIncompatibleMessage` | Incompatible payload access represented by 
`SubscriptionIncompatibleHandlerException` |
+| `ErrConsumerFenced`, `ErrOwnerFenced` | 
`SubscriptionConsumerFencedException`, `SubscriptionOwnerFencedException` |
 
-这些哨兵可以被后续操作错误包装,调用方使用 `errors.Is` 识别。TsFile 不支持错误不得触发连接重试或文件载荷确认。Pull 
本轮返回错误而不交付任何消息,包括并行分支已经取得的记录;本轮记录不得推进位置、进入处理器或自动提交缓存,此前成功交付及提交的状态不回滚。调用方可退订相关 
Topic 后继续拉取。
+Operation errors can wrap these sentinels; callers identify them with 
`errors.Is`. Unsupported TsFile errors must not trigger connection retries or 
file-payload acknowledgments. Pull returns an error and no messages for that 
round, including records obtained by parallel branches. That round must not 
advance positions or enter processor or automatic-commit buffers. Previously 
delivered records and confirmed progress are not rolled back. Callers can 
unsubscribe the offending topic and poll again.
 
-后续步骤尚需实现公共 Consumer 和构造、实际记录续取循环、多节点协调、提交进度与恢复、后台任务、内置 Watermark/ColumnAlign 
Processor,以及消费示例和行为测试。内部 Provider 已有提交 RPC,但尚未实现公共 Consumer 
的交付和确认链。管理查询复用根模块解码器,本轮不修改其对畸形数据的处理逻辑。当前仅完成静态核对,没有编译、运行测试或执行格式工具,不提供运行验证结论。
+Remaining work includes Push consumers, built-in Watermark/ColumnAlign 
processors, further consumption examples, and behavior tests. Management 
queries reuse the root module's decoder; this step does not change its handling 
of malformed data. Verification has been static only: no compilation, tests, or 
formatting tools have run, and no runtime validation result is claimed.
diff --git a/subscription/consumer.go b/subscription/consumer.go
index 1473026..23b5b3e 100644
--- a/subscription/consumer.go
+++ b/subscription/consumer.go
@@ -76,8 +76,9 @@ type SubscriptionConsumerInfo struct {
 
 // SubscriptionPullConsumer fetches record messages explicitly. Poll and 
PollWithInfo use
 // server timestamp units for message data and time.Duration for timeouts. The
-// shorter of the timeout and the context deadline bounds a polling operation.
-// No topics means all subscribed topics.
+// positive timeout includes waiting for other foreground operations and bounds
+// network polling, subject to an earlier context deadline. Processor callbacks
+// run serially and must return promptly. No topics means all subscribed 
topics.
 //
 // A TsFile decoding error returns no messages for that poll round, including
 // records from parallel requests. That round is not acknowledged, added to the
@@ -90,6 +91,11 @@ type SubscriptionPullConsumer interface {
        // Poll retrieves messages from the named topics, waiting up to timeout.
        // Omitting topics selects all current subscriptions. An empty result 
with a
        // nil error is normal when no records arrive within the polling period.
+       // A negative timeout is invalid. Zero skips waiting for a busy 
consumer or
+       // connection recovery and attempts one round of server polls with no 
server
+       // wait; network I/O remains bounded by ctx. Caller cancellation is an 
error.
+       // Only expiration of the poll's own budget may return complete records 
from
+       // healthy parallel requests while discarding incomplete sibling 
results.
        // It returns an error when polling, context cancellation, or decoding 
fails.
        Poll(ctx context.Context, timeout time.Duration, topics ...string) 
([]SubscriptionMessage, error)
        // PollWithInfo polls with the same topic, timeout, and error semantics 
as
diff --git a/subscription/doc.go b/subscription/doc.go
index 1864210..6f68007 100644
--- a/subscription/doc.go
+++ b/subscription/doc.go
@@ -24,8 +24,9 @@
 // NewSubscriptionSession. Consumer configuration defaults and internal control
 // protocol/provider support are available. Poll response and record decoding,
 // record views, message release, and watermark messages are implemented 
internally.
-// Public consumers, background coordination, and built-in processors remain
-// subsequent implementation steps.
+// NewSubscriptionPullConsumer provides pull consumption, record continuation,
+// commit and seek coordination, background heartbeats, and provider recovery.
+// Push consumers 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/pull_consumer.go b/subscription/pull_consumer.go
new file mode 100644
index 0000000..b8ecbbc
--- /dev/null
+++ b/subscription/pull_consumer.go
@@ -0,0 +1,513 @@
+/*
+ * 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"
+       "crypto/rand"
+       "encoding/hex"
+       "errors"
+       "fmt"
+       "sort"
+       "sync"
+       "sync/atomic"
+       "time"
+)
+
+var subscriptionInstanceEpoch atomic.Int64
+
+// NewSubscriptionPullConsumer copies and validates config without opening a
+// connection. Start with DefaultSubscriptionPullConsumerConfig for root/root
+// authentication defaults. Call Open before subscribing or polling; canceling
+// Open's context after it returns does not stop the consumer's background 
work.
+func NewSubscriptionPullConsumer(config SubscriptionPullConsumerConfig) 
(SubscriptionPullConsumer, error) {
+       resolved, err := normalizeSubscriptionPullConsumerConfig(config)
+       if err != nil {
+               return nil, err
+       }
+       var suffix [8]byte
+       if _, err := rand.Read(suffix[:]); err != nil {
+               return nil, fmt.Errorf("subscription: generate consumer 
instance identity: %w", err)
+       }
+       var epoch int64
+       for {
+               previous := subscriptionInstanceEpoch.Load()
+               epoch = max(time.Now().UnixMilli(), previous+1)
+               if subscriptionInstanceEpoch.CompareAndSwap(previous, epoch) {
+                       break
+               }
+       }
+       consumer := &subscriptionPullConsumer{
+               config: resolved,
+               instanceID: fmt.Sprintf("%016x-%s", epoch, 
hex.EncodeToString(suffix[:])),
+               flow: make(chan struct{}, 1),
+               progressOperations: make(chan struct{}, 1),
+               syncGate: make(chan struct{}, 1),
+               recovery: make(chan struct{}, 1),
+               providers: make(map[int32]*subscriptionProvider),
+               endpoints: make(map[int32]string),
+               topics: make(map[string]map[string]string),
+               heartbeatBusy: make(map[*subscriptionProvider]bool),
+               positions: make(map[string]TopicProgress),
+               committed: make(map[string]TopicProgress),
+               uncommitted: 
make(map[subscriptionCommitKey]subscriptionPendingCommit),
+               redirectAcks: make(map[subscriptionCommitKey]CommitContext),
+               identity: SubscriptionConsumerInfo{
+                       ConsumerID: resolved.Consumer.ConsumerID,
+                       GroupID: resolved.Consumer.GroupID,
+                       OwnerID: resolved.Consumer.OwnerID,
+                       OwnerEpoch: resolved.Consumer.OwnerEpoch,
+               },
+       }
+       return consumer, nil
+}
+
+type subscriptionPullConsumer struct {
+       config SubscriptionPullConsumerConfig
+       instanceID string
+       mu sync.RWMutex
+       flow chan struct{}
+       progressOperations chan struct{}
+       syncGate chan struct{}
+       recovery chan struct{}
+       workers sync.WaitGroup
+       providers map[int32]*subscriptionProvider
+       endpoints map[int32]string
+       topics map[string]map[string]string
+       identity SubscriptionConsumerInfo
+       opened bool
+       released bool
+       closing bool
+       fenced error
+       generation uint64
+       topicRevision uint64
+       lifeCtx context.Context
+       lifeCancel context.CancelFunc
+       openingCancel context.CancelFunc
+       flowCancel context.CancelFunc
+       heartbeatBusy map[*subscriptionProvider]bool
+       processors []SubscriptionMessageProcessor
+       drained []SubscriptionMessage
+       bufferedContexts []CommitContext
+       positions map[string]TopicProgress
+       committed map[string]TopicProgress
+       uncommitted map[subscriptionCommitKey]subscriptionPendingCommit
+       redirectAcks map[subscriptionCommitKey]CommitContext
+       watermark int64
+       hasWatermark bool
+       pendingCritical error
+       pollCursor uint64
+}
+
+func (c *subscriptionPullConsumer) acquireFlow(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 c.flow <- struct{}{}:
+               return nil
+       case <-ctx.Done():
+               return ctx.Err()
+       }
+}
+
+func (c *subscriptionPullConsumer) releaseFlow() {
+       <-c.flow
+}
+
+func (c *subscriptionPullConsumer) stateErrorLocked(allowClosing bool) error {
+       if c.fenced != nil {
+               return c.fenced
+       }
+       if c.released || (c.closing && !allowClosing) {
+               return ErrClosed
+       }
+       if !c.opened {
+               return ErrNotOpen
+       }
+       return nil
+}
+
+func (c *subscriptionPullConsumer) checkOpen() error {
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       return c.stateErrorLocked(false)
+}
+
+func (c *subscriptionPullConsumer) beginOperation(ctx context.Context) 
(context.Context, func(), error) {
+       return c.beginQueuedOperation(ctx, ctx)
+}
+
+// beginQueuedOperation includes time spent waiting for the foreground gate in 
a
+// poll's budget, while keeping the caller/lifetime context separately 
observable.
+func (c *subscriptionPullConsumer) beginQueuedOperation(ctx, queueCtx 
context.Context) (context.Context, func(), error) {
+       if ctx == nil {
+               return nil, nil, errors.New("subscription: context must not be 
nil")
+       }
+       if err := c.acquireFlow(queueCtx); err != nil {
+               return nil, nil, err
+       }
+       return c.beginAcquiredOperation(ctx)
+}
+
+func (c *subscriptionPullConsumer) beginNonblockingOperation(ctx 
context.Context) (context.Context, func(), bool, error) {
+       if ctx == nil {
+               return nil, nil, false, errors.New("subscription: context must 
not be nil")
+       }
+       if err := ctx.Err(); err != nil {
+               return nil, nil, false, err
+       }
+       select {
+       case c.flow <- struct{}{}:
+               operationCtx, finish, err := c.beginAcquiredOperation(ctx)
+               return operationCtx, finish, err == nil, err
+       default:
+               return nil, nil, false, c.checkOpen()
+       }
+}
+
+func (c *subscriptionPullConsumer) beginAcquiredOperation(ctx context.Context) 
(context.Context, func(), error) {
+       if err := ctx.Err(); err != nil {
+               c.releaseFlow()
+               return nil, nil, err
+       }
+       c.mu.Lock()
+       if err := c.stateErrorLocked(false); err != nil {
+               c.mu.Unlock()
+               c.releaseFlow()
+               return nil, nil, err
+       }
+       operationCtx, cancel := context.WithCancel(ctx)
+       stop := context.AfterFunc(c.lifeCtx, cancel)
+       c.flowCancel = cancel
+       c.mu.Unlock()
+       return operationCtx, func() {
+               stop()
+               cancel()
+               c.mu.Lock()
+               c.flowCancel = nil
+               c.mu.Unlock()
+               c.releaseFlow()
+       }, nil
+}
+
+// linkContext registers a concurrent operation before releasing the state 
lock,
+// so Close cannot race a Wait with a late WaitGroup.Add.
+func (c *subscriptionPullConsumer) linkContext(ctx context.Context) 
(context.Context, func(), error) {
+       if ctx == nil {
+               return nil, nil, errors.New("subscription: context must not be 
nil")
+       }
+       if err := ctx.Err(); err != nil {
+               return nil, nil, err
+       }
+       c.mu.Lock()
+       if err := c.stateErrorLocked(false); err != nil {
+               c.mu.Unlock()
+               return nil, nil, err
+       }
+       operationCtx, cancel := context.WithCancel(ctx)
+       stop := context.AfterFunc(c.lifeCtx, cancel)
+       c.workers.Add(1)
+       c.mu.Unlock()
+       return operationCtx, func() {
+               stop()
+               cancel()
+               c.workers.Done()
+       }, nil
+}
+
+func (c *subscriptionPullConsumer) Open(ctx context.Context) error {
+       if err := c.acquireFlow(ctx); err != nil {
+               return err
+       }
+       defer c.releaseFlow()
+       c.mu.Lock()
+       if c.fenced != nil || c.released || c.closing {
+               err := c.fenced
+               if err == nil {
+                       err = ErrClosed
+               }
+               c.mu.Unlock()
+               return err
+       }
+       if c.opened {
+               c.mu.Unlock()
+               return nil
+       }
+       openingCtx, cancel := context.WithCancel(ctx)
+       c.openingCancel = cancel
+       generation := c.generation
+       c.mu.Unlock()
+       defer cancel()
+       err := c.recoverProviders(openingCtx)
+       c.mu.Lock()
+       c.openingCancel = nil
+       if c.generation != generation || c.closing || c.released {
+               err = ErrClosed
+       }
+       if err == nil {
+               err = openingCtx.Err()
+       }
+       if err == nil && c.fenced != nil {
+               err = c.fenced
+       }
+       if err != nil {
+               providers := c.detachProvidersLocked()
+               c.mu.Unlock()
+               for _, provider := range providers {
+                       _ = provider.connection.abort()
+               }
+               return err
+       }
+       c.lifeCtx, c.lifeCancel = context.WithCancel(context.Background())
+       c.opened = true
+       c.workers.Add(3)
+       c.mu.Unlock()
+       go c.runHeartbeatScheduler()
+       go c.runEndpointSync()
+       go c.runAutoCommit()
+       return nil
+}
+
+func (c *subscriptionPullConsumer) Close() error {
+       c.mu.Lock()
+       if c.released || c.closing {
+               c.mu.Unlock()
+               return nil
+       }
+       c.closing = true
+       c.generation++
+       if c.openingCancel != nil {
+               c.openingCancel()
+       }
+       if c.flowCancel != nil {
+               c.flowCancel()
+       }
+       c.mu.Unlock()
+       // The canceled foreground operation will release its gate after its RPC
+       // unwinds. Processor callbacks are serialized through the same gate.
+       c.flow <- struct{}{}
+       defer c.releaseFlow()
+       c.mu.RLock()
+       opened, fenced := c.opened, c.fenced
+       c.mu.RUnlock()
+       if opened && fenced == nil {
+               drained, err := c.drainForClose()
+               if err != nil {
+                       c.mu.Lock()
+                       c.closing = false
+                       c.mu.Unlock()
+                       return err
+               }
+               if !*c.config.AutoCommit && (len(drained) != 0 || 
c.processorBufferedCount() != 0) {
+                       c.drained = append(c.drained, drained...)
+                       c.refreshBufferedContexts()
+                       c.mu.Lock()
+                       c.closing = false
+                       c.mu.Unlock()
+                       return errors.New("subscription: drain buffered 
messages, process and commit them, then retry Close")
+               }
+               if *c.config.AutoCommit {
+                       c.trackDelivered(drained)
+               }
+       }
+       c.mu.Lock()
+       if c.lifeCancel != nil {
+               c.lifeCancel()
+       }
+       c.mu.Unlock()
+       c.workers.Wait()
+       ctx, cancel := context.WithTimeout(context.Background(), 
min(c.config.Consumer.Connection.ConnectTimeout, 5*time.Second))
+       defer cancel()
+       var failures []error
+       if opened && fenced == nil && *c.config.AutoCommit {
+               if err := c.commitContexts(ctx, c.pendingCommitContexts(true, 
time.Now()), false); err != nil {
+                       failures = append(failures, err)
+               }
+       }
+       c.mu.Lock()
+       fenced = c.fenced
+       providers := c.detachProvidersLocked()
+       c.opened = false
+       c.released = true
+       c.closing = false
+       c.mu.Unlock()
+       results := make(chan error, len(providers))
+       for _, provider := range providers {
+               go func(provider *subscriptionProvider) {
+                       results <- provider.close(ctx, fenced != nil)
+               }(provider)
+       }
+       for range providers {
+               if err := <-results; err != nil {
+                       failures = append(failures, err)
+               }
+       }
+       return errors.Join(failures...)
+}
+
+func (c *subscriptionPullConsumer) Info() SubscriptionConsumerInfo {
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       info := c.identity
+       if info.OwnerEpoch != nil {
+               epoch := *info.OwnerEpoch
+               info.OwnerEpoch = &epoch
+       }
+       return info
+}
+
+func (c *subscriptionPullConsumer) LatestWatermark() (int64, bool) {
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       return c.watermark, c.hasWatermark
+}
+
+func (c *subscriptionPullConsumer) AllConsumed() bool {
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       return len(c.topics) == 0
+}
+
+func (c *subscriptionPullConsumer) Subscribe(ctx context.Context, topics 
...string) error {
+       return c.updateSubscriptions(ctx, topics, false)
+}
+
+func (c *subscriptionPullConsumer) Unsubscribe(ctx context.Context, topics 
...string) error {
+       return c.updateSubscriptions(ctx, topics, true)
+}
+
+func (c *subscriptionPullConsumer) updateSubscriptions(ctx context.Context, 
topics []string, unsubscribe bool) error {
+       operationCtx, finish, err := c.beginOperation(ctx)
+       if err != nil {
+               return err
+       }
+       defer finish()
+       parsed := make([]string, 0, len(topics))
+       for _, topic := range topics {
+               name, err := parseSubscriptionIdentifier(topic)
+               if err != nil {
+                       return err
+               }
+               parsed = append(parsed, name)
+       }
+       return c.changeSubscriptions(operationCtx, parsed, unsubscribe)
+}
+
+// changeSubscriptions assumes the flow gate is held and names are already in
+// protocol form. Heartbeat and termination names must not be parsed a second 
time.
+func (c *subscriptionPullConsumer) changeSubscriptions(ctx context.Context, 
topics []string, unsubscribe bool) error {
+       if err := c.checkOpen(); err != nil {
+               return err
+       }
+       if len(topics) == 0 {
+               return nil
+       }
+       c.mu.Lock()
+       c.topicRevision++
+       c.mu.Unlock()
+       defer func() {
+               c.mu.Lock()
+               c.topicRevision++
+               c.mu.Unlock()
+       }()
+       providers := c.providerSnapshot()
+       if !hasAvailableSubscriptionProvider(providers) {
+               if err := c.recoverProviders(ctx); err != nil {
+                       return err
+               }
+               providers = c.providerSnapshot()
+       }
+       var failures []error
+       for _, provider := range providers {
+               if provider.connection.isClosed() {
+                       continue
+               }
+               current, err := provider.subscribe(ctx, topics, unsubscribe)
+               if err == nil {
+                       c.mu.Lock()
+                       c.topics = current
+                       if unsubscribe {
+                               for key, commitContext := range c.redirectAcks {
+                                       for _, topic := range topics {
+                                               if commitContext.Topic == topic 
{
+                                                       delete(c.redirectAcks, 
key)
+                                               }
+                                       }
+                               }
+                       }
+                       c.mu.Unlock()
+                       return nil
+               }
+               err = c.handleProviderError(provider, err)
+               if errors.Is(err, ErrConsumerFenced) || errors.Is(err, 
ErrOwnerFenced) || ctx.Err() != nil {
+                       return err
+               }
+               var status *subscriptionStatusError
+               if errors.As(err, &status) && status.Code == 1911 {
+                       // As in Java, a pipe procedure can finish after its 
timeout. A later
+                       // heartbeat reconciles the server's subscription 
configuration.
+                       return nil
+               }
+               failures = append(failures, err)
+       }
+       if len(failures) == 0 {
+               return errors.New("subscription: no available subscription 
providers")
+       }
+       return errors.Join(failures...)
+}
+
+func (c *subscriptionPullConsumer) providerSnapshot() []*subscriptionProvider {
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       providers := make([]*subscriptionProvider, 0, len(c.providers))
+       for _, provider := range c.providers {
+               providers = append(providers, provider)
+       }
+       sort.Slice(providers, func(i, j int) bool { return 
providers[i].dataNodeID < providers[j].dataNodeID })
+       return providers
+}
+
+func (c *subscriptionPullConsumer) providerForNode(id int32) 
*subscriptionProvider {
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       return c.providers[id]
+}
+
+func (c *subscriptionPullConsumer) detachProvidersLocked() 
[]*subscriptionProvider {
+       providers := make([]*subscriptionProvider, 0, len(c.providers))
+       for _, provider := range c.providers {
+               providers = append(providers, provider)
+       }
+       c.providers = make(map[int32]*subscriptionProvider)
+       return providers
+}
+
+func hasAvailableSubscriptionProvider(providers []*subscriptionProvider) bool {
+       for _, provider := range providers {
+               if !provider.connection.isClosed() {
+                       return true
+               }
+       }
+       return false
+}
diff --git a/subscription/pull_flow.go b/subscription/pull_flow.go
new file mode 100644
index 0000000..2d2b360
--- /dev/null
+++ b/subscription/pull_flow.go
@@ -0,0 +1,739 @@
+/*
+ * 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"
+       "math/rand/v2"
+       "sort"
+       "time"
+)
+
+type flowPollResult struct {
+       messages []SubscriptionMessage
+       emptyContexts []CommitContext
+       nackContexts []CommitContext
+       rollbackContexts []CommitContext
+       terminated []string
+       err error
+}
+
+func (c *subscriptionPullConsumer) Poll(ctx context.Context, timeout 
time.Duration, topics ...string) ([]SubscriptionMessage, error) {
+       operationCtx, pollCtx, finish, acquired, err := c.beginFlowPoll(ctx, 
timeout)
+       if err != nil || !acquired {
+               return nil, err
+       }
+       defer finish()
+       return c.pollLocked(operationCtx, pollCtx, timeout == 0, topics)
+}
+
+func (c *subscriptionPullConsumer) PollWithInfo(ctx context.Context, timeout 
time.Duration, topics ...string) (PollResult, error) {
+       operationCtx, pollCtx, finish, acquired, err := c.beginFlowPoll(ctx, 
timeout)
+       if err != nil || !acquired {
+               return PollResult{}, err
+       }
+       defer finish()
+       messages, err := c.pollLocked(operationCtx, pollCtx, timeout == 0, 
topics)
+       if err != nil {
+               return PollResult{}, err
+       }
+       result := PollResult{Messages: messages, BufferedCount: 
c.processorBufferedCount()}
+       for _, processor := range c.processors {
+               if reporter, ok := processor.(WatermarkReporter); ok {
+                       result.Watermark, result.HasWatermark = 
reporter.Watermark()
+               }
+       }
+       return result, nil
+}
+
+// beginFlowPoll starts the network budget before waiting for the flow gate.
+// The operation context stays tied to the caller and consumer lifetime, so a
+// budget expiration remains distinguishable from cancellation of consumption.
+func (c *subscriptionPullConsumer) beginFlowPoll(ctx context.Context, timeout 
time.Duration) (operationCtx, pollCtx context.Context, finish func(), acquired 
bool, err error) {
+       if ctx == nil {
+               return nil, nil, nil, false, errors.New("subscription: context 
must not be nil")
+       }
+       if timeout < 0 {
+               return nil, nil, nil, false, errors.New("subscription: poll 
timeout must not be negative")
+       }
+       if timeout == 0 {
+               operationCtx, finish, acquired, err = 
c.beginNonblockingOperation(ctx)
+               return operationCtx, operationCtx, finish, acquired, err
+       }
+       queueCtx, cancelQueue := context.WithTimeout(ctx, timeout)
+       operationCtx, release, err := c.beginQueuedOperation(ctx, queueCtx)
+       if err != nil {
+               cancelQueue()
+               if stateErr := c.checkOpen(); stateErr != nil {
+                       return nil, nil, nil, false, stateErr
+               }
+               if callerErr := ctx.Err(); callerErr != nil {
+                       return nil, nil, nil, false, callerErr
+               }
+               if errors.Is(err, context.DeadlineExceeded) {
+                       return nil, nil, nil, false, nil
+               }
+               return nil, nil, nil, false, err
+       }
+       if queueCtx.Err() != nil {
+               release()
+               cancelQueue()
+               if stateErr := c.checkOpen(); stateErr != nil {
+                       return nil, nil, nil, false, stateErr
+               }
+               if callerErr := ctx.Err(); callerErr != nil {
+                       return nil, nil, nil, false, callerErr
+               }
+               return nil, nil, nil, false, nil
+       }
+       deadline, _ := queueCtx.Deadline()
+       pollCtx, cancelPoll := context.WithDeadline(operationCtx, deadline)
+       return operationCtx, pollCtx, func() {
+               cancelPoll()
+               cancelQueue()
+               release()
+       }, true, nil
+}
+
+func (c *subscriptionPullConsumer) pollLocked(operationCtx, pollCtx 
context.Context, immediate bool, topics []string) ([]SubscriptionMessage, 
error) {
+       selected, err := c.flowTopics(topics)
+       if err != nil {
+               return nil, err
+       }
+       c.mu.Lock()
+       pending := c.pendingCritical
+       c.pendingCritical = nil
+       c.mu.Unlock()
+       if pending != nil {
+               return nil, pending
+       }
+       if len(selected) == 0 {
+               return nil, nil
+       }
+       networkReady := true
+       if !hasAvailableSubscriptionProvider(c.providerSnapshot()) {
+               if immediate {
+                       // A zero-wait poll can drive existing processor state, 
but must
+                       // not turn into a synchronous connection-recovery 
attempt.
+                       c.requestRecovery()
+                       networkReady = false
+               } else if err := c.recoverProviders(pollCtx); err != nil {
+                       if stateErr := c.checkOpen(); stateErr != nil {
+                               return nil, stateErr
+                       }
+                       if operationCtx.Err() == nil && errors.Is(err, 
context.DeadlineExceeded) && pollCtx.Err() != nil {
+                               // Still let processors advance or flush their 
retained records on
+                               // an empty input when only the network budget 
was exhausted.
+                               networkReady = false
+                       } else {
+                               return nil, err
+                       }
+               }
+       }
+       var results []flowPollResult
+       if networkReady {
+               results = c.pollFlowPartitions(pollCtx, selected, immediate)
+       }
+       var messages []SubscriptionMessage
+       var emptyContexts, failedContexts, allContexts []CommitContext
+       var terminations []string
+       var fatal, critical, ordinary error
+       for _, result := range results {
+               allContexts = append(allContexts, result.rollbackContexts...)
+               allContexts = append(allContexts, result.nackContexts...)
+               failedContexts = append(failedContexts, result.nackContexts...)
+               if result.err != nil {
+                       failedContexts = append(failedContexts, 
result.rollbackContexts...)
+                       if flowFatalPollError(result.err) {
+                               if fatal == nil {
+                                       fatal = result.err
+                               }
+                       } else if flowCriticalPollError(result.err) {
+                               critical = result.err
+                       } else if !((errors.Is(result.err, 
context.DeadlineExceeded) || errors.Is(result.err, context.Canceled)) && 
pollCtx.Err() != nil) {
+                               ordinary = result.err
+                       }
+                       continue
+               }
+               messages = append(messages, result.messages...)
+               emptyContexts = append(emptyContexts, result.emptyContexts...)
+               terminations = append(terminations, result.terminated...)
+       }
+       if err := c.checkOpen(); err != nil {
+               c.rollbackFlow(pollCtx, allContexts)
+               return nil, err
+       }
+       if err := operationCtx.Err(); err != nil {
+               c.rollbackFlow(pollCtx, allContexts)
+               return nil, err
+       }
+       if fatal != nil {
+               c.rollbackFlow(pollCtx, allContexts)
+               return nil, fatal
+       }
+       if len(messages) == 0 && critical != nil {
+               c.rollbackFlow(pollCtx, allContexts)
+               return nil, critical
+       }
+       if len(messages) == 0 && len(emptyContexts) == 0 && len(terminations) 
== 0 && ordinary != nil {
+               c.rollbackFlow(pollCtx, allContexts)
+               return nil, ordinary
+       }
+       if critical != nil {
+               c.mu.Lock()
+               if c.pendingCritical == nil {
+                       c.pendingCritical = critical
+               }
+               c.mu.Unlock()
+       }
+       // The caller/lifetime context aborts the entire round. Exhausting only 
the
+       // polling budget instead preserves already complete healthy 
partitions, as
+       // Java does for completed sibling futures. Do not start cleanup RPCs 
after
+       // that budget has expired; undelivered events remain unconfirmed.
+       c.rollbackFlow(pollCtx, failedContexts)
+       if pollCtx.Err() == nil && len(emptyContexts) != 0 {
+               if err := c.commitContexts(pollCtx, emptyContexts, false); err 
!= nil {
+                       if !(operationCtx.Err() == nil && pollCtx.Err() != nil 
&& errors.Is(err, context.DeadlineExceeded)) {
+                               c.rollbackFlow(pollCtx, allContexts)
+                               return nil, err
+                       }
+               }
+       }
+       if pollCtx.Err() == nil && len(terminations) != 0 {
+               names := uniqueFlowTopics(terminations)
+               if err := c.changeSubscriptions(pollCtx, names, true); err != 
nil {
+                       if !(operationCtx.Err() == nil && pollCtx.Err() != nil 
&& errors.Is(err, context.DeadlineExceeded)) {
+                               c.rollbackFlow(pollCtx, allContexts)
+                               return nil, err
+                       }
+               }
+       }
+       processed := messages
+       for _, processor := range c.processors {
+               if err := operationCtx.Err(); err != nil {
+                       c.rollbackFlow(pollCtx, allContexts)
+                       return nil, err
+               }
+               if err := c.checkOpen(); err != nil {
+                       c.rollbackFlow(pollCtx, allContexts)
+                       return nil, err
+               }
+               processed, err = processor.Process(processed)
+               if err != nil {
+                       c.refreshBufferedContexts()
+                       c.rollbackFlow(pollCtx, allContexts)
+                       return nil, err
+               }
+       }
+       c.refreshBufferedContexts()
+       if err := operationCtx.Err(); err != nil {
+               c.rollbackFlow(pollCtx, allContexts)
+               return nil, err
+       }
+       if err := c.checkOpen(); err != nil {
+               c.rollbackFlow(pollCtx, allContexts)
+               return nil, err
+       }
+       c.flushRedirectAcks(pollCtx, messages)
+       if err := c.checkOpen(); err != nil {
+               c.rollbackFlow(pollCtx, allContexts)
+               return nil, err
+       }
+       if err := operationCtx.Err(); err != nil {
+               c.rollbackFlow(pollCtx, allContexts)
+               return nil, err
+       }
+       // Fetch progress can include records retained by a successful 
processor, but
+       // automatic commit only tracks the records actually handed to the 
caller.
+       c.advancePositions(messages)
+       // Observe raw watermark signals even if a processor consumed them.
+       _ = c.visibleFlowMessages(messages)
+       processed = c.visibleFlowMessages(processed)
+       c.trackDelivered(processed)
+       return processed, nil
+}
+
+func (c *subscriptionPullConsumer) flowTopics(requested []string) ([]string, 
error) {
+       names := make([]string, 0, len(requested))
+       for _, topic := range requested {
+               name, err := parseSubscriptionIdentifier(topic)
+               if err != nil {
+                       return nil, err
+               }
+               names = append(names, name)
+       }
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       if len(requested) == 0 {
+               for name := range c.topics {
+                       names = append(names, name)
+               }
+       } else {
+               selected := names[:0]
+               for _, name := range names {
+                       if _, subscribed := c.topics[name]; subscribed {
+                               selected = append(selected, name)
+                       }
+               }
+               names = selected
+       }
+       return uniqueFlowTopics(names), nil
+}
+
+func uniqueFlowTopics(topics []string) []string {
+       seen := make(map[string]struct{}, len(topics))
+       for _, topic := range topics {
+               seen[topic] = struct{}{}
+       }
+       names := make([]string, 0, len(seen))
+       for topic := range seen {
+               names = append(names, topic)
+       }
+       sort.Strings(names)
+       return names
+}
+
+func (c *subscriptionPullConsumer) pollFlowPartitions(ctx context.Context, 
topics []string, immediate bool) []flowPollResult {
+       parallelism := min(c.config.Consumer.MaxPollParallelism, len(topics))
+       if parallelism < 1 {
+               parallelism = 1
+       }
+       partitions := make([][]string, parallelism)
+       for index, topic := range topics {
+               partitions[index%parallelism] = 
append(partitions[index%parallelism], topic)
+       }
+       cursor := c.pollCursor
+       c.pollCursor++
+       partitionCtx, cancel := context.WithCancel(ctx)
+       defer cancel()
+       type partitionResult struct {
+               index int
+               result flowPollResult
+       }
+       completed := make(chan partitionResult, parallelism)
+       for index, partition := range partitions {
+               go func(index int, topics []string) {
+                       completed <- partitionResult{index: index, result: 
c.pollFlowPartition(partitionCtx, topics, cursor+uint64(index), immediate)}
+               }(index, partition)
+       }
+       results := make([]flowPollResult, parallelism)
+       for range partitions {
+               result := <-completed
+               results[result.index] = result.result
+               if flowFatalPollError(result.result.err) {
+                       cancel()
+               }
+       }
+       return results
+}
+
+func (c *subscriptionPullConsumer) pollFlowPartition(ctx context.Context, 
topics []string, cursor uint64, immediate bool) (result flowPollResult) {
+       var lastFailure error
+       for {
+               if err := ctx.Err(); err != nil {
+                       result.err = err
+                       return result
+               }
+               if err := c.checkOpen(); err != nil {
+                       result.err = err
+                       return result
+               }
+               providers := c.providerSnapshot()
+               available := providers[:0]
+               for _, provider := range providers {
+                       if !provider.connection.isClosed() {
+                               available = append(available, provider)
+                       }
+               }
+               if len(available) == 0 {
+                       c.requestRecovery()
+                       if lastFailure == nil {
+                               lastFailure = errors.New("subscription: no 
available provider for poll")
+                       }
+                       result.err = lastFailure
+                       return result
+               }
+               progress := make(map[string]TopicProgress, len(topics))
+               c.mu.RLock()
+               for _, topic := range topics {
+                       if position := c.positions[topic]; len(position) != 0 {
+                               progress[topic] = cloneTopicProgress(position)
+                       }
+               }
+               c.mu.RUnlock()
+               healthy := false
+               for attempt := range available {
+                       provider := 
available[(int(cursor%uint64(len(available)))+attempt)%len(available)]
+                       responses, err := provider.poll(ctx, topics, 
flowRemainingMilliseconds(ctx, len(available)-attempt, immediate), 
int64(provider.bodyLimit), progress)
+                       if err != nil {
+                               err = c.handleProviderError(provider, err)
+                               if flowFatalPollError(err) || 
flowCriticalPollError(err) || ctx.Err() != nil {
+                                       result.err = err
+                                       return result
+                               }
+                               lastFailure = err
+                               continue
+                       }
+                       healthy = true
+                       for _, response := range responses {
+                               switch response.Type {
+                               case subscriptionResponseTablets:
+                                       rollbackIndex := 
len(result.rollbackContexts)
+                                       if 
flowCommitContextCommittable(response.CommitContext) {
+                                               result.rollbackContexts = 
append(result.rollbackContexts, response.CommitContext)
+                                       }
+                                       message, stale, err := 
c.completeFlowRecord(ctx, provider, response)
+                                       if stale {
+                                               result.rollbackContexts = 
result.rollbackContexts[:rollbackIndex]
+                                               continue
+                                       }
+                                       if err != nil {
+                                               err = 
c.handleProviderError(provider, err)
+                                               result.err = err
+                                               return result
+                                       }
+                                       if message == nil {
+                                               if 
flowCommitContextCommittable(response.CommitContext) {
+                                                       result.emptyContexts = 
append(result.emptyContexts, response.CommitContext)
+                                               }
+                                       } else {
+                                               result.messages = 
append(result.messages, message)
+                                       }
+                               case subscriptionResponseWatermark:
+                                       message, err := 
response.message(c.config.Consumer.Dialect)
+                                       if err != nil {
+                                               result.err = err
+                                               return result
+                                       }
+                                       result.messages = 
append(result.messages, message)
+                               case subscriptionResponseTermination:
+                                       result.terminated = 
append(result.terminated, response.CommitContext.Topic)
+                               case subscriptionResponseError:
+                                       if isOutdatedFlowResponse(response) {
+                                               continue
+                                       }
+                                       failure := 
&subscriptionPollError{Message: response.ErrorMessage, Critical: 
response.Critical}
+                                       if response.Critical {
+                                               result.err = failure
+                                               return result
+                                       }
+                                       if 
flowCommitContextCommittable(response.CommitContext) {
+                                               result.nackContexts = 
append(result.nackContexts, response.CommitContext)
+                                       }
+                                       lastFailure = failure
+                               default:
+                                       result.err = fmt.Errorf("subscription: 
unsupported poll response type %d", response.Type)
+                                       return result
+                               }
+                       }
+                       if len(result.messages) != 0 || 
len(result.emptyContexts) != 0 || len(result.terminated) != 0 {
+                               return result
+                       }
+               }
+               if !healthy && lastFailure != nil {
+                       result.err = lastFailure
+                       return result
+               }
+               if immediate {
+                       return result
+               }
+               // Back off only after visiting all available providers. A slow 
or idle
+               // provider must not insert a pause before a ready sibling is 
checked.
+               timer := 
time.NewTimer(time.Duration(50+rand.IntN(100))*time.Millisecond)
+               select {
+               case <-ctx.Done():
+                       timer.Stop()
+                       result.err = ctx.Err()
+                       return result
+               case <-timer.C:
+               }
+               cursor++
+       }
+}
+
+func (c *subscriptionPullConsumer) AddProcessor(processor 
SubscriptionMessageProcessor) error {
+       if processor == nil {
+               return errors.New("subscription: processor must not be nil")
+       }
+       if err := c.acquireFlow(context.Background()); err != nil {
+               return err
+       }
+       defer c.releaseFlow()
+       c.mu.RLock()
+       stateErr := c.fenced
+       if stateErr == nil && (c.released || c.closing) {
+               stateErr = ErrClosed
+       }
+       c.mu.RUnlock()
+       if stateErr != nil {
+               return stateErr
+       }
+       c.processors = append(c.processors, processor)
+       c.refreshBufferedContexts()
+       return nil
+}
+
+func (c *subscriptionPullConsumer) DrainBufferedMessages(ctx context.Context) 
([]SubscriptionMessage, error) {
+       operationCtx, finish, err := c.beginOperation(ctx)
+       if err != nil {
+               return nil, err
+       }
+       defer finish()
+       defer c.refreshBufferedContexts()
+       var messages []SubscriptionMessage
+       if len(c.drained) != 0 {
+               messages, c.drained = c.drained, nil
+       } else {
+               messages, err = c.flushProcessors()
+               if err != nil {
+                       c.drained = append(c.drained, messages...)
+                       return nil, err
+               }
+       }
+       if err := operationCtx.Err(); err != nil {
+               c.drained = append(c.drained, messages...)
+               return nil, err
+       }
+       if err := c.checkOpen(); err != nil {
+               c.drained = append(c.drained, messages...)
+               return nil, err
+       }
+       messages = c.visibleFlowMessages(messages)
+       c.trackDelivered(messages)
+       return messages, nil
+}
+
+// flushProcessors feeds upstream output through each later processing stage
+// before appending that stage's own flushed output. The caller owns the flow 
gate.
+func (c *subscriptionPullConsumer) flushProcessors() (messages 
[]SubscriptionMessage, err error) {
+       defer c.refreshBufferedContexts()
+       for _, processor := range c.processors {
+               if len(messages) != 0 {
+                       processed, processErr := processor.Process(messages)
+                       if processErr != nil {
+                               return messages, processErr
+                       }
+                       messages = processed
+               }
+               flushed, flushErr := processor.Flush()
+               messages = append(messages, flushed...)
+               if flushErr != nil {
+                       return messages, flushErr
+               }
+       }
+       return c.visibleFlowMessages(messages), nil
+}
+
+func (c *subscriptionPullConsumer) drainForClose() ([]SubscriptionMessage, 
error) {
+       defer c.refreshBufferedContexts()
+       messages := c.drained
+       c.drained = nil
+       flushed, err := c.flushProcessors()
+       messages = append(messages, flushed...)
+       if err != nil {
+               c.drained = append(c.drained, messages...)
+               return nil, err
+       }
+       return c.visibleFlowMessages(messages), nil
+}
+
+func (c *subscriptionPullConsumer) refreshBufferedContexts() {
+       var contexts []CommitContext
+       for _, message := range c.drained {
+               if message != nil {
+                       commitContext := message.CommitContext()
+                       if flowCommitContextCommittable(commitContext) {
+                               contexts = append(contexts, 
cloneMessageCommitContext(commitContext))
+                       }
+               }
+       }
+       for _, processor := range c.processors {
+               if buffered, ok := processor.(BufferingProcessor); ok {
+                       for _, commitContext := range 
buffered.Buffered().Contexts {
+                               if flowCommitContextCommittable(commitContext) {
+                                       contexts = append(contexts, 
cloneMessageCommitContext(commitContext))
+                               }
+                       }
+               }
+       }
+       c.mu.Lock()
+       c.bufferedContexts = contexts
+       c.mu.Unlock()
+}
+
+func (c *subscriptionPullConsumer) processorBufferedCount() int {
+       count := 0
+       for _, processor := range c.processors {
+               if buffered, ok := processor.(BufferingProcessor); ok {
+                       count += buffered.Buffered().Count
+               }
+       }
+       return count
+}
+
+func (c *subscriptionPullConsumer) validateProcessorReset(topic string) error {
+       c.mu.RLock()
+       multiple := len(c.topics) > 1
+       c.mu.RUnlock()
+       if !multiple {
+               return nil
+       }
+       for _, processor := range c.processors {
+               if _, ok := processor.(TopicResetter); !ok {
+                       return fmt.Errorf("subscription: processor %T cannot 
reset topic %q while multiple topics are subscribed", processor, topic)
+               }
+       }
+       return nil
+}
+
+func (c *subscriptionPullConsumer) resetProcessors(topic string) {
+       for _, processor := range c.processors {
+               if resetter, ok := processor.(TopicResetter); ok {
+                       resetter.ResetTopic(topic)
+               } else {
+                       processor.Reset()
+               }
+       }
+       retained := c.drained[:0]
+       for _, message := range c.drained {
+               if message != nil && message.CommitContext().Topic == topic {
+                       message.Release()
+                       continue
+               }
+               retained = append(retained, message)
+       }
+       clear(c.drained[len(retained):])
+       c.drained = retained
+       c.refreshBufferedContexts()
+}
+
+// visibleFlowMessages also observes watermarks consumed by a processor. 
Callers
+// pass the original successful poll messages separately when a stage removes 
them.
+func (c *subscriptionPullConsumer) visibleFlowMessages(messages 
[]SubscriptionMessage) []SubscriptionMessage {
+       visible := make([]SubscriptionMessage, 0, len(messages))
+       for _, message := range messages {
+               if message == nil {
+                       continue
+               }
+               if timestamp, ok := message.Watermark(); ok {
+                       c.mu.Lock()
+                       if !c.hasWatermark || timestamp > c.watermark {
+                               c.watermark, c.hasWatermark = timestamp, true
+                       }
+                       c.mu.Unlock()
+                       continue
+               }
+               if message.Kind() == RecordMessage {
+                       visible = append(visible, message)
+               }
+       }
+       return visible
+}
+
+func flowCommitContextCommittable(commitContext CommitContext) bool {
+       return commitContext.Writer != nil || commitContext.CommitID != 
InvalidCommitID
+}
+
+func isOutdatedFlowResponse(response subscriptionPollResponse) bool {
+       return response.Type == subscriptionResponseError && !response.Critical 
&&
+               (response.ErrorMessage == "outdated subscription event" || 
response.ErrorMessage == "过期的订阅事件")
+}
+
+func flowCriticalPollError(err error) bool {
+       var status *subscriptionStatusError
+       if errors.As(err, &status) {
+               return status.Critical
+       }
+       var payload *subscriptionPollError
+       return errors.As(err, &payload) && payload.Critical
+}
+
+func flowFatalPollError(err error) bool {
+       return errors.Is(err, ErrUnsupportedTsFile) || errors.Is(err, 
ErrConsumerFenced) || errors.Is(err, ErrOwnerFenced)
+}
+
+func (c *subscriptionPullConsumer) rollbackFlow(ctx context.Context, contexts 
[]CommitContext) {
+       if len(contexts) == 0 || ctx.Err() != nil || c.checkOpen() != nil {
+               return
+       }
+       // A failed cleanup never replaces the original poll error. In 
particular,
+       // NACK is not replayed when a transport failure schedules provider 
recovery.
+       _ = c.commitContexts(ctx, contexts, true)
+}
+
+func (c *subscriptionPullConsumer) completeFlowRecord(ctx context.Context, 
provider *subscriptionProvider, response subscriptionPollResponse) 
(SubscriptionMessage, bool, error) {
+       for response.NextOffset > 0 {
+               if err := ctx.Err(); err != nil {
+                       return nil, false, err
+               }
+               if err := c.checkOpen(); err != nil {
+                       return nil, false, err
+               }
+               pages, err := provider.pollTablets(ctx, response.CommitContext, 
response.NextOffset, flowRemainingMilliseconds(ctx, 1, false), 
int64(provider.bodyLimit))
+               if err != nil {
+                       return nil, false, err
+               }
+               if len(pages) == 0 {
+                       return nil, true, nil
+               }
+               if len(pages) != 1 {
+                       return nil, false, fmt.Errorf("subscription: tablet 
continuation returned %d responses", len(pages))
+               }
+               next := pages[0]
+               if isOutdatedFlowResponse(next) {
+                       return nil, true, nil
+               }
+               if next.Type == subscriptionResponseError {
+                       return nil, false, &subscriptionPollError{Message: 
next.ErrorMessage, Critical: next.Critical}
+               }
+               if next.NextOffset > 0 && next.NextOffset <= 
response.NextOffset {
+                       return nil, false, errors.New("subscription: tablet 
continuation offset did not advance")
+               }
+               if err := response.appendTablets(next); err != nil {
+                       return nil, false, err
+               }
+       }
+       message, err := response.message(c.config.Consumer.Dialect)
+       return message, false, err
+}
+
+func flowRemainingMilliseconds(ctx context.Context, providers int, immediate 
bool) int64 {
+       if immediate {
+               return 0
+       }
+       deadline, ok := ctx.Deadline()
+       if !ok {
+               return 0
+       }
+       remaining := time.Until(deadline)
+       if providers > 1 {
+               remaining /= time.Duration(providers)
+       }
+       if remaining <= 0 {
+               return 0
+       }
+       milliseconds := remaining.Milliseconds()
+       if remaining%time.Millisecond != 0 {
+               milliseconds++
+       }
+       return milliseconds
+}
diff --git a/subscription/pull_progress.go b/subscription/pull_progress.go
new file mode 100644
index 0000000..83aea81
--- /dev/null
+++ b/subscription/pull_progress.go
@@ -0,0 +1,594 @@
+/*
+ * 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"
+       "sort"
+       "time"
+)
+
+// subscriptionCommitKey includes every identity field without borrowing a
+// mutable Writer pointer, so accepted contexts remove exactly their delivery.
+type subscriptionCommitKey struct {
+       DataNodeID int32
+       RebootTimes int32
+       Topic string
+       GroupID string
+       CommitID int64
+       SeekGeneration int64
+       RegionID string
+       PhysicalTime int64
+       HasWriter bool
+       Writer WriterPosition
+}
+
+type subscriptionPendingCommit struct {
+       Context CommitContext
+       DeliveredAt time.Time
+}
+
+func subscriptionContextKey(value CommitContext) subscriptionCommitKey {
+       key := subscriptionCommitKey{
+               DataNodeID: value.DataNodeID,
+               RebootTimes: value.RebootTimes,
+               Topic: value.Topic,
+               GroupID: value.GroupID,
+               CommitID: value.CommitID,
+               SeekGeneration: value.SeekGeneration,
+               RegionID: value.RegionID,
+               PhysicalTime: value.PhysicalTime,
+       }
+       if value.Writer != nil {
+               key.HasWriter = true
+               key.Writer = *value.Writer
+       }
+       return key
+}
+
+func cloneCommitContexts(contexts []CommitContext) []CommitContext {
+       result := make([]CommitContext, len(contexts))
+       for index, commitContext := range contexts {
+               result[index] = cloneMessageCommitContext(commitContext)
+       }
+       return result
+}
+
+func cloneTopicProgress(progress TopicProgress) TopicProgress {
+       result := make(TopicProgress, len(progress))
+       for region, writers := range progress {
+               positions := make(RegionProgress, len(writers))
+               for writer, position := range writers {
+                       positions[writer] = position
+               }
+               result[region] = positions
+       }
+       return result
+}
+
+func (c *subscriptionPullConsumer) Commit(ctx context.Context, messages 
...SubscriptionMessage) error {
+       operationCtx, finish, err := c.linkContext(ctx)
+       if err != nil {
+               return err
+       }
+       defer finish()
+       contexts, err := c.messageCommitContexts(messages)
+       if err != nil {
+               return err
+       }
+       return c.commitContexts(operationCtx, contexts, false)
+}
+
+func (c *subscriptionPullConsumer) CommitAsync(ctx context.Context, messages 
...SubscriptionMessage) <-chan error {
+       result := make(chan error, 1)
+       operationCtx, finish, err := c.linkContext(ctx)
+       if err != nil {
+               result <- err
+               close(result)
+               return result
+       }
+       contexts, err := c.messageCommitContexts(messages)
+       if err != nil {
+               finish()
+               result <- err
+               close(result)
+               return result
+       }
+       go func() {
+               defer finish()
+               defer close(result)
+               result <- c.commitContexts(operationCtx, contexts, false)
+       }()
+       return result
+}
+
+func (c *subscriptionPullConsumer) messageCommitContexts(messages 
[]SubscriptionMessage) ([]CommitContext, error) {
+       c.mu.RLock()
+       groupID := c.identity.GroupID
+       c.mu.RUnlock()
+       contexts := make([]CommitContext, 0, len(messages))
+       seen := make(map[subscriptionCommitKey]struct{}, len(messages))
+       for _, message := range messages {
+               if message == nil {
+                       return nil, errors.New("subscription: cannot commit a 
nil message")
+               }
+               if record, ok := message.(*subscriptionMessage); ok && record 
== nil {
+                       return nil, errors.New("subscription: cannot commit a 
nil message")
+               }
+               if message.Kind() != RecordMessage {
+                       return nil, ErrIncompatibleMessage
+               }
+               commitContext := message.CommitContext()
+               if commitContext.Topic == "" || commitContext.GroupID != 
groupID {
+                       return nil, errors.New("subscription: message does not 
belong to this consumer group")
+               }
+               if !subscriptionContextCommittable(commitContext) {
+                       return nil, errors.New("subscription: message has no 
committable context")
+               }
+               key := subscriptionContextKey(commitContext)
+               if _, exists := seen[key]; !exists {
+                       seen[key] = struct{}{}
+                       contexts = append(contexts, 
cloneMessageCommitContext(commitContext))
+               }
+       }
+       return contexts, nil
+}
+
+func (c *subscriptionPullConsumer) acquireProgress(ctx context.Context) error {
+       if err := ctx.Err(); err != nil {
+               return err
+       }
+       select {
+       case c.progressOperations <- struct{}{}:
+               return nil
+       case <-ctx.Done():
+               return ctx.Err()
+       }
+}
+
+// commitContexts serializes acknowledgment responses with seek state changes,
+// but does not occupy the poll flow gate. A retry never repeats accepted 
entries.
+func (c *subscriptionPullConsumer) commitContexts(ctx context.Context, 
contexts []CommitContext, nack bool) error {
+       if err := c.acquireProgress(ctx); err != nil {
+               return err
+       }
+       defer func() { <-c.progressOperations }()
+       return c.commitContextsLocked(ctx, contexts, nack)
+}
+
+func (c *subscriptionPullConsumer) commitContextsLocked(ctx context.Context, 
contexts []CommitContext, nack bool) error {
+       groups := make(map[int32][]CommitContext)
+       seen := make(map[subscriptionCommitKey]struct{}, len(contexts))
+       for _, commitContext := range contexts {
+               if !subscriptionContextCommittable(commitContext) {
+                       continue
+               }
+               key := subscriptionContextKey(commitContext)
+               if _, exists := seen[key]; exists {
+                       continue
+               }
+               seen[key] = struct{}{}
+               groups[commitContext.DataNodeID] = 
append(groups[commitContext.DataNodeID], 
cloneMessageCommitContext(commitContext))
+       }
+       nodes := make([]int, 0, len(groups))
+       for node := range groups {
+               nodes = append(nodes, int(node))
+       }
+       sort.Ints(nodes)
+       var failures []error
+       for _, node := range nodes {
+               if err := c.commitNode(ctx, int32(node), groups[int32(node)], 
nack); err != nil {
+                       failures = append(failures, err)
+                       if errors.Is(err, context.Canceled) || errors.Is(err, 
context.DeadlineExceeded) ||
+                               errors.Is(err, ErrConsumerFenced) || 
errors.Is(err, ErrOwnerFenced) || subscriptionCriticalCommitError(err) {
+                               break
+                       }
+               }
+       }
+       return errors.Join(failures...)
+}
+
+func (c *subscriptionPullConsumer) commitNode(ctx context.Context, node int32, 
contexts []CommitContext, nack bool) error {
+       remaining := cloneCommitContexts(contexts)
+       var lastFailure error
+       for attempt := 0; len(remaining) != 0; attempt++ {
+               if err := ctx.Err(); err != nil {
+                       return err
+               }
+               c.mu.RLock()
+               stateErr := c.stateErrorLocked(true)
+               closing := c.closing || c.released
+               c.mu.RUnlock()
+               if stateErr != nil {
+                       return stateErr
+               }
+               provider := c.providerForNode(node)
+               var completed subscriptionCommitResult
+               var failure error
+               if provider == nil || provider.connection.isClosed() {
+                       failure = fmt.Errorf("subscription: no available 
provider for commit node %d", node)
+                       if !nack {
+                               c.stageRedirectAcks(remaining)
+                       }
+               } else {
+                       completed, failure = provider.commit(ctx, remaining, 
nack)
+                       if failure != nil {
+                               failure = c.handleProviderError(provider, 
failure)
+                       }
+               }
+               remaining = c.applyCommitResult(remaining, completed, nack)
+               if !nack && (provider == nil || provider.connection.isClosed()) 
{
+                       c.stageRedirectAcks(remaining)
+               }
+               if failure != nil {
+                       lastFailure = failure
+                       if errors.Is(failure, ErrOwnerFenced) || 
errors.Is(failure, ErrConsumerFenced) ||
+                               subscriptionCriticalCommitError(failure) || 
ctx.Err() != nil {
+                               return failure
+                       }
+                       var status *subscriptionStatusError
+                       if errors.As(failure, &status) && status.Code != 1920 {
+                               return failure
+                       }
+               }
+               if len(remaining) == 0 {
+                       return nil
+               }
+               c.mu.RLock()
+               closing = c.closing || c.released
+               c.mu.RUnlock()
+               if !closing && (provider == nil || 
provider.connection.isClosed()) {
+                       c.requestRecovery()
+               }
+               if nack || closing || attempt >= 3 {
+                       break
+               }
+               if provider == nil || provider.connection.isClosed() {
+                       if err := c.recoverProviders(ctx); err != nil {
+                               lastFailure = errors.Join(lastFailure, err)
+                               if errors.Is(err, ErrConsumerFenced) || 
errors.Is(err, ErrOwnerFenced) || ctx.Err() != nil {
+                                       return lastFailure
+                               }
+                       }
+               }
+               timer := time.NewTimer(time.Second)
+               select {
+               case <-timer.C:
+               case <-ctx.Done():
+                       timer.Stop()
+                       return ctx.Err()
+               }
+       }
+       return errors.Join(lastFailure, fmt.Errorf("subscription: commit 
accepted %d of %d contexts", len(contexts)-len(remaining), len(contexts)))
+}
+
+func subscriptionCriticalCommitError(err error) bool {
+       var status *subscriptionStatusError
+       if errors.As(err, &status) {
+               return status.Critical
+       }
+       var payload *subscriptionPollError
+       return errors.As(err, &payload) && payload.Critical
+}
+
+func (c *subscriptionPullConsumer) applyCommitResult(requested 
[]CommitContext, completed subscriptionCommitResult, nack bool) []CommitContext 
{
+       accepted := make(map[subscriptionCommitKey]struct{}, 
len(completed.Accepted))
+       for _, commitContext := range completed.Accepted {
+               accepted[subscriptionContextKey(commitContext)] = struct{}{}
+       }
+       c.mu.Lock()
+       defer c.mu.Unlock()
+       if !nack {
+               for topic, progress := range completed.Progress {
+                       mergeSubscriptionProgress(c.committed, topic, progress)
+               }
+       }
+       remaining := make([]CommitContext, 0, len(requested))
+       for _, commitContext := range requested {
+               key := subscriptionContextKey(commitContext)
+               if _, ok := accepted[key]; !ok {
+                       remaining = append(remaining, commitContext)
+                       continue
+               }
+               if !nack {
+                       delete(c.uncommitted, key)
+                       delete(c.redirectAcks, key)
+               }
+       }
+       return remaining
+}
+
+func (c *subscriptionPullConsumer) stageRedirectAcks(contexts []CommitContext) 
{
+       c.mu.Lock()
+       defer c.mu.Unlock()
+       for _, commitContext := range contexts {
+               if commitContext.Writer != nil && commitContext.RegionID != "" {
+                       c.redirectAcks[subscriptionContextKey(commitContext)] = 
cloneMessageCommitContext(commitContext)
+               }
+       }
+}
+
+func (c *subscriptionPullConsumer) flushRedirectAcks(ctx context.Context, 
messages []SubscriptionMessage) {
+       if err := c.acquireProgress(ctx); err != nil {
+               return
+       }
+       defer func() { <-c.progressOperations }()
+       if err := c.checkOpen(); err != nil {
+               return
+       }
+       type topicRegion struct { topic, region string }
+       targets := make(map[topicRegion]int32)
+       for _, message := range messages {
+               commitContext := message.CommitContext()
+               if commitContext.Writer != nil && commitContext.RegionID != "" {
+                       targets[topicRegion{commitContext.Topic, 
commitContext.RegionID}] = commitContext.DataNodeID
+               }
+       }
+       for target, node := range targets {
+               if ctx.Err() != nil || c.checkOpen() != nil {
+                       return
+               }
+               provider := c.providerForNode(node)
+               if provider == nil || provider.connection.isClosed() {
+                       continue
+               }
+               c.mu.RLock()
+               var contexts []CommitContext
+               for _, pending := range c.redirectAcks {
+                       if pending.Topic == target.topic && pending.RegionID == 
target.region {
+                               contexts = append(contexts, 
cloneMessageCommitContext(pending))
+                       }
+               }
+               c.mu.RUnlock()
+               if len(contexts) == 0 {
+                       continue
+               }
+               completed, err := provider.commit(ctx, contexts, false)
+               c.applyCommitResult(contexts, completed, false)
+               if err != nil {
+                       c.handleProviderError(provider, err)
+               }
+       }
+}
+
+func (c *subscriptionPullConsumer) trackDelivered(messages 
[]SubscriptionMessage) {
+       if c.config.AutoCommit == nil || !*c.config.AutoCommit {
+               return
+       }
+       now := time.Now()
+       c.mu.Lock()
+       defer c.mu.Unlock()
+       for _, message := range messages {
+               if message.Kind() != RecordMessage {
+                       continue
+               }
+               commitContext := message.CommitContext()
+               if !subscriptionContextCommittable(commitContext) {
+                       continue
+               }
+               key := subscriptionContextKey(commitContext)
+               if _, exists := c.uncommitted[key]; !exists {
+                       c.uncommitted[key] = subscriptionPendingCommit{Context: 
cloneMessageCommitContext(commitContext), DeliveredAt: now}
+               }
+       }
+}
+
+func (c *subscriptionPullConsumer) pendingCommitContexts(all bool, now 
time.Time) []CommitContext {
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       var contexts []CommitContext
+       for _, pending := range c.uncommitted {
+               if all || 
!now.Before(pending.DeliveredAt.Add(c.config.AutoCommitInterval)) {
+                       contexts = append(contexts, 
cloneMessageCommitContext(pending.Context))
+               }
+       }
+       return contexts
+}
+
+func (c *subscriptionPullConsumer) autoCommit(ctx context.Context, now 
time.Time) {
+       if c.config.AutoCommit == nil || !*c.config.AutoCommit {
+               return
+       }
+       if err := c.acquireProgress(ctx); err != nil {
+               return
+       }
+       defer func() { <-c.progressOperations }()
+       contexts := c.pendingCommitContexts(false, now)
+       if len(contexts) != 0 {
+               _ = c.commitContextsLocked(ctx, contexts, false)
+       }
+}
+
+func (c *subscriptionPullConsumer) advancePositions(messages 
[]SubscriptionMessage) {
+       c.mu.Lock()
+       defer c.mu.Unlock()
+       for _, message := range messages {
+               commitContext := message.CommitContext()
+               writer, progress, ok := 
subscriptionContextProgress(commitContext)
+               if ok {
+                       mergeSubscriptionProgress(c.positions, 
commitContext.Topic, TopicProgress{writer.RegionID: RegionProgress{writer: 
progress}})
+               }
+       }
+}
+
+func subscriptionContextCommittable(commitContext CommitContext) bool {
+       return commitContext.Writer != nil || commitContext.CommitID != 
InvalidCommitID
+}
+
+func subscriptionContextProgress(commitContext CommitContext) (WriterID, 
WriterProgress, bool) {
+       if commitContext.Writer != nil {
+               return commitContext.Writer.ID, commitContext.Writer.Progress, 
true
+       }
+       if commitContext.RegionID == "" || commitContext.CommitID < 0 {
+               return WriterID{}, WriterProgress{}, false
+       }
+       return WriterID{RegionID: commitContext.RegionID, NodeID: 
commitContext.DataNodeID},
+               WriterProgress{PhysicalTime: commitContext.PhysicalTime, 
LocalSeq: commitContext.CommitID}, true
+}
+
+func mergeSubscriptionProgress(target map[string]TopicProgress, topic string, 
progress TopicProgress) {
+       if topic == "" {
+               return
+       }
+       for _, writers := range progress {
+               for writer, next := range writers {
+                       if target[topic] == nil {
+                               target[topic] = make(TopicProgress)
+                       }
+                       if target[topic][writer.RegionID] == nil {
+                               target[topic][writer.RegionID] = 
make(RegionProgress)
+                       }
+                       previous, exists := 
target[topic][writer.RegionID][writer]
+                       if !exists || next.PhysicalTime > previous.PhysicalTime 
||
+                               (next.PhysicalTime == previous.PhysicalTime && 
next.LocalSeq > previous.LocalSeq) {
+                               target[topic][writer.RegionID][writer] = next
+                       }
+               }
+       }
+}
+
+func (c *subscriptionPullConsumer) Positions(topic string) (TopicProgress, 
error) {
+       name, err := parseSubscriptionIdentifier(topic)
+       if err != nil {
+               return nil, err
+       }
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       if err := c.stateErrorLocked(false); err != nil {
+               return nil, err
+       }
+       return cloneTopicProgress(c.positions[name]), nil
+}
+
+func (c *subscriptionPullConsumer) CommittedPositions(topic string) 
(TopicProgress, error) {
+       name, err := parseSubscriptionIdentifier(topic)
+       if err != nil {
+               return nil, err
+       }
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       if err := c.stateErrorLocked(false); err != nil {
+               return nil, err
+       }
+       return cloneTopicProgress(c.committed[name]), nil
+}
+
+func (c *subscriptionPullConsumer) SeekToBeginning(ctx context.Context, topic 
string) error {
+       return c.seekProgress(ctx, topic, subscriptionSeekBeginning, nil)
+}
+
+func (c *subscriptionPullConsumer) SeekToEnd(ctx context.Context, topic 
string) error {
+       return c.seekProgress(ctx, topic, subscriptionSeekEnd, nil)
+}
+
+func (c *subscriptionPullConsumer) Seek(ctx context.Context, topic string, 
progress TopicProgress) error {
+       return c.seekProgress(ctx, topic, subscriptionSeekProgress, progress)
+}
+
+func (c *subscriptionPullConsumer) SeekAfter(ctx context.Context, topic 
string, progress TopicProgress) error {
+       return c.seekProgress(ctx, topic, subscriptionSeekAfterProgress, 
progress)
+}
+
+func (c *subscriptionPullConsumer) seekProgress(ctx context.Context, topic 
string, kind int16, progress TopicProgress) error {
+       operationCtx, finish, err := c.beginOperation(ctx)
+       if err != nil {
+               return err
+       }
+       defer finish()
+       name, err := parseSubscriptionIdentifier(topic)
+       if err != nil {
+               return err
+       }
+       if err := c.validateProcessorReset(name); err != nil {
+               return err
+       }
+       if err := c.acquireProgress(operationCtx); err != nil {
+               return err
+       }
+       defer func() { <-c.progressOperations }()
+       progress = cloneTopicProgress(progress)
+       providers := c.providerSnapshot()
+       if !hasAvailableSubscriptionProvider(providers) {
+               if err := c.recoverProviders(operationCtx); err != nil {
+                       return err
+               }
+               providers = c.providerSnapshot()
+       }
+       available := 0
+       for _, provider := range providers {
+               if provider.connection.isClosed() {
+                       continue
+               }
+               available++
+               if err := provider.seek(operationCtx, name, kind, progress); 
err != nil {
+                       err = c.handleProviderError(provider, err)
+                       return err
+               }
+       }
+       if available == 0 {
+               return errors.New("subscription: no available provider for 
seek")
+       }
+       if err := operationCtx.Err(); err != nil {
+               return err
+       }
+       c.mu.Lock()
+       if err := c.stateErrorLocked(false); err != nil {
+               c.mu.Unlock()
+               return err
+       }
+       if kind == subscriptionSeekBeginning || kind == subscriptionSeekEnd {
+               delete(c.positions, name)
+               delete(c.committed, name)
+       } else {
+               overlaySubscriptionSeekProgress(c.positions, name, progress)
+               overlaySubscriptionSeekProgress(c.committed, name, progress)
+       }
+       for key := range c.uncommitted {
+               if key.Topic == name {
+                       delete(c.uncommitted, key)
+               }
+       }
+       for key := range c.redirectAcks {
+               if key.Topic == name {
+                       delete(c.redirectAcks, key)
+               }
+       }
+       c.mu.Unlock()
+       c.resetProcessors(name)
+       return nil
+}
+
+func overlaySubscriptionSeekProgress(target map[string]TopicProgress, topic 
string, progress TopicProgress) {
+       for region, writers := range progress {
+               if region == "" || len(writers) == 0 {
+                       continue
+               }
+               if target[topic] == nil {
+                       target[topic] = make(TopicProgress)
+               }
+               copy := make(RegionProgress, len(writers))
+               for writer, position := range writers {
+                       copy[writer] = position
+               }
+               target[topic][region] = copy
+       }
+}
diff --git a/subscription/pull_providers.go b/subscription/pull_providers.go
new file mode 100644
index 0000000..1992f6d
--- /dev/null
+++ b/subscription/pull_providers.go
@@ -0,0 +1,404 @@
+/*
+ * 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"
+       "sort"
+       "time"
+)
+
+func (c *subscriptionPullConsumer) requestRecovery() {
+       select {
+       case c.recovery <- struct{}{}:
+       default:
+       }
+}
+
+func (c *subscriptionPullConsumer) handleProviderError(provider 
*subscriptionProvider, failure error) error {
+       if failure == nil || errors.Is(failure, ErrUnsupportedTsFile) {
+               return failure
+       }
+       if errors.Is(failure, ErrConsumerFenced) {
+               c.mu.Lock()
+               current := c.providers[provider.dataNodeID] == provider
+               if current && c.fenced == nil {
+                       c.fenced = failure
+                       if c.lifeCancel != nil {
+                               c.lifeCancel()
+                       }
+                       if c.flowCancel != nil {
+                               c.flowCancel()
+                       }
+               }
+               fenced := c.fenced
+               c.mu.Unlock()
+               if !current && fenced == nil {
+                       _ = provider.connection.abort()
+                       c.requestRecovery()
+                       return fmt.Errorf("subscription: obsolete provider %s 
lost its connection", provider.endpoint)
+               }
+               return failure
+       }
+       if provider.connection.isClosed() {
+               c.requestRecovery()
+       }
+       return failure
+}
+
+func (c *subscriptionPullConsumer) providerConfig() SubscriptionConsumerConfig 
{
+       c.mu.RLock()
+       defer c.mu.RUnlock()
+       config := c.config.Consumer
+       config.ConsumerID = c.identity.ConsumerID
+       config.GroupID = c.identity.GroupID
+       return config
+}
+
+func (c *subscriptionPullConsumer) publishProvider(provider 
*subscriptionProvider, generation uint64) error {
+       c.mu.Lock()
+       if c.generation != generation || c.released || c.closing || c.fenced != 
nil {
+               failure := c.fenced
+               if failure == nil {
+                       failure = ErrClosed
+               }
+               c.mu.Unlock()
+               _ = provider.connection.abort()
+               return failure
+       }
+       if (c.identity.ConsumerID != "" && c.identity.ConsumerID != 
provider.consumerID) ||
+               (c.identity.GroupID != "" && c.identity.GroupID != 
provider.groupID) {
+               c.mu.Unlock()
+               _ = provider.connection.abort()
+               return errors.New("subscription: providers returned 
inconsistent consumer identities")
+       }
+       c.identity.ConsumerID = provider.consumerID
+       c.identity.GroupID = provider.groupID
+       previous := c.providers[provider.dataNodeID]
+       c.providers[provider.dataNodeID] = provider
+       c.endpoints[provider.dataNodeID] = provider.endpoint
+       c.mu.Unlock()
+       if previous != nil && previous != provider {
+               // Replacement must preserve the server-side consumer and 
subscriptions.
+               _ = previous.connection.abort()
+       }
+       return nil
+}
+
+// recoverProviders serializes discovery and replacement without taking the 
flow
+// gate. Foreground subscription/seek operations can request recovery while 
they
+// hold that gate; heartbeat callbacks never need it to publish endpoint 
changes.
+func (c *subscriptionPullConsumer) recoverProviders(ctx context.Context) error 
{
+       if err := ctx.Err(); err != nil {
+               return err
+       }
+       select {
+       case c.syncGate <- struct{}{}:
+               defer func() { <-c.syncGate }()
+       case <-ctx.Done():
+               return ctx.Err()
+       }
+       c.mu.RLock()
+       if c.released || c.closing || c.fenced != nil {
+               failure := c.fenced
+               if failure == nil {
+                       failure = ErrClosed
+               }
+               c.mu.RUnlock()
+               return failure
+       }
+       generation := c.generation
+       c.mu.RUnlock()
+       var failures []error
+       var discovered map[int32]string
+       for _, provider := range c.providerSnapshot() {
+               if provider.connection.isClosed() {
+                       continue
+               }
+               response, _, err := c.providerHeartbeat(ctx, provider)
+               if err == nil {
+                       discovered = response.Endpoints
+                       break
+               }
+               err = c.handleProviderError(provider, err)
+               if errors.Is(err, ErrConsumerFenced) || ctx.Err() != nil {
+                       return err
+               }
+               failures = append(failures, err)
+       }
+       if !hasAvailableSubscriptionProvider(c.providerSnapshot()) {
+               addresses := append([]string(nil), 
c.config.Consumer.Connection.NodeURLs...)
+               c.mu.RLock()
+               for _, address := range c.endpoints {
+                       addresses = append(addresses, address)
+               }
+               c.mu.RUnlock()
+               seen := make(map[string]bool)
+               for _, address := range addresses {
+                       if seen[address] {
+                               continue
+                       }
+                       seen[address] = true
+                       provider, err := openSubscriptionProvider(ctx, 
c.providerConfig(), address, c.instanceID)
+                       if err != nil {
+                               if errors.Is(err, ErrConsumerFenced) {
+                                       c.mu.Lock()
+                                       if c.fenced == nil && c.generation == 
generation {
+                                               c.fenced = err
+                                       }
+                                       c.mu.Unlock()
+                                       return err
+                               }
+                               failures = append(failures, 
fmt.Errorf("subscription: connect seed %s: %w", address, err))
+                               if ctx.Err() != nil {
+                                       return ctx.Err()
+                               }
+                               continue
+                       }
+                       if err := c.publishProvider(provider, generation); err 
!= nil {
+                               return err
+                       }
+                       response, _, err := c.providerHeartbeat(ctx, provider)
+                       if err == nil {
+                               discovered = response.Endpoints
+                               break
+                       }
+                       err = c.handleProviderError(provider, err)
+                       if errors.Is(err, ErrConsumerFenced) || ctx.Err() != 
nil {
+                               return err
+                       }
+                       failures = append(failures, err)
+                       if !provider.connection.isClosed() {
+                               break
+                       }
+               }
+       }
+       c.mu.RLock()
+       known := make(map[int32]string, len(c.endpoints))
+       for id, endpoint := range c.endpoints {
+               known[id] = endpoint
+       }
+       c.mu.RUnlock()
+       if len(discovered) != 0 {
+               known = discovered
+       }
+       ids := make([]int32, 0, len(known))
+       for id := range known {
+               ids = append(ids, id)
+       }
+       sort.Slice(ids, func(i, j int) bool { return ids[i] < ids[j] })
+       for _, id := range ids {
+               if err := ctx.Err(); err != nil {
+                       return err
+               }
+               previous := c.providerForNode(id)
+               if previous != nil && !previous.connection.isClosed() && 
previous.endpoint == known[id] {
+                       continue
+               }
+               provider, err := openSubscriptionProvider(ctx, 
c.providerConfig(), known[id], c.instanceID)
+               if err != nil {
+                       if errors.Is(err, ErrConsumerFenced) {
+                               c.mu.Lock()
+                               if c.fenced == nil && c.generation == 
generation {
+                                       c.fenced = err
+                                       if c.lifeCancel != nil {
+                                               c.lifeCancel()
+                                       }
+                               }
+                               c.mu.Unlock()
+                               return err
+                       }
+                       failures = append(failures, err)
+                       continue
+               }
+               if provider.dataNodeID != id {
+                       _ = provider.connection.abort()
+                       failures = append(failures, fmt.Errorf("subscription: 
endpoint %s returned DataNode %d instead of %d", known[id], 
provider.dataNodeID, id))
+                       continue
+               }
+               if err := c.publishProvider(provider, generation); err != nil {
+                       return err
+               }
+       }
+       if len(discovered) != 0 {
+               var stale []*subscriptionProvider
+               c.mu.Lock()
+               if c.generation == generation && !c.closing && !c.released {
+                       c.endpoints = known
+                       for id, provider := range c.providers {
+                               if _, exists := known[id]; !exists {
+                                       delete(c.providers, id)
+                                       stale = append(stale, provider)
+                               }
+                       }
+               }
+               c.mu.Unlock()
+               for _, provider := range stale {
+                       _ = provider.connection.abort()
+               }
+       }
+       if !hasAvailableSubscriptionProvider(c.providerSnapshot()) {
+               if len(failures) == 0 {
+                       return errors.New("subscription: no available 
subscription providers")
+               }
+               return errors.Join(failures...)
+       }
+       return nil
+}
+
+func (c *subscriptionPullConsumer) providerHeartbeat(ctx context.Context, 
provider *subscriptionProvider) (subscriptionHeartbeat, uint64, error) {
+       c.mu.RLock()
+       revision := c.topicRevision
+       contexts := make([]CommitContext, 0)
+       for _, commitContext := range c.bufferedContexts {
+               if commitContext.DataNodeID == provider.dataNodeID {
+                       contexts = append(contexts, 
cloneMessageCommitContext(commitContext))
+               }
+       }
+       c.mu.RUnlock()
+       heartbeatCtx, cancel := context.WithTimeout(ctx, 
c.config.Consumer.Connection.ConnectTimeout)
+       defer cancel()
+       response, err := provider.heartbeat(heartbeatCtx, contexts)
+       if err != nil {
+               // An expired wait for a busy provider's gate must not kill the 
healthy
+               // RPC that currently owns it. Actual RPC cancellation already 
aborts it.
+               if heartbeatCtx.Err() == nil {
+                       _ = provider.connection.abort()
+               }
+               return response, revision, err
+       }
+       c.mu.Lock()
+       if c.providers[provider.dataNodeID] == provider && 
!provider.connection.isClosed() && !c.released && !c.closing {
+               if c.topicRevision == revision {
+                       c.topics = response.Topics
+               } else {
+                       response.Unsubscribe = nil
+               }
+               for id, endpoint := range response.Endpoints {
+                       c.endpoints[id] = endpoint
+               }
+       } else {
+               response.Unsubscribe = nil
+       }
+       c.mu.Unlock()
+       return response, revision, nil
+}
+
+func (c *subscriptionPullConsumer) runHeartbeatScheduler() {
+       defer c.workers.Done()
+       ticker := time.NewTicker(c.config.Consumer.HeartbeatInterval)
+       defer ticker.Stop()
+       for {
+               select {
+               case <-c.lifeCtx.Done():
+                       return
+               case <-ticker.C:
+                       for _, provider := range c.providerSnapshot() {
+                               c.mu.Lock()
+                               if c.closing || c.released || c.fenced != nil 
|| c.heartbeatBusy[provider] || provider.connection.isClosed() {
+                                       c.mu.Unlock()
+                                       continue
+                               }
+                               c.heartbeatBusy[provider] = true
+                               c.workers.Add(1)
+                               c.mu.Unlock()
+                               go c.runProviderHeartbeat(provider)
+                       }
+               }
+       }
+}
+
+func (c *subscriptionPullConsumer) runProviderHeartbeat(provider 
*subscriptionProvider) {
+       defer c.workers.Done()
+       defer func() {
+               c.mu.Lock()
+               delete(c.heartbeatBusy, provider)
+               c.mu.Unlock()
+       }()
+       response, revision, err := c.providerHeartbeat(c.lifeCtx, provider)
+       if err != nil {
+               c.handleProviderError(provider, err)
+               return
+       }
+       if len(response.Unsubscribe) != 0 {
+               ctx, cancel := context.WithTimeout(c.lifeCtx, 
c.config.Consumer.Connection.ConnectTimeout)
+               defer cancel()
+               operationCtx, finish, err := c.beginOperation(ctx)
+               if err != nil {
+                       return
+               }
+               defer finish()
+               c.mu.RLock()
+               current := c.providers[provider.dataNodeID] == provider && 
c.topicRevision == revision
+               c.mu.RUnlock()
+               if current {
+                       _ = c.changeSubscriptions(operationCtx, 
response.Unsubscribe, true)
+               }
+       }
+}
+
+func (c *subscriptionPullConsumer) runEndpointSync() {
+       defer c.workers.Done()
+       ticker := time.NewTicker(c.config.Consumer.EndpointsSyncInterval)
+       defer ticker.Stop()
+       var lastRecovery time.Time
+       for {
+               select {
+               case <-c.lifeCtx.Done():
+                       return
+               case <-ticker.C:
+               case <-c.recovery:
+               }
+               if c.lifeCtx.Err() != nil {
+                       return
+               }
+               if delay := time.Until(lastRecovery.Add(5 * time.Second)); 
delay > 0 {
+                       timer := time.NewTimer(delay)
+                       select {
+                       case <-timer.C:
+                       case <-c.lifeCtx.Done():
+                               timer.Stop()
+                               return
+                       }
+               }
+               lastRecovery = time.Now()
+               _ = c.recoverProviders(c.lifeCtx)
+       }
+}
+
+func (c *subscriptionPullConsumer) runAutoCommit() {
+       defer c.workers.Done()
+       if !*c.config.AutoCommit {
+               return
+       }
+       ticker := time.NewTicker(c.config.AutoCommitInterval)
+       defer ticker.Stop()
+       for {
+               select {
+               case <-c.lifeCtx.Done():
+                       return
+               case now := <-ticker.C:
+                       ctx, cancel := context.WithTimeout(c.lifeCtx, 
c.config.Consumer.Connection.ConnectTimeout)
+                       c.autoCommit(ctx, now)
+                       cancel()
+               }
+       }
+}

Reply via email to