Sort external events dependencies

events-domain/src/main/java/io/split/android/client/events/SplitEventsManager.java

@@ -9,6 +9,7 @@
 import io.harness.events.EventHandler;
 import io.harness.events.EventsManager;
 import io.harness.events.EventsManagers;
+
 import io.split.android.client.api.EventMetadata;
 import io.split.android.client.events.executors.SplitEventExecutorResources;
 import io.split.android.client.events.executors.SplitEventExecutorResourcesImpl;

events-domain/src/test/java/io/split/android/client/events/SplitEventsManagerConfigFactoryTest.java

@@ -0,0 +1,214 @@
+package io.split.android.client.events;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+import org.junit.Test;
+
+import java.util.Set;
+
+import io.harness.events.EventsManagerConfig;
+
+public class SplitEventsManagerConfigFactoryTest {
+
+    @Test
+    public void configIsNotNull() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+        assertNotNull(config);
+    }
+
+    @Test
+    public void sdkReadyRequiresTargetingRulesSyncCompleteAndMembershipsSyncComplete() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Set<SplitInternalEvent> requireAll = config.getRequireAll().get(SplitEvent.SDK_READY);
+        assertNotNull("SDK_READY should have requireAll configuration", requireAll);
+        assertTrue("SDK_READY should require TARGETING_RULES_SYNC_COMPLETE",
+                requireAll.contains(SplitInternalEvent.TARGETING_RULES_SYNC_COMPLETE));
+        assertTrue("SDK_READY should require MEMBERSHIPS_SYNC_COMPLETE",
+                requireAll.contains(SplitInternalEvent.MEMBERSHIPS_SYNC_COMPLETE));
+        assertEquals("SDK_READY should require exactly 2 events", 2, requireAll.size());
+    }
+
+    @Test
+    public void sdkReadyHasPrerequisiteSdkReadyFromCache() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Set<SplitEvent> prerequisites = config.getPrerequisites().get(SplitEvent.SDK_READY);
+        assertNotNull("SDK_READY should have prerequisites", prerequisites);
+        assertTrue("SDK_READY should require SDK_READY_FROM_CACHE as prerequisite",
+                prerequisites.contains(SplitEvent.SDK_READY_FROM_CACHE));
+    }
+
+    @Test
+    public void sdkReadyHasExecutionLimitOne() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Integer limit = config.getExecutionLimits().get(SplitEvent.SDK_READY);
+        assertNotNull("SDK_READY should have execution limit", limit);
+        assertEquals("SDK_READY should fire at most once", 1, (int) limit);
+    }
+
+    @Test
+    public void sdkReadyFromCacheHasOrOfAndsConfiguration() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Set<Set<SplitInternalEvent>> requireAnyGroups = config.getRequireAny().get(SplitEvent.SDK_READY_FROM_CACHE);
+        assertNotNull("SDK_READY_FROM_CACHE should have requireAny configuration", requireAnyGroups);
+        assertEquals("SDK_READY_FROM_CACHE should have 2 groups (cache and sync)", 2, requireAnyGroups.size());
+
+        boolean hasCacheGroup = false;
+        boolean hasSyncGroup = false;
+        for (Set<SplitInternalEvent> group : requireAnyGroups) {
+            if (group.size() == 4 &&
+                    group.contains(SplitInternalEvent.SPLITS_LOADED_FROM_STORAGE) &&
+                    group.contains(SplitInternalEvent.MY_SEGMENTS_LOADED_FROM_STORAGE) &&
+                    group.contains(SplitInternalEvent.ATTRIBUTES_LOADED_FROM_STORAGE) &&
+                    group.contains(SplitInternalEvent.ENCRYPTION_MIGRATION_DONE)) {
+                hasCacheGroup = true;
+            }
+            if (group.size() == 2 &&
+                    group.contains(SplitInternalEvent.TARGETING_RULES_SYNC_COMPLETE) &&
+                    group.contains(SplitInternalEvent.MEMBERSHIPS_SYNC_COMPLETE)) {
+                hasSyncGroup = true;
+            }
+        }
+        assertTrue("SDK_READY_FROM_CACHE should have cache group", hasCacheGroup);
+        assertTrue("SDK_READY_FROM_CACHE should have sync group", hasSyncGroup);
+    }
+
+    @Test
+    public void sdkReadyFromCacheHasExecutionLimitOne() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Integer limit = config.getExecutionLimits().get(SplitEvent.SDK_READY_FROM_CACHE);
+        assertNotNull("SDK_READY_FROM_CACHE should have execution limit", limit);
+        assertEquals("SDK_READY_FROM_CACHE should fire at most once", 1, (int) limit);
+    }
+    @Test
+    public void sdkReadyTimedOutRequiresTimeoutReached() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Set<Set<SplitInternalEvent>> requireAnyGroups = config.getRequireAny().get(SplitEvent.SDK_READY_TIMED_OUT);
+        assertNotNull("SDK_READY_TIMED_OUT should have requireAny configuration", requireAnyGroups);
+
+        boolean hasTimeoutTrigger = false;
+        for (Set<SplitInternalEvent> group : requireAnyGroups) {
+            if (group.contains(SplitInternalEvent.SDK_READY_TIMEOUT_REACHED)) {
+                hasTimeoutTrigger = true;
+                break;
+            }
+        }
+        assertTrue("SDK_READY_TIMED_OUT should be triggered by SDK_READY_TIMEOUT_REACHED", hasTimeoutTrigger);
+    }
+
+    @Test
+    public void sdkReadyTimedOutIsSuppressedBySdkReady() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Set<SplitEvent> suppressors = config.getSuppressedBy().get(SplitEvent.SDK_READY_TIMED_OUT);
+        assertNotNull("SDK_READY_TIMED_OUT should have suppressors", suppressors);
+        assertTrue("SDK_READY_TIMED_OUT should be suppressed by SDK_READY",
+                suppressors.contains(SplitEvent.SDK_READY));
+    }
+
+    @Test
+    public void sdkReadyTimedOutHasExecutionLimitOne() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Integer limit = config.getExecutionLimits().get(SplitEvent.SDK_READY_TIMED_OUT);
+        assertNotNull("SDK_READY_TIMED_OUT should have execution limit", limit);
+        assertEquals("SDK_READY_TIMED_OUT should fire at most once", 1, (int) limit);
+    }
+
+    @Test
+    public void sdkUpdateHasCorrectTriggers() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Set<Set<SplitInternalEvent>> requireAnyGroups = config.getRequireAny().get(SplitEvent.SDK_UPDATE);
+        assertNotNull("SDK_UPDATE should have requireAny configuration", requireAnyGroups);
+
+        // Each trigger should be in its own singleton group
+        boolean hasSplitsUpdated = false;
+        boolean hasMySegmentsUpdated = false;
+        boolean hasMyLargeSegmentsUpdated = false;
+        boolean hasRuleBasedSegmentsUpdated = false;
+        boolean hasSplitKilledNotification = false;
+
+        for (Set<SplitInternalEvent> group : requireAnyGroups) {
+            if (group.size() == 1) {
+                if (group.contains(SplitInternalEvent.SPLITS_UPDATED)) hasSplitsUpdated = true;
+                if (group.contains(SplitInternalEvent.MY_SEGMENTS_UPDATED)) hasMySegmentsUpdated = true;
+                if (group.contains(SplitInternalEvent.MY_LARGE_SEGMENTS_UPDATED)) hasMyLargeSegmentsUpdated = true;
+                if (group.contains(SplitInternalEvent.RULE_BASED_SEGMENTS_UPDATED)) hasRuleBasedSegmentsUpdated = true;
+                if (group.contains(SplitInternalEvent.SPLIT_KILLED_NOTIFICATION)) hasSplitKilledNotification = true;
+            }
+        }
+
+        assertTrue("SDK_UPDATE should be triggered by SPLITS_UPDATED", hasSplitsUpdated);
+        assertTrue("SDK_UPDATE should be triggered by MY_SEGMENTS_UPDATED", hasMySegmentsUpdated);
+        assertTrue("SDK_UPDATE should be triggered by MY_LARGE_SEGMENTS_UPDATED", hasMyLargeSegmentsUpdated);
+        assertTrue("SDK_UPDATE should be triggered by RULE_BASED_SEGMENTS_UPDATED", hasRuleBasedSegmentsUpdated);
+        assertTrue("SDK_UPDATE should be triggered by SPLIT_KILLED_NOTIFICATION", hasSplitKilledNotification);
+    }
+
+    @Test
+    public void sdkUpdateHasPrerequisiteSdkReady() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Set<SplitEvent> prerequisites = config.getPrerequisites().get(SplitEvent.SDK_UPDATE);
+        assertNotNull("SDK_UPDATE should have prerequisites", prerequisites);
+        assertTrue("SDK_UPDATE should require SDK_READY as prerequisite",
+                prerequisites.contains(SplitEvent.SDK_READY));
+    }
+
+    @Test
+    public void sdkUpdateHasUnlimitedExecutions() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        Integer limit = config.getExecutionLimits().get(SplitEvent.SDK_UPDATE);
+        assertNotNull("SDK_UPDATE should have execution limit", limit);
+        assertEquals("SDK_UPDATE should have unlimited executions (-1)", -1, (int) limit);
+    }
+
+    @Test
+    public void evaluationOrderIsNotEmpty() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        assertNotNull("Evaluation order should not be null", config.getEvaluationOrder());
+        assertFalse("Evaluation order should not be empty", config.getEvaluationOrder().isEmpty());
+    }
+
+    @Test
+    public void evaluationOrderContainsAllConfiguredExternalEvents() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        assertTrue("Evaluation order should contain SDK_READY",
+                config.getEvaluationOrder().contains(SplitEvent.SDK_READY));
+        assertTrue("Evaluation order should contain SDK_READY_FROM_CACHE",
+                config.getEvaluationOrder().contains(SplitEvent.SDK_READY_FROM_CACHE));
+        assertTrue("Evaluation order should contain SDK_READY_TIMED_OUT",
+                config.getEvaluationOrder().contains(SplitEvent.SDK_READY_TIMED_OUT));
+        assertTrue("Evaluation order should contain SDK_UPDATE",
+                config.getEvaluationOrder().contains(SplitEvent.SDK_UPDATE));
+    }
+
+    @Test
+    public void evaluationOrderHasPrerequisitesBeforeDependents() {
+        EventsManagerConfig<SplitEvent, SplitInternalEvent> config = SplitEventsManagerConfigFactory.create();
+
+        // SDK_READY_FROM_CACHE must come before SDK_READY (prerequisite)
+        int readyFromCacheIndex = config.getEvaluationOrder().indexOf(SplitEvent.SDK_READY_FROM_CACHE);
+        int readyIndex = config.getEvaluationOrder().indexOf(SplitEvent.SDK_READY);
+        assertTrue("SDK_READY_FROM_CACHE should be evaluated before SDK_READY",
+                readyFromCacheIndex < readyIndex);
+
+        // SDK_READY must come before SDK_UPDATE (prerequisite)
+        int updateIndex = config.getEvaluationOrder().indexOf(SplitEvent.SDK_UPDATE);
+        assertTrue("SDK_READY should be evaluated before SDK_UPDATE",
+                readyIndex < updateIndex);
+    }
+}
+

events/README.md

@@ -3,3 +3,71 @@
 This module provides a generic events management system.
 
 Allows the definition of internal and external events interdependencies, as well as registration.
+
+## Core Concepts
+
+### Internal vs External Events
+
+- **Internal Events**: Low-level events triggered by the system (e.g., data loaded, sync completed)
+- **External Events**: High-level events exposed to consumers (e.g., SDK_READY, SDK_UPDATE)
+
+### Event Configuration
+
+Events are configured using `EventsManagerConfig.Builder`:
+
+- **`requireAll(external, internal...)`**: External event fires when ALL internal events have occurred
+- **`requireAny(external, internal...)`**: External event fires when ANY internal event occurs
+- **`requireAny(external, Set<internal>...)`**: OR-of-ANDs pattern; fires when any group is fully satisfied
+- **`prerequisite(external, prerequisiteExternal)`**: External event can only fire after the prerequisite external event has fired
+- **`suppressedBy(external, suppressorExternal)`**: External event is permanently suppressed if the suppressor external event has already fired
+- **`executionLimit(external, limit)`**: Max times the event can fire (-1 = unlimited, 1 = once only)
+
+## Topological Sort for Evaluation Order
+
+The events system uses **topological sorting** to determine the order in which external events are evaluated. This is essential for correctness.
+
+### Evaluation Flow
+
+1. **Internal Event Arrives**: A single internal event can potentially satisfy conditions for multiple external events.
+2. **Single-Pass Evaluation**: The system iterates through a pre-computed list of external events (`mEvaluationOrder`).
+3. **Order Matters**: This list is topologically sorted so that events with dependencies (prerequisites/suppression) come *after* the events they depend on.
+
+### Why It's Necessary
+
+When a single internal event notification could trigger multiple external events, they must be evaluated in the correct order based on their dependencies.
+
+#### Prerequisite Example
+
+```
+SDK_READY_FROM_CACHE  ←prerequisite←  SDK_READY
+```
+
+If both events' conditions are satisfied by the same internal event:
+
+- **Without sort**: If `SDK_READY` is checked first, `prerequisitesSatisfied()` returns `false` because `SDK_READY_FROM_CACHE` hasn't fired yet. `SDK_READY` misses its chance to fire in this cycle.
+- **With sort**: `SDK_READY_FROM_CACHE` is evaluated first, fires, then `SDK_READY` sees its prerequisite satisfied and fires—all in one pass.
+
+#### SuppressedBy Example
+
+```
+SDK_READY  ──suppressedBy──►  SDK_READY_TIMED_OUT
+```
+
+If both events' conditions are satisfied by the same internal event:
+
+- **Without sort**: If `SDK_READY_TIMED_OUT` is checked first, `isSuppressed()` returns `false` because `SDK_READY` hasn't fired yet. Both events fire incorrectly.
+- **With sort**: `SDK_READY` is evaluated first, fires, then `SDK_READY_TIMED_OUT` sees it's suppressed and doesn't fire.
+
+### Implementation Details
+
+The sorting logic is split into:
+
+- **`EventsManagerConfig`**: Holds the raw configuration.
+- **`EvaluationOrderComputer`**: Gathers all configured events and builds the dependency graph based on prerequisites and suppressors.
+- **`TopologicalSorter`**: A generic utility that performs the DFS-based topological sort with cycle detection.
+
+The topological sort treats both `prerequisite` and `suppressedBy` as dependency edges:
+- If A has `prerequisite` B → B must be evaluated before A
+- If A is `suppressedBy` B → B must be evaluated before A
+
+**Note:** All configured events are included in the evaluation order, even those without dependencies. Independent events can appear anywhere in the list relative to each other, but always before/after their dependents/dependencies as required.