imbajin commented on code in PR #525: URL: https://github.com/apache/hugegraph-doc/pull/525#discussion_r4297143402
########## 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: Updated both EN (line 723) and CN (line 714) to specify that the client must first stop and drain the import attempt before initiating a fresh GET and acquire request with a new token. ########## 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: Added the notice in both languages (EN line 1026, CN line 1018) stating that restore, graph-source, Spark connector, or older Loader imports must not be run while owned imports are active. -- 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]
