feat: Add test harness support for flag change listeners in Server SDKs

[aaron-zeisler]

This pull request is part of a larger set of PRs that implement Flag Change Listener tests for server SDKs. Here's the list of pull requests that I currently have open:

• [sdk-test-harness] feat: Add test harness support for flag change listeners in Server SDKs <-- This PR
• [go-server-sdk] feat(contract-tests): Implement flag change listener tests in the Go server SDK
• [js-core] feat(contract-tests): Implement flag change listener tests in the Node server SDK

---

Summary

Flag Change Listener Contract Tests

This PR adds contract tests for the SDK flag change listener feature — the ability for applications to subscribe to notifications when flag configurations or evaluated values change. Listener registration uses dynamic commands (rather than SDK creation params) because listeners are typically added and removed during a client's lifetime, and this approach enables future tests for unregistration and runtime listener management.

Design

The test harness already has a well-established pattern for verifying async, event-driven SDK behavior: the HTTP callback pattern (used by hooks, migrations, etc.). Flag change listeners follow the same approach.

                          ┌─────────────────────────┐
                          │     SDK Test Harness     │
                          │                          │
                          │  1. Create mock stream   │
                          │  2. Start SDK client     │
                          │  3. Register listener ──────────┐
                          │  4. Push flag update     │      │
                          │  5. Assert notification  │      │
                          │         ▲                │      │
                          └─────────│────────────────┘      │
                                    │                       │
                             POST   │                       │  Command
                             notification                   │  (JSON)
                                    │                       │
                          ┌─────────│────────────────┐      │
                          │   Callback Endpoint      │      ▼
                          │   (mock HTTP server)     │ ┌──────────────┐
                          │                          │ │  SDK Test    │
                          │   Receives JSON:         │ │  Service     │
                          │   {                      │ │              │
                          │     "listenerId": "...", │ │  Wraps SDK   │
                          │     "flagKey": "...",    │ │  listener    │
                          │     "oldValue": ...,     │ │  API, POSTs  │
                          │     "newValue": ...      │ │  back on     │
                          │   }                      │ │  change      │
                          └──────────────────────────┘ └──────────────┘

Flow:

1. The test harness initializes the SDK client with flags loaded via a mock streaming endpoint
2. The harness sends a register command to the test service, providing a callback URL
3. The test service calls the SDK's native listener API (e.g., FlagTracker.AddFlagChangeListener in Go)
4. The harness pushes a flag update through the mock streaming service
5. The SDK detects the change and fires the listener
6. The test service POSTs a ListenerNotification to the callback URL
7. The harness asserts on the notification contents (flag key, old/new values)

Two Listener Types

Listener Type	Command	Fires when...	Notification includes
Flag Change	registerFlagChangeListener	Flag configuration changes (any update)	flagKey only
Flag Value Change	registerFlagValueChangeListener	Evaluated value changes for a specific context	flagKey, oldValue, newValue

The distinction matters: a flag change listener fires on any configuration update (e.g., targeting rule edits), even if the evaluated value stays the same. A flag value change listener only fires when the value the application would see actually differs.

Capabilities

Tests are split across two capabilities so SDKs only run tests for APIs they actually provide:

Capability	Required for	SDKs
flag-change-listeners	Config change listeners	All server-side SDKs
flag-value-change-listeners	Value change listeners (old/new)	Go, Java, .NET, Python, Ruby

The Node.js server SDK, for example, only supports config change events (update / update:KEY) and does not have a native value change listener API, so it advertises only flag-change-listeners.

Test Coverage

Test	What it verifies
Flag Change Listener (flag-change-listeners)
Receives notification when flag changes	Basic listener fires on update
Fires on config change even when value unchanged	Fires regardless of value delta (e.g., targeting rule edit)
Receives notifications for different flags	Listener fires for multiple distinct flag updates
Flag Value Change Listener (flag-value-change-listeners)
Receives notification when value changes	Reports correct old and new values
Does not notify when value is unchanged	Suppresses no-op updates (same value, new version)
Multiple listeners both receive notification	Two listeners on the same flag both fire independently
Is context specific	Value change is evaluated per-context (user-1 changes, user-2 doesn't)

What SDK Repositories Need to Implement

Each SDK's test service must:

1. Add capabilities to the GET / status response:
   • "flag-change-listeners" — all SDKs with a config change listener API
   • "flag-value-change-listeners" — only SDKs with a native value change listener API (Go, Java, .NET, Python, Ruby)
2. Handle new commands on the client command endpoint:
   • registerFlagChangeListener — subscribe to the SDK's flag change API, POST a ListenerNotification to the callback URL when the listener fires
   • registerFlagValueChangeListener (if advertising the capability) — subscribe to the SDK's flag value change API, capturing old/new values and POSTing them to the callback URL
   • unregisterListener — remove a previously registered listener by its ID
3. Maintain a listener map keyed by listenerId so that unregisterListener can clean up correctly

No changes to the SDK itself are required — only the test service wrapper.

---

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

Provide links to any issues in this repository or elsewhere relating to this pull request.

Describe the solution you've provided

Provide a clear and concise description of what you expect to happen.

Describe alternatives you've considered

Provide a clear and concise description of any alternative solutions or features you've considered.

Additional context

Add any other context about the pull request here.

---

Note

Low Risk
Low risk: mostly adds new contract tests and service-spec/command definitions, and the new listener tests are gated behind opt-in capabilities so existing SDK test services should not be affected unless they advertise them.

Overview
Adds contract-test coverage for flag change listeners in server-side SDK suites, including both general config change listeners and optional value change (old/new) listeners.

Introduces new test-service surface area to support those tests: new capabilities (flag-change-listeners, flag-value-change-listeners), new commands (registerFlagChangeListener, registerFlagValueChangeListener, unregisterListener) and payload types (ListenerNotification), plus a mock HTTP callback endpoint (ListenerCallbackService) and SDKClient helpers to register/unregister listeners. Updates docs/service_spec.md to document the new capabilities.

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

[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.}

[cursor]

Body logged before ReadAll error is checked

Low Severity

The result of io.ReadAll is passed to logger.Printf on line 44 before the err return value is checked on line 45. If the read fails, bytes may be nil or contain only partial data, yet it gets logged as if it were a complete notification. While string(nil) won't panic in Go, this produces misleading debug output. The events_service.go in the same package correctly checks the error before using the data.