From 505c1daf345a0486594086561aa73a43f5b9bb61 Mon Sep 17 00:00:00 2001 From: imbajin Date: Tue, 13 Oct 2026 12:03:25 +0800 Subject: [PATCH 1/4] docs: explain loader mode ownership - document protocol 1 and matching client/server requirements - describe fixed owner lifecycle and permissions - clarify abnormal exit recovery and deployment limits --- content/cn/docs/clients/restful-api/graphs.md | 48 ++++++++++++++++++ .../quickstart/toolchain/hugegraph-loader.md | 24 +++++++++ content/en/docs/clients/restful-api/graphs.md | 50 +++++++++++++++++++ .../quickstart/toolchain/hugegraph-loader.md | 27 ++++++++++ 4 files changed, 149 insertions(+) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 22a3e98ae..fe12b48c8 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/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,52 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode } ``` +#### 6.3.5 LOADING owner 管理 {#loading-ownership} + +实现 owner 协议 1 的 Server 提供以下接口。仅支持 `LOADING` 枚举不能说明支持这些接口。 +启用鉴权时，两个接口沿用模式设置接口的权限要求，即图空间管理权限（`space`）或该图所有者权限，并校验 STATUS 写权限。 +Server 将句柄绑定到实际鉴权用户；token 本身不赋予权限。申请、释放和重试必须保持相同身份。 + +```text +GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +`200` 能力响应包含图实例 UUID 和当前非负 epoch： + +```json +{ + "protocol": 1, + "instance": "", + "epoch": 0 +} +``` + +每轮导入生成一个新的标准 UUID 作为 `token`，保留返回的 `instance` 和 `epoch`，通过以下请求申请，并设置 `Content-Type: application/json`： + +```text +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +```json +{ + "action": "acquire", + "instance": "", + "epoch": 0, + "token": "" +} +``` + +确认申请成功时返回 `200`，回显 `protocol`、`instance`、`epoch` 和 `token`，并返回 `state: "active"` 和 `mode: "LOADING"`。 +释放时只把 `action` 改为 `release`，其他三项保持原值；响应的 `state` 为 `released`，`mode` 为当前实际模式。 +活跃句柄的重复申请与重复释放是幂等的。`200` 响应中的 `state` 若为 `released`，则不能视为申请成功。 +释放未知句柄会取消可能仍在途的申请。已释放句柄不能再次申请；申请结果不确定时，不要生成新句柄重试。 + +首个 owner 只能从 `NONE` 申请；其他 owner 可以共享由 owner 管理的 `LOADING`，最后一个活跃 owner 释放后恢复 `NONE`。 +申请会拒绝手动设置的 `LOADING`、`RESTORING` 和 `MERGING`；释放未知句柄不会改变这些手动模式。 + +状态保存在单个 Server 图实例的内存中，不提供跨 Server 协调、数据请求隔离或自动过期。请使用固定的 Server 直连地址。 +worker 关闭、释放失败和异常退出的处理参见 [Loader owner 与恢复说明](/cn/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership)。 + ### 6.4 Snapshot #### 6.4.1 创建快照 diff --git a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md index 8cdcd4eab..5362f855f 100644 --- a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md @@ -28,6 +28,9 @@ HugeGraph-Loader 是 HugeGraph 的数据导入组件，能够将多种数据源 > > **测试指南**：如需在本地运行 Loader 测试，请参考 [工具链本地测试指南](/cn/docs/guides/toolchain-local-test) +> 本文中的普通导入要求 Server 与 Client/Loader 都包含 [LOADING owner 协议 1](/cn/docs/clients/restful-api/graphs/#loading-ownership) 实现。 +> Client/Server 的常规 CRUD 兼容性不能替代这一能力要求。 + ### 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} + +请同时升级 Server 与 Client/Loader，使用包含 `/mode/owners` 协议 1 实现的版本；仅凭版本号或 Docker `latest` 标签不能确认该能力。 +Server 1.7 支持 `LOADING` 枚举，但没有 owner 接口。普通导入在能力缺失或无效时失败，不会回退到枚举模式 PUT 或 `NONE`。 +检查发生在 `--clear-all-data`、创建 Schema 和写入导入数据之前；`--create-graph` 可能先创建目标图。图数据源和恢复导入仍使用独立的 `RESTORING` 路径。 + +每个导入上下文固定使用一个 `instance`/`epoch`/`token` 句柄完成申请、重试与释放。首个 owner 只能从 `NONE` 申请并启用 `LOADING`， +其他 owner 可以加入由 owner 管理的 `LOADING`。一个导入结束时，其他 owner 仍活跃则保持 `LOADING`；最后一个 owner 释放后恢复 `NONE`。 +手动设置的 `LOADING`、`RESTORING` 或 `MERGING` 必须在没有活跃导入时先恢复为 `NONE`，再启动普通导入。 +owner 管理不会隔离多个导入之间的 Schema 修改或 `--clear-all-data`，这些操作需要单独协调。 + +整个导入过程应直连同一台稳定的 Server。owner 状态仅属于该 Server 上实际运行的图实例，不提供跨 Server 协调，普通数据请求也不按 owner 句柄隔离。 +导入期间不支持负载均衡地址、节点故障切换、图重载或 Server 重启。 + +清理时，Loader 先停止并等待自己的 worker 全部退出，再释放原句柄；申请可能已经生效但响应丢失时也使用同一句柄取消。 +worker 无法退出时会保留上下文与 owner，供后续再次关闭。嵌入式调用方需要调用 `HugeGraphLoader.shutdown()`。 +释放失败时会报告句柄；确认导入进程及其在途写入都已停止后，使用相同鉴权身份在同一图实例上重试释放。已释放句柄不能用于另一轮导入。 + +`kill -9` 无法执行清理，可能留下活跃 owner；没有租约或自动过期机制。如果记录的句柄丢失，先停止所有导入及其在途写入， +再重新打开图或重启 Server 以清除本地 owner 状态。重启不会撤销已经执行的数据或 Schema 清理。 + ### 4 完整示例 下面给出的是 hugegraph-loader 包中 example 目录下的例子。([GitHub 地址](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader/assembly/static/example/file)) diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 235ff454c..9cafcc4e9 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/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,54 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode } ``` +#### 6.3.5 LOADING ownership {#loading-ownership} + +Server builds implementing ownership protocol 1 expose the following endpoints. Support for the `LOADING` enum alone does not imply support for them. +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": "", + "epoch": 0 +} +``` + +Generate a new canonical 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": "", + "epoch": 0, + "token": "" +} +``` + +A confirmed acquisition returns `200`, echoing `protocol`, `instance`, `epoch` and `token`, with `state: "active"` and `mode: "LOADING"`. +Release with `action: "release"` and the identical tuple; the response has `state: "released"` and the effective graph mode. +Repeated acquire for an active handle and repeated release are idempotent. A `200` response with `state: "released"` does not confirm acquisition. +Releasing an unknown handle cancels a possibly delayed acquire. A released handle cannot acquire again; +never generate a new tuple to retry an uncertain acquire. + +The first owner can acquire only from `NONE`. Further owners can share owner-managed `LOADING`; the last active release restores `NONE`. +Acquisition rejects manually set `LOADING`, `RESTORING` and `MERGING`. An unknown-handle release leaves such a manual mode unchanged. + +State is held in memory by one Server graph instance, without cross-Server coordination, data-request fencing or automatic expiry. +Use a fixed direct Server endpoint. See [Loader ownership and recovery](/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership) for worker shutdown, +failed release and abnormal-exit recovery. + ### 6.4 Snapshot #### 6.4.1 Create a snapshot diff --git a/content/en/docs/quickstart/toolchain/hugegraph-loader.md b/content/en/docs/quickstart/toolchain/hugegraph-loader.md index fa94864b7..e32b72a6e 100644 --- a/content/en/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/en/docs/quickstart/toolchain/hugegraph-loader.md @@ -27,6 +27,10 @@ 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 +> Normal imports in this guide require Server and Client/Loader builds that implement +> [loading ownership protocol 1](/docs/clients/restful-api/graphs/#loading-ownership). +> General Client/Server CRUD compatibility does not satisfy this requirement. + > **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 +990,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} + +Upgrade both Server and Client/Loader to builds containing `/mode/owners` protocol 1; a version number or Docker `latest` tag alone does not confirm support. +Server 1.7 recognizes `LOADING` but has no ownership endpoint. Normal imports fail if the capability is absent or invalid, without falling back to enum +mode PUT or `NONE`. This check precedes `--clear-all-data`, Schema creation and import-data writes; `--create-graph` can create the target graph first. +Graph-source and restore imports continue to use their separate `RESTORING` path. + +Each load context keeps one `instance`/`epoch`/`token` handle for acquisition, retries and release. The first owner requires `NONE` and enables `LOADING`; +another owner can join that owned `LOADING` state. Finishing one import preserves `LOADING` while another owner is active; the last release restores `NONE`. +Manual `LOADING`, `RESTORING` or `MERGING` must be returned to `NONE` with no active imports before a normal import starts. +Ownership does not isolate Schema changes or `--clear-all-data` from other imports; coordinate these operations separately. + +Use one directly addressed, stable Server for the entire import. Ownership is local to that actual Server graph instance, with no cross-Server coordination +or owner fencing on ordinary data requests. Load balancers, node failover, graph reload and Server restart during import are unsupported. + +Cleanup stops and drains the Loader's workers before releasing its handle, including when acquisition may have succeeded but its response was lost. +If workers cannot terminate, the context and owner remain for a later shutdown attempt. Embedded callers must call `HugeGraphLoader.shutdown()`. +A failed release reports the handle; after stopping the importer and its in-flight writes, retry release on the same graph instance with the same +authenticated identity. Released handles cannot be reused for another import. + +`kill -9` can leave an owner active because it cannot run cleanup; there is no lease or automatic expiry. If the recorded handle is lost, stop all imports +and their in-flight writes before reopening the graph or restarting Server to discard local ownership. Restart does not undo data or Schema cleanup. + ### 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)) From 94c984b2bd72dae3a2234ef2b7df312f1b7a1e70 Mon Sep 17 00:00:00 2001 From: imbajin Date: Tue, 13 Oct 2026 14:12:36 +0800 Subject: [PATCH 2/4] docs: clarify proposed loader mode support - qualify owner protection as proposed and unreleased - pin paired Server and Client/Loader sources - explain restore capability checks and drained cleanup --- content/cn/docs/clients/restful-api/graphs.md | 7 +++++- .../quickstart/toolchain/hugegraph-loader.md | 18 +++++++++++---- content/en/docs/clients/restful-api/graphs.md | 7 +++++- .../quickstart/toolchain/hugegraph-loader.md | 22 +++++++++++++------ 4 files changed, 41 insertions(+), 13 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index fe12b48c8..2d9f3e1fd 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -659,7 +659,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode #### 6.3.5 LOADING owner 管理 {#loading-ownership} -实现 owner 协议 1 的 Server 提供以下接口。仅支持 `LOADING` 枚举不能说明支持这些接口。 +以下尚未发布的 owner 协议 1 接口要求使用包含 [Server #3331](https://github.com/apache/hugegraph/pull/3331) 的构建； +Loader 集成另需配套的 [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815)。 +已发布包、较早的 1.8 构建与当前 Apache master 不包含该合同；仅支持 `LOADING` 枚举不能说明支持这些接口。 启用鉴权时，两个接口沿用模式设置接口的权限要求，即图空间管理权限（`space`）或该图所有者权限，并校验 STATUS 写权限。 Server 将句柄绑定到实际鉴权用户；token 本身不赋予权限。申请、释放和重试必须保持相同身份。 @@ -700,6 +702,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners 首个 owner 只能从 `NONE` 申请；其他 owner 可以共享由 owner 管理的 `LOADING`，最后一个活跃 owner 释放后恢复 `NONE`。 申请会拒绝手动设置的 `LOADING`、`RESTORING` 和 `MERGING`；释放未知句柄不会改变这些手动模式。 +Loader 的图数据源和恢复导入会先检查协议 1，再通过枚举接口设置 `RESTORING`，不申请 `LOADING` owner。 +仅在模式 PUT 成功后，清理才会在 worker 全部退出后恢复 `NONE`；PUT 失败不会触发该重置。 + 状态保存在单个 Server 图实例的内存中，不提供跨 Server 协调、数据请求隔离或自动过期。请使用固定的 Server 直连地址。 worker 关闭、释放失败和异常退出的处理参见 [Loader owner 与恢复说明](/cn/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership)。 diff --git a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md index 5362f855f..c2d54bf5c 100644 --- a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md @@ -28,7 +28,9 @@ HugeGraph-Loader 是 HugeGraph 的数据导入组件，能够将多种数据源 > > **测试指南**：如需在本地运行 Loader 测试，请参考 [工具链本地测试指南](/cn/docs/guides/toolchain-local-test) -> 本文中的普通导入要求 Server 与 Client/Loader 都包含 [LOADING owner 协议 1](/cn/docs/clients/restful-api/graphs/#loading-ownership) 实现。 +> **尚未发布的导入保护方案**：[LOADING owner 协议 1](/cn/docs/clients/restful-api/graphs/#loading-ownership) 要求同时使用包含 +> [Server #3331](https://github.com/apache/hugegraph/pull/3331) 与 [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) 的构建。 +> 已发布包、较早的 1.8 构建与当前 Apache master 不包含该合同；下文下载和 master 构建命令不会选择这两份 PR 构建。 > Client/Server 的常规 CRUD 兼容性不能替代这一能力要求。 ### 2 获取 HugeGraph-Loader @@ -987,9 +989,17 @@ bin/hugegraph-loader.sh \ #### 3.4.6 并发导入与 LOADING owner {#loading-ownership} -请同时升级 Server 与 Client/Loader，使用包含 `/mode/owners` 协议 1 实现的版本；仅凭版本号或 Docker `latest` 标签不能确认该能力。 -Server 1.7 支持 `LOADING` 枚举，但没有 owner 接口。普通导入在能力缺失或无效时失败，不会回退到枚举模式 PUT 或 `NONE`。 -检查发生在 `--clear-all-data`、创建 Schema 和写入导入数据之前；`--create-graph` 可能先创建目标图。图数据源和恢复导入仍使用独立的 `RESTORING` 路径。 +此尚未发布的合同要求使用配套的 [Server #3331](https://github.com/apache/hugegraph/pull/3331) 与 +[Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) 构建。已审查的源码为 +[Server](https://github.com/apache/hugegraph/tree/257a6a7ac2867daf4567f0d1a050123a8ff651cb) 和 +[Client/Loader](https://github.com/apache/hugegraph-toolchain/tree/de942c5ebe9fd2bbd5b8776a3534b57aed6448bb)。 +已发布包、较早的 1.8 构建与当前 Apache master 不包含该合同；仅凭版本号或 Docker `latest` 标签不能确认该能力。 +Server 1.7 支持 `LOADING` 枚举，但没有 owner 接口。导入在能力缺失或无效时失败，不会回退到枚举模式 PUT 或 `NONE`。 +检查发生在 `--clear-all-data`、创建 Schema 和写入导入数据之前；`--create-graph` 可能先创建目标图。 + +图数据源和恢复导入也会先检查协议 1，再通过枚举接口设置 `RESTORING`，不申请 `LOADING` owner。 +仅在 `RESTORING` PUT 成功后，清理才会在停止并等待自己的 worker 全部退出后恢复 `NONE`；PUT 失败不会触发该重置。 +请单独协调这类导入与其他并发导入；此路径不提供跨 Server 锁。 每个导入上下文固定使用一个 `instance`/`epoch`/`token` 句柄完成申请、重试与释放。首个 owner 只能从 `NONE` 申请并启用 `LOADING`， 其他 owner 可以加入由 owner 管理的 `LOADING`。一个导入结束时，其他 owner 仍活跃则保持 `LOADING`；最后一个 owner 释放后恢复 `NONE`。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 9cafcc4e9..b68ceea99 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -664,7 +664,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode #### 6.3.5 LOADING ownership {#loading-ownership} -Server builds implementing ownership protocol 1 expose the following endpoints. Support for the `LOADING` enum alone does not imply support for them. +These proposed, unreleased endpoints require a build containing [Server #3331](https://github.com/apache/hugegraph/pull/3331). +Loader integration also requires [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815). +Released packages, earlier 1.8 builds and current Apache master lack this contract. 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. @@ -706,6 +708,9 @@ never generate a new tuple to retry an uncertain acquire. The first owner can acquire only from `NONE`. Further owners can share owner-managed `LOADING`; the last active release restores `NONE`. Acquisition rejects manually set `LOADING`, `RESTORING` and `MERGING`. An unknown-handle release leaves such a manual mode unchanged. +Loader graph-source and restore imports check protocol 1, then use the enum API for `RESTORING` without acquiring a `LOADING` owner. +After a successful mode PUT, their cleanup drains the workers before restoring `NONE`. A failed mode PUT does not trigger that reset. + State is held in memory by one Server graph instance, without cross-Server coordination, data-request fencing or automatic expiry. Use a fixed direct Server endpoint. See [Loader ownership and recovery](/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership) for worker shutdown, failed release and abnormal-exit recovery. diff --git a/content/en/docs/quickstart/toolchain/hugegraph-loader.md b/content/en/docs/quickstart/toolchain/hugegraph-loader.md index e32b72a6e..e898dde3d 100644 --- a/content/en/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/en/docs/quickstart/toolchain/hugegraph-loader.md @@ -27,9 +27,10 @@ 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 -> Normal imports in this guide require Server and Client/Loader builds that implement -> [loading ownership protocol 1](/docs/clients/restful-api/graphs/#loading-ownership). -> General Client/Server CRUD compatibility does not satisfy this requirement. +> **Proposed, unreleased import protection:** [loading ownership protocol 1](/docs/clients/restful-api/graphs/#loading-ownership) requires builds containing +> both [Server #3331](https://github.com/apache/hugegraph/pull/3331) and [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815). +> Released packages, earlier 1.8 builds and current Apache master do not contain this contract; the download and master-build instructions below do not +> select those PR builds. General Client/Server CRUD compatibility does not satisfy this requirement. > **Testing Guide**: For running HugeGraph-Loader tests locally, please refer to [HugeGraph Toolchain Local Testing Guide](/docs/guides/toolchain-local-test) @@ -992,10 +993,17 @@ Expected result: two vertices and zero edges imported. This example uses dedicat #### 3.4.6 Concurrent imports and LOADING ownership {#loading-ownership} -Upgrade both Server and Client/Loader to builds containing `/mode/owners` protocol 1; a version number or Docker `latest` tag alone does not confirm support. -Server 1.7 recognizes `LOADING` but has no ownership endpoint. Normal imports fail if the capability is absent or invalid, without falling back to enum -mode PUT or `NONE`. This check precedes `--clear-all-data`, Schema creation and import-data writes; `--create-graph` can create the target graph first. -Graph-source and restore imports continue to use their separate `RESTORING` path. +This proposed contract requires matching builds from [Server #3331](https://github.com/apache/hugegraph/pull/3331) and +[Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815). The reviewed sources are +[Server](https://github.com/apache/hugegraph/tree/257a6a7ac2867daf4567f0d1a050123a8ff651cb) and +[Client/Loader](https://github.com/apache/hugegraph-toolchain/tree/de942c5ebe9fd2bbd5b8776a3534b57aed6448bb). +Released packages, earlier 1.8 builds and current Apache master lack this contract. A version number or Docker `latest` tag alone does not confirm support. +Server 1.7 recognizes `LOADING` but has no ownership endpoint. Imports fail if the capability is absent or invalid, without falling back to enum mode PUT +or `NONE`. This check precedes `--clear-all-data`, Schema creation and import-data writes; `--create-graph` can create the target graph first. + +Graph-source and restore imports also check protocol 1 before setting `RESTORING` through the enum API. They do not acquire a `LOADING` +owner. After a successful `RESTORING` PUT, cleanup stops and drains their workers before restoring `NONE`; a failed PUT does not trigger that reset. +Coordinate these imports separately from concurrent imports; this path does not provide cross-Server locking. Each load context keeps one `instance`/`epoch`/`token` handle for acquisition, retries and release. The first owner requires `NONE` and enables `LOADING`; another owner can join that owned `LOADING` state. Finishing one import preserves `LOADING` while another owner is active; the last release restores `NONE`. From 4ff825ceabb5ee2533a77db3646182a38063edee Mon Sep 17 00:00:00 2001 From: imbajin Date: Tue, 13 Oct 2026 18:29:58 +0800 Subject: [PATCH 3/4] docs: narrow loader ownership contract - preserve old Server import behavior - scope ownership to ordinary imports - clarify manual owner-release recovery - keep Hubble cleanup in a separate change --- content/cn/docs/clients/restful-api/graphs.md | 20 ++++--- .../quickstart/toolchain/hugegraph-loader.md | 43 ++++++--------- content/en/docs/clients/restful-api/graphs.md | 21 ++++---- .../quickstart/toolchain/hugegraph-loader.md | 54 ++++++++----------- 4 files changed, 58 insertions(+), 80 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 2d9f3e1fd..6a1cefba2 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -694,19 +694,17 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners } ``` -确认申请成功时返回 `200`，回显 `protocol`、`instance`、`epoch` 和 `token`，并返回 `state: "active"` 和 `mode: "LOADING"`。 -释放时只把 `action` 改为 `release`，其他三项保持原值；响应的 `state` 为 `released`，`mode` 为当前实际模式。 -活跃句柄的重复申请与重复释放是幂等的。`200` 响应中的 `state` 若为 `released`，则不能视为申请成功。 -释放未知句柄会取消可能仍在途的申请。已释放句柄不能再次申请；申请结果不确定时，不要生成新句柄重试。 +确认申请成功时返回 `200`，回显 `protocol`、`instance`、`epoch` 和 `token`，并返回 `state: "active"` 与 `mode: "LOADING"`。 +释放时只把 `action` 改为 `release`，句柄保持不变；响应中包含 `state: "released"` 和当前实际模式。 +重试保留同一句柄；Server 校验其鉴权身份、instance 和 epoch。已释放句柄不能再次申请。 -首个 owner 只能从 `NONE` 申请；其他 owner 可以共享由 owner 管理的 `LOADING`，最后一个活跃 owner 释放后恢复 `NONE`。 -申请会拒绝手动设置的 `LOADING`、`RESTORING` 和 `MERGING`；释放未知句柄不会改变这些手动模式。 +首个 owner 要求 `NONE`；其他 owner 共享由 owner 管理的 `LOADING`，最后一个释放后恢复 `NONE`。 +手动设置的 `LOADING`、`RESTORING` 和 `MERGING` 不会被接管；owner 活跃时，旧枚举 PUT 会拒绝模式修改。 -Loader 的图数据源和恢复导入会先检查协议 1，再通过枚举接口设置 `RESTORING`，不申请 `LOADING` owner。 -仅在模式 PUT 成功后，清理才会在 worker 全部退出后恢复 `NONE`；PUT 失败不会触发该重置。 - -状态保存在单个 Server 图实例的内存中，不提供跨 Server 协调、数据请求隔离或自动过期。请使用固定的 Server 直连地址。 -worker 关闭、释放失败和异常退出的处理参见 [Loader owner 与恢复说明](/cn/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership)。 +该协议保护同一 Server 上实际运行的图实例中的普通导入，句柄绑定到实际鉴权身份、instance 和 epoch。 +它不提供跨 Server 协调、数据写入隔离或自动过期。请使用固定的 Server 直连地址，在导入停止后释放。 +升级后的 Loader 仅在 owner 探测返回接口路由不受支持的 `404` 时回退到旧行为；其他错误仍失败。 +图数据源和恢复导入保留原有枚举模式行为，参见 [Loader 兼容与恢复说明](/cn/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership)。 ### 6.4 Snapshot diff --git a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md index c2d54bf5c..735ca83bf 100644 --- a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md @@ -28,10 +28,9 @@ HugeGraph-Loader 是 HugeGraph 的数据导入组件，能够将多种数据源 > > **测试指南**：如需在本地运行 Loader 测试，请参考 [工具链本地测试指南](/cn/docs/guides/toolchain-local-test) -> **尚未发布的导入保护方案**：[LOADING owner 协议 1](/cn/docs/clients/restful-api/graphs/#loading-ownership) 要求同时使用包含 -> [Server #3331](https://github.com/apache/hugegraph/pull/3331) 与 [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) 的构建。 -> 已发布包、较早的 1.8 构建与当前 Apache master 不包含该合同；下文下载和 master 构建命令不会选择这两份 PR 构建。 -> Client/Server 的常规 CRUD 兼容性不能替代这一能力要求。 +> **尚未发布的并发保护方案**：普通导入需要配套的 [Server #3331](https://github.com/apache/hugegraph/pull/3331) 和 +> [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) 构建，才能获得同一 Server 上的 owner 保护。 +> 已发布包和当前 Apache master 尚无此保护；旧 Server 保持下文说明的原有导入行为。 ### 2 获取 HugeGraph-Loader @@ -989,32 +988,24 @@ bin/hugegraph-loader.sh \ #### 3.4.6 并发导入与 LOADING owner {#loading-ownership} -此尚未发布的合同要求使用配套的 [Server #3331](https://github.com/apache/hugegraph/pull/3331) 与 -[Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) 构建。已审查的源码为 -[Server](https://github.com/apache/hugegraph/tree/257a6a7ac2867daf4567f0d1a050123a8ff651cb) 和 -[Client/Loader](https://github.com/apache/hugegraph-toolchain/tree/de942c5ebe9fd2bbd5b8776a3534b57aed6448bb)。 -已发布包、较早的 1.8 构建与当前 Apache master 不包含该合同；仅凭版本号或 Docker `latest` 标签不能确认该能力。 -Server 1.7 支持 `LOADING` 枚举，但没有 owner 接口。导入在能力缺失或无效时失败，不会回退到枚举模式 PUT 或 `NONE`。 -检查发生在 `--clear-all-data`、创建 Schema 和写入导入数据之前；`--create-graph` 可能先创建目标图。 +此拟议功能需要配套的 [Server #3331](https://github.com/apache/hugegraph/pull/3331) 与 +[Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) 构建。仅凭版本号或 Docker `latest` 标签不能确认支持情况。 -图数据源和恢复导入也会先检查协议 1，再通过枚举接口设置 `RESTORING`，不申请 `LOADING` owner。 -仅在 `RESTORING` PUT 成功后，清理才会在停止并等待自己的 worker 全部退出后恢复 `NONE`；PUT 失败不会触发该重置。 -请单独协调这类导入与其他并发导入；此路径不提供跨 Server 锁。 +升级后的 Loader 在普通导入时探测 `/mode/owners`；仅接口路由不受支持的 `404` 会回退到原来的枚举 `LOADING`/`NONE` 流程。 +这会保留 Server 1.7 等旧 Server 的行为，但不提供不同 Loader 进程之间的保护。 +权限、网络、无效响应和申请 owner 的错误不会触发回退。图数据源和恢复导入保留原有 `RESTORING` 流程， +不探测 owner 能力，也不新增自动恢复 `NONE` 的行为。 -每个导入上下文固定使用一个 `instance`/`epoch`/`token` 句柄完成申请、重试与释放。首个 owner 只能从 `NONE` 申请并启用 `LOADING`， -其他 owner 可以加入由 owner 管理的 `LOADING`。一个导入结束时，其他 owner 仍活跃则保持 `LOADING`；最后一个 owner 释放后恢复 `NONE`。 -手动设置的 `LOADING`、`RESTORING` 或 `MERGING` 必须在没有活跃导入时先恢复为 `NONE`，再启动普通导入。 -owner 管理不会隔离多个导入之间的 Schema 修改或 `--clear-all-data`，这些操作需要单独协调。 +支持该协议的 Server 上，每轮普通导入保留一个 `instance`/`epoch`/`token` 句柄。首个 owner 从 `NONE` 启用 `LOADING`， +其他 Loader 进程可加入该状态。一个导入结束时，其他 owner 仍活跃则保持 `LOADING`；最后一个 owner 释放后恢复 `NONE`。 +手动设置的 `LOADING`、`RESTORING` 和 `MERGING` 不会被接管；Schema 修改和 `--clear-all-data` 仍须单独协调。 -整个导入过程应直连同一台稳定的 Server。owner 状态仅属于该 Server 上实际运行的图实例，不提供跨 Server 协调，普通数据请求也不按 owner 句柄隔离。 -导入期间不支持负载均衡地址、节点故障切换、图重载或 Server 重启。 +申请和释放应使用同一个 Server 直连地址与鉴权身份。owner 属于该 Server 上实际运行的图实例， +不提供跨 Server 协调或普通数据写入隔离。导入停止后释放其原句柄；嵌入式调用方需要调用 `HugeGraphLoader.shutdown()` 关闭 Loader。 -清理时，Loader 先停止并等待自己的 worker 全部退出，再释放原句柄；申请可能已经生效但响应丢失时也使用同一句柄取消。 -worker 无法退出时会保留上下文与 owner，供后续再次关闭。嵌入式调用方需要调用 `HugeGraphLoader.shutdown()`。 -释放失败时会报告句柄；确认导入进程及其在途写入都已停止后，使用相同鉴权身份在同一图实例上重试释放。已释放句柄不能用于另一轮导入。 - -`kill -9` 无法执行清理，可能留下活跃 owner；没有租约或自动过期机制。如果记录的句柄丢失，先停止所有导入及其在途写入， -再重新打开图或重启 Server 以清除本地 owner 状态。重启不会撤销已经执行的数据或 Schema 清理。 +释放失败时，停止导入后用同一句柄与鉴权身份重试 REST 释放；shutdown 不保证自动重试。 +owner 不会自动过期。句柄丢失或 `kill -9` 后，先停止所有导入及其在途写入，再重新打开图或重启 Server。 +恢复不会撤销已有写入或 Schema/数据清理。Hubble 任务清理属于独立的 [Hubble #814](https://github.com/apache/hugegraph-toolchain/pull/814) 修改。 ### 4 完整示例 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index b68ceea99..74b6b913a 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -700,20 +700,17 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners ``` A confirmed acquisition returns `200`, echoing `protocol`, `instance`, `epoch` and `token`, with `state: "active"` and `mode: "LOADING"`. -Release with `action: "release"` and the identical tuple; the response has `state: "released"` and the effective graph mode. -Repeated acquire for an active handle and repeated release are idempotent. A `200` response with `state: "released"` does not confirm acquisition. -Releasing an unknown handle cancels a possibly delayed acquire. A released handle cannot acquire again; -never generate a new tuple to retry an uncertain acquire. +Release with `action: "release"` and the same handle; its response has `state: "released"` and the effective graph mode. +Keep one handle for retries; Server checks its principal, instance and epoch. A released handle cannot acquire again. -The first owner can acquire only from `NONE`. Further owners can share owner-managed `LOADING`; the last active release restores `NONE`. -Acquisition rejects manually set `LOADING`, `RESTORING` and `MERGING`. An unknown-handle release leaves such a manual mode unchanged. +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. -Loader graph-source and restore imports check protocol 1, then use the enum API for `RESTORING` without acquiring a `LOADING` owner. -After a successful mode PUT, their cleanup drains the workers before restoring `NONE`. A failed mode PUT does not trigger that reset. - -State is held in memory by one Server graph instance, without cross-Server coordination, data-request fencing or automatic expiry. -Use a fixed direct Server endpoint. See [Loader ownership and recovery](/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership) for worker shutdown, -failed release and abnormal-exit recovery. +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 diff --git a/content/en/docs/quickstart/toolchain/hugegraph-loader.md b/content/en/docs/quickstart/toolchain/hugegraph-loader.md index e898dde3d..0fd6afff5 100644 --- a/content/en/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/en/docs/quickstart/toolchain/hugegraph-loader.md @@ -27,10 +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 -> **Proposed, unreleased import protection:** [loading ownership protocol 1](/docs/clients/restful-api/graphs/#loading-ownership) requires builds containing -> both [Server #3331](https://github.com/apache/hugegraph/pull/3331) and [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815). -> Released packages, earlier 1.8 builds and current Apache master do not contain this contract; the download and master-build instructions below do not -> select those PR builds. General Client/Server CRUD compatibility does not satisfy this requirement. +> **Proposed, unreleased concurrency protection:** ordinary imports gain same-Server ownership protection with matching +> [Server #3331](https://github.com/apache/hugegraph/pull/3331) and [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) builds. +> Released packages and current Apache master lack this 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) @@ -993,33 +992,26 @@ Expected result: two vertices and zero edges imported. This example uses dedicat #### 3.4.6 Concurrent imports and LOADING ownership {#loading-ownership} -This proposed contract requires matching builds from [Server #3331](https://github.com/apache/hugegraph/pull/3331) and -[Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815). The reviewed sources are -[Server](https://github.com/apache/hugegraph/tree/257a6a7ac2867daf4567f0d1a050123a8ff651cb) and -[Client/Loader](https://github.com/apache/hugegraph-toolchain/tree/de942c5ebe9fd2bbd5b8776a3534b57aed6448bb). -Released packages, earlier 1.8 builds and current Apache master lack this contract. A version number or Docker `latest` tag alone does not confirm support. -Server 1.7 recognizes `LOADING` but has no ownership endpoint. Imports fail if the capability is absent or invalid, without falling back to enum mode PUT -or `NONE`. This check precedes `--clear-all-data`, Schema creation and import-data writes; `--create-graph` can create the target graph first. - -Graph-source and restore imports also check protocol 1 before setting `RESTORING` through the enum API. They do not acquire a `LOADING` -owner. After a successful `RESTORING` PUT, cleanup stops and drains their workers before restoring `NONE`; a failed PUT does not trigger that reset. -Coordinate these imports separately from concurrent imports; this path does not provide cross-Server locking. - -Each load context keeps one `instance`/`epoch`/`token` handle for acquisition, retries and release. The first owner requires `NONE` and enables `LOADING`; -another owner can join that owned `LOADING` state. Finishing one import preserves `LOADING` while another owner is active; the last release restores `NONE`. -Manual `LOADING`, `RESTORING` or `MERGING` must be returned to `NONE` with no active imports before a normal import starts. -Ownership does not isolate Schema changes or `--clear-all-data` from other imports; coordinate these operations separately. - -Use one directly addressed, stable Server for the entire import. Ownership is local to that actual Server graph instance, with no cross-Server coordination -or owner fencing on ordinary data requests. Load balancers, node failover, graph reload and Server restart during import are unsupported. - -Cleanup stops and drains the Loader's workers before releasing its handle, including when acquisition may have succeeded but its response was lost. -If workers cannot terminate, the context and owner remain for a later shutdown attempt. Embedded callers must call `HugeGraphLoader.shutdown()`. -A failed release reports the handle; after stopping the importer and its in-flight writes, retry release on the same graph instance with the same -authenticated identity. Released handles cannot be reused for another import. - -`kill -9` can leave an owner active because it cannot run cleanup; there is no lease or automatic expiry. If the recorded handle is lost, stop all imports -and their in-flight writes before reopening the graph or restarting Server to discard local ownership. Restart does not undo data or Schema cleanup. +This proposed feature requires matching [Server #3331](https://github.com/apache/hugegraph/pull/3331) and +[Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) builds. A version label or Docker `latest` tag does not confirm support. + +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, stop the import and retry the REST release 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's task cleanup is a separate change in +[Hubble #814](https://github.com/apache/hugegraph-toolchain/pull/814). ### 4 Complete example From 019fb6e32939bed019410ddb539963128e224a49 Mon Sep 17 00:00:00 2001 From: imbajin Date: Wed, 14 Oct 2026 04:09:04 +0800 Subject: [PATCH 4/4] docs: clarify loading ownership acquisition and clean unreleased references --- content/cn/docs/clients/restful-api/graphs.md | 12 ++++++------ .../quickstart/toolchain/hugegraph-loader.md | 13 ++++++------- content/en/docs/clients/restful-api/graphs.md | 16 ++++++++++------ .../quickstart/toolchain/hugegraph-loader.md | 15 +++++++-------- 4 files changed, 29 insertions(+), 27 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 6a1cefba2..dbba3cad8 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -659,9 +659,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode #### 6.3.5 LOADING owner 管理 {#loading-ownership} -以下尚未发布的 owner 协议 1 接口要求使用包含 [Server #3331](https://github.com/apache/hugegraph/pull/3331) 的构建； -Loader 集成另需配套的 [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815)。 -已发布包、较早的 1.8 构建与当前 Apache master 不包含该合同；仅支持 `LOADING` 枚举不能说明支持这些接口。 +自 HugeGraph 1.8.0 起提供 owner 协议 1 接口；Loader 需使用配套的 1.8.0 及以上版本客户端。 +旧版本发行包不包含该协议；仅支持 `LOADING` 枚举不能说明支持这些接口。 启用鉴权时，两个接口沿用模式设置接口的权限要求，即图空间管理权限（`space`）或该图所有者权限，并校验 STATUS 写权限。 Server 将句柄绑定到实际鉴权用户；token 本身不赋予权限。申请、释放和重试必须保持相同身份。 @@ -679,7 +678,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners } ``` -每轮导入生成一个新的标准 UUID 作为 `token`，保留返回的 `instance` 和 `epoch`，通过以下请求申请，并设置 `Content-Type: application/json`： +每轮导入生成一个新的小写连字符 UUID（lowercase hyphenated UUID）作为 `token`，保留返回的 `instance` 和 `epoch`，通过以下请求申请，并设置 `Content-Type: application/json`： ```text PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners @@ -694,8 +693,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners } ``` -确认申请成功时返回 `200`，回显 `protocol`、`instance`、`epoch` 和 `token`，并返回 `state: "active"` 与 `mode: "LOADING"`。 -释放时只把 `action` 改为 `release`，句柄保持不变；响应中包含 `state: "released"` 和当前实际模式。 +只有响应中包含 `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`。 diff --git a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md index 735ca83bf..814f8db3d 100644 --- a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md @@ -28,9 +28,8 @@ HugeGraph-Loader 是 HugeGraph 的数据导入组件，能够将多种数据源 > > **测试指南**：如需在本地运行 Loader 测试，请参考 [工具链本地测试指南](/cn/docs/guides/toolchain-local-test) -> **尚未发布的并发保护方案**：普通导入需要配套的 [Server #3331](https://github.com/apache/hugegraph/pull/3331) 和 -> [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) 构建，才能获得同一 Server 上的 owner 保护。 -> 已发布包和当前 Apache master 尚无此保护；旧 Server 保持下文说明的原有导入行为。 +> **并发导入保护方案**：自 1.8.0 起，普通导入支持在同一 Server 实例上获取 owner 保护。 +> 旧版 Server 保持下文说明的原有导入行为。 ### 2 获取 HugeGraph-Loader @@ -988,8 +987,7 @@ bin/hugegraph-loader.sh \ #### 3.4.6 并发导入与 LOADING owner {#loading-ownership} -此拟议功能需要配套的 [Server #3331](https://github.com/apache/hugegraph/pull/3331) 与 -[Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) 构建。仅凭版本号或 Docker `latest` 标签不能确认支持情况。 +自 1.8.0 版本起，Loader 支持并发导入模式所有权保护协议。 升级后的 Loader 在普通导入时探测 `/mode/owners`；仅接口路由不受支持的 `404` 会回退到原来的枚举 `LOADING`/`NONE` 流程。 这会保留 Server 1.7 等旧 Server 的行为，但不提供不同 Loader 进程之间的保护。 @@ -1003,9 +1001,10 @@ bin/hugegraph-loader.sh \ 申请和释放应使用同一个 Server 直连地址与鉴权身份。owner 属于该 Server 上实际运行的图实例， 不提供跨 Server 协调或普通数据写入隔离。导入停止后释放其原句柄；嵌入式调用方需要调用 `HugeGraphLoader.shutdown()` 关闭 Loader。 -释放失败时，停止导入后用同一句柄与鉴权身份重试 REST 释放；shutdown 不保证自动重试。 +释放失败时，错误信息会打印对应句柄（格式为 `instance/epoch/token`，如 `Failed to release LOADING owner //`）。 +停止导入后，可通过相同鉴权身份调用 [RESTful API 释放接口](/cn/docs/clients/restful-api/graphs/#loading-ownership) 手动释放；shutdown 不保证自动重试。 owner 不会自动过期。句柄丢失或 `kill -9` 后，先停止所有导入及其在途写入，再重新打开图或重启 Server。 -恢复不会撤销已有写入或 Schema/数据清理。Hubble 任务清理属于独立的 [Hubble #814](https://github.com/apache/hugegraph-toolchain/pull/814) 修改。 +恢复不会撤销已有写入或 Schema/数据清理。Hubble 任务清理在后续版本中独立维护。 ### 4 完整示例 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 74b6b913a..d494b4bb3 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -664,9 +664,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode #### 6.3.5 LOADING ownership {#loading-ownership} -These proposed, unreleased endpoints require a build containing [Server #3331](https://github.com/apache/hugegraph/pull/3331). -Loader integration also requires [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815). -Released packages, earlier 1.8 builds and current Apache master lack this contract. Support for the `LOADING` enum alone does not imply support for it. +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. @@ -684,7 +684,8 @@ The `200` capability response contains the graph-instance UUID and current nonne } ``` -Generate a new canonical UUID `token` for each import, retain the returned `instance` and `epoch`, and acquire with `Content-Type: application/json`: +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 @@ -699,8 +700,11 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners } ``` -A confirmed acquisition returns `200`, echoing `protocol`, `instance`, `epoch` and `token`, with `state: "active"` and `mode: "LOADING"`. -Release with `action: "release"` and the same handle; its response has `state: "released"` and the effective graph mode. +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`. diff --git a/content/en/docs/quickstart/toolchain/hugegraph-loader.md b/content/en/docs/quickstart/toolchain/hugegraph-loader.md index 0fd6afff5..3b74508ae 100644 --- a/content/en/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/en/docs/quickstart/toolchain/hugegraph-loader.md @@ -27,9 +27,8 @@ 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 -> **Proposed, unreleased concurrency protection:** ordinary imports gain same-Server ownership protection with matching -> [Server #3331](https://github.com/apache/hugegraph/pull/3331) and [Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) builds. -> Released packages and current Apache master lack this protection. Older Servers retain the legacy import behavior described below. +> **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) @@ -992,8 +991,7 @@ Expected result: two vertices and zero edges imported. This example uses dedicat #### 3.4.6 Concurrent imports and LOADING ownership {#loading-ownership} -This proposed feature requires matching [Server #3331](https://github.com/apache/hugegraph/pull/3331) and -[Client/Loader #815](https://github.com/apache/hugegraph-toolchain/pull/815) builds. A version label or Docker `latest` tag does not confirm support. +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. @@ -1008,10 +1006,11 @@ Use the same direct Server endpoint and authenticated identity for acquisition a 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, stop the import and retry the REST release with the same handle and authenticated identity; shutdown does not promise automatic retry. +If release fails, the failure message outputs the handle (`instance/epoch/token`, e.g., `Failed to release LOADING owner //`). +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's task cleanup is a separate change in -[Hubble #814](https://github.com/apache/hugegraph-toolchain/pull/814). +restarting Server. Recovery does not undo writes or Schema/data cleanup. Hubble task cleanup is maintained independently in subsequent releases. ### 4 Complete example