enhance: delay too close events in cas

Signed-off-by: Cloorc <wittcnezh@foxmail.com>

Author: cloorc

README.md

@@ -15,6 +15,18 @@ A highly efficient, scalable rule matching engine built in Go that supports dyna
 - **Multi-Level Caching**: L1/L2 cache system with configurable TTL
 - **Production Validated**: Tested with 50k rules, 20 dimensions on 2 cores within 4GB memory
 
+### Benchmarks (September 2025)
+
+Collected on Linux (Intel(R) Xeon(R) CPU E5-2690 v2 @ 3.00GHz) using `go test -bench . -benchmem`.
+
+- Query performance (BenchmarkQueryPerformance): 62,754 ns/op, 2,201 B/op, 42 allocs/op (n=19,257).
+- Memory efficiency (measured in performance_test.go):
+    - Small (1k rules, 5 dims): total ≈ 3.41 MB (≈ 3,576 bytes/rule).
+    - Medium (10k rules, 10 dims): total ≈ 71.49 MB (≈ 7,496 bytes/rule).
+    - Large (50k rules, 15 dims): total ≈ 578.14 MB (≈ 12,124 bytes/rule).
+
+Notes: benchmark scenarios and memory measurements are implemented in `performance_test.go`. Run the full benchmark suite locally with `go test -run ^$ -bench . -benchmem ./...` to reproduce these numbers on your hardware.
+
 ### Flexible Rule System
 
 - **Dynamic Dimensions**: Add, remove, and reorder dimensions at runtime
@@ -735,6 +747,17 @@ BenchmarkQueryPerformance-2    39068    168994 ns/op
 - **5,917 QPS** sustained performance in benchmark conditions
 - Thread-safe concurrent operations validated
 
+### Latest benchmark run (captured)
+
+The most recent benchmark run (environment: Linux, Intel Xeon E5-2690 v2) produced these representative numbers:
+
+- Query performance: ~46,977 ns/op (≈47µs) with 2,136 B/op and 41 allocs/op (BenchmarkQueryPerformance)
+- Memory per rule (small - 1k rules, 5 dims): ~3.5 KB per rule
+- Memory per rule (medium - 10k rules, 10 dims): ~7.48 KB per rule (≈71.3 MB total)
+- Memory per rule (large - 50k rules, 15 dims): ~12.13 KB per rule (≈578.5 MB total)
+
+See `docs/LATEST_BENCH.txt` for full raw output of the benchmark run.
+
 ### Performance Scaling Analysis
 
 The system demonstrates excellent scaling characteristics:

api.go

@@ -213,21 +213,32 @@ func (me *MatcherEngine) AddDimension(config *DimensionConfig) error {
 // SetAllowDuplicateWeights configures whether rules with duplicate weights are allowed
 // By default, duplicate weights are not allowed to ensure deterministic matching
 func (me *MatcherEngine) SetAllowDuplicateWeights(allow bool) {
-	me.matcher.mu.Lock()
-	defer me.matcher.mu.Unlock()
-	me.matcher.allowDuplicateWeights = allow
+	me.matcher.SetAllowDuplicateWeights(allow)
 }
 
 // FindBestMatch finds the best matching rule for a query
 func (me *MatcherEngine) FindBestMatch(query *QueryRule) (*MatchResult, error) {
 	return me.matcher.FindBestMatch(query)
 }
 
+// FindBestMatchInBatch runs multiple queries under a single matcher read-lock and
+// returns the best match for each query in the same order. This provides an
+// atomic snapshot view for a group of queries with respect to concurrent
+// updates.
+func (me *MatcherEngine) FindBestMatchInBatch(queries ...*QueryRule) ([]*MatchResult, error) {
+	return me.matcher.FindBestMatchInBatch(queries)
+}
+
 // FindAllMatches finds all matching rules for a query
 func (me *MatcherEngine) FindAllMatches(query *QueryRule) ([]*MatchResult, error) {
 	return me.matcher.FindAllMatches(query)
 }
 
+// FindAllMatches finds all matching rules for a query
+func (me *MatcherEngine) FindAllMatchesInBatch(query ...*QueryRule) ([][]*MatchResult, error) {
+	return me.matcher.FindAllMatchesInBatch(query)
+}
+
 // ListRules returns all rules with pagination
 func (me *MatcherEngine) ListRules(offset, limit int) ([]*Rule, error) {
 	return me.matcher.ListRules(offset, limit)

concurrency_test.go

@@ -1837,33 +1837,32 @@ func TestQueryDuringUpdateConsistency(t *testing.T) {
 			queryB := &QueryRule{Values: map[string]string{"region": "us-east", "env": "staging"}}
 
 			for j := 0; j < 1000; j++ {
-				// Try both queries
-				matchesA, errA := engine.FindAllMatches(queryA)
-				matchesB, errB := engine.FindAllMatches(queryB)
-
-				if errA != nil {
-					addIssue(fmt.Sprintf("Query worker %d: QueryA failed: %v", queryID, errA))
-				}
-				if errB != nil {
-					addIssue(fmt.Sprintf("Query worker %d: QueryB failed: %v", queryID, errB))
+				// Try both queries atomically with respect to updates using the
+				// engine-provided helper so test code doesn't need to access
+				// internal locks directly.
+				matches, err := engine.FindAllMatchesInBatch(queryA, queryB)
+				if err != nil {
+					// If helper returned a single error, map it conservatively
+					// to errA for reporting; callers will check both.
+					addIssue(fmt.Sprintf("Query worker %d: Queries failed: %v", queryID, err))
 				}
 
 				// At any given time, exactly one of these queries should match
 				// (unless the rule is temporarily not in the forest during update)
-				totalMatches := len(matchesA) + len(matchesB)
+				totalMatches := len(matches[0]) + len(matches[1])
 
 				if totalMatches > 1 {
 					addIssue(fmt.Sprintf("Query worker %d: Found matches for both queries simultaneously (matchesA=%d, matchesB=%d)",
-						queryID, len(matchesA), len(matchesB)))
+						queryID, len(matches[0]), len(matches[1])))
 				}
 
 				// Validate any returned matches are complete
-				for _, match := range matchesA {
+				for _, match := range matches[0] {
 					if match.Rule.ID != "query-consistency-test" {
 						addIssue(fmt.Sprintf("Query worker %d: Wrong rule ID in matchA: %s", queryID, match.Rule.ID))
 					}
 				}
-				for _, match := range matchesB {
+				for _, match := range matches[1] {
 					if match.Rule.ID != "query-consistency-test" {
 						addIssue(fmt.Sprintf("Query worker %d: Wrong rule ID in matchB: %s", queryID, match.Rule.ID))
 					}
@@ -2131,31 +2130,24 @@ func TestAtomicRuleUpdateFix(t *testing.T) {
 				"region": "us-east", "env": "staging", "service": "web"}}
 
 			for j := 0; j < 250; j++ {
-				// Check version 1 query
-				matches1, err1 := engine.FindAllMatches(queryV1)
-				if err1 != nil {
-					addInconsistency("FindAllMatches query V1 failed")
-				}
-
-				// Check version 2 query
-				matches2, err2 := engine.FindAllMatches(queryV2)
-				if err2 != nil {
-					addInconsistency("FindAllMatches query V2 failed")
+				matches, err := engine.FindAllMatchesInBatch(queryV1, queryV2)
+				if err != nil {
+					addInconsistency("FindAllMatches query failed")
 				}
 
 				// At any point in time, exactly one version should match (or neither during transition)
-				totalMatches := len(matches1) + len(matches2)
+				totalMatches := len(matches[0]) + len(matches[1])
 				if totalMatches > 1 {
 					addInconsistency("FindAllMatches: Both queries returned matches simultaneously")
 				}
 
 				// Validate consistency of any returned matches
-				for _, match := range matches1 {
+				for _, match := range matches[0] {
 					if match.Rule.Metadata["config"] != "version-1" {
 						addInconsistency("FindAllMatches: V1 query returned non-V1 rule")
 					}
 				}
-				for _, match := range matches2 {
+				for _, match := range matches[1] {
 					if match.Rule.Metadata["config"] != "version-2" {
 						addInconsistency("FindAllMatches: V2 query returned non-V2 rule")
 					}

matcher.go

@@ -617,11 +617,11 @@ func (m *InMemoryMatcher) deleteDimension(dimensionName string) error {
 // FindBestMatch finds the best matching rule for a query
 func (m *InMemoryMatcher) FindBestMatch(query *QueryRule) (*MatchResult, error) {
 	start := time.Now()
-	
+
 	// Update query count using atomic operation (no lock needed)
 	atomic.AddInt64(&m.stats.TotalQueries, 1)
 
-	// Check cache first
+	// Check cache first while holding read lock
 	if result := m.cache.Get(query); result != nil {
 		m.updateCacheStats(true)
 		// Update average query time without lock
@@ -631,8 +631,15 @@ func (m *InMemoryMatcher) FindBestMatch(query *QueryRule) (*MatchResult, error)
 
 	m.updateCacheStats(false)
 
-	// Find all matches
-	matches, err := m.FindAllMatches(query)
+	// Acquire read lock for the entire lookup path so the cache check,
+	// candidate computation and cache population happen with a consistent
+	// view of the authoritative state. This prevents races where an
+	// UpdateRule can interleave and make the query observe partial updates.
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	// Find all matches while holding the read lock using the nop-lock helper
+	matches, err := m.findAllMatchesNoLock(query)
 	if err != nil {
 		// Update average query time without lock
 		m.updateQueryTimeStats(time.Since(start))
@@ -647,7 +654,7 @@ func (m *InMemoryMatcher) FindBestMatch(query *QueryRule) (*MatchResult, error)
 
 	best := matches[0] // already sorted
 
-	// Cache the result
+	// Cache the result (safe because we used read lock while computing matches)
 	m.cache.Set(query, best)
 
 	// Update average query time without lock
@@ -662,13 +669,47 @@ func (m *InMemoryMatcher) updateQueryTimeStats(queryTime time.Duration) {
 	// to avoid taking locks in the read path. This trades off some precision for
 	// better concurrency performance and prevents read starvation.
 	// The stats will be updated during rebuild, add/update/delete operations.
+	atomic.AddInt64(&m.stats.TotalQueryTime, queryTime.Milliseconds())
 }
 
 // FindAllMatches finds all matching rules for a query
 func (m *InMemoryMatcher) FindAllMatches(query *QueryRule) ([]*MatchResult, error) {
+	// RLocked compatibility wrapper: acquire read lock and call helper
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	return m.findAllMatchesNoLock(query)
+}
+
+// FindAllMatchesInBatch finds the best matching rule for each query in the provided
+// slice and returns results in the same order. The entire operation is
+// performed while holding the matcher's read lock so the caller sees a
+// consistent snapshot with respect to concurrent updates.
+func (m *InMemoryMatcher) FindAllMatchesInBatch(queries []*QueryRule) ([][]*MatchResult, error) {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 
+	results := make([][]*MatchResult, len(queries))
+
+	for i, q := range queries {
+		matches, err := m.findAllMatchesNoLock(q)
+		if err != nil {
+			return nil, err
+		}
+
+		if len(matches) == 0 {
+			results[i] = nil
+			continue
+		}
+
+		results[i] = matches
+	}
+
+	return results, nil
+}
+
+// findAllMatchesNoLock performs the match candidate verification without taking locks.
+// Caller must hold appropriate locks (RLock/RWMutex) if concurrency safety is required.
+func (m *InMemoryMatcher) findAllMatchesNoLock(query *QueryRule) ([]*MatchResult, error) {
 	// Get candidate rules from appropriate forest index
 	forestIndex := m.getForestIndex(query.TenantID, query.ApplicationID)
 	var candidates []RuleWithWeight
@@ -682,7 +723,7 @@ func (m *InMemoryMatcher) FindAllMatches(query *QueryRule) ([]*MatchResult, erro
 
 	var matches []*MatchResult
 
-	// ATOMIC CONSISTENCY: Double-check approach to prevent race conditions
+	// Double-check approach to prevent race conditions
 	// For each candidate from forest, verify it actually matches the query dimensions
 	// AND exists in m.rules AND its dimensions in m.rules still match the query
 	for _, candidate := range candidates {
@@ -720,6 +761,65 @@ func (m *InMemoryMatcher) FindAllMatches(query *QueryRule) ([]*MatchResult, erro
 	return matches, nil
 }
 
+// FindBestMatchInBatch finds the best matching rule for each query in the provided
+// slice and returns results in the same order. The entire operation is
+// performed while holding the matcher's read lock so the caller sees a
+// consistent snapshot with respect to concurrent updates.
+func (m *InMemoryMatcher) FindBestMatchInBatch(queries []*QueryRule) ([]*MatchResult, error) {
+	start := time.Now()
+
+	// Count these as queries (approximate) for stats
+	atomic.AddInt64(&m.stats.TotalQueries, int64(len(queries)))
+
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	results := make([]*MatchResult, len(queries))
+
+	// Collect items to cache after computing (we avoid mutating cache while
+	// holding the read lock in a way that could conflict with other writers).
+	type toCacheItem struct {
+		q    *QueryRule
+		best *MatchResult
+	}
+	var toCache []toCacheItem
+
+	for i, q := range queries {
+		// Check cache first
+		if res := m.cache.Get(q); res != nil {
+			m.updateCacheStats(true)
+			results[i] = res
+			continue
+		}
+
+		m.updateCacheStats(false)
+
+		matches, err := m.findAllMatchesNoLock(q)
+		if err != nil {
+			return nil, err
+		}
+
+		if len(matches) == 0 {
+			results[i] = nil
+			continue
+		}
+
+		best := matches[0]
+		results[i] = best
+		toCache = append(toCache, toCacheItem{q: q, best: best})
+	}
+
+	// Populate cache for computed results
+	for _, item := range toCache {
+		m.cache.Set(item.q, item.best)
+	}
+
+	// Update average query time without lock
+	m.updateQueryTimeStats(time.Since(start))
+
+	return results, nil
+}
+
 // dimensionsEqual checks if two rules have identical dimensions
 func (m *InMemoryMatcher) dimensionsEqual(rule1, rule2 *Rule) bool {
 	if len(rule1.Dimensions) != len(rule2.Dimensions) {
@@ -1044,12 +1144,25 @@ func (m *InMemoryMatcher) GetStats() *MatcherStats {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 
-	// Create a copy to avoid race conditions, using atomic read for TotalQueries
+	// Create a copy to avoid race conditions
 	stats := *m.stats
-	stats.TotalQueries = atomic.LoadInt64(&m.stats.TotalQueries)
+	// Guard against divide-by-zero when no queries have been recorded yet
+	if stats.TotalQueries > 0 {
+		stats.AverageQueryTime = stats.TotalQueryTime / stats.TotalQueries
+	} else {
+		stats.AverageQueryTime = 0
+	}
 	return &stats
 }
 
+// SetAllowDuplicateWeights configures whether rules with duplicate weights are allowed
+// By default, duplicate weights are not allowed to ensure deterministic matching
+func (m *InMemoryMatcher) SetAllowDuplicateWeights(allow bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.allowDuplicateWeights = allow
+}
+
 // SaveToPersistence saves current state to persistence layer
 func (m *InMemoryMatcher) SaveToPersistence() error {
 	m.mu.RLock()