Skip to content

feat: Parse protocolFallbackTTL from FDv2 goodbye - #265

Open
beekld wants to merge 4 commits into
mainfrom
devin/1794878452-goodbye-fallback-ttl
Open

beekld wants to merge 4 commits into
mainfrom
devin/1794878452-goodbye-fallback-ttl

Conversation

@beekld

@beekld beekld commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Parses the optional protocolFallbackTTL field of the FDv2 goodbye payload in launchdarkly-java-sdk-internal, so the server SDK can treat it as an FDv1 fallback directive.

Part of SDK-2987.

  • Goodbye.getProtocolFallbackTTL() and FDv2ActionGoodbye.getProtocolFallbackTTL() return a nullable Duration: null when the field is absent or JSON null, the value in seconds when it is a number, and Duration.ZERO when it is present but not a number.
  • Duration.ZERO works as "use the default TTL", because the spec already treats 0 that way (DATASYSTEM 1.6.1.3–1.6.1.5). A malformed TTL still counts as a directive.
  • Out-of-range clamping and jitter are deliberately left out of this library. The server SDK will apply them in a follow-up PR after this is released.
  • The one-arg constructors are kept, so existing callers still compile.
Implementation details
  • A field-level Gson TypeAdapter on Goodbye.protocolFallbackTTL is needed because existing tests round-trip Goodbye through Gson, and Gson can't reflect into java.time.Duration on JDK 17. parse() reuses the adapter's read logic.
  • Tests cover absent, integer, fractional, 0, negative, >3600, string/bool/object/array (→ ZERO) and JSON null (→ absent), plus pass-through in FDv2ProtocolHandler.
  • Ran ./gradlew test checkstyleMain checkstyleTest in lib/shared/internal.

Link to Devin session: https://app.devin.ai/sessions/cce64c67519f4babaa75176c06961c5e
Open in Devin Desktop: https://app.devin.ai/desktop/session/cce64c67519f4babaa75176c06961c5e?variant=devin
Requested by: @beekld


Note

Overview
Adds optional protocolFallbackTTL to the FDv2 goodbye payload and threads it through the protocol handler so callers can react when the server signals an FDv1-style fallback.

Goodbye now stores a nullable Duration, parses protocolFallbackTTL from JSON (numeric seconds, including fractions), and round-trips it via a Gson TypeAdapter because JDK 17 cannot reflect Duration. Malformed or non-numeric values become Duration.ZERO (meaning “use default TTL” per spec); absent field or JSON null stays null. FDv2ActionGoodbye exposes the same value, and goodbye handling passes it through from the payload.

Tests cover parsing edge cases and handler pass-through; existing one-arg constructors remain for backward compatibility. Clamping and jitter are intentionally left for a later server SDK change.

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

devin-ai-integration Bot and others added 4 commits November 17, 2026 01:22
Co-Authored-By: Bee Klimt <bklimt@launchdarkly.com>
Co-Authored-By: Bee Klimt <bklimt@launchdarkly.com>
Co-Authored-By: Bee Klimt <bklimt@launchdarkly.com>
@beekld
beekld requested a review from a team as a code owner November 17, 2026 01:24
@devin-ai-integration

Copy link
Copy Markdown
Contributor

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

@cursor cursor Bot added the risk:low label Nov 17, 2026

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Risk: low.

Automated risk review (dry run): Low

This PR would be automatically approved.

Why: It adds optional protocolFallbackTTL parsing on FDv2 Goodbye and pass-through in FDv2ProtocolHandler, with tests for absent, numeric, and malformed values. There are no infrastructure, auth, or approval-policy changes.

If you disagree with this review, share this PR in #feedback-agent-approvals or submit a changes-requested review explaining why.

Open in Web View Automation 

Sent by Cursor Approval Agent: Dry-Run PR Approver

return Duration.ofMillis((long) (reader.nextDouble() * 1000));
}
reader.skipValue();
return Duration.ZERO;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Hmm, is it actually safe to treat missing or incorrect-type values as 0? Are they always treated the same?

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.

A missing field isn't mapped to 0. It stays null, which means "no directive". Only a field that is present but not a number becomes ZERO.

For a field that is present, the spec handles wrong-type and 0 the same way: 1.6.1.4 says a malformed TTL uses the default, and 1.6.1.5 says 0, negative, and >1h also use the default. Both get the jittered 1h default.

Still, ZERO is a sentinel, so this only works if every consumer knows it means "default". If you'd prefer something less implicit, I see two options:

  • Keep the raw value (LDValue), as rust-server-sdk does with Option<serde_json::Value>, and let the server SDK interpret it.
  • Apply the (0, 1h] check here and return null for absent, a valid Duration for in range, and a single documented "use default" value otherwise.

Do you want me to switch to one of those?

Written by Devin

reason = reader.nextString();
break;
case "protocolFallbackTTL":
if (reader.peek() == JsonToken.NULL) {

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

It's kinda strange to special-case null here, when the adapter already handles other non-number cases differently.

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.

I special-cased JSON null to match two things. Gson's @JsonAdapter is null-safe by default, so Gson deserialization already reads null as absent. And rust-server-sdk treats null as absent, because serde reads a JSON null into Option as None.

The spec only talks about the field's "presence", though. If we count "protocolFallbackTTL": null as present, it becomes a directive with the default TTL, parse() just calls the adapter, and the special case goes away. Rust and the Gson path would then differ from this on null, but only Gson round-trip tests use the Gson path.

Should I drop the special case?

Written by Devin

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant