Skip to content

refactor(server): use typed graph registry keys - #3482

Open
iiiiSaber wants to merge 2 commits into
apache:masterfrom
iiiiSaber:refactor/graph-manager-key
Open

iiiiSaber wants to merge 2 commits into
apache:masterfrom
iiiiSaber:refactor/graph-manager-key

Conversation

@iiiiSaber

@iiiiSaber iiiiSaber commented Nov 17, 2026 •

Copy link
Copy Markdown

Purpose of the PR

Address the GraphManager FIXME by replacing combined string keys with typed graph identities.

In GraphManager there is a comment to ask for fix:

    //FIXME: add one class like graphKey as key,which contains graphSpace and graphName
    private final Map<String, Graph> graphs;
    private final Set<String> localGraphs;
    private final Set<String> removingGraphs;
    ...

Main Changes

  • Introduce the immutable GraphKey record.
public record GraphKey(String graphSpace, String graphName) {

    public GraphKey {
        Objects.requireNonNull(graphSpace, "graphSpace");
        Objects.requireNonNull(graphName, "graphName");
    }
    ...
}
    private final Map<GraphKey, Graph> graphs;
    private final Set<GraphKey> localGraphs;
    private final Set<GraphKey> removingGraphs;
    ...
  • Use typed keys for registry and lifecycle tracking.
  • Preserve string interfaces and the live graph-name view.
  • Add regression tests and update existing fixtures.

Verifying these changes

  • Trivial rework / code cleanup without any test coverage. (No Need)
  • Already covered by existing tests.
  • Need tests and can be verified as follows:

128 focused tests passed, including four new regression tests. Formatting, full clean compilation, and git diff --check passed.

Does this PR potentially affect the following parts?

  • Dependencies
  • Modify configurations
  • The public API
  • Other affects: internal graph registry and lifecycle tracking.
  • Nope

Documentation Status

  • Doc - TODO
  • Doc - Done
  • Doc - No Need: internal refactor.

- Introduce GraphKey for graph-space and graph-name identity.
- Migrate registry and lifecycle tracking to typed keys.
- Preserve string boundaries and the live graph-name view.
- Add registry regressions and adapt existing lifecycle fixtures.
@codecov

codecov Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 72.72727% with 33 lines in your changes missing coverage. Please review.
✅ Project coverage is 58.65%. Comparing base (8828d82) to head (3c36b71).
⚠️ Report is 2 commits behind head on master.

Files with missing lines Patch % Lines
...n/java/org/apache/hugegraph/core/GraphManager.java 70.27% 16 Missing and 17 partials ⚠️
Additional details and impacted files
@@             Coverage Diff              @@
##             master    #3482      +/-   ##
============================================
+ Coverage     58.52%   58.65%   +0.13%     
- Complexity     2717     3096     +379     
============================================
  Files           779      780       +1     
  Lines         69439    69645     +206     
  Branches       9577     9708     +131     
============================================
+ Hits          40637    40849     +212     
- Misses        25108    25114       +6     
+ Partials       3694     3682      -12     
Flag Coverage Δ *Carryforward flag
commons 96.37% <ø> (ø) Carriedforward from f9523ab
hstore 36.24% <32.23%> (+0.02%) ⬆️
pd 56.83% <ø> (ø) Carriedforward from f9523ab
server_hbase 42.55% <ø> (+0.06%) ⬆️ Carriedforward from f9523ab
server_memory 56.77% <72.72%> (+0.12%) ⬆️
server_rocksdb 43.05% <21.48%> (+0.04%) ⬆️
store 36.20% <ø> (ø) Carriedforward from f9523ab

*This pull request uses carry forward flags. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: no. Score: 9/10. Summary: GraphKey replaces every string registry key in GraphManager with matching behaviour under the graph and graph space naming rules, and the 128 focused GraphManager unit tests pass at this head.

@imbajin imbajin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Score: 8.2/10 · Confidence: medium

Blocking: no

Summary

No new actionable regression confirmed in the typed graph registry conversion.

Evidence

Traced registry creation, lookup, removal and reload, the live names view, metadata string boundaries, and graph-name validation. The latter excludes the delimiter from graph names.

Validation notes

Live PD events and multi-node lifecycle behavior were not independently tested. An older event parser still splits hyphenated graph-space names; an introduced regression was not established. Approval is withheld pending those integration checks.

- Validate parsed graph-space and graph-name components.
- Reuse GraphKey for update metadata lookup and logging.
- Cover normal, hyphenated, malformed and unknown event names.
@iiiiSaber

Copy link
Copy Markdown
Author

Hi @imbajin, thanks for your valuable review.

I updated graphUpdateHandler to use GraphKey consistently for name validation, metadata lookup, and logging, with regression coverage.

Also I ran a real local cluster with one PD, one Store, and two Servers.
All 17 checks passed, covering notification propagation, cross-Server REST/Gremlin reads, same-name recreation, graph-space isolation, and reload.
Receiving-Server logs were checked before graph lookups to exclude lazy loading.

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: no. Score: 9/10. Summary: GraphKey replaces every string key in the GraphManager registry and PD event handlers, including graphUpdateHandler, and parses the same parts as before for all valid graph and graph space names. UnitTestSuite passes at this head with GraphManagerGraphKeyTest included.

@imbajin imbajin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Score: 8.2/10 · Confidence: medium

Blocking: no

Summary

No new actionable issue found in the typed graph registry and metadata update changes.

Evidence

Reviewed graph-key conversion across registry lifecycle and metadata boundaries. The latest update handler now uses the parsed key for metadata lookup, and graph-name validation excludes the separator. New tests cover update handling and graph-space names with separators.

Validation notes

No tests or distributed PD/Store integration were independently run in this review. The author's reported multi-node checks were not independently reproduced.

@iiiiSaber iiiiSaber closed this Nov 19, 2026
@iiiiSaber iiiiSaber reopened this Nov 19, 2026
@iiiiSaber

iiiiSaber commented Nov 19, 2026 •

Copy link
Copy Markdown
Author

@imbajin Thanks for the follow-up review. Here are the details and recorded results from my latest local multi-Server verification.

Environment and tested source

  • Run date: November 19, 2026, starting at 22:19:55 (Asia/Shanghai).
  • HugeGraph 1.8.0 built from source, using Temurin 17.0.21 and Maven 3.9.9.
  • Tested source: 3c36b71732543ef216b89ea4d028956422574d3d. Recorded GraphManager and GraphKey source hashes match this commit.
  • One real PD, one real Store and two real Server JVMs on one machine, with fresh dedicated data directories and loopback addresses. PD notifications were not mocked.
Process REST port Other ports
PD 28620 gRPC 28686; Raft 28610
Store 28520 gRPC 28500; Raft 28510
Server A 28080 Gremlin 28182
Server B 28081 Gremlin 28183

Verification method

I used a temporary Python script to send requests through Server A and check the resulting behavior on Server B:

  • ADD: wait for B's notification receipt and graph construction logs before making a graph lookup on B.
  • UPDATE: wait for B's update-handler log, then verify its read mode through the API.
  • REMOVE: wait for B's close/removal logs, then check that its Gremlin binding is absent.
  • Write schema and vertices through A and read them through both REST and Gremlin on B.
  • Recreate the same graph name, verify that old data is absent, and verify the new data.
  • Use the same graph name in two spaces to check update and deletion isolation.
  • Reload B and verify that the replacement graph and its data remain available.

Checking B's logs before graph lookups avoids counting lazy graph loading as proof of ADD notification propagation.

Results

All 17 scripted functional checkpoints passed. These are checkpoints in one cluster run, not 17 existing project test cases or separate deployments.

# Checkpoint Result
1 create notification: DEFAULT/key_probe PASS
2 cross-Server REST and Gremlin data: DEFAULT/key_probe PASS
3 update notification: DEFAULT/key_probe -> ALL PASS
4 update notification: DEFAULT/key_probe -> OLTP_ONLY PASS
5 remove notification: DEFAULT/key_probe PASS
6 create notification: DEFAULT/key_probe PASS
7 same-name recreation has no old vertices PASS
8 cross-Server REST and Gremlin data: DEFAULT/key_probe PASS
9 create notification: key_space_a/same_name PASS
10 create notification: key_space_b/same_name PASS
11 update notification: key_space_a/same_name -> ALL PASS
12 read-mode update isolated by graph space PASS
13 remove notification: key_space_a/same_name PASS
14 deletion isolated by graph space PASS
15 Server B reload retains replacement graph and data PASS
16 remove notification: DEFAULT/key_probe PASS
17 remove notification: key_space_b/same_name PASS

Example ADD evidence from Server B, before querying the graph:

2026-11-19 22:21:27 [grpc-default-executor-1] [INFO] o.a.h.c.GraphManager - Accept graph add signal from etcd for DEFAULT-key_probe
2026-11-19 22:21:27 [grpc-default-executor-1] [INFO] o.a.h.c.GraphManager - Add graph space:DEFAULT graph:key_probe

Example read-mode update evidence:

2026-11-19 22:21:30 [grpc-default-executor-2] [INFO] o.a.h.c.GraphManager - Update graph space:DEFAULT graph:key_probe

B then returned {"graph_read_mode":"ALL"}. After same-name recreation, B returned an empty vertex list and subsequently read the new generation_two marker through REST and Gremlin. Reloading B retained that marker.

Scripts and recorded output

I am uploading the scripts and recorded output individually, using their original file extensions.

  • cluster.py: runtime configuration and process startup.
  • verify.py: API requests, receiving-Server log checks and assertions.
  • results.json: all 17 recorded checkpoints with responses and event evidence.
  • verification.log: concise PASS output from the run.

verification.log

cluster.py

verify.py

run_retry.py

results.json

Reproduction

With Java 17 and Maven available, use a separate source checkout at 3c36b7173, set JAVA_HOME to the JDK, and build:

export HUGEGRAPH_SOURCE="$PWD"
mvn package \
  -pl hugegraph-server/hugegraph-dist,hugegraph-pd/hg-pd-dist,hugegraph-store/hg-store-dist \
  -am -Dmaven.test.skip=true -Dmaven.javadoc.skip=true

Place the three Python scripts in a fresh writable directory outside the checkout. With Python 3, PyYAML and the listed ports available:

python3 run_retry.py

The launcher generates a fresh local PD REST secret. Server REST authentication is disabled for this loopback-only setup. The uploaded launcher has been adapted to accept HUGEGRAPH_SOURCE and JAVA_HOME instead of machine-specific paths; those portability edits were syntax-checked, not counted as another run.

This verifies the listed local multi-Server functional scenarios. No integration-test or CI code is added to this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants