feat: add Domains (formerly Clients) (#185)

[mstepien]

Description

This PR introduces the Domains (formerly Named Clients) feature to the OpenFeature Kotlin SDK, ensuring full compliance with the OpenFeature Domains specification.

Domains allow logical binding of clients with specific providers, enabling the use of multiple providers in a single application. If no specific provider or context is bound to a given domain, the system gracefully falls back to the globally configured default provider and evaluation context.

Changes Made

• Client Metadata Updates: Added domain: String? to ClientMetadata. Concurrently deprecated name in favor of domain to align with the wider OpenFeature schema and specification.
• Support for Domain-Bound Providers: Augmented OpenFeatureAPI with domain-parameterized methods (e.g., setProvider(domain, provider), getProvider(domain), getProviderStatus(domain)).
• Domain State Isolation: Introduced ProviderRepository and DomainState to isolate lifecycle, observers, events, and execution flow tracking per domain in a thread-safe manner using atomic flow substitutions and Mutex.
• Domain-Specific Evaluation Context: Permitted setting and retrieving EvaluationContext on a per-domain basis setEvaluationContext(domain, context). A domain client will first attempt to use its specific contextual state before defaulting back to the global execution context.
• Event Flow Isolation: Ensured that hot-swapping providers and evaluating events dynamically bubbles up isolated state and OpenFeatureStatus to the individual domain correctly.
• E2E Validation: Provided test coverage in ProviderRepositoryTest and DomainE2ETest to enforce atomic state concurrency, dynamically mapped fallback lifecycles, and strict hook/event propagation rules bounded to isolated domains.

Related Issues

Closes #185

Testing

• End-to-end domain evaluation test assertions executed (DomainE2ETest)
• Concurrency and flow-mapping assertions completed (ProviderRepositoryTest)
• Evaluated hook propagation order locally.
• Unit/Integration tests all passed successfully on JVM target.

Reviewer Focus

• Please verify the fallback logic in OpenFeatureAPI where missing domain contexts gracefully fallback to global contexts without breaking isolation.
• Sanity-check the coroutine scope management and flow-switching inside ProviderRepository (getStateFlow()) for potential leaks when updating providers rapidly.

[gemini-code-assist]

Code Review

This pull request introduces domain-specific support to the Kotlin SDK, allowing providers and evaluation contexts to be isolated per domain while maintaining a global fallback mechanism. Key architectural changes include the addition of a ProviderRepository to manage DomainState and updates to OpenFeatureAPI and OpenFeatureClient to handle domain-specific logic. The review feedback highlights several critical issues regarding state isolation: specifically, ensuring that initialContext is bound to the correct domain, using domain-specific contexts during provider initialization and event tracking, and correctly propagating global context updates when no domain override exists. Additionally, there is a recommendation to handle dispatcher changes more dynamically within the domain state listener.

[typotter]

Spec 3.2.2.4 requires the API to have a mechanism to manage (create and remove) evaluation context for an associated domain.

There is no clearEvaluationContext(domain) method. Once domain context is set, it can be replaced but not cleared to revert to global fallback. Worth considering whether setEvaluationContext(domain, emptyContext) is sufficient or whether an explicit clear is needed.

[mstepien]

Spec 3.2.2.4 requires the API to have a mechanism to manage (create and remove) evaluation context for an associated domain.

There is no clearEvaluationContext(domain) method. Once domain context is set, it can be replaced but not cleared to revert to global fallback. Worth considering whether setEvaluationContext(domain, emptyContext) is sufficient or whether an explicit clear is needed.

fixed with ca14dfa

[mstepien]

2026-04-22-23 PR Update: Multi-Domain Isolation, Lifecycle Management, and Specification Compliance

This update brings core specification's requirements regarding isolated eventing, shared provider lifecycles, and evaluation context management.

Provider Lifecycle & Deduplication

• Thread-safe Shared Provider Tracking (Spec 1.1.2.3): Implemented global reference counting in ProviderRepository. OpenFeatureAPI now ensures a shared provider's shutdown() function is only invoked once the provider's global reference count across all domains safely reaches zero.
• Initialization Deduplication (Spec 1.1.2.2): Introduced Mutex-backed initialization tracking to guarantee that a provider bound to multiple domains is only actively initialized exactly once.
• Global Health Ledger (Spec 1.1.2.2): Created a centralized status tracker that securely syncs background health transitions (like ProviderError crashes or ProviderStale) across all active domains sharing a provider instance.
• Synthetic Event Emission: Ensures that domains successfully bypassing redundant initialization actively poll the global ledger and synthetically rebroadcast the synchronized state (e.g., ProviderReady) to their downstream clients.

Domain-Isolated Eventing

• Client Event Observability (Specs 5.2.1, 5.2.7): Added observeEvents() and observe<T>() APIs to the Client interface, natively routing domain-isolated provider events directly to end users.
• Context Event Generation (Specs 5.3.4.1-3): Hardened the setEvaluationContext workflow to securely isolate event emissions. It now emits ProviderReconciling prior to execution, ProviderContextChanged on success, and catches unhandled exceptions to emit ProviderError if a crash occurs within the provider's onContextSet.

Evaluation Context Management

• Domain Context Merging (Spec 3.2.3): Added context merging capabilities bound per domain, including an internal cache to eliminate garbage collection overhead during rapid, highly-concurrent flag evaluations.
• Context Teardown (Spec 3.2.2.4): Added the ability to clear and manage evaluation contexts natively per domain, fortified with granular contextMutex locks to prevent TOCTOU race condition deadlocks.

Architecture Hardening & Tech Debt

• State Encapsulation: Refactored architecture to hide internal state objects (DomainState) from the public API.
• Memory & Thread Safety: Memoized the defaultDomainState flow to prevent allocations, eliminated race conditions during rapid provider swapping, and ensured all phantom background observer coroutines cancel out completely upon OpenFeatureAPI.shutdown().