bitflicker64 commented on code in PR #525: URL: https://github.com/apache/hugegraph-doc/pull/525#discussion_r4297100312
########## content/en/docs/clients/restful-api/graphs.md: ########## @@ -677,6 +679,83 @@ 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, current nonnegative epoch, and state revision: + +```json +{ + "protocol": 1, + "instance": "<instance UUID>", + "epoch": 0, + "revision": 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 Review Comment: Minor: This tells a client to GET a new epoch and acquire with a new token right after a `released` acquire receipt. The merged Server guidance says not to do that. `docs/server-runtime.md` on apache/hugegraph master (added by #3331) says the client must not refresh a retired handle automatically, because a new token could undo an earlier cancellation or an administrator `recover`; the import attempt must be stopped and drained first. The merged Loader agrees: `LoadingModeOwner.verify` throws on a `released` acquire receipt and never retries. Example: an administrator runs `recover` while a client acquire is in flight. That acquire returns `released`, and a client following this text acquires again on the graph that was just reset. Please say: stop and drain that import attempt, then start a new attempt with a fresh GET and a new token. This corrects my own earlier suggestion here. CN line 714 needs the same change. ########## content/en/docs/quickstart/toolchain/hugegraph-loader.md: ########## @@ -986,6 +989,42 @@ 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 concurrent import protection via the LOADING ownership protocol. Review Comment: Resolved by the upstream merges, not by a change here: apache/hugegraph#3331 merged as 0a3d0ab9b and apache/hugegraph-toolchain#815 as 50b1e193, so the `master` branches this page follows now carry the `mode/owners` code. 6.3.5 already says released packages and earlier 1.8 builds lack the protocol, so no extra caveat is needed. ########## content/cn/docs/clients/restful-api/graphs.md: ########## @@ -671,6 +673,77 @@ 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` 枚举不能说明支持这些接口。 Review Comment: Minor: This line drops part of the EN version limit. EN graphs.md line 686 says released packages and earlier 1.8 builds lack the protocol. This CN line only names older released packages, while the line above says the endpoints exist from 1.8.0. A CN reader running a 1.8.0 build made before apache/hugegraph#3331 merged is therefore told the endpoints exist, and the Loader then silently falls back to the legacy enum flow on the route-level 404. Please add the earlier-1.8-builds clause here so both languages state the same limit. ########## content/en/docs/quickstart/toolchain/hugegraph-loader.md: ########## @@ -986,6 +989,42 @@ 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 concurrent import protection via the LOADING ownership protocol. + +```mermaid +graph TD + A["Graph Mode: NONE"] -->|First Loader acquires owner| B["LOADING Mode (Acquires Token)"] + B -->|Concurrent Loaders join| B + B -->|Loader finishes & releases| B + B -->|Last Loader releases| C["Restores to NONE"] + B -.->|Abnormal exit / kill -9| D["Manual Recovery / Restart"] + D -.->|"Last owner released, or recover/restart"| A + D -.->|"Other owners still active"| B +``` + +1. **Probe and Acquire**: Loader probes `/mode/owners`. The first Loader obtains an ownership handle (`instance/epoch/token`), + transitioning graph mode from `NONE` to `LOADING`; concurrent Loaders can join. +2. **Data Import**: Loaders holding valid handles execute concurrent imports while preserving `LOADING` mode. +3. **Graceful Release**: When an import completes, Loader drains its workers and releases its handle. When the last owner releases, + graph mode automatically returns to `NONE`. +4. **Failure Recovery**: If abnormal exit (e.g. `kill -9`) leaves an orphaned owner, stop and drain all related imports and graph writes, + then perform administrator recovery via the [RESTful API recovery endpoint](/docs/clients/restful-api/graphs/#loading-ownership) or + restart the Server. Manual `release` applies only when the caller still holds its token (e.g. a direct REST client). +{.steps} + +> [!NOTE] +> **Compatibility and Operational Notes** +> - **Legacy Compatibility**: During ordinary imports, only an unsupported-route `404` status on `/mode/owners` falls back to the legacy enum +> `LOADING`/`NONE` flow (maintains compatibility with Server 1.7, without multi-loader protection). +> Network or permission errors, or a `404` for a missing graph, do not trigger fallback. +> - **Restore and Graph Source Imports**: Retain the `RESTORING` flow without ownership probes or automatic resets. After a restore import completes, Review Comment: Minor: This note says restore and graph-source imports retain the `RESTORING` flow, but it does not say that this flow fails while ordinary imports hold ownership. `LoadingMode.mode(GraphMode)` on apache/hugegraph master throws `ConflictException` while owners are active, and `GraphsAPI.mode` returns it as HTTP 409. `LoadContext.setRestoreMode` on Toolchain master sends the enum `PUT .../mode` with `RESTORING`, so a restore or graph-source import started next to a running owned import fails at startup. The Spark connector (`HGLoadContext.setLoadingMode`) and pre-1.8 Loaders use the same enum setter. graphs.md 6.3.5 states the rejection and Toolchain master `hugegraph-loader/README.md` warns about it, but a Loader reader only sees this note. Please add one sentence: do not run restore, graph-source, Spark connector or older Loader imports while owned imports are active. CN line 1015 needs it too. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
