chore: Support flag change listeners in contract tests

[devin-ai-integration]

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

Related issues

• sdk-test-harness#317 — Adds flag change listener contract tests to the test harness
• go-server-sdk#349 — Reference Go implementation

Describe the solution you've provided

Implements test service support for the new flag change listener contract tests. No changes to the SDK itself — only the contract test service (contract-tests/) is modified.

New file: flag_change_listener.rb

Introduces a ListenerRegistry that manages active listener subscriptions for an SDK client entity. Two callback listener classes (FlagChangeCallbackListener and FlagValueChangeCallbackListener) implement the #update method expected by the SDK's FlagTracker and POST ListenerNotification JSON payloads to the callback URI provided by the test harness.

The registry handles:

• General flag change listeners — registered via FlagTracker#add_listener
• Flag value change listeners — registered via FlagTracker#add_flag_value_change_listener, which handles context-specific evaluation and old/new value tracking internally
• Unregistration — removes the listener from the tracker and the internal map
• Duplicate ID safety — re-registering with an existing ID removes the old listener first
• Cleanup — close_all is called when the client entity shuts down

Capabilities advertised: flag-change-listeners and flag-value-change-listeners

Commands handled: registerFlagChangeListener, registerFlagValueChangeListener, unregisterListener

Human review checklist — items worth close attention:

1. Context construction for value change listeners (client_entity.rb:236): Uses LDContext.create(params[:context]) on the symbolized-key hash from JSON parsing. Other commands pass params[:context] directly to SDK methods that internally call make_context, but add_flag_value_change_listener expects an LDContext so explicit creation is needed. Verify this produces a valid context from the test harness payload format.
2. Adapter vs. inner listener storage (flag_change_listener.rb:93): For value change listeners, the registry stores the adapter returned by add_flag_value_change_listener (not the inner callback listener). This is intentional — the adapter is what must be passed to remove_listener per the SDK API.
3. Thread safety timing (flag_change_listener.rb:75-77): The listener is stored in the map before calling @tracker.add_listener. If an unregister command races in, it might call remove_listener on a not-yet-registered listener. This should be benign but worth noting.
4. Error handling: Both callback listeners rescue and log errors rather than propagating them. This prevents listener errors from crashing the test service, which is appropriate for testing.

---

Devin session: https://app.devin.ai/sessions/5a3ff6991d1147f5b56df8c048b8dcc2
Requested by: @keelerm84

---

Note

Medium Risk
Limited to the contract test service, but introduces new listener lifecycle/concurrency and outbound callback POSTs that could cause flaky tests or resource leaks if mis-registered or not cleaned up correctly.

Overview
Adds contract-test-service support for flag change listener contract tests by introducing a ListenerRegistry that registers/unregisters SDK flag_tracker listeners and posts change notifications to a harness-provided callback URI.

The service now advertises flag-change-listeners/flag-value-change-listeners, handles new commands (registerFlagChangeListener, registerFlagValueChangeListener, unregisterListener), and ensures listeners are removed on client shutdown. CI is updated to run contract tests v3.0.0-alpha.4.

^{Written by Cursor Bugbot for commit 1b84760. This will update automatically on new commits. Configure here.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}