Conversation
Lock down the current encode/decode behavior of LongEncoding as a compatibility contract: exact outputs across the full value range including the wrapping arithmetic around Long.MIN_VALUE, accepted non-canonical inputs, and the exception class for each rejected input. Exception messages are deliberately not part of the contract. The corpus is generated by running the current implementation (LongEncodingGoldenGenerator, deterministic seed) and verified two ways: LongEncodingGoldenTest replays every line against the current implementation, and regenerates the corpus in memory to check the committed file matches the generator, so the two cannot drift apart. Both tests are registered in UnitTestSuite so commons CI runs them.
dosubot
Bot
added
size:XS
|
Due to the lack of activity, the current pr is marked as stale and will be closed after 180 days, any update will remove the stale label |
|
@imbajin seeing your interest in my proposal wdyt here? |
|
@dpol1 Sorry I haven't replied to your proposal directly sooner. We've been focused on getting 1.8.0 released as soon as possible, and we're looking to take the Rust work forward in the 1.9–2.0 timeframe. As the release work wraps up, we'll discuss the proposal together with the other PMC members and follow up here and in the related issues. A Rust refactor touches quite a few areas, so we do need some additional time to research the options and confirm the scope and compatibility requirements. Thanks for the proposal and the groundwork in this PR. The community is very interested in your proposal and supportive of your involvement and this direction. As the release progresses, we'll follow up as soon as possible to exchange ideas and discuss the next steps, including through IM or Discord for quicker back-and-forth. |
2 participants
Purpose of the PR
LongEncodingencodes ids and sortable keys, so its exact behavior is a compatibility contract, including the intentional overflow wrapping aroundLong.MIN_VALUEand inputs the decoder accepts but the encoder never produces. Today that contract exists only implicitly in the implementation. This PR pins it in a committed, implementation-independent corpus that any port or refactor can be checked against line by line.Main Changes
LongEncodingGoldenGenerator(test scope): produces the corpus by running the current implementation and recording, for each input, the exact output or the exception class. Deterministic: fixed value sets plus a fixed random seed, duplicate lines dropped.longencoding-golden.txt(test resource): 3940 cases, plain ASCII, tab separated with\uXXXXescapes. Covers full-range round trips includingLong.MIN_VALUE/MAX_VALUE, non-canonical decode inputs (00decodes to MIN while encode produces010), arbitrary UTF-16 decode input including surrogates, the error taxonomy (IllegalArgumentExceptionvsNumberFormatExceptionvs NPE), and length limits.LongEncodingGoldenTest: two checks. It replays every corpus line against the implementation, and it regenerates the corpus in memory to assert the committed file matches the generator output exactly, so generator and resource cannot drift apart.UnitTestSuiteso commons CI executes them.Review guide: the review surface is the generator (case selection, ~370 lines), the corpus format documented in the file header, and the two-way check mechanics. The corpus file is generated output verified by
testCorpusMatchesGeneratorand does not need line-by-line review.Contract boundaries: six operations (
encodeSortable/decodeSortable,encodeB64/decodeB64,encodeSignedB64/decodeSignedB64). Exact output strings and decoded values are contract; the exception class is contract, the exception message deliberately is not. No production code changes.Verifying these changes
mvn test -pl hugegraph-commons/hugegraph-common -Dtest=UnitTestSuite -DskipCommonsTests=falseon JDK 11 (the commons CI toolchain): 345 tests, the only errors are 2 environment NPEs inMachineInfoTestthat reproduce identically on a clean master checkout in the same environment.apache-rat:check,checkstyle:checkandgit diff --checkare clean.Does this PR potentially affect the following parts?
Documentation Status
Doc - No Need(user docs unaffected; the technical contract is documented in [Proposal] Java compatibility fixtures and PoC selection matrix for the Rust modernization groundwork #3145, the corpus file header, and this PR)