docs: explain loader mode ownership

content/cn/docs/clients/restful-api/graphs.md

@@ -577,6 +577,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode
 
 > 合法的图模式包括：NONE，RESTORING，MERGING，LOADING
 
+存在活跃的 loading owner 时，此枚举 PUT 会拒绝所有模式修改，包括 `"LOADING"`。请先停止导入 worker，再释放其 owner。
+
 ##### Response Status
 
 ```javascript
@@ -655,6 +657,55 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode
 }
 ```
 
+#### 6.3.5 LOADING owner 管理 {#loading-ownership}
+
+自 HugeGraph 1.8.0 起提供 owner 协议 1 接口；Loader 需使用配套的 1.8.0 及以上版本客户端。
+旧版本发行包不包含该协议；仅支持 `LOADING` 枚举不能说明支持这些接口。
+启用鉴权时，两个接口沿用模式设置接口的权限要求，即图空间管理权限（`space`）或该图所有者权限，并校验 STATUS 写权限。
+Server 将句柄绑定到实际鉴权用户；token 本身不赋予权限。申请、释放和重试必须保持相同身份。
+
+```text
+GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners
+```
+
+`200` 能力响应包含图实例 UUID 和当前非负 epoch：
+
+```json
+{
+    "protocol": 1,
+    "instance": "<instance UUID>",
+    "epoch": 0
+}
+```
+
+每轮导入生成一个新的小写连字符 UUID（lowercase hyphenated UUID）作为 `token`，保留返回的 `instance` 和 `epoch`，通过以下请求申请，并设置 `Content-Type: application/json`：
+
+```text
+PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners
+```
+
+```json
+{
+    "action": "acquire",
+    "instance": "<instance UUID>",
+    "epoch": 0,
+    "token": "<import UUID>"
+}
+```
+
+只有响应中包含 `state: "active"` 时才表示申请成功；此时返回 `200` 并回显 `protocol`、`instance`、`epoch`、`token` 以及 `mode: "LOADING"`。
+若返回 `200` 但 `state: "released"`，说明该句柄已失效或已被提前取消，此时并未获得 owner 保护，必须重新通过 GET 获取新的 `instance` 和 `epoch` 并生成全新 token 重新申请。
+释放时将 `action` 设置为 `release`，句柄保持不变；响应中包含 `state: "released"` 和当前实际模式。未申请前直接调用释放会被记录，并导致后续使用该句柄的申请直接返回 `released`。
+重试保留同一句柄；Server 校验其鉴权身份、instance 和 epoch。已释放句柄不能再次申请。
+
+首个 owner 要求 `NONE`；其他 owner 共享由 owner 管理的 `LOADING`，最后一个释放后恢复 `NONE`。
+手动设置的 `LOADING`、`RESTORING` 和 `MERGING` 不会被接管；owner 活跃时，旧枚举 PUT 会拒绝模式修改。
+
+该协议保护同一 Server 上实际运行的图实例中的普通导入，句柄绑定到实际鉴权身份、instance 和 epoch。
+它不提供跨 Server 协调、数据写入隔离或自动过期。请使用固定的 Server 直连地址，在导入停止后释放。
+升级后的 Loader 仅在 owner 探测返回接口路由不受支持的 `404` 时回退到旧行为；其他错误仍失败。
+图数据源和恢复导入保留原有枚举模式行为，参见 [Loader 兼容与恢复说明](/cn/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership)。
+
 ### 6.4 Snapshot
 
 #### 6.4.1 创建快照

content/cn/docs/quickstart/toolchain/hugegraph-loader.md

@@ -28,6 +28,9 @@ HugeGraph-Loader 是 HugeGraph 的数据导入组件，能够将多种数据源
 > 
 > **测试指南**：如需在本地运行 Loader 测试，请参考 [工具链本地测试指南](/cn/docs/guides/toolchain-local-test)
 
+> **并发导入保护方案**：自 1.8.0 起，普通导入支持在同一 Server 实例上获取 owner 保护。
+> 旧版 Server 保持下文说明的原有导入行为。
+
 ### 2 获取 HugeGraph-Loader
 
 可以通过以下三种方式获取 HugeGraph-Loader：
@@ -982,6 +985,27 @@ bin/hugegraph-loader.sh \
 
 本例用独立的 `docs_smoke_person` 标签和 `docs_*` 属性，避免与预置的 `person` 样例数据冲突。成功时统计中应显示顶点写入成功数为 `2`、边写入成功数为 `0`。也可以在 Hubble 的 Gremlin 工作台查询 `g.V().hasLabel('docs_smoke_person').values('docs_name')`，结果应包含 `docs-smoke-alice` 和 `docs-smoke-bob`。
 
+#### 3.4.6 并发导入与 LOADING owner {#loading-ownership}
+
+自 1.8.0 版本起，Loader 支持并发导入模式所有权保护协议。
+
+升级后的 Loader 在普通导入时探测 `/mode/owners`；仅接口路由不受支持的 `404` 会回退到原来的枚举 `LOADING`/`NONE` 流程。
+这会保留 Server 1.7 等旧 Server 的行为，但不提供不同 Loader 进程之间的保护。
+权限、网络、无效响应和申请 owner 的错误不会触发回退。图数据源和恢复导入保留原有 `RESTORING` 流程，
+不探测 owner 能力，也不新增自动恢复 `NONE` 的行为。
+
+支持该协议的 Server 上，每轮普通导入保留一个 `instance`/`epoch`/`token` 句柄。首个 owner 从 `NONE` 启用 `LOADING`，
+其他 Loader 进程可加入该状态。一个导入结束时，其他 owner 仍活跃则保持 `LOADING`；最后一个 owner 释放后恢复 `NONE`。
+手动设置的 `LOADING`、`RESTORING` 和 `MERGING` 不会被接管；Schema 修改和 `--clear-all-data` 仍须单独协调。
+
+申请和释放应使用同一个 Server 直连地址与鉴权身份。owner 属于该 Server 上实际运行的图实例，
+不提供跨 Server 协调或普通数据写入隔离。导入停止后释放其原句柄；嵌入式调用方需要调用 `HugeGraphLoader.shutdown()` 关闭 Loader。
+
+释放失败时，错误信息会打印对应句柄（格式为 `instance/epoch/token`，如 `Failed to release LOADING owner <instance>/<epoch>/<token>`）。
+停止导入后，可通过相同鉴权身份调用 [RESTful API 释放接口](/cn/docs/clients/restful-api/graphs/#loading-ownership) 手动释放；shutdown 不保证自动重试。
+owner 不会自动过期。句柄丢失或 `kill -9` 后，先停止所有导入及其在途写入，再重新打开图或重启 Server。
+恢复不会撤销已有写入或 Schema/数据清理。Hubble 任务清理在后续版本中独立维护。
+
 ### 4 完整示例
 
 下面给出的是 hugegraph-loader 包中 example 目录下的例子。([GitHub 地址](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader/assembly/static/example/file))

content/en/docs/clients/restful-api/graphs.md

@@ -576,6 +576,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode
 
 > Allowed graph mode values are: NONE, RESTORING, MERGING, LOADING
 
+While loading owners are active, this enum PUT rejects all mode changes, including `"LOADING"`. Release the owners after their import workers stop.
+
 ##### Response Status
 
 ```javascript
@@ -660,6 +662,60 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode
 }
 ```
 
+#### 6.3.5 LOADING ownership {#loading-ownership}
+
+Starting with HugeGraph 1.8.0, the Server provides the protocol 1 endpoints for LOADING ownership;
+Loader integration requires a matching 1.8.0 or newer client.
+Released packages and earlier 1.8 builds lack this protocol. Support for the `LOADING` enum alone does not imply support for it.
+With authentication enabled, both endpoints use the mode setter's permissions: graph-space management (`space`) or graph ownership, with STATUS write
+authorization. Server binds the handle to the authenticated principal; a token grants no permission. Keep the same identity for acquire, release and retries.
+
+```text
+GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners
+```
+
+The `200` capability response contains the graph-instance UUID and current nonnegative epoch:
+
+```json
+{
+    "protocol": 1,
+    "instance": "<instance UUID>",
+    "epoch": 0
+}
+```
+
+Generate a new lowercase hyphenated UUID `token` for each import, retain the returned `instance` and `epoch`,
+and acquire with `Content-Type: application/json`:
+
+```text
+PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners
+```
+
+```json
+{
+    "action": "acquire",
+    "instance": "<instance UUID>",
+    "epoch": 0,
+    "token": "<import UUID>"
+}
+```
+
+An acquire succeeded only when the response returns `200` with `state: "active"`, echoing `protocol`, `instance`, `epoch`, `token`, and `mode: "LOADING"`.
+A `200` response with `state: "released"` means the handle is finished or was preemptively released; it does not grant ownership. In that case, start again
+with a fresh GET for `instance` and `epoch` and generate a new token.
+Release with `action: "release"` and the same handle; its response has `state: "released"` and the effective graph mode. Calling release before acquire is
+recorded and causes a subsequent acquire with that handle to return `released`.
+Keep one handle for retries; Server checks its principal, instance and epoch. A released handle cannot acquire again.
+
+The first owner requires `NONE`. Other owners share owner-managed `LOADING`; the last release restores `NONE`.
+Manually set `LOADING`, `RESTORING` and `MERGING` are not adopted. While owners are active, the legacy enum PUT rejects mode changes.
+
+This protects ordinary imports on one live Server graph instance, with the handle bound to its authenticated principal, instance and epoch.
+It provides no cross-Server coordination, data-write isolation or automatic expiry. Use a fixed direct Server endpoint and release after the import stops.
+The upgraded Loader falls back to old behavior only for an unsupported-route `404` from its ownership probe; other errors remain failures.
+Graph-source and restore imports retain their original enum-mode behavior. See
+[Loader compatibility and recovery](/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership).
+
 ### 6.4 Snapshot
 
 #### 6.4.1 Create a snapshot

content/en/docs/quickstart/toolchain/hugegraph-loader.md

@@ -27,6 +27,9 @@ It will be explained in detail below.
 
 > Note: HugeGraph-Loader requires HugeGraph Server service, please refer to [HugeGraph-Server Quick Start](/docs/quickstart/hugegraph/hugegraph-server) to download and start Server
 
+> **Concurrency protection:** starting with HugeGraph 1.8.0, ordinary imports acquire same-Server ownership protection.
+> Older Servers retain the legacy import behavior described below.
+
 > **Testing Guide**: For running HugeGraph-Loader tests locally, please refer to [HugeGraph Toolchain Local Testing Guide](/docs/guides/toolchain-local-test)
 
 ### 2 Get HugeGraph-Loader
@@ -986,6 +989,29 @@ bin/hugegraph-loader.sh \
 
 Expected result: two vertices and zero edges imported. This example uses dedicated schema names to avoid conflicts with a preloaded `person` label. In Hubble, run `g.V().hasLabel('docs_smoke_person').values('docs_name')` to confirm `docs-smoke-alice` and `docs-smoke-bob`.
 
+#### 3.4.6 Concurrent imports and LOADING ownership {#loading-ownership}
+
+Starting with HugeGraph 1.8.0, Loader supports the concurrent import LOADING ownership protocol.
+
+For ordinary imports, the upgraded Loader probes `/mode/owners`. Only a route-level unsupported `404` selects the original enum `LOADING`/`NONE` flow.
+That fallback preserves old-Server behavior, including Server 1.7, but provides no protection between separate Loader processes.
+Permission, network, invalid-response and acquisition errors do not trigger fallback. Graph-source and restore imports keep their existing `RESTORING`
+flow, without the ownership probe or a new automatic reset to `NONE`.
+
+On a supporting Server, each ordinary import retains one `instance`/`epoch`/`token` handle. The first owner requires `NONE` and enables `LOADING`;
+other Loader processes can join that owned state. One import finishing leaves `LOADING` while another owner remains; the last release restores `NONE`.
+Manual `LOADING`, `RESTORING` and `MERGING` are not adopted. Schema changes and `--clear-all-data` still need separate coordination.
+
+Use the same direct Server endpoint and authenticated identity for acquisition and release. Ownership belongs to that live graph instance;
+it does not coordinate across Servers or isolate ordinary data writes. Release the retained handle after its import has stopped.
+Embedded callers must close their Loader with `HugeGraphLoader.shutdown()`.
+
+If release fails, the failure message outputs the handle (`instance/epoch/token`, e.g., `Failed to release LOADING owner <instance>/<epoch>/<token>`).
+Stop the importer and retry the release manually via the [RESTful API release endpoint](/docs/clients/restful-api/graphs/#loading-ownership) with the
+same handle and authenticated identity; shutdown does not promise automatic retry.
+Owners have no automatic expiry. If the handle is lost or after `kill -9`, stop all imports and their in-flight writes before reopening the graph or
+restarting Server. Recovery does not undo writes or Schema/data cleanup. Hubble task cleanup is maintained independently in subsequent releases.
+
 ### 4 Complete example
 
 Given below is an example in the example directory of the hugegraph-loader package. ([GitHub address](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader/assembly/static/example/file))