28081952945

Committed 24 Jun 2026 07:16AM UTC coverage: 92.745% (+0.1%) from 92.602%

Build # 28081952945

Build Type

push

github

Committed by

Hyshmily

Commit Message

feat: add HotKeyPreload annotation, Intercept QPS-trigger mode

Signed-off-by: Hyshmily <cxm8607@outlook.com>

Coverage Stats

1199 of 1347 branches covered (89.01%)

Branch coverage included in aggregate %.

50 of 52 new or added lines in 2 files covered. (96.15%)

1 existing line in 1 file now uncovered.

3416 of 3629 relevant lines covered (94.13%)

4.25 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

69.23

/common/src/main/java/io/github/hyshmily/hotkey/autoconfigure/HotKeyRedisAutoConfiguration.java

/*
 * Copyright 2026 Hyshmily. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.github.hyshmily.hotkey.autoconfigure;

import com.github.benmanes.caffeine.cache.Cache;
import io.github.hyshmily.hotkey.HotKey;
import io.github.hyshmily.hotkey.cache.CacheExpireManager;
import io.github.hyshmily.hotkey.cache.HotKeyCache;
import io.github.hyshmily.hotkey.cache.SingleFlight;
import io.github.hyshmily.hotkey.hotkeydetector.HotKeyDetector;
import io.github.hyshmily.hotkey.reporting.HotKeyReporter;
import io.github.hyshmily.hotkey.rule.RuleMatcher;
import io.github.hyshmily.hotkey.sharding.RingManager;
import io.github.hyshmily.hotkey.sharding.ClusterHealthView;
import io.github.hyshmily.hotkey.sync.local.CacheSyncPublisher;
import io.github.hyshmily.hotkey.util.version.VersionController;
import java.util.Optional;
import java.util.concurrent.Executor;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.data.redis.core.StringRedisTemplate;

/**
 * Redis-enhanced auto-configuration that overrides the default
 * {@link HotKeyCache} with one that supports version-based stale detection.
 *
 * <p>Activates when a {@link RedisTemplate} bean is available.
 * {@link StringRedisTemplate} is injected as optional — if absent,
 * version tracking falls back to a node-local counter ({@link
 * io.github.hyshmily.hotkey.util.InstanceIdGenerator#getNodeId()} + {@link
 * java.util.concurrent.atomic.AtomicLong}) with a {@code Long.MIN_VALUE}
 * base, ensuring degraded versions from different JVMs occupy distinct ranges.
 *
 * <p>Runs <em>after</em> {@link HotKeyAutoConfiguration} so its
 * {@code @ConditionalOnMissingBean} on {@code hotKeyCache} wins over the
 * non-Redis variant, and after {@link RedisAutoConfiguration} so the Redis
 * infrastructure is ready.
 *
 * <p>Also creates a {@link RuleMatcher} with optional Redis persistence,
 * enabling rule CRUD operations to survive app restarts.
 */
@AutoConfiguration(after = { HotKeyAutoConfiguration.class, RedisAutoConfiguration.class })
@ConditionalOnClass(name = "org.springframework.data.redis.core.RedisTemplate")
@EnableConfigurationProperties(HotKeyProperties.class)
public class HotKeyRedisAutoConfiguration {

  /**
   * Create the {@link RuleMatcher} with optional Redis persistence and broadcast support.
   *
   * <p>When a {@link StringRedisTemplate} is available, rules (blacklist/whitelist)
   * are persisted in Redis under the key {@code hotkey:rules}, surviving app restarts.
   * When a {@link CacheSyncPublisher} is available, rule changes are broadcast to
   * peer instances for cluster-wide consistency.
   *
   * @param redisTemplateProvider optional provider for StringRedisTemplate (Redis persistence);
   *                              may be absent
   * @param publisherProvider     optional provider for the cache sync publisher (cross-instance
   *                              broadcast); may be absent
   * @return a new RuleMatcher instance with optional Redis-backed persistence
   */
  @Bean
  @ConditionalOnMissingBean
  public RuleMatcher ruleMatcher(
    ObjectProvider<StringRedisTemplate> redisTemplateProvider,
    ObjectProvider<CacheSyncPublisher> publisherProvider
  ) {
    return new RuleMatcher(
      Optional.ofNullable(redisTemplateProvider.getIfAvailable()),
      Optional.ofNullable(publisherProvider.getIfAvailable())
    );
  }

  /**
   * Create the Redis-enhanced {@link HotKeyCache} with version-based stale detection.
   *
   * <p>The {@link StringRedisTemplate} is optional — if absent, version tracking falls
   * back to a node-local counter ({@code Long.MIN_VALUE + nodeId + counter}), ensuring
   * graceful degradation when Redis is temporarily unavailable. The full HotKeyCache
   * pipeline includes: TopK detection, L1 Caffeine, SingleFlight dedup, soft/hard
   * expiry, cross-instance sync, reporting, rule matching, and consistent-hash routing.
   *
   * @param hotKeyDetector     the app-side TopK detector for hot-key frequency tracking
   * @param hotLocalCache      the L1 Caffeine cache (shared across all keys)
   * @param singleFlight       the deduplication layer for concurrent cache-load requests
   * @param expireManager      the soft/hard expiration manager for TTL control
   * @param syncPublisher      optional cache sync publisher for cross-instance broadcast
   * @param hotKeyReporter     optional hot key reporter for app-to-Worker data flow
   * @param hotKeyExecutor     the dedicated HotKey async executor
   * @param redisTemplateProvider optional provider for StringRedisTemplate (version tracking);
   *                              may be absent
   * @param properties         the HotKey configuration properties
   * @param ruleMatcher        the rule matcher for blacklist/whitelist evaluation
   * @return a new Redis-backed HotKeyCache instance
   */
  @Bean
  @ConditionalOnMissingBean
  @ConditionalOnBean(RedisTemplate.class)
  @ConditionalOnClass(HotKeyDetector.class)
  @SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection")
  public HotKeyCache hotKeyCache(
    @Qualifier("hotKeyDetector") HotKeyDetector hotKeyDetector,
    Cache<String, Object> hotLocalCache,
    SingleFlight singleFlight,
    CacheExpireManager expireManager,
    Optional<CacheSyncPublisher> syncPublisher,
    Optional<HotKeyReporter> hotKeyReporter,
    @Qualifier("hotKeyExecutor") Executor hotKeyExecutor,
    ObjectProvider<StringRedisTemplate> redisTemplateProvider,
    HotKeyProperties properties,
    RuleMatcher ruleMatcher,
    ObjectProvider<ClusterHealthView> healthViewProvider
  ) {
    return new HotKeyCache(
      hotKeyDetector,
      hotLocalCache,
      singleFlight,
      expireManager,
      hotKeyExecutor,
      syncPublisher,
      hotKeyReporter,
      ruleMatcher,
      new VersionController(
        Optional.ofNullable(redisTemplateProvider.getIfAvailable()),
        properties.getVersionKeyTtlMinutes()
      ),
      healthViewProvider.getIfAvailable(() ->
        new ClusterHealthView(
          properties.getExpectedWorkerCount(),
          properties.getHeartbeat().getTimeoutMs(),
          properties.getHeartbeat().getDegradeAfterFailures()
        )
      )
    );
  }

  /**
   * Fallback {@link HotKey} facade bean for the Redis-enhanced path.
   *
   * <p>Only active when a {@link HotKeyCache} bean exists but no {@link HotKey}
   * has been defined yet. This covers the case where the primary
   * {@link HotKeyFacadeAutoConfiguration} is excluded and the {@link HotKeyCache}
   * originates from this configuration. The returned facade provides the full
   * public API including read/write/invalidate operations, TopK introspection,
   * and rule management.
   *
   * @param hotKeyCache    the Redis-backed HotKeyCache instance (never {@code null})
   * @param hotKeyDetector the app-side TopK detector (never {@code null})
   * @return a new HotKey facade instance
   */
  @Bean
  @ConditionalOnBean(HotKeyCache.class)
  @ConditionalOnMissingBean
  public HotKey hotKey(HotKeyCache hotKeyCache, @Qualifier("hotKeyDetector") HotKeyDetector hotKeyDetector) {
    return new HotKey(hotKeyCache, hotKeyDetector, null);
  }
}

1	/*
2	* Copyright 2026 Hyshmily. All Rights Reserved.
3	*
4	* Licensed under the Apache License, Version 2.0 (the "License");
5	* you may not use this file except in compliance with the License.
6	* You may obtain a copy of the License at
7	*
8	* http://www.apache.org/licenses/LICENSE-2.0
9	*
10	* Unless required by applicable law or agreed to in writing, software
11	* distributed under the License is distributed on an "AS IS" BASIS,
12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13	* See the License for the specific language governing permissions and
14	* limitations under the License.
15	*/
16	package io.github.hyshmily.hotkey.autoconfigure;
17
18	import com.github.benmanes.caffeine.cache.Cache;
19	import io.github.hyshmily.hotkey.HotKey;
20	import io.github.hyshmily.hotkey.cache.CacheExpireManager;
21	import io.github.hyshmily.hotkey.cache.HotKeyCache;
22	import io.github.hyshmily.hotkey.cache.SingleFlight;
23	import io.github.hyshmily.hotkey.hotkeydetector.HotKeyDetector;
24	import io.github.hyshmily.hotkey.reporting.HotKeyReporter;
25	import io.github.hyshmily.hotkey.rule.RuleMatcher;
26	import io.github.hyshmily.hotkey.sharding.RingManager;
27	import io.github.hyshmily.hotkey.sharding.ClusterHealthView;
28	import io.github.hyshmily.hotkey.sync.local.CacheSyncPublisher;
29	import io.github.hyshmily.hotkey.util.version.VersionController;
30	import java.util.Optional;
31	import java.util.concurrent.Executor;
32	import org.springframework.beans.factory.ObjectProvider;
33	import org.springframework.beans.factory.annotation.Qualifier;
34	import org.springframework.boot.autoconfigure.AutoConfiguration;
35	import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
36	import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
37	import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
38	import org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration;
39	import org.springframework.boot.context.properties.EnableConfigurationProperties;
40	import org.springframework.context.annotation.Bean;
41	import org.springframework.data.redis.core.RedisTemplate;
42	import org.springframework.data.redis.core.StringRedisTemplate;
43
44	/**
45	* Redis-enhanced auto-configuration that overrides the default
46	* {@link HotKeyCache} with one that supports version-based stale detection.
47	*
48	* <p>Activates when a {@link RedisTemplate} bean is available.
49	* {@link StringRedisTemplate} is injected as optional — if absent,
50	* version tracking falls back to a node-local counter ({@link
51	* io.github.hyshmily.hotkey.util.InstanceIdGenerator#getNodeId()} + {@link
52	* java.util.concurrent.atomic.AtomicLong}) with a {@code Long.MIN_VALUE}
53	* base, ensuring degraded versions from different JVMs occupy distinct ranges.
54	*
55	* <p>Runs <em>after</em> {@link HotKeyAutoConfiguration} so its
56	* {@code @ConditionalOnMissingBean} on {@code hotKeyCache} wins over the
57	* non-Redis variant, and after {@link RedisAutoConfiguration} so the Redis
58	* infrastructure is ready.
59	*
60	* <p>Also creates a {@link RuleMatcher} with optional Redis persistence,
61	* enabling rule CRUD operations to survive app restarts.
62	*/
63	@AutoConfiguration(after = { HotKeyAutoConfiguration.class, RedisAutoConfiguration.class })
64	@ConditionalOnClass(name = "org.springframework.data.redis.core.RedisTemplate")
65	@EnableConfigurationProperties(HotKeyProperties.class)
66	public class HotKeyRedisAutoConfiguration {	3✔
67
68	/**
69	* Create the {@link RuleMatcher} with optional Redis persistence and broadcast support.
70	*
71	* <p>When a {@link StringRedisTemplate} is available, rules (blacklist/whitelist)
72	* are persisted in Redis under the key {@code hotkey:rules}, surviving app restarts.
73	* When a {@link CacheSyncPublisher} is available, rule changes are broadcast to
74	* peer instances for cluster-wide consistency.
75	*
76	* @param redisTemplateProvider optional provider for StringRedisTemplate (Redis persistence);
77	* may be absent
78	* @param publisherProvider optional provider for the cache sync publisher (cross-instance
79	* broadcast); may be absent
80	* @return a new RuleMatcher instance with optional Redis-backed persistence
81	*/
82	@Bean
83	@ConditionalOnMissingBean
84	public RuleMatcher ruleMatcher(
85	ObjectProvider<StringRedisTemplate> redisTemplateProvider,
86	ObjectProvider<CacheSyncPublisher> publisherProvider
87	) {
88	return new RuleMatcher(	4✔
89	Optional.ofNullable(redisTemplateProvider.getIfAvailable()),	4✔
90	Optional.ofNullable(publisherProvider.getIfAvailable())	4✔
91	);
92	}
93
94	/**
95	* Create the Redis-enhanced {@link HotKeyCache} with version-based stale detection.
96	*
97	* <p>The {@link StringRedisTemplate} is optional — if absent, version tracking falls
98	* back to a node-local counter ({@code Long.MIN_VALUE + nodeId + counter}), ensuring
99	* graceful degradation when Redis is temporarily unavailable. The full HotKeyCache
100	* pipeline includes: TopK detection, L1 Caffeine, SingleFlight dedup, soft/hard
101	* expiry, cross-instance sync, reporting, rule matching, and consistent-hash routing.
102	*
103	* @param hotKeyDetector the app-side TopK detector for hot-key frequency tracking
104	* @param hotLocalCache the L1 Caffeine cache (shared across all keys)
105	* @param singleFlight the deduplication layer for concurrent cache-load requests
106	* @param expireManager the soft/hard expiration manager for TTL control
107	* @param syncPublisher optional cache sync publisher for cross-instance broadcast
108	* @param hotKeyReporter optional hot key reporter for app-to-Worker data flow
109	* @param hotKeyExecutor the dedicated HotKey async executor
110	* @param redisTemplateProvider optional provider for StringRedisTemplate (version tracking);
111	* may be absent
112	* @param properties the HotKey configuration properties
113	* @param ruleMatcher the rule matcher for blacklist/whitelist evaluation
114	* @return a new Redis-backed HotKeyCache instance
115	*/
116	@Bean
117	@ConditionalOnMissingBean
118	@ConditionalOnBean(RedisTemplate.class)
119	@ConditionalOnClass(HotKeyDetector.class)
120	@SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection")
121	public HotKeyCache hotKeyCache(
122	@Qualifier("hotKeyDetector") HotKeyDetector hotKeyDetector,
123	Cache<String, Object> hotLocalCache,
124	SingleFlight singleFlight,
125	CacheExpireManager expireManager,
126	Optional<CacheSyncPublisher> syncPublisher,
127	Optional<HotKeyReporter> hotKeyReporter,
128	@Qualifier("hotKeyExecutor") Executor hotKeyExecutor,
129	ObjectProvider<StringRedisTemplate> redisTemplateProvider,
130	HotKeyProperties properties,
131	RuleMatcher ruleMatcher,
132	ObjectProvider<ClusterHealthView> healthViewProvider
133	) {
134	return new HotKeyCache(	14✔
135	hotKeyDetector,
136	hotLocalCache,
137	singleFlight,
138	expireManager,
139	hotKeyExecutor,
140	syncPublisher,
141	hotKeyReporter,
142	ruleMatcher,
143	new VersionController(
144	Optional.ofNullable(redisTemplateProvider.getIfAvailable()),	4✔
145	properties.getVersionKeyTtlMinutes()	5✔
146	),
147	healthViewProvider.getIfAvailable(() ->	3✔
UNCOV 148	new ClusterHealthView(	×
149	properties.getExpectedWorkerCount(),	×
150	properties.getHeartbeat().getTimeoutMs(),	×
151	properties.getHeartbeat().getDegradeAfterFailures()	×
152	)
153	)
154	);
155	}
156
157	/**
158	* Fallback {@link HotKey} facade bean for the Redis-enhanced path.
159	*
160	* <p>Only active when a {@link HotKeyCache} bean exists but no {@link HotKey}
161	* has been defined yet. This covers the case where the primary
162	* {@link HotKeyFacadeAutoConfiguration} is excluded and the {@link HotKeyCache}
163	* originates from this configuration. The returned facade provides the full
164	* public API including read/write/invalidate operations, TopK introspection,
165	* and rule management.
166	*
167	* @param hotKeyCache the Redis-backed HotKeyCache instance (never {@code null})
168	* @param hotKeyDetector the app-side TopK detector (never {@code null})
169	* @return a new HotKey facade instance
170	*/
171	@Bean
172	@ConditionalOnBean(HotKeyCache.class)
173	@ConditionalOnMissingBean
174	public HotKey hotKey(HotKeyCache hotKeyCache, @Qualifier("hotKeyDetector") HotKeyDetector hotKeyDetector) {
175	return new HotKey(hotKeyCache, hotKeyDetector, null);	7✔
176	}
177	}

Hyshmily / hotkey / 28081952945

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous