feat(server): adapt Hubble 2.0 & add graph/role management

[Yeaury]

Purpose of the PR

Adapt the Server APIs needed by Hubble 2.0 so the community Server can support
Hubble's graph, GraphSpace, default graph, default role, schema template, and
manager flows.

Hubble2 will use only the canonical APIs listed below. Since Hubble2 has not
been released, legacy form-based APIs and state-changing GET aliases are not
compatibility requirements and should be removed before release.

Hubble2 reference: hugegraph/hugegraph-toolchain#4

Main Changes

• Graph management (GraphsAPI.java)
• GraphSpace and default-role APIs (GraphSpaceAPI.java)
• GraphSpace managers (ManagerAPI.java)
• Schema templates (SchemaTemplateAPI.java)
• Authentication and graph metadata support

Integration Boundaries

• Hubble2 uses canonical graph create/default APIs:
  • POST /graphspaces/{graphspace}/graphs/{name}
  • POST /graphspaces/{graphspace}/graphs/{name}/default
  • DELETE /graphspaces/{graphspace}/graphs/{name}/default
• Server and Hubble should remove legacy form-urlencoded graph creation and
  state-changing GET aliases before Hubble2 is released.
• GraphSpace lifecycle, default role, schema template, and manager APIs are
  PD-mode APIs. Standalone/non-PD Hubble should hide or degrade these flows
  instead of requiring Server to emulate the full PD GraphSpace model.
• Hubble2 non-PD flows should continue to use DEFAULT GraphSpace and graph
  operations that are meaningful in standalone mode.
• Graph clear must remain user-oriented and expose two real operations:
  data-only clear that preserves schema, and schema-and-data clear. Server must
  implement and verify both semantics before Hubble wires both user actions.

Known Integration Follow-ups

• Current PD smoke found GET /graphspaces/DEFAULT/graphs returning an empty
  list while direct GET /graphspaces/DEFAULT/graphs/hugegraph succeeds.
• Hubble Gremlin overview can still show max counts when Server-side Gremlin
  execution does not provide the expected g alias.
• Default-role checks still need a full Hubble PD workflow smoke after the API
  boundary is finalized.

Server follow-up status

• Require memory_monitor.period to be positive, while keeping
  memory_monitor.threshold=1.0 as the disable switch.
• Roll back MemoryMonitor, Gremlin, and REST resources if MemoryMonitor
  construction or startup fails.
• Validate GraphSpace and OBSERVER graph existence in the manager
  default-role check.
• Pass the selected Maven backend profile into the test JVM and remove the
  nonexistent singular auth/manager/default test route.
• Implement two explicit graph-clear operations in Server: data-only clear
  that preserves schema, and schema-and-data clear. Define canonical APIs,
  confirmation/error semantics, and verify behavior across supported backends.
• Remove the Server public GET default-graph mutation aliases before
  Hubble2 is released; retain only the canonical POST/DELETE operations.

Hubble migration status

• Use the canonical JSON graph-create resource path.
• Use canonical POST/DELETE methods to set and unset the default graph.
• Read the default graph through the canonical Server endpoint.
• Align default-role calls and handle the empty 204 delete response.
• Align schema-template and graph-profile contracts.
• Use the canonical Server PUT contract for backend-to-Server graph
  metadata updates; the legacy Hubble GET /update route is removed.
• Remove the form-urlencoded graph-create facade and legacy default-role
  facades; keep only canonical resource APIs.
• Normalize the default-graph read to /graphs/default and remove Hubble
  GET default-graph mutation aliases.
• Make graph clear confirmation explicit and safe: show the graph name and
  deletion scope, warn that it is irreversible, and require strong confirmation.
• Stop Hubble from using per-graph reload. The shared Client overload stays
  for now, but is explicitly deprecated because Server accepts only update.
• Hide the default-GraphSpace mutation; Hubble no longer exposes its own GET
  mutation facade.

Hubble TODOs

• After Server implements both graph-clear modes, wire the two confirmed
  Hubble actions to non-GET operations: data-only clear that preserves schema,
  and schema-and-data clear. Keep both user-facing actions and add UI smoke
  coverage proving the invoked mode and deletion scope.
• Complete the outstanding PD integration smoke for graph list/lifecycle,
  default-role/account/role, loader peers, algorithms, and async tasks once the
  Server API boundary and test environment are available.

Remaining design decisions

• Hubble2 is unreleased and does not require legacy API compatibility.
• Decide whether default-role owner input needs an explicit user/group type
  when a user and group can share the same name.
• Decide the canonical Server contract for default GraphSpace before the
  feature is exposed by Hubble.

Verifying these changes

• Server unit coverage for the master check and default-role permission
  boundaries.
• Server regression coverage for MemoryMonitor configuration/startup
  rollback, manager resource validation, and backend-profile propagation.
• Hubble2 non-PD smoke for graph management, default graph APIs, and
  canonical graph create path.
• Hubble2 packaged loader/auth smoke with current toolchain loader/client.
• Hubble2 PD minimal API smoke for versions, GraphSpace list/get, direct
  graph get, schema template list, and Gremlin schema/data read-write.
• Server tests for data-only and schema-and-data clear across the supported
  standalone and distributed backends.
• Hubble UI smoke proving that each clear action invokes the correct Server
  mode and that its confirmation accurately describes the deletion scope.
• Hubble2 PD graph list/lifecycle smoke.
• Hubble2 PD default-role/account/role smoke.
• Hubble2 PD loader peers, algorithms, and async task smoke.

[Copilot]

Pull request overview

This PR adds/extends HugeGraph Server REST endpoints and auth-layer capabilities needed by the Hubble 2.0 frontend, focusing on graph profile listing, default graph selection, default role management, and schema template CRUD within graphspaces.

Changes:

• Added graph profile listing + default-graph set/unset/query APIs, plus graph create compatibility tweaks.
• Implemented default-graph/default-role persistence methods in the AuthManager interface and its implementations/proxies.
• Introduced schema template CRUD API and corresponding GraphManager helpers.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/util/ConfigUtil.java	Adds config-to-string helper used by graph profile listing.
hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/auth/AuthManager.java	Extends auth interface for default graph/role operations.
hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/auth/StandardAuthManager.java	Implements new default graph/role methods (non-PD auth manager).
hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/auth/StandardAuthManagerV2.java	Implements new default graph/role methods (PD-mode auth manager).
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/auth/HugeGraphAuthProxy.java	Proxies/delegates new AuthManager methods.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/core/GraphManager.java	Adds schema template management helpers.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/GraphsAPI.java	Adds graph profile listing, default graph APIs, manage/update behavior, and create defaults.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/space/GraphSpaceAPI.java	Adds default role management endpoints and JSON tolerance.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ManagerAPI.java	Adds endpoint to query whether current user has a default role.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/space/SchemaTemplateAPI.java	New schema template CRUD endpoint implementation.

Comments suppressed due to low confidence (1)

hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/GraphsAPI.java:443

• configs is only validated as non-null when clone_graph_name is empty. If clone_graph_name is provided and the request body is omitted/empty, configs can be null and convConfig(configs) will throw a NullPointerException in the clone branch. Consider defaulting configs to an empty map (or making convConfig() null-safe) before using it for cloning.

        // Check required parameters for creating graph
        if (StringUtils.isEmpty(clone)) {
            // Only check required parameters when creating new graph, not when cloning
            E.checkArgument(configs != null, "Config parameters cannot be null");
            // Auto-fill defaults for PD/HStore mode when not provided
            configs.putIfAbsent("backend", "hstore");
            configs.putIfAbsent("serializer", "binary");
            configs.putIfAbsent("store", name);
            // Map frontend 'schema' field to backend config key
            Object schema = configs.remove("schema");
            if (schema != null && !schema.toString().isEmpty()) {
                configs.put("schema.init_template", schema.toString());
            }
        }

        String creator = HugeGraphAuthProxy.username();

        if (StringUtils.isNotEmpty(clone)) {
            // Clone from existing graph
            LOG.debug("Clone graph '{}' to '{}' in graph space '{}'", clone, name, graphSpace);
            graph = manager.cloneGraph(graphSpace, clone, name, convConfig(configs));
        } else {
            // Create new graph
            graph = manager.createGraph(graphSpace, name, creator,
                                        convConfig(configs), true);
        }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[imbajin]

新增 API 单机版（非 PD）兼容性对照

目标：社区默认的 RocksDB 单机版通过 graphspace=DEFAULT 使用 GraphsAPI，应支持图的增删改查和基础权限管理。GraphSpaceAPI、ManagerAPI、SchemaTemplateAPI 属于 PD 专属功能，不需要兼容。

需要兼容单机版的端点（GraphsAPI）

API 端点	当前状态	问题说明	需要的改动
GET .../graphs/profile	⚠️	ConfigUtil.writeConfigToString 序列化全部配置项，可能泄露 password/token 等敏感字段	白名单过滤或排除敏感 key
PUT .../graphs/{name} (manage/update nickname)	❌	1. isExistedGraphNickname() 调用 metaManager.graphConfigs() — 非 PD 下 MetaManager 未初始化，NPE；2. exist.nickname() 只改内存，缺少持久化调用	1. 加 isPDEnabled() 分支，非 PD 下用内存图列表做去重；2. 补充持久化调用
POST .../graphs (create JSON)	❌	无条件执行 configs.putIfAbsent("backend", "hstore")，单机版默认 RocksDB 会被覆盖为 hstore 导致创建失败	用 if (manager.isPDEnabled()) 包裹 hstore/binary 默认值填充
POST .../graphs/{name} (createByText)	❌	委托 create() 方法，同上	同上（修复 create 即可）
POST .../graphs/{name}/default (设置默认图)	✅	StandardAuthManager 已实现	无
DELETE .../graphs/{name}/default (取消默认图)	✅	StandardAuthManager 已实现	无
GET .../graphs/default (查询默认图)	✅	StandardAuthManager 已实现	无

PD 专属端点（无需兼容单机版）

API 端点	归属	说明
POST/GET/DELETE .../graphspaces/{gs}/role	GraphSpaceAPI	图空间级角色管理，PD-only by design
GET /auth/manager/default	ManagerAPI	已有 ensurePdModeEnabled() 门禁
GET/POST/PUT/DELETE .../schematemplates[/{name}]	SchemaTemplateAPI	全部走 metaManager，PD-only

总结：7 个 GraphsAPI 端点需要兼容单机版。其中 3 个需要代码改动（manage 需加 isPDEnabled() 分支 + 持久化修复，create/createByText 需条件化 hstore 默认值），1 个需过滤敏感配置，3 个已可正常工作。

[imbajin]

Follow-up review after the latest update: these are remaining current-PR issues that look small enough to fix directly, while already-covered findings are intentionally not duplicated.

[imbajin]

Follow-up TODO for CI coverage:

Add a real distributed-mode CI job that boots PD + Store and runs the hstore-backed graphspace API tests against that environment. The tests added in this PR compile and are gated to backend=hstore, but they still rely on an external PD/Store runtime to prove the full happy path.

Suggested scope for a separate issue:

1. Start a minimal PD + Store + Server stack in CI.
2. Run the hstore/PD graphspace API suite, including default graph, default role, and schema template lifecycle coverage.
3. Keep the existing standalone/RocksDB compatibility tests separate so both modes remain visible.

This is not necessarily a blocker for the current PR, but it is the right follow-up to prevent these Hubble-compatible APIs from only being validated at compile time.

[VGalaxies]

Review summary

• Blocking: yes
• Summary: The PR introduces a cluster master safety regression and an authorization gap in default-role management.
• Evidence:
  • git diff origin/master...HEAD
  • mvn -pl hugegraph-server/hugegraph-api -am -DskipTests -Dmaven.javadoc.skip=true compile passed

[VGalaxies]

High: Existing live master detection is swallowed

hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/task/ServerInfoManager.java:139

Evidence

• The uniqueness check at lines 131-133 throws when another alive master exists, but the new broad catch (Exception e) at line 139 logs and continues to saveServerInfo() at line 149.

Impact

• A node can register itself as master even after detecting an existing alive master, allowing multiple masters in the same cluster.

Requested fix

• Do not catch the invariant failure. Only handle the specific schema-mismatch/read error if needed, and rethrow when an existing alive master is found.

[imbajin]

Follow-up boundary notes after rechecking the current Hubble2 branch:

• Hubble2 currently still calls graph creation as form-urlencoded POST /graphspaces/{graphspace}/graphs and default graph through GET aliases such as setdefault/getdefault. I am not adding these extra Server compatibility aliases in this pass. Since Hubble2 is still under development, the cleaner direction is to adjust Hubble2 to the Server API contract unless we explicitly decide to expand the Server public API.
• The master heartbeat uniqueness concern is tied to the deprecated master-worker scheduling path. I am not adding more code to that path here.
• The current Server-side patch is limited to issues that remain valid independent of those boundaries: default-role auth cache invalidation, keeping GraphSpace profile PD-only, and making hstore graphspace API tests fail fast instead of hiding API failures as skips.

[imbajin]

Blocking: yes. Summary: Current head still has a shared-storage server-info regression and a test coverage gap; visible hbase CI is failing. Evidence: final gate saw build-server (hbase, 11) and codecov/patch failures; static review of refs/remotes/pr/3008.

[imbajin]

heartbeat() now re-saves missing ServerInfo for master nodes too, and the latest hbase job is failing on that path. The log shows ServerInfo is missing: DEFAULT-hugegraph/server-1, re-saving it now, then GremlinApiTest.testClearAndInit hits Already existed master 'DEFAULT-hugegraph/server-1' in current cluster, followed by decreaseLoad() NPEs because self ServerInfo is still missing for DEFAULT-hugegraph/server1. Please make current-node master re-registration idempotent, or skip only the normalized current node in the uniqueness scan, and guard decreaseLoad() when self ServerInfo is unavailable.

[imbajin]

This endpoint checks raw default-role metadata without first validating that the path graphspace exists, and for OBSERVER it only checks that graph is non-empty. A typo or stale graph name can therefore return a metadata result instead of a clear 4xx. Please mirror GraphSpaceAPI: validate the graphspace before the auth lookup, and for observer roles verify that the graph exists in that graphspace before calling isDefaultRole().

[imbajin]

Adding the backend-specific suites here does not make them run in CI as written. The new standalone and hstore tests gate on System.getProperty("backend"), but run-api-test.sh invokes Maven as mvn ... -P api-test,$BACKEND, and the surefire config does not pass the Maven backend profile property into the test JVM. That leaves backend null, so assumeStandaloneMode() skips the standalone suite and GraphSpaceApiTest skips as non-hstore. Please pass backend into surefire, for example with systemPropertyVariables, or call Maven with -Dbackend=$BACKEND.

[imbajin]

TODO: update related doc