bitflicker64 commented on code in PR #525: URL: https://github.com/apache/hugegraph-doc/pull/525#discussion_r4261510701
########## content/en/docs/clients/restful-api/graphs.md: ########## @@ -660,6 +662,56 @@ 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. +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 canonical UUID `token` for each import, retain the returned `instance` and `epoch`, and acquire with `Content-Type: application/json`: Review Comment: Minor: "canonical UUID" leaves out that the Server accepts lowercase only. `LoadingMode.update` in apache/hugegraph#3331 checks `token.length() == 36 && UUID.fromString(token).toString().equals(token)`, and `UUID.toString()` is lowercase, so an uppercase token fails with "Loading owner token must be a canonical UUID". `uuidgen` on macOS prints uppercase, so a reader following this section by hand hits that error. Please say the token is a lowercase hyphenated UUID, here and in the CN sentence at line 682 ("标准 UUID"). ########## content/cn/docs/clients/restful-api/graphs.md: ########## @@ -655,6 +657,55 @@ 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` 枚举不能说明支持这些接口。 Review Comment: Minor: "该合同" translates the EN "this contract" with the word for a legal agreement. The rest of this section calls the same thing "owner 协议" (line 662, "owner 协议 1 接口"). Please use "该协议" here so the page uses one term for it. ########## content/en/docs/clients/restful-api/graphs.md: ########## @@ -660,6 +662,56 @@ 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. +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 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": "<instance UUID>", + "epoch": 0, + "token": "<import UUID>" +} +``` + +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. +Keep one handle for retries; Server checks its principal, instance and epoch. A released handle cannot acquire again. Review Comment: Minor: this paragraph does not say how a refused acquire is reported, and the Server reports it with `200`. In `LoadingMode.update` (apache/hugegraph#3331 at 4a42a77), an `acquire` for a handle that is not active and was already released, or carries an older epoch, returns `receipt(epoch, token, "released")` instead of throwing. A `release` for a handle the Server has never seen is also recorded, and a later `acquire` with it returns `released`. A client that checks only the HTTP status would import without holding ownership. Please state that an acquire succeeded only when the response has `state: "active"`, that `200` with `state: "released"` means the handle is finished (start again with a new token and a fresh GET for `instance` and `epoch`), and that releasing first cancels a later acquire. The CN paragraph at line 699 needs the same addition. ########## content/en/docs/quickstart/toolchain/hugegraph-loader.md: ########## @@ -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} + +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. Review Comment: Minor: "retry the REST release with the same handle" does not tell a command-line user where to find that handle. In apache/hugegraph-toolchain#815 at 63cfd76 the Loader does not log it on acquire; it appears only in the failure text from `LoadContext.unsetLoadingMode`, `Failed to release LOADING owner <instance>/<epoch>/<token>; retry the same handle`. Please say that the handle is printed in that error as `instance/epoch/token`, and link the REST section for the request body. The CN paragraph at line 1006 needs the same sentence. -- 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]
