Configuration Source Extraction part 2/5 - Add flagsSnapshotId Field

[typotter]

Configuration Source Extraction part 2/5 - Add flagsSnapshotId Field

🥞 Configuration Refactor Stacked Pull Requests 🥞

🔲 Make HTTP client injectable via constructor (#207)
🔲 Integrate default HTTP client implementation (#206)
🔲 Add configuration HTTP client interface (#205)
👉 Add flagsSnapshotId field to Configuration (this PR)
✅ Extract DTO interfaces for downstream SDK extensibility (#197)
⬇️ feature/v4 (trunk)

Motivation and Context

This PR adds a flagsSnapshotId field to the Configuration class as preparation for HTTP ETag-based caching. While this PR only adds the field structure, future PRs will populate it from HTTP responses to enable efficient caching.

The flagsSnapshotId will store HTTP ETag values, enabling:

• Conditional HTTP requests using If-None-Match headers
• 304 Not Modified responses from the server
• Bandwidth savings (skip downloading unchanged configurations)
• CPU savings (skip JSON parsing on 304 responses)
• Reduced unnecessary bandit fetches and callbacks

Description

Adds the flagsSnapshotId field to Configuration with all necessary boilerplate, but does not yet implement HTTP caching behavior.

Changes

• Added flagsSnapshotId field to Configuration class (private final String, @nullable)
• Updated constructor signature to accept flagsSnapshotId parameter (4th-to-last position)
• Updated equals(), hashCode(), and toString() to include the new field
• Added getter getFlagsSnapshotId() with comprehensive JavaDoc
• Updated Configuration.Builder to accept and pass through flagsSnapshotId parameter
• Updated all Configuration.builder() call sites throughout codebase to pass null
• Updated test fixtures to include the new field

Why Field-Only Approach?

This PR intentionally does NOT modify EppoHttpClient because:

• EppoHttpClient will be deleted in PR Configuration Source Extraction part 4/5 - Integrate Default HTTP Client #206 (replaced with DefaultEppoConfigurationHttpClient)
• Modifying it would create merge conflicts and wasted effort
• The field can be added now and populated later when the new HTTP client is integrated

Future Implementation (PR #206)

When the new HTTP client is integrated, the flagsSnapshotId will be populated:

• Extract ETag from ConfigurationResponse.getETag()
• Pass to Configuration.builder(payload, eTag)
• ConfigurationRequestor will use config.getFlagsSnapshotId() for If-None-Match headers
• Server returns 304 Not Modified when configuration unchanged

How has this been documented?

• Added comprehensive JavaDoc to getFlagsSnapshotId() method
• JavaDoc explains the field represents a snapshot identifier for caching
• Notes that it will be used for HTTP conditional requests in future implementations
• All documentation builds without warnings

How has this been tested?

• ✅ All 279+ tests pass
• ✅ JavaDoc builds successfully (./gradlew javadoc)
• ✅ All Configuration.builder() calls updated to include null parameter
• ✅ No changes to EppoHttpClient (verified clean)
• Updated test fixtures:
  • ConfigurationBuilderTest - constructor calls updated
  • ConfigurationRequestorTest - builder calls updated
  • BaseEppoClientTest - builder calls updated
  • BaseEppoClientBanditTest - builder calls updated

Breaking Changes

⚠️ Constructor signature change: The Configuration constructor now requires a flagsSnapshotId parameter (4th-to-last position). This is an internal API used only within this repository, so external impact is zero.

Migration: Any code directly calling the Configuration constructor must add null as the 4th-to-last parameter.

Dependencies

Depends on: PR #197 (typo/dto-interface-extraction)
Blocks: PRs #205, #206, #207