Skip to content

refactor(server): upgrade TinkerPop to 3.8.1 with compatibility gates (3/3) - #3263

Open
contrueCT wants to merge 31 commits into
apache:masterfrom
hugegraph:task/tp381-3-upgrade-validation
Open

contrueCT wants to merge 31 commits into
apache:masterfrom
hugegraph:task/tp381-3-upgrade-validation

Conversation

@contrueCT

@contrueCT contrueCT commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Purpose of the PR

Part 3 of a three-PR upgrade series targeting apache/hugegraph:master. Upgrade TinkerPop to 3.8.1 and Groovy to 4.0.25 with compatibility gates.

Merge order: apache#3261 (Java 17 foundation) → apache#3262 (query semantics) → apache#3263 (TinkerPop upgrade). All three PRs target master directly. Merge this PR after apache#3261 and apache#3262. Until the prerequisites are merged, the Files changed tab includes their changes; the part-3-only diff is available in community #233. This series develops the Java/TinkerPop modernization work tracked in apache#3117 and apache#3069, with the target version advanced to TinkerPop 3.8.1.

Source: hugegraph/hugegraph#233, submitted directly from hugegraph:task/tp381-3-upgrade-validation. The local validation statements below are carried over from that source PR; CI on this ASF PR head remains the merge gate.

Main Changes

  • Upgrade Server and distributed modules to TinkerPop 3.8.1 and Groovy 4.0.25. Adapt predicate and step APIs, GraphSON/GraphBinary registration and Cypher result normalization.
  • Keep Gremlin Groovy as the default engine; optional GremlinLang transport migration is outside this PR.
  • Run Structure/Process compatibility steps for the new upgrade branch on Memory, RocksDB and HStore. Include provider lifecycle and feature scenarios instead of relying on skipped CI steps.
  • Update release dependency/license metadata in a separate commit so it can be reviewed separately from the implementation.
  • Align Netty modules through the 4.1.137.Final BOM, replacing TinkerPop 3.8.1's vulnerable 4.1.125.Final dependency and updating release metadata.

Verifying these changes

  • Already covered by existing compatibility, traversal and serialization tests.
  • Local validation: Java 17 formatting and all-module clean compile passed. Provider lifecycle checks passed on Memory and RocksDB, including reopening after context shutdown. Report-gate checks passed for all TP entry points, including missing, malformed, empty, fully skipped and stale reports. HStore lifecycle and the full suites remain CI merge gates.
  • Full API, Structure/Process and distributed HStore CI must pass on this PR head before merging. A green workflow with skipped TinkerPop steps is insufficient.

Does this PR potentially affect the following parts?

  • Dependencies
  • Modify configurations
  • The public API
  • Other affects: client serialization and script compatibility
  • Nope

Documentation Status

Repository documentation: docs/upgrade-tinkerpop-3.8.md and docs/query-semantics.md.

contrueCT and others added 22 commits October 3, 2026 00:09
- Poll the Raft readiness endpoint before client tests
- Accept only HTTP 200 as a ready PD response
- Prevent authentication failures from passing startup checks
- Inherit the PD readiness wait from the foundation branch
- Keep the query semantics changes unchanged
- Preserve existing stack ancestry for downstream pull requests
- Exercise cleanup and close/reopen on the selected backend
- Reject empty or entirely skipped reports through every TP entry point
- Isolate RocksDB fixtures from source formatting and cover gate failures
- Inherit PD readiness checks while preserving downstream stack ancestry
- Use the default single-disk layout for the lifecycle fixture
- Keep data and WAL under the JUnit temporary directory
- Prevent optional index mappings from escaping test-owned storage
- Document vertex and edge uniform-list feature flag changes
- Preserve schema-defined LIST guidance and migration expectations
- Align both architecture diagrams with TinkerPop 3.8.1
- Close committed fallback iterators on success and failure
- Assert that count optimization retains the ordering barrier
- Cover cleanup through the primary-key count fallback path
- Inherit committed count iterator cleanup from the query PR
- Carry the strengthened ordering and cleanup regression tests
- Preserve the upgrade stack and downstream commit ancestry
- limit backend count to traversal start scans
- cover repeated scans, input bulk and explicit ids
- document intermediate scan count semantics
- align predicate pushdown with supported conditions
- preserve type operands through nested negation
- test native type filters and document execution
- inherit intermediate scan count protection
- include count boundary regression tests
- keep the upgrade branch aligned with query semantics
@codecov

codecov Bot commented Oct 3, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 39.82869% with 281 lines in your changes missing coverage. Please review.
✅ Project coverage is 41.67%. Comparing base (176fb56) to head (a140671).
⚠️ Report is 1 commits behind head on master.

Files with missing lines Patch % Lines
...he/hugegraph/traversal/optimize/TraversalUtil.java 17.29% 139 Missing and 14 partials ⚠️
.../org/apache/hugegraph/api/cypher/CypherClient.java 34.61% 25 Missing and 9 partials ⚠️
...va/org/apache/hugegraph/io/HugeGraphSONModule.java 25.00% 27 Missing ⚠️
...rg/apache/hugegraph/store/meta/GraphIdManager.java 84.21% 10 Missing and 8 partials ⚠️
...ain/java/org/apache/hugegraph/util/Reflection.java 20.00% 16 Missing ⚠️
.../apache/hugegraph/backend/tx/GraphTransaction.java 42.10% 9 Missing and 2 partials ⚠️
...aph/io/HugeGraphTypeSerializerRegistryBuilder.java 50.00% 6 Missing ⚠️
...he/hugegraph/traversal/optimize/HugeCountStep.java 0.00% 3 Missing ⚠️
...aph/traversal/optimize/HugePrimaryKeyStrategy.java 62.50% 1 Missing and 2 partials ⚠️
...ugegraph/backend/serializer/SerializerFactory.java 33.33% 1 Missing and 1 partial ⚠️
... and 6 more
Additional details and impacted files
@@             Coverage Diff              @@
##             master    #3263      +/-   ##
============================================
+ Coverage     41.57%   41.67%   +0.10%     
- Complexity     7311     7400      +89     
============================================
  Files           793      795       +2     
  Lines         69106    69491     +385     
  Branches       9258     9339      +81     
============================================
+ Hits          28730    28963     +233     
- Misses        37098    37223     +125     
- Partials       3278     3305      +27     

☔ 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.

- remove Commons from required checks
- require the Java 17 memory Server check
- retain analysis and license checks
- avoid claiming TinkerPop 3.8.1 in the foundation
- describe shared TinkerPop and Kryo access needs
- retain the test and runtime permission boundary
- describe V1 fallback with generic type metadata
- keep all three client examples consistent
- retain the supplied serializer and registry settings
- update both Store dependencies to Fastjson 1.2.84
- align the release license and dependency inventory
- retain the Fastjson 1.x dependency contract
- inherit the Fastjson security patch
- align required checks with Java 17
- retain consistent test JVM guidance
- inherit the Fastjson security patch
- align required checks with Java 17
- retain consistent test JVM guidance

# Conflicts:
#	install-dist/release-docs/LICENSE
- override the legacy client transitive dependency
- retain the existing client and production versions
- remove obsolete release inventory entries
- inherit the cluster Commons Text override
- retain the query behavior and client version
- align release dependency metadata
- inherit the cluster Commons Text override
- retain the upgrade behavior and client version
- align release dependency metadata

# Conflicts:
#	install-dist/scripts/dependency/known-dependencies.txt
@imbajin imbajin mentioned this pull request Oct 4, 2026
3 of 9 tasks
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.

2 participants