add pipe permission control specifications (#981)

Author: leto-bbq

src/UserGuide/Master/Tree/User-Manual/Data-Sync_apache.md

@@ -79,7 +79,7 @@ By declaratively configuring the specific content of the three parts through SQL
 
 ### 1.2 Functional limitations and instructions
 
-The schema and auth synchronization functions have the following limitations:
+1. The schema and auth synchronization functions have the following limitations:
 
 - When using schema synchronization, it is required that the consensus protocol for `Schema region` and `ConfigNode`  must be the default ratis protocol. This means that the `iotdb-system.properties` configuration file should contain the settings `config_node_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus` and `schema_region_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`. If these are not specified, the default ratis protocol is used.
 
@@ -89,6 +89,22 @@ The schema and auth synchronization functions have the following limitations:
 
 - During data synchronization tasks, please avoid performing any deletion operations to prevent inconsistent states between the two ends.
 
+2. Pipe Permission Control Specifications
+
+- When creating a pipe, a username and password can be specified for the extraction/write‑back plugins. If the password is incorrect, creation is prohibited. If not specified, the current user is used for synchronization by default.
+
+- During data/metadata synchronization, filtering is first performed according to the path pattern (pattern/path) configured in the Pipe, followed by authentication based on the user’s read permissions:
+    - If the permission scope is greater than or equal to the write path: full synchronization.
+    - If the permission scope has no intersection with the write path: no synchronization.
+    - If the permission scope is smaller than the write path or overlaps partially: synchronize only the intersecting part.
+
+- When encountering data for which the user lacks permission:
+    - If the sender’s skipIf=no‑privileges, the unauthorized data is skipped.
+    - If skipIf is left empty (unconfigured), the task reports an error (Error 803).
+    - Note: This skipIf configuration is independent of the receiver’s skipIf setting (which defaults to empty).
+
+- Data under root.__system and root.__audit will not be synchronized.
+
 ## 2. Usage Instructions
 
 Data synchronization tasks have three states: RUNNING, STOPPED, and DROPPED. The task state transitions are shown in the following diagram:

src/UserGuide/Master/Tree/User-Manual/Data-Sync_timecho.md

@@ -79,7 +79,7 @@ By declaratively configuring the specific content of the three parts through SQL
 
 ### 1.2 Functional limitations and instructions
 
-The schema and auth synchronization functions have the following limitations:
+1. The schema and auth synchronization functions have the following limitations:
 
 - When using schema synchronization, it is required that the consensus protocol for `Schema region` and `ConfigNode`  must be the default ratis protocol. This means that the `iotdb-system.properties` configuration file should contain the settings `config_node_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus` and `schema_region_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`. If these are not specified, the default ratis protocol is used.
 
@@ -91,6 +91,22 @@ The schema and auth synchronization functions have the following limitations:
 
 - During data synchronization tasks, please avoid performing any deletion operations to prevent inconsistent states between the two ends.
 
+2. Pipe Permission Control Specifications
+
+- When creating a pipe, a username and password can be specified for the extraction/write‑back plugins. If the password is incorrect, creation is prohibited. If not specified, the current user is used for synchronization by default.
+
+- During data/metadata synchronization, filtering is first performed according to the path pattern (pattern/path) configured in the Pipe, followed by authentication based on the user’s read permissions:
+    - If the permission scope is greater than or equal to the write path: full synchronization.
+    - If the permission scope has no intersection with the write path: no synchronization.
+    - If the permission scope is smaller than the write path or overlaps partially: synchronize only the intersecting part.
+
+- When encountering data for which the user lacks permission:
+    - If the sender’s skipIf=no‑privileges, the unauthorized data is skipped.
+    - If skipIf is left empty (unconfigured), the task reports an error (Error 803).
+    - Note: This skipIf configuration is independent of the receiver’s skipIf setting (which defaults to empty).
+
+- Data under root.__system and root.__audit will not be synchronized.
+
 ## 2. Usage Instructions
 
 Data synchronization tasks have three states: RUNNING, STOPPED, and DROPPED. The task state transitions are shown in the following diagram:

src/UserGuide/latest/User-Manual/Data-Sync_apache.md

@@ -79,7 +79,7 @@ By declaratively configuring the specific content of the three parts through SQL
 
 ### 1.2 Functional limitations and instructions
 
-The schema and auth synchronization functions have the following limitations:
+1. The schema and auth synchronization functions have the following limitations:
 
 - When using schema synchronization, it is required that the consensus protocol for `Schema region` and `ConfigNode`  must be the default ratis protocol. This means that the `iotdb-system.properties` configuration file should contain the settings `config_node_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus` and `schema_region_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`. If these are not specified, the default ratis protocol is used.
 
@@ -89,6 +89,22 @@ The schema and auth synchronization functions have the following limitations:
 
 - During data synchronization tasks, please avoid performing any deletion operations to prevent inconsistent states between the two ends.
 
+2. Pipe Permission Control Specifications
+
+- When creating a pipe, a username and password can be specified for the extraction/write‑back plugins. If the password is incorrect, creation is prohibited. If not specified, the current user is used for synchronization by default.
+
+- During data/metadata synchronization, filtering is first performed according to the path pattern (pattern/path) configured in the Pipe, followed by authentication based on the user’s read permissions:
+    - If the permission scope is greater than or equal to the write path: full synchronization.
+    - If the permission scope has no intersection with the write path: no synchronization.
+    - If the permission scope is smaller than the write path or overlaps partially: synchronize only the intersecting part.
+
+- When encountering data for which the user lacks permission:
+    - If the sender’s skipIf=no‑privileges, the unauthorized data is skipped.
+    - If skipIf is left empty (unconfigured), the task reports an error (Error 803).
+    - Note: This skipIf configuration is independent of the receiver’s skipIf setting (which defaults to empty).
+
+- Data under root.__system and root.__audit will not be synchronized.
+
 ## 2. Usage Instructions
 
 Data synchronization tasks have three states: RUNNING, STOPPED, and DROPPED. The task state transitions are shown in the following diagram:

src/UserGuide/latest/User-Manual/Data-Sync_timecho.md

@@ -79,7 +79,7 @@ By declaratively configuring the specific content of the three parts through SQL
 
 ### 1.2 Functional limitations and instructions
 
-The schema and auth synchronization functions have the following limitations:
+1. The schema and auth synchronization functions have the following limitations:
 
 - When using schema synchronization, it is required that the consensus protocol for `Schema region` and `ConfigNode`  must be the default ratis protocol. This means that the `iotdb-system.properties` configuration file should contain the settings `config_node_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus` and `schema_region_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`. If these are not specified, the default ratis protocol is used.
 
@@ -91,6 +91,22 @@ The schema and auth synchronization functions have the following limitations:
 
 - During data synchronization tasks, please avoid performing any deletion operations to prevent inconsistent states between the two ends.
 
+2. Pipe Permission Control Specifications
+
+- When creating a pipe, a username and password can be specified for the extraction/write‑back plugins. If the password is incorrect, creation is prohibited. If not specified, the current user is used for synchronization by default.
+
+- During data/metadata synchronization, filtering is first performed according to the path pattern (pattern/path) configured in the Pipe, followed by authentication based on the user’s read permissions:
+    - If the permission scope is greater than or equal to the write path: full synchronization.
+    - If the permission scope has no intersection with the write path: no synchronization.
+    - If the permission scope is smaller than the write path or overlaps partially: synchronize only the intersecting part.
+
+- When encountering data for which the user lacks permission:
+    - If the sender’s skipIf=no‑privileges, the unauthorized data is skipped.
+    - If skipIf is left empty (unconfigured), the task reports an error (Error 803).
+    - Note: This skipIf configuration is independent of the receiver’s skipIf setting (which defaults to empty).
+
+- Data under root.__system and root.__audit will not be synchronized.
+
 ## 2. Usage Instructions
 
 Data synchronization tasks have three states: RUNNING, STOPPED, and DROPPED. The task state transitions are shown in the following diagram:

src/zh/UserGuide/Master/Tree/User-Manual/Data-Sync_apache.md

@@ -78,7 +78,7 @@
 
 ### 1.2 功能限制及说明
 
-元数据（schema）、权限（auth）同步功能存在如下限制：
+1. 元数据（schema）、权限（auth）同步功能存在如下限制：
 
 - 使用元数据同步时，要求`Schema region`、`ConfigNode` 的共识协议必须为默认的 ratis 协议，即`iotdb-system.properties`配置文件中是否包含`config_node_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`、`schema_region_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`，不包含即为默认值ratis 协议。
 
@@ -88,6 +88,24 @@
 
 - 在进行数据同步任务时，请避免执行任何删除操作，防止两端状态不一致。
 
+2. Pipe 权限控制规范如下：
+
+- 创建 pipe 时，可以对抽取/写回插件指定用户名和密码。密码错误则禁止创建，未指定时默认使用当前用户进行同步。
+
+- 数据/元数据同步时，先根据 Pipe 配置的路径模式(pattern/path)筛选，再基于用户读取权限进行鉴权
+
+    - 权限范围≥写入路径：完整同步
+
+    - 权限范围与写入路径无交集：不同步
+
+    - 权限范围<写入路径或存在交集：同步交集部分
+
+- 遇到无权限数据时，若发送端 skipIf=no-privileges，则跳过无权限数据；若 skipIf 配置为空，任务报错（803错误）
+
+    - 注意：此 skipIf 配置与接收端的 skipIf（默认为空）相互独立
+
+- 对于 root.__system, root.__audit 均不会同步
+
 ## 2. 使用说明
 
 数据同步任务有三种状态：RUNNING、STOPPED 和 DROPPED。任务状态转换如下图所示：

src/zh/UserGuide/Master/Tree/User-Manual/Data-Sync_timecho.md

@@ -78,7 +78,7 @@
 
 ### 1.2 功能限制及说明
 
-元数据（schema）、权限（auth）同步功能存在如下限制：
+1. 元数据（schema）、权限（auth）同步功能存在如下限制：
 
 - 使用元数据同步时，要求`Schema region`、`ConfigNode` 的共识协议必须为默认的 ratis 协议，即`iotdb-system.properties`配置文件中是否包含`config_node_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`、`schema_region_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`，不包含即为默认值ratis 协议。
 
@@ -90,6 +90,24 @@
 
 - 在进行数据同步任务时，请避免执行任何删除操作，防止两端状态不一致。
 
+2. Pipe 权限控制规范如下：
+
+- 创建 pipe 时，可以对抽取/写回插件指定用户名和密码。密码错误则禁止创建，未指定时默认使用当前用户进行同步。
+
+- 数据/元数据同步时，先根据 Pipe 配置的路径模式(pattern/path)筛选，再基于用户读取权限进行鉴权
+
+  - 权限范围≥写入路径：完整同步
+
+  - 权限范围与写入路径无交集：不同步
+
+  - 权限范围<写入路径或存在交集：同步交集部分
+
+- 遇到无权限数据时，若发送端 skipIf=no-privileges，则跳过无权限数据；若 skipIf 配置为空，任务报错（803错误）
+
+  - 注意：此 skipIf 配置与接收端的 skipIf（默认为空）相互独立
+
+- 对于 root.__system, root.__audit 均不会同步
+
 ## 2. 使用说明
 
 数据同步任务有三种状态：RUNNING、STOPPED 和 DROPPED。任务状态转换如下图所示：

src/zh/UserGuide/latest/User-Manual/Data-Sync_apache.md

@@ -78,7 +78,7 @@
 
 ### 1.2 功能限制及说明
 
-元数据（schema）、权限（auth）同步功能存在如下限制：
+1. 元数据（schema）、权限（auth）同步功能存在如下限制：
 
 - 使用元数据同步时，要求`Schema region`、`ConfigNode` 的共识协议必须为默认的 ratis 协议，即`iotdb-system.properties`配置文件中是否包含`config_node_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`、`schema_region_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`，不包含即为默认值ratis 协议。
 
@@ -88,6 +88,24 @@
 
 - 在进行数据同步任务时，请避免执行任何删除操作，防止两端状态不一致。
 
+2. Pipe 权限控制规范如下：
+
+- 创建 pipe 时，可以对抽取/写回插件指定用户名和密码。密码错误则禁止创建，未指定时默认使用当前用户进行同步。
+
+- 数据/元数据同步时，先根据 Pipe 配置的路径模式(pattern/path)筛选，再基于用户读取权限进行鉴权
+
+    - 权限范围≥写入路径：完整同步
+
+    - 权限范围与写入路径无交集：不同步
+
+    - 权限范围<写入路径或存在交集：同步交集部分
+
+- 遇到无权限数据时，若发送端 skipIf=no-privileges，则跳过无权限数据；若 skipIf 配置为空，任务报错（803错误）
+
+    - 注意：此 skipIf 配置与接收端的 skipIf（默认为空）相互独立
+
+- 对于 root.__system, root.__audit 均不会同步
+
 ## 2. 使用说明
 
 数据同步任务有三种状态：RUNNING、STOPPED 和 DROPPED。任务状态转换如下图所示：

src/zh/UserGuide/latest/User-Manual/Data-Sync_timecho.md

@@ -78,7 +78,7 @@
 
 ### 1.2 功能限制及说明
 
-元数据（schema）、权限（auth）同步功能存在如下限制：
+1. 元数据（schema）、权限（auth）同步功能存在如下限制：
 
 - 使用元数据同步时，要求`Schema region`、`ConfigNode` 的共识协议必须为默认的 ratis 协议，即`iotdb-system.properties`配置文件中是否包含`config_node_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`、`schema_region_consensus_protocol_class=org.apache.iotdb.consensus.ratis.RatisConsensus`，不包含即为默认值ratis 协议。
 
@@ -90,6 +90,24 @@
 
 - 在进行数据同步任务时，请避免执行任何删除操作，防止两端状态不一致。
 
+2. Pipe 权限控制规范如下：
+
+- 创建 pipe 时，可以对抽取/写回插件指定用户名和密码。密码错误则禁止创建，未指定时默认使用当前用户进行同步。
+
+- 数据/元数据同步时，先根据 Pipe 配置的路径模式(pattern/path)筛选，再基于用户读取权限进行鉴权
+
+  - 权限范围≥写入路径：完整同步
+
+  - 权限范围与写入路径无交集：不同步
+
+  - 权限范围<写入路径或存在交集：同步交集部分
+
+- 遇到无权限数据时，若发送端 skipIf=no-privileges，则跳过无权限数据；若 skipIf 配置为空，任务报错（803错误）
+
+  - 注意：此 skipIf 配置与接收端的 skipIf（默认为空）相互独立
+
+- 对于 root.__system, root.__audit 均不会同步
+
 ## 2. 使用说明
 
 数据同步任务有三种状态：RUNNING、STOPPED 和 DROPPED。任务状态转换如下图所示：