[Bug] Client UserAPI falls back to an incompatible auth path on Server 1.5

[looksaw2]

Bug Type (问题类型)

rest-api (结果不合预期)

Before submit

• I had searched in the issues and found no similar issues.

Environment (环境信息)

• HugeGraph Server: 1.5.0 (Core 1.5.0, REST API 0.71.0.0)
• Reproduction Hubble/Toolchain baseline: 60df3c51 (before the compatibility changes)
• Current upstream PR target: be7ef3a
• Authentication: StandardAuthenticator enabled
• Deployment: standalone, DEFAULT / hugegraph
• OS: macOS
• Browser: Google Chrome
• Data size: not data-dependent

Expected & Actual behavior (期望与实际表现)

When the current Java Client connects to an authentication-enabled HugeGraph Server 1.5, AuthManager creates UserAPI with the GraphSpace-scoped path. Because Server 1.5 does not support GraphSpace, RestClient removes the graphspaces/DEFAULT/ prefix and sends the request to /auth/users. Server 1.5 instead requires /graphs/{graph}/auth/users, and that legacy endpoint returns a users wrapper.

As a result, user lookup fails even when the supplied Basic credentials are valid. The Hubble screenshots below show the broader user-visible login symptom; this issue is intentionally scoped to the Java Client UserAPI path and response handling. Full Hubble login compatibility should be handled separately.

Steps to reproduce

1. Start HugeGraph Server 1.5.0 with StandardAuthenticator enabled.
2. Confirm GET /versions reports Core 1.5.0.
3. Confirm the test credentials are accepted by GET /graphs/hugegraph/auth/users?name=<user>.
4. Create a current pre-fix HugeClient for DEFAULT / hugegraph.
5. Call client.auth().getUser(<existing-user>).
6. Observe that the client falls back to /auth/users instead of /graphs/hugegraph/auth/users, so the lookup fails.

Before evidence

Step 1: Open the Hubble login page

Step 2: Enter credentials already verified against the Server 1.5 graph-scoped auth endpoint

Step 3: Submit the login form

Actual behavior

The legacy server request is routed to the unscoped /auth/users endpoint and user lookup fails. In Hubble this surfaces as Request failed: Failed to login HugeGraph Server.

Expected behavior

When GraphSpace is unsupported and a graph name is available, UserAPI should use /graphs/{graph}/auth/users and read the legacy users response wrapper. The existing GraphSpace-scoped behavior for modern servers should remain unchanged.

Proposed focused fix

• Add a graph-aware legacy auth path in the Java Client.
• Use it only when GraphSpace is unsupported and a graph name is present.
• Parse the Server 1.5 users wrapper in UserAPI.getByName().
• Add regression tests for both legacy and modern paths.

Vertex/Edge example (问题点 / 边数据举例)

N/A — this issue is not dependent on vertex or edge data.

Schema [VertexLabel, EdgeLabel, IndexLabel] (元数据结构)

N/A — this issue is caused by authentication endpoint compatibility, not graph schema.

[dosubot]

Good bug report — I've traced through the relevant code and can confirm the root cause and a precise fix path.

Root cause

HugeClient.checkServerApiVersion() sets supportGs to false for any server with Core < 1.7.0 [1]:

boolean supportGs = VersionUtil.gte(this.version.getCoreVersion(), "1.7.0");
this.client.setSupportGs(supportGs);

When supportGs is false, every REST call strips the graphspaces/DEFAULT/ prefix [2]:

private static String removeDefaultGsPrefix(String path) {
    final String DEFAULT_GS_PATH_PREFIX = "graphspaces/DEFAULT/";
    return path.replaceFirst(DEFAULT_GS_PATH_PREFIX, EMPTY);
}

AuthAPI builds its path as graphspaces/%s/auth/%s [3], so after prefix removal the resolved path becomes /auth/users. But Server 1.5 requires /graphs/{graph}/auth/users — that legacy graph-scoped path simply doesn't exist in the current AuthAPI.

Additionally, UserAPI has no getByName() method [4], so the Server 1.5 users wrapper response can't be parsed either.

Why graph is lost

AuthManager accepts graph in its constructor but never forwards it to UserAPI — it only passes graphSpace [5]:

public AuthManager(RestClient client, String graphSpace, String graph) {
    ...
    this.userAPI = new UserAPI(client, graphSpace);
    ...
}

On the Hubble side, HugeClientUtil.tryConnect() calls HugeClient.builder(url, graph), which defaults graphSpace to "DEFAULT" [6] [7]. The graph name does flow into initManagers → AuthManager, but AuthManager discards it.

Fix approach (aligns with your proposal)

1. Add a legacy path constant in AuthAPI — e.g. "graphs/%s/auth/%s" — and select it when supportGs is false and a graph name is available.
2. Thread graph through AuthManager into UserAPI — the constructor already receives it; just forward it.
3. Add getByName() to UserAPI — issue GET /graphs/{graph}/auth/users?name={name} and parse the users list wrapper that Server 1.5 returns.
4. Preserve modern behavior — when supportGs is true (Core ≥ 1.7.0), keep the existing graphspaces/DEFAULT/auth/users path.
5. Tests — the existing UserApiTest only exercises the GraphSpace constructor [8]. Add a variant that constructs UserAPI with a graph name and supportGs = false to cover the legacy path and response parsing.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[looksaw2]

I’ve opened #760, which aims to address this issue with a focused Java Client change. The PR includes the implementation, regression tests, real Server 1.5 verification, and matching before/after evidence.