Skip to content

fix: Accept a payload-transferred event without the deprecated version field - #279

Open
bradbunce wants to merge 1 commit into
launchdarkly:mainfrom
launchdarkly-labs:fix/payload-transferred-optional-version
Open

bradbunce wants to merge 1 commit into
launchdarkly:mainfrom
launchdarkly-labs:fix/payload-transferred-optional-version

Conversation

@bradbunce

@bradbunce bradbunce commented Nov 20, 2026 •

Copy link
Copy Markdown

Requirements

  • I have added test coverage for new or changed functionality
  • I have followed the repository's pull request submission guidelines
  • I have validated my changes against all supported platform versions

Tested on JDK 17 locally and on JDK 8 in CI, which is the only version lib/shared/internal's CI job runs. Not tested on Java 11 or Android. The change is plain parsing code with no version-specific APIs.

Related issues

  • FDV2PL 3.4 (payload-transferred) in sdk-specs: version is optional and deprecated. It "has no semantic meaning", and new SDK implementations "MUST treat this field as being absent".
  • Found while building a client-side Java SDK on top of java-sdk-internal.

Describe the solution you've provided

PayloadTransferred.parse no longer rejects a payload-transferred event that has no version field, or whose version isn't an integer. Today it throws SerializationException in both cases. If the service stopped sending the field, which the spec allows, every FDv2 payload would fail to parse in every SDK built on this library.

  • A missing version is read as 0.
  • A version that isn't a whole number fitting in an int is skipped and read as 0. That includes null, strings, fractions, out-of-range numbers, objects and arrays.
  • An integer version is still kept, so getVersion(), and the selector version the protocol handler builds from it, are unchanged for every payload that parses today.
  • state is still required.
  • The Javadoc for getVersion() and the constructor now says the field is deprecated and meaningless.

Tests:

  • FDv2PayloadsTest: payloadTransferred_ThrowsWhenVersionFieldMissing is replaced by payloadTransferred_TreatsMissingVersionAsZero.
  • FDv2PayloadsTest: new payloadTransferred_TreatsNonIntegerVersionAsZero and payloadTransferred_KeepsAnIntegerVersion.
  • FDv2ProtocolHandlerTest: new payloadTransferred_WithoutVersionCompletesTheTransfer.
  • The three new behavior tests fail without this change. All 327 tests in lib/shared/internal pass.

Describe alternatives you've considered

Ignoring the field entirely, even when it's an integer, as the spec's "MUST NOT parse or use its value" suggests. That would change getVersion() and Selector.getVersion() for existing callers, so I left it as a separate decision. Nothing in the server SDK reads the selector version today.

Additional context

The service currently sends "version": 0, so this doesn't change behavior against today's service. It removes a parse failure if the field is ever omitted.


Note

Overview
Aligns PayloadTransferred parsing with FDv2 spec 3.4: the deprecated version field is no longer required, and malformed values no longer fail deserialization.

PayloadTransferred.parse defaults missing version to 0, parses integer values when present, and maps any non-integer JSON (null, strings, floats, objects, etc.) to 0 via new readOptionalInt. Only state remains required. Javadoc now documents that version is deprecated and meaningless.

Tests replace the “missing version throws” case with coverage for missing, invalid, and valid integer versions, plus a protocol-handler test confirming a payload-transferred event with only state still completes a full transfer.

Reviewed by Cursor Bugbot for commit 9bbcdc5. Bugbot is set up for automated code reviews on this repo. Configure here.

…n field

FDV2PL 3.4 makes the payload-transferred version field optional and
deprecated: it has no meaning, and SDKs must treat it as absent. The
parser threw when the field was missing and failed on any non-integer
value. It now reads a missing or non-integer version as 0. An integer
version is still kept, so getVersion() and the selector are unchanged
for every payload that parses today.
@bradbunce bradbunce closed this Nov 20, 2026
@bradbunce bradbunce reopened this Nov 20, 2026
@bradbunce bradbunce closed this Nov 20, 2026
@bradbunce bradbunce reopened this Nov 20, 2026
@bradbunce

Copy link
Copy Markdown
Author

All checks have passed across three CI runs, including build-test-java-sdk-internal, which covers this change. The remaining failures are all in setup-java, before the build starts: "Checksum verification failed for Temurin-Hotspot version 8.0.514+1" (expected 27eda854…, actual 16388e6e…). The same error shows up intermittently in okhttp-eventsource CI, so it looks like a stale checksum for that Temurin 8 release rather than anything in this PR. Could a maintainer rerun the failed jobs?

@bradbunce
bradbunce marked this pull request as ready for review November 20, 2026 15:02
@bradbunce
bradbunce requested a review from a team as a code owner November 20, 2026 15:03
@tanderson-ld
tanderson-ld self-requested a review November 20, 2026 18:21

This branch has not been deployed

No deployments
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