diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java b/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java index 6b7176e6c..bec31078f 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java +++ b/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java @@ -72,8 +72,11 @@ public class AdminApiGuardFilter extends OncePerRequestFilter { *

原因:桌面客户端(Python)直连这些接口且不带任何认证头,先于客户端发布开启会 * 让线上集采/跟价全线 401。待携带 X-Internal-Token 的新客户端铺开后,把开关置 true * (或把这些前缀从 USER_TOOL_PREFIXES 移除、直接无条件纳入)即可完成收紧。 + * + *

包级可见(不是 private):{@code ClientVersionGuardFilter} 复用同一份"桌面客户端直连的 + * 用户态前缀"口径。**这份清单改动会同时改动两个闸门的覆盖面**,改前先想清楚版本地板是否也该跟着变。 */ - private static final String[] USER_TOOL_PREFIXES = { + static final String[] USER_TOOL_PREFIXES = { "/api/collect-data", "/api/price-track", // 2026-09 全维度审查补:以下前缀此前完全在守卫范围之外。 diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java b/backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java new file mode 100644 index 000000000..d1b2ee79c --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java @@ -0,0 +1,291 @@ +package com.nanri.aiimage.config; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.nanri.aiimage.common.api.ApiResponse; +import io.micrometer.core.instrument.Counter; +import io.micrometer.core.instrument.MeterRegistry; +import jakarta.servlet.FilterChain; +import jakarta.servlet.ServletException; +import jakarta.servlet.http.HttpServletRequest; +import jakarta.servlet.http.HttpServletResponse; +import lombok.extern.slf4j.Slf4j; +import org.springframework.beans.factory.ObjectProvider; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.beans.factory.annotation.Value; +import org.springframework.core.Ordered; +import org.springframework.core.annotation.Order; +import org.springframework.stereotype.Component; +import org.springframework.web.filter.OncePerRequestFilter; + +import java.io.IOException; +import java.util.LinkedHashMap; +import java.util.Map; +import java.util.Set; +import java.util.concurrent.ConcurrentHashMap; + +/** + * 客户端版本硬地板:桌面客户端(ShuFuAI)上报的 {@value #HEADER} 低于服务端最低支持版本时的判定点。 + * + *

此前全仓唯一的 {@code minClientVersion} 在 digitalhuman 模块里,而且只是个**存进库又原样 + * 吐回 VO 的字段**({@code DigitalHumanVersionService:86} 写入、{@code :258} 读出,两处都是透传, + * 全树没有一处比较过它),对桌面客户端的 API 面零约束。本类是那个缺口的真闸门。 + * + *

三档开关,默认态 = **现网零行为变更**: + *

+ * 判不出来的头({@code "abc"}、{@code "4.x.6"})永不被拒,只进 {@code unparsable} 计数: + * 一次格式异常不该由客户端承担断服代价。 + * + *

受管前缀取自 {@link AdminApiGuardFilter#USER_TOOL_PREFIXES}(**同一份出处**,不复制清单: + * 那份常量记的正是"桌面客户端直连的用户态接口"),另加 {@value #CLIENT_ENTRY_PREFIX} + * ({@code /api/client}——客户端取凭据的第一跳,不在那份名单里,但它同样得能被地板挡住)。 + * {@code /api/version/**}(更新检查)与 {@code /api/admin/**}、{@code /api/internal/**} 一律**不在** + * 受管集合内:被拒的老客户端必须永远能拿到升级信息,否则闸门把自己变成砖。 + * + *

响应体沿用项目约定(HTTP 200 + {@code {success:false, code, message, data}},与 + * {@code GlobalExceptionHandler} 同形),业务码 {@value #CODE_TOO_OLD}:401/403 已被鉴权与 + * 越权占用,4011 是被顶下线,这里取同一族的 4012。 + * + *

紧急回退:把 {@code min-supported-version} 置空即可(无需重启改代码),或 + * {@code aiimage.client-version.enforce=false} 退回纯记账。 + */ +@Slf4j +@Component +@Order(Ordered.LOWEST_PRECEDENCE) +public class ClientVersionGuardFilter extends OncePerRequestFilter { + + /** 客户端自报版本的请求头(由 app_client 的 user_token 出口钩子注入,只对自家后端基址生效)。 */ + public static final String HEADER = "X-Client-Version"; + + /** 低于地板时的业务码;与 {@code DeviceSessionPolicy.CODE_KICKED=4011} 同族。 */ + public static final int CODE_TOO_OLD = 4012; + + /** 取凭据那一跳:桌面端入口,不在 {@link AdminApiGuardFilter#USER_TOOL_PREFIXES} 里,单独补上。 */ + static final String CLIENT_ENTRY_PREFIX = "/api/client"; + + /** 指标名:按 verdict(below/unreported/unparsable)与是否 enforce 打标签,装机分布由 version 标签给出。 */ + static final String METRIC = "aiimage.client.version.floor"; + + private static final String VERDICT_BELOW = "below"; + private static final String VERDICT_UNREPORTED = "unreported"; + private static final String VERDICT_UNPARSABLE = "unparsable"; + + /** WARN 去重上限:版本号是有限集合,超上限后不再新增键(只继续计数),防无界增长。 */ + private static final int WARN_KEYS_MAX = 64; + + private final ObjectMapper objectMapper; + private final MeterRegistry meterRegistry; + private final Set warned = ConcurrentHashMap.newKeySet(); + + @Value("${aiimage.client-version.min-supported-version:}") + private String minSupportedVersion; + + @Value("${aiimage.client-version.enforce:false}") + private boolean enforce; + + @Value("${aiimage.client-version.reject-unreported:false}") + private boolean rejectUnreported; + + public ClientVersionGuardFilter(ObjectMapper objectMapper) { + this(objectMapper, (MeterRegistry) null); + } + + public ClientVersionGuardFilter(ObjectMapper objectMapper, MeterRegistry meterRegistry) { + this.objectMapper = objectMapper; + this.meterRegistry = meterRegistry; + } + + /** 生产构造:Micrometer 注册表可选(无注册表时只留日志,与 {@code IdempotentRetryGuard} 同口径)。 */ + @Autowired + public ClientVersionGuardFilter(ObjectMapper objectMapper, + ObjectProvider meterRegistryProvider) { + this(objectMapper, meterRegistryProvider == null ? null : meterRegistryProvider.getIfAvailable()); + } + + /** 闸门是否已配置(最低版本非空)。空 = 惰性,现网默认态。 */ + public boolean isConfigured() { + return minSupportedVersion != null && !minSupportedVersion.trim().isEmpty(); + } + + @Override + protected boolean shouldNotFilter(HttpServletRequest request) { + return !isConfigured() || !isClientFacing(request.getRequestURI()); + } + + @Override + protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) + throws IOException, ServletException { + String uri = request.getRequestURI(); + String reported = headerValue(request); + String verdict = verdictOf(reported); + if (verdict == null) { + chain.doFilter(request, response); + return; + } + count(verdict, reported); + if (firstWitness(verdict, reported)) { + // 一次配置变更会被每个在跑的客户端逐请求命中:这里按 (verdict, version) 去重, + // 量交给指标,日志只留第一条(与 10-06 通知放大的处置同一口径)。 + log.warn("[版本地板] {} {} 自报版本={} 最低支持={} verdict={} enforce={} —— {}", + request.getMethod(), uri, reported, minSupportedVersion.trim(), verdict, enforce, + enforce ? "本次已拒绝" : "记账模式,暂不拒绝"); + } + if (shouldReject(verdict)) { + writeTooOld(request, response, reported, verdict); + return; + } + chain.doFilter(request, response); + } + + /** + * 归类:{@value #VERDICT_BELOW}/{@value #VERDICT_UNREPORTED}/{@value #VERDICT_UNPARSABLE}; + * 达标返回 null(什么都不做)。 + */ + private String verdictOf(String reported) { + long[] floor = parse(minSupportedVersion); + if (floor == null) { + // 配置本身写坏了(比如塞了个 "v4.0"):不猜、不拒,只记一条,等人工把配置改对。 + return isBlank(reported) ? null : VERDICT_UNPARSABLE; + } + if (isBlank(reported)) { + return VERDICT_UNREPORTED; + } + long[] actual = parse(reported); + if (actual == null) { + return VERDICT_UNPARSABLE; + } + return compare(actual, floor) < 0 ? VERDICT_BELOW : null; + } + + /** 只有"确实低于地板"(以及显式打开的 unreported)才拒;unparsable 永不被拒。 */ + private boolean shouldReject(String verdict) { + if (!enforce) { + return false; + } + if (VERDICT_BELOW.equals(verdict)) { + return true; + } + return VERDICT_UNREPORTED.equals(verdict) && rejectUnreported; + } + + /** 桌面客户端会走的入口前缀(含取凭据那一跳)。 */ + static boolean isClientFacing(String uri) { + if (uri == null) { + return false; + } + for (String prefix : AdminApiGuardFilter.USER_TOOL_PREFIXES) { + if (uri.startsWith(prefix)) { + return true; + } + } + return uri.startsWith(CLIENT_ENTRY_PREFIX); + } + + private static String headerValue(HttpServletRequest request) { + String raw = request.getHeader(HEADER); + return raw == null ? "" : raw.trim(); + } + + private static boolean isBlank(String value) { + return value == null || value.isEmpty(); + } + + /** + * 解析点分数字版本:{@code 4.0.46} → {@code [4,0,46]};任何一段非数字(含空串、{@code 4.x})返回 null。 + * 故意不做"取前缀数字"这类容错:猜出来的版本号会被当成合法装机统计进去。 + */ + static long[] parse(String version) { + if (version == null) { + return null; + } + String text = version.trim(); + if (text.isEmpty()) { + return null; + } + String[] parts = text.split("\\.", -1); + long[] segments = new long[parts.length]; + for (int i = 0; i < parts.length; i++) { + String part = parts[i].trim(); + if (part.isEmpty() || !isAllDigits(part)) { + return null; + } + try { + segments[i] = Long.parseLong(part); + } catch (NumberFormatException overflow) { + return null; + } + } + return segments; + } + + private static boolean isAllDigits(String text) { + for (int i = 0; i < text.length(); i++) { + if (text.charAt(i) < '0' || text.charAt(i) > '9') { + return false; + } + } + return true; + } + + /** 逐段比较,短的一方缺段按 0 补:{@code 4.0 == 4.0.0},{@code 4.0 < 4.0.1},{@code 4.0.46.2 > 4.0.46}。 */ + static int compare(long[] left, long[] right) { + int length = Math.max(left.length, right.length); + for (int i = 0; i < length; i++) { + long a = i < left.length ? left[i] : 0L; + long b = i < right.length ? right[i] : 0L; + if (a != b) { + return Long.compare(a, b); + } + } + return 0; + } + + /** 每个 (verdict, version) 组合只许第一条 WARN 通过;返回 true 表示"这次是第一条"。 */ + boolean firstWitness(String verdict, String version) { + String key = verdict + "@" + version; + if (warned.contains(key)) { + return false; + } + if (warned.size() >= WARN_KEYS_MAX) { + return false; + } + return warned.add(key); + } + + private void count(String verdict, String version) { + if (meterRegistry == null) { + return; + } + Counter.builder(METRIC) + .tag("verdict", verdict) + .tag("version", isBlank(version) ? "unknown" : version) + .tag("enforce", String.valueOf(enforce)) + .register(meterRegistry) + .increment(); + } + + private void writeTooOld(HttpServletRequest request, HttpServletResponse response, + String reported, String verdict) throws IOException { + Map data = new LinkedHashMap<>(); + data.put("minSupportedVersion", minSupportedVersion.trim()); + data.put("reportedVersion", reported); + data.put("verdict", verdict); + data.put("uri", request.getRequestURI()); + String message = VERDICT_UNREPORTED.equals(verdict) + ? "客户端版本未知(未上报 " + HEADER + "),请升级到 " + minSupportedVersion.trim() + " 及以上" + : "客户端版本过低(" + reported + "),请升级到 " + minSupportedVersion.trim() + " 及以上"; + response.setStatus(HttpServletResponse.SC_OK); + response.setContentType("application/json;charset=UTF-8"); + response.getWriter().write(objectMapper.writeValueAsString( + new ApiResponse<>(false, message, data, CODE_TOO_OLD))); + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/config/ClientVersionGuardFilterTest.java b/backend-java/src/test/java/com/nanri/aiimage/config/ClientVersionGuardFilterTest.java new file mode 100644 index 000000000..fe7565f83 --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/config/ClientVersionGuardFilterTest.java @@ -0,0 +1,267 @@ +package com.nanri.aiimage.config; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import io.micrometer.core.instrument.MeterRegistry; +import io.micrometer.core.instrument.simple.SimpleMeterRegistry; +import org.junit.jupiter.api.Test; +import org.springframework.mock.web.MockFilterChain; +import org.springframework.mock.web.MockHttpServletRequest; +import org.springframework.mock.web.MockHttpServletResponse; +import org.springframework.test.util.ReflectionTestUtils; + +import java.util.ArrayList; +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * 客户端版本硬地板判据:**两种模式各钉一条**,并证明默认态(min 未配置)逐请求等价于没装闸门。 + * + *

记账模式必须"只留痕不动响应"(chain 继续、响应体一个字节都不许多),执法模式必须"根本不放行" + * (chain 不前进 + 4012 体)。这两个断言分别挡住两类事故:只记账却顺手改了响应 = 现网故障; + * 想执法却只记了账 = 地板形同虚设。 + * + *

重跑:{@code mvn -o test -Dtest=ClientVersionGuardFilterTest}(cwd = backend-java)。 + */ +class ClientVersionGuardFilterTest { + + private final ObjectMapper objectMapper = new ObjectMapper(); + + private ClientVersionGuardFilter filter(String minVersion, boolean enforce, boolean rejectUnreported, + MeterRegistry registry) { + ClientVersionGuardFilter filter = new ClientVersionGuardFilter(objectMapper, registry); + ReflectionTestUtils.setField(filter, "minSupportedVersion", minVersion); + ReflectionTestUtils.setField(filter, "enforce", enforce); + ReflectionTestUtils.setField(filter, "rejectUnreported", rejectUnreported); + return filter; + } + + private ClientVersionGuardFilter accounting(String minVersion) { + return filter(minVersion, false, false, null); + } + + private ClientVersionGuardFilter enforcing(String minVersion) { + return filter(minVersion, true, false, null); + } + + private MockHttpServletRequest post(String uri, String reportedVersion) { + MockHttpServletRequest request = new MockHttpServletRequest("POST", uri); + if (reportedVersion != null) { + request.addHeader(ClientVersionGuardFilter.HEADER, reportedVersion); + } + return request; + } + + private long counterValue(MeterRegistry registry, String verdict, String version) { + io.micrometer.core.instrument.Counter counter = registry.find(ClientVersionGuardFilter.METRIC) + .tag("verdict", verdict).tag("version", version).counter(); + return counter == null ? 0L : (long) counter.count(); + } + + // ------------------------------------------------------------- 默认态:零行为变更 + + @Test + void minVersionUnsetMakesTheGateTotallyInert() throws Exception { + MeterRegistry registry = new SimpleMeterRegistry(); + ClientVersionGuardFilter filter = filter("", false, false, registry); + + // 一个明显"该被挡住"的老版本 + 一个不带版本的客户端核心入口:闸门惰性时都必须原样放行 + for (MockHttpServletRequest request : + new MockHttpServletRequest[]{post("/api/shop-match/tasks/1/result", "1.0.0"), + post("/api/client/credentials", null)}) { + MockHttpServletResponse response = new MockHttpServletResponse(); + MockFilterChain chain = new MockFilterChain(); + filter.doFilter(request, response, chain); + assertThat(chain.getRequest()).as("%s 应被放行", request.getRequestURI()).isNotNull(); + assertThat(response.getContentAsByteArray()).isEmpty(); + } + assertThat(registry.find(ClientVersionGuardFilter.METRIC).counter()).isNull(); + } + + @Test + void nonClientFacingPathsAreNeverJudged() throws Exception { + MeterRegistry registry = new SimpleMeterRegistry(); + ClientVersionGuardFilter filter = filter("4.0.46", true, true, registry); + + // 执法模式、且 unreported 也拒:这三类面一条都不许被 judge + for (MockHttpServletRequest request : new MockHttpServletRequest[]{ + post("/api/version/latest", "1.0.0"), + post("/api/admin/users", "1.0.0"), + post("/api/internal/user-proxy", null)}) { + MockHttpServletResponse response = new MockHttpServletResponse(); + MockFilterChain chain = new MockFilterChain(); + filter.doFilter(request, response, chain); + assertThat(chain.getRequest()).as("%s 不在受管面内", request.getRequestURI()).isNotNull(); + assertThat(response.getContentAsByteArray()).isEmpty(); + } + assertThat(registry.find(ClientVersionGuardFilter.METRIC).counter()).isNull(); + } + + // ------------------------------------------------------------- 记账模式(默认档位) + + @Test + void belowFloorInAccountingModeRecordsWithoutTouchingTheResponse() throws Exception { + MeterRegistry registry = new SimpleMeterRegistry(); + ClientVersionGuardFilter filter = filter("4.0.46", false, false, registry); + + MockFilterChain chain = new MockFilterChain(); + MockHttpServletResponse response = new MockHttpServletResponse(); + filter.doFilter(post("/api/publish/tasks/7/result", "4.0.45"), response, chain); + + assertThat(chain.getRequest()).as("记账模式不许截断请求").isNotNull(); + assertThat(response.getContentAsByteArray()).as("记账模式响应体必须一个字节都不许多").isEmpty(); + assertThat(counterValue(registry, "below", "4.0.45")).isEqualTo(1L); + } + + @Test + void accountingCountsEveryRequestButWarnsOncePerVersion() throws Exception { + MeterRegistry registry = new SimpleMeterRegistry(); + ClientVersionGuardFilter filter = filter("4.0.46", false, false, registry); + + // 同一个老客户端连打三次:指标必须数到 3(巡检看的是量),WARN 只许第一条 + for (int i = 0; i < 3; i++) { + filter.doFilter(post("/api/price-track/tasks/1/result", "4.0.40"), + new MockHttpServletResponse(), new MockFilterChain()); + } + assertThat(counterValue(registry, "below", "4.0.40")).as("日志去重不许把计数一起吞掉").isEqualTo(3L); + assertThat(filter.firstWitness("below", "4.0.40")).as("4.0.40 已经留过一条 WARN").isFalse(); + assertThat(filter.firstWitness("below", "4.0.41")).as("新出现过低版本应允许留第一条").isTrue(); + } + + @Test + void unreportedAndUnparsableBothLandInTheirOwnBuckets() throws Exception { + MeterRegistry registry = new SimpleMeterRegistry(); + ClientVersionGuardFilter filter = filter("4.0.46", false, false, registry); + + filter.doFilter(post("/api/brand/tasks", null), new MockHttpServletResponse(), new MockFilterChain()); + filter.doFilter(post("/api/brand/tasks", " "), new MockHttpServletResponse(), new MockFilterChain()); + filter.doFilter(post("/api/brand/tasks", "4.x.6"), new MockHttpServletResponse(), new MockFilterChain()); + + assertThat(counterValue(registry, "unreported", "unknown")).isEqualTo(2L); + assertThat(counterValue(registry, "unparsable", "4.x.6")).isEqualTo(1L); + assertThat(registry.find(ClientVersionGuardFilter.METRIC).tag("verdict", "below").counter()) + .as("报不出版本不等于版本低").isNull(); + } + + // ------------------------------------------------------------- 执法模式 + + @Test + void belowFloorInEnforceModeRefusesWithoutReachingTheController() throws Exception { + MeterRegistry registry = new SimpleMeterRegistry(); + ClientVersionGuardFilter filter = filter("4.0.46", true, false, registry); + MockHttpServletResponse response = new MockHttpServletResponse(); + MockFilterChain chain = new MockFilterChain(); + + filter.doFilter(post("/api/similar-asin/tasks/9/result", "4.0.44"), response, chain); + + assertThat(chain.getRequest()).as("执法模式必须截断,不能让老客户端进到 controller").isNull(); + JsonNode body = objectMapper.readTree(response.getContentAsString()); + assertThat(body.get("success").asBoolean()).isFalse(); + assertThat(body.get("code").asInt()).isEqualTo(ClientVersionGuardFilter.CODE_TOO_OLD); + assertThat(body.get("message").asText()).contains("客户端版本过低").contains("4.0.46"); + assertThat(body.get("data").get("minSupportedVersion").asText()).isEqualTo("4.0.46"); + assertThat(body.get("data").get("reportedVersion").asText()).isEqualTo("4.0.44"); + assertThat(counterValue(registry, "below", "4.0.44")).isEqualTo(1L); + } + + @Test + void unreportedOldInstallsAreSparedUntilTheSeparateSwitchIsFlipped() throws Exception { + MockFilterChain spared = new MockFilterChain(); + MockHttpServletResponse sparedResponse = new MockHttpServletResponse(); + // 存量装机不知道有这个头:光翻 enforce 就把它们判死 = 一次配置变更打停全线 + enforcing("4.0.46").doFilter(post("/api/shop-match/tasks/1/items", null), sparedResponse, spared); + assertThat(spared.getRequest()).as("reject-unreported 默认 false,未上报的装机不许被误杀").isNotNull(); + assertThat(sparedResponse.getContentAsByteArray()).isEmpty(); + + MeterRegistry registry = new SimpleMeterRegistry(); + ClientVersionGuardFilter both = filter("4.0.46", true, true, registry); + MockFilterChain refused = new MockFilterChain(); + MockHttpServletResponse refusedResponse = new MockHttpServletResponse(); + both.doFilter(post("/api/shop-match/tasks/1/items", null), refusedResponse, refused); + assertThat(refused.getRequest()).as("两个开关都打开后,未上报也要被拒").isNull(); + assertThat(objectMapper.readTree(refusedResponse.getContentAsString()).get("code").asInt()) + .isEqualTo(ClientVersionGuardFilter.CODE_TOO_OLD); + assertThat(counterValue(registry, "unreported", "unknown")).isEqualTo(1L); + } + + @Test + void unparsableVersionIsNeverRefusedEvenInEnforceMode() throws Exception { + ClientVersionGuardFilter filter = enforcing("4.0.46"); + MockFilterChain chain = new MockFilterChain(); + MockHttpServletResponse response = new MockHttpServletResponse(); + + filter.doFilter(post("/api/publish/tasks/1/result", "4.x.6"), response, chain); + + assertThat(chain.getRequest()).as("一次格式异常不该由客户端承担断服代价").isNotNull(); + assertThat(response.getContentAsByteArray()).isEmpty(); + } + + @Test + void aVersionAtOrAboveTheFloorIsPassedWithoutAnyTrace() throws Exception { + MeterRegistry registry = new SimpleMeterRegistry(); + ClientVersionGuardFilter filter = filter("4.0.46", true, true, registry); + + filter.doFilter(post("/api/publish/tasks/1/result", "4.0.46"), new MockHttpServletResponse(), + new MockFilterChain()); + filter.doFilter(post("/api/publish/tasks/1/result", "4.1.0"), new MockHttpServletResponse(), + new MockFilterChain()); + + assertThat(registry.find(ClientVersionGuardFilter.METRIC).counter()).isNull(); + } + + @Test + void aBrokenFloorConfigNeverRefusesAnyone() throws Exception { + // 把最低版本写成 "v4.0" 这类解析不出来的值:闸门不许据此拒绝任何客户端 + ClientVersionGuardFilter filter = enforcing("v4.0"); + MockFilterChain chain = new MockFilterChain(); + MockHttpServletResponse response = new MockHttpServletResponse(); + + filter.doFilter(post("/api/publish/tasks/1/result", "1.0.0"), response, chain); + + assertThat(chain.getRequest()).isNotNull(); + assertThat(response.getContentAsByteArray()).isEmpty(); + } + + // ------------------------------------------------------------- 名单与解析 + + @Test + void clientFacingPrefixesComeFromTheAdminGuardListPlusTheCredentialEntry() { + List missing = new ArrayList<>(); + for (String prefix : AdminApiGuardFilter.USER_TOOL_PREFIXES) { + if (!ClientVersionGuardFilter.isClientFacing(prefix + "/anything")) { + missing.add(prefix); + } + } + assertThat(missing).as("受管面必须整份继承用户态名单,不许有漏项").isEmpty(); + assertThat(ClientVersionGuardFilter.isClientFacing("/api/client/credentials")).isTrue(); + + // 反向:这三类必须不在名单里,否则被拒的老客户端拿不到升级信息(闸门把自己变成砖) + assertThat(ClientVersionGuardFilter.isClientFacing("/api/version/latest")).isFalse(); + assertThat(ClientVersionGuardFilter.isClientFacing("/api/admin/users")).isFalse(); + assertThat(ClientVersionGuardFilter.isClientFacing("/api/internal/user-proxy")).isFalse(); + assertThat(ClientVersionGuardFilter.isClientFacing(null)).isFalse(); + } + + @Test + void versionParsingAndOrdering() { + assertThat(ClientVersionGuardFilter.parse("4.0.46")).containsExactly(4L, 0L, 46L); + assertThat(ClientVersionGuardFilter.parse(" 4.0.46 ")).containsExactly(4L, 0L, 46L); + assertThat(ClientVersionGuardFilter.parse("4.0")).containsExactly(4L, 0L); + assertThat(ClientVersionGuardFilter.parse("")).isNull(); + assertThat(ClientVersionGuardFilter.parse(" ")).isNull(); + assertThat(ClientVersionGuardFilter.parse("4..6")).isNull(); + assertThat(ClientVersionGuardFilter.parse("4.x.6")).isNull(); + assertThat(ClientVersionGuardFilter.parse("v4.0.6")).isNull(); + assertThat(ClientVersionGuardFilter.parse("4.0.6-beta")).isNull(); + + assertThat(ClientVersionGuardFilter.compare( + ClientVersionGuardFilter.parse("4.0"), ClientVersionGuardFilter.parse("4.0.0"))).isZero(); + assertThat(ClientVersionGuardFilter.compare( + ClientVersionGuardFilter.parse("4.0"), ClientVersionGuardFilter.parse("4.0.1"))).isNegative(); + assertThat(ClientVersionGuardFilter.compare( + ClientVersionGuardFilter.parse("4.0.46.2"), ClientVersionGuardFilter.parse("4.0.46"))).isPositive(); + assertThat(ClientVersionGuardFilter.compare( + ClientVersionGuardFilter.parse("10.0"), ClientVersionGuardFilter.parse("9.9.9"))).isPositive(); + } +}