docs(auth): mark group paths as the GraphSpace-format exception - #500
Merged
Merged
Conversation
Contributor
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
Update or clarify the group API examples to match GraphSpace-scoped IDs and behavior.
Review effort: Lite
Findings: None
What changed in this PR
This PR clarifies the version-specific group authentication paths in the English and Chinese REST API documentation.
Changes:
- Documents
/auth/groupsas the HugeGraph 1.7.0 exception. - Adds GraphSpace API context to both language versions.
| File | Summary |
|---|---|
content/en/docs/clients/restful-api/auth.md |
Adds English routing clarification. |
content/cn/docs/clients/restful-api/auth.md |
Adds Chinese routing clarification. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
imbajin
reviewed
Sep 25, 2026
imbajin
left a comment
imbajin
left a comment
Member
There was a problem hiding this comment.
Blocking: no. Summary: The versioned route distinction is correct, but the new 404 statement is unconditional and the later GraphSpace examples use legacy group IDs. Evidence: 1.7.0 AuthenticationFilter runs @PreMatching before route matching; GraphSpaceGroupAPI generates scoped group names.
Adarsh-Me
added a commit
to Adarsh-Me/hugegraph-doc
that referenced
this pull request
Sep 25, 2026
imbajin's review on apache#500 flagged two things and both are right. 1. The notice said the prefixed group path "returns 404" on 1.7.0. That route is unregistered there, but 404 is not unconditional: AuthenticationFilter is @Provider @PreMatching @priority(AUTHENTICATION), so it runs before route matching. Inside authenticate() a missing Authorization header throws NotAuthorizedException (401) and an IP outside the white list throws ForbiddenException (403); only when manager.requireAuthentication() is false does the filter return User.ANONYMOUS and leave routing to produce 404. Same code at 1.7.0 and at master, so the notice now says unregistered and names the condition. 2. The GraphSpace group examples still carried 1.5.x ids. JsonGroup build(graphSpace) persists scopedPrefix(graphSpace) + a dashless UUID, where scopedPrefix is "~hubble_role:v1:" + base64url(graphspace) + ":", and StandardAuthManagerV2.createGroup assigns id = IdGenerator.of(group.name()). A DEFAULT-space group is therefore addressed as ~hubble_role:v1:REVGQVVMVA:<32 hex>, and the request's group_name is only a client label: build() ignores it while checkCreate() requires it non-null. The five group examples now use the generated id, and the PUT body drops group_name because build(HugeGroup) rejects any other value with "The name of group can't be updated". Mirrored in Chinese, as the guide requires. Left alone deliberately: 10.5 and 10.6 embed the same legacy -69: group id inside belong/access ids. That is a second pass over two more sections and is worth its own change rather than being bundled here. Verified from source through the contents API at ref 1.7.0 and master: AuthenticationFilter.java, GraphSpaceGroupAPI.java, GroupAPI.java, StandardAuthManagerV2.java (SCOPED_GROUP_PREFIX, scopedGroupPrefix, isScopedGroup, createGroup) and HugeGroup.java. base64url("DEFAULT") = REVGQVVMVA computed rather than guessed, and the example hex is 32 chars to match isScopedGroup()'s [0-9a-f]{32}. Executed locally, the one CI step that needs no hugo: python3 -m unittest discover -s scripts -p 'test_*.py' = 166 tests with 8 failures + 14 errors, identical failing-name sets at this commit and at pristine HEAD, so this change is regression-neutral; those 22 are Windows path-separator asserts in the suite, not this text. dist/validate-links.sh is not trustworthy on this host (it flags 275 links, including ./auth from graphspace.md, as resolving outside content/), so the diff was checked differently: it adds and removes no markdown link syntax at all. Staged blobs re-checked at 0 CR bytes. Not verified: no hugo build, no Java and no Docker on this host, so no request was ever issued against a 1.7.0 or master server. The 401/403/404 ordering and the id shape are read from source, not observed. Refs: apache/hugegraph#3019
GroupAPI is mounted at /auth/groups on every version, and the
/graphspaces/{graphspace}/auth/groups form only exists from
apache/hugegraph#3096 onward, so on the 1.7.0 release the prefixed group
URL 404s while the page presents it as the 1.7.0+ spelling. Adds the
exception to the version notice and to the group section, in both
languages.
Refs: apache/hugegraph#3019
The previous note said GroupAPI is mounted at /auth/groups "in every version". That is wrong and it contradicts the 1.5.x line directly above it: at tags 1.2.0, 1.3.0 and 1.5.0 the class is @path("graphs/{graph}/auth/ groups"), i.e. prefixed with the graph name like the other auth APIs, and the unprefixed /auth/groups only appears at 1.7.0. GraphSpaceGroupAPI.java is absent at all of those refs, so no 1.5.x build serves the unprefixed form either. A reader on 1.5.x sent to /auth/groups by this page would hit a 404 - the same defect this PR exists to fix. Verified from source at each ref via the contents API, not inference: GroupAPI.java @path at 1.2.0/1.3.0/1.5.0 = graphs/{graph}/auth/groups, at 1.7.0/master = /auth/groups; GraphSpaceGroupAPI.java only at master. Tag 1.0.0 has no api/auth directory at that path, so the wording now names 1.5.x and 1.7.0 rather than generalising over every release. Not verified: no hugo build here (no hugo, Go 1.26 vs pinned 1.27.0, and scripts/hugo.sh needs python), so CI is the build check for this text.
imbajin's review on apache#500 flagged two things and both are right. 1. The notice said the prefixed group path "returns 404" on 1.7.0. That route is unregistered there, but 404 is not unconditional: AuthenticationFilter is @Provider @PreMatching @priority(AUTHENTICATION), so it runs before route matching. Inside authenticate() a missing Authorization header throws NotAuthorizedException (401) and an IP outside the white list throws ForbiddenException (403); only when manager.requireAuthentication() is false does the filter return User.ANONYMOUS and leave routing to produce 404. Same code at 1.7.0 and at master, so the notice now says unregistered and names the condition. 2. The GraphSpace group examples still carried 1.5.x ids. JsonGroup build(graphSpace) persists scopedPrefix(graphSpace) + a dashless UUID, where scopedPrefix is "~hubble_role:v1:" + base64url(graphspace) + ":", and StandardAuthManagerV2.createGroup assigns id = IdGenerator.of(group.name()). A DEFAULT-space group is therefore addressed as ~hubble_role:v1:REVGQVVMVA:<32 hex>, and the request's group_name is only a client label: build() ignores it while checkCreate() requires it non-null. The five group examples now use the generated id, and the PUT body drops group_name because build(HugeGroup) rejects any other value with "The name of group can't be updated". Mirrored in Chinese, as the guide requires. Left alone deliberately: 10.5 and 10.6 embed the same legacy -69: group id inside belong/access ids. That is a second pass over two more sections and is worth its own change rather than being bundled here. Verified from source through the contents API at ref 1.7.0 and master: AuthenticationFilter.java, GraphSpaceGroupAPI.java, GroupAPI.java, StandardAuthManagerV2.java (SCOPED_GROUP_PREFIX, scopedGroupPrefix, isScopedGroup, createGroup) and HugeGroup.java. base64url("DEFAULT") = REVGQVVMVA computed rather than guessed, and the example hex is 32 chars to match isScopedGroup()'s [0-9a-f]{32}. Executed locally, the one CI step that needs no hugo: python3 -m unittest discover -s scripts -p 'test_*.py' = 166 tests with 8 failures + 14 errors, identical failing-name sets at this commit and at pristine HEAD, so this change is regression-neutral; those 22 are Windows path-separator asserts in the suite, not this text. dist/validate-links.sh is not trustworthy on this host (it flags 275 links, including ./auth from graphspace.md, as resolving outside content/), so the diff was checked differently: it adds and removes no markdown link syntax at all. Staged blobs re-checked at 0 CR bytes. Not verified: no hugo build, no Java and no Docker on this host, so no request was ever issued against a 1.7.0 or master server. The 401/403/404 ordering and the id shape are read from source, not observed. Refs: apache/hugegraph#3019
Adarsh-Me
force-pushed
the
fix-3019-auth-groups-paths
branch
from
September 26, 2026 06:27
817d347 to
210b911
Compare
Contributor
Author
|
Rebased onto |
Contributor
Author
|
Correction on state, not on the diagnosis: the rebased head |
- Clarify version-specific group routes and 404 behavior. - Use GraphSpace group, target, belong, and access IDs. - URL-encode composite IDs in relationship paths. - Keep English and Chinese examples aligned.
- Set the Markdown editor line limit to 120 characters. - Reflow changed English and Chinese documentation lines. - Use response-ID placeholders for long relationship paths. - Record the Markdown line-length rule in AGENTS.md.
- Leave the repository Markdown line width unset. - Set new prose guidance to 160 characters in AGENTS.md. - Keep existing one-line paragraphs intact and tighten new notes. - Use response-ID placeholders for generated relationship paths.
- Link release-specific behavior to the 1.7 site docs. - Keep the current master versus 1.7 group routes clear. - Remove outdated 1.5 path and ID descriptions.
- Link release-specific behavior to the published 1.7 docs. - Explain master and 1.7 group routes in plain Chinese. - Replace unsupported internal links to fix source validation.
imbajin
approved these changes
Sep 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
content/{en,cn}/docs/clients/restful-api/auth.mdclaim "1.7.0+: Auth API paths use GraphSpace format" and then document the group endpoints as/graphspaces/DEFAULT/auth/groups. That spelling is wrong for the group API on 1.7.0 — which is exactly what apache/hugegraph#3019 reports as a 404.Verified against source, not folklore:
1.7.0masterUserAPI/TargetAPI/BelongAPI/AccessAPI/ManagerAPI/ProjectAPI@Path("graphspaces/{graphspace}/auth/…")GroupAPI@Path("/auth/groups")GraphSpaceGroupAPI@Path("graphspaces/{graphspace}/auth/groups")GraphSpaceGroupAPIarrived in apache/hugegraph#3096 (2026-07-21), andApplicationConfig.java:72mounts it viapackages("org.apache.hugegraph.api"), so on master both spellings are live but on 1.7.0 only/auth/groupsis. The page also already contradicts itself:quickstart/client/hugegraph-client-python.mdsays "groups stay at the server-level/auth/groups".The change adds the exception to the version notice and a note at the head of the group section, in both languages. Group URLs themselves are left as-is, since this page documents the development version where the prefixed route does exist.
Checklist (from
contribution.md)hugoinstalled, Go is 1.26 vs the pinned 1.27.0, andscripts/hugo.shadditionally needs Python, which this host does not have. CI is the build verification for this change.content/en/andcontent/cn/both updated/docs/...and/cn/docs/...unchanged (markdown content only)Question for maintainers
release-1.7.0carries the same prefixed group URLs, and that branch is what the archived 1.7 version on the site serves — so a 1.7.0 user gets the wrong spelling from the version they are actually running. Want a backport of this note torelease-1.7.0?AI use
Authored with an AI assistant (Qoder); every claim above was read out of the referenced source files at the stated refs rather than inferred.