diff --git a/AGENTS.md b/AGENTS.md index 260cf911b8..e1d8e835e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -180,8 +180,10 @@ authoritative. Legacy VoteLog read methods catch SQL failures and return empty/zero values, so the inspection layer must probe readability first. Preserve the 10-second JDBC statement timeout: summary/search/trace return `UNAVAILABLE` when logging is disabled, the adapter is missing, or the probe fails, while vote-site health exposes `voteLogReadable:false`, skips aggregates, and uses explicit unavailable or -unreadable statuses instead of `NO_RECENT_VOTES`. The probe is point-in-time; legacy methods can still return empty if the -database fails after it succeeds, so removing that race requires an explicit table error-result API. +unreadable statuses instead of `NO_RECENT_VOTES`. During an inspection, preserve the worker-local strict read scope: +a later SQL read failure returns `UNAVAILABLE`, never successful empty/zero data. Restore the prior scope on every exit +and preserve legacy fallbacks outside inspections. The probe remains point-in-time and does not guarantee a transactional +snapshot across multiple reads. VoteLog records selected events: vote receipt, vote milestone, vote-streak reward, top-voter reward, and vote-shop purchase. `IMMEDIATE` and `CACHED` describe processing status. A shared `voteId` correlates written rows, but the table is diff --git a/VotingPlugin/src/main/java/com/bencodez/votingplugin/control/ControlInspectionService.java b/VotingPlugin/src/main/java/com/bencodez/votingplugin/control/ControlInspectionService.java index 6c6cc2855f..16a7fb4aaf 100644 --- a/VotingPlugin/src/main/java/com/bencodez/votingplugin/control/ControlInspectionService.java +++ b/VotingPlugin/src/main/java/com/bencodez/votingplugin/control/ControlInspectionService.java @@ -75,7 +75,7 @@ public JsonObject inspect(JsonObject query) { String kind = requiredString(query, "kind", 64); if (!KINDS.contains(kind)) throw new IllegalArgumentException("inspection kind is unsupported"); JsonObject filters = optionalObject(query, "filters"); - JsonObject result = switch (kind) { + JsonObject result = com.bencodez.votingplugin.votelog.VoteLogReadScope.read(() -> switch (kind) { case "overview" -> overview(filters); case "vote-site-health" -> voteSiteHealth(filters); case "player" -> player(filters); @@ -88,7 +88,7 @@ public JsonObject inspect(JsonObject query) { case "diagnostics" -> diagnostics(filters); case "network-health" -> networkHealth(filters); default -> throw new IllegalArgumentException("inspection kind is unsupported"); - }; + }, () -> { throw new InspectionUnavailableException("vote log query is unavailable"); }); JsonObject envelope = new JsonObject(); envelope.addProperty("schemaVersion", SCHEMA_VERSION); envelope.addProperty("kind", kind); diff --git a/VotingPlugin/src/main/java/com/bencodez/votingplugin/votelog/VoteLogMysqlTable.java b/VotingPlugin/src/main/java/com/bencodez/votingplugin/votelog/VoteLogMysqlTable.java index 4734c1a88d..ceaef7b50d 100644 --- a/VotingPlugin/src/main/java/com/bencodez/votingplugin/votelog/VoteLogMysqlTable.java +++ b/VotingPlugin/src/main/java/com/bencodez/votingplugin/votelog/VoteLogMysqlTable.java @@ -181,6 +181,7 @@ public List getDistinctServers(int days, int limit) { return out; } } catch (SQLException e) { + VoteLogReadScope.queryFailed(); debug(e); return java.util.Collections.emptyList(); } @@ -262,6 +263,7 @@ public List getTopServers(int days, int limit, VoteLogEvent eventFi rs.close(); return out; } catch (SQLException e) { + VoteLogReadScope.queryFailed(); debug(e); return java.util.Collections.emptyList(); } @@ -859,6 +861,7 @@ public List getDistinctServices(int days, int limit) { return out; } } catch (SQLException e) { + VoteLogReadScope.queryFailed(); debug(e); return java.util.Collections.emptyList(); } @@ -896,6 +899,7 @@ public List getServiceHealth(int days, int limit) { return List.copyOf(result); } } catch (SQLException e) { + VoteLogReadScope.queryFailed(); debug(e); return List.of(); } @@ -941,6 +945,7 @@ public List getServiceHealthForServices(int days, List se return List.copyOf(result); } } catch (SQLException e) { + VoteLogReadScope.queryFailed(); debug(e); return List.of(); } @@ -1263,6 +1268,7 @@ public VoteLogCounts getCounts(int days, VoteLogEvent eventFilter) { } } } catch (SQLException e) { + VoteLogReadScope.queryFailed(); debug(e); } @@ -1311,6 +1317,7 @@ public long getUniqueVoters(int days, VoteLogEvent eventFilter) { } } } catch (SQLException e) { + VoteLogReadScope.queryFailed(); debug(e); } return 0; @@ -1367,6 +1374,7 @@ public List getTopServices(int days, int limit, VoteLogEvent event rs.close(); return out; } catch (SQLException e) { + VoteLogReadScope.queryFailed(); debug(e); return java.util.Collections.emptyList(); } @@ -1404,6 +1412,7 @@ private List query(String sql, Object[] params) { rs.close(); return out; } catch (SQLException e) { + VoteLogReadScope.queryFailed(); debug(e); return java.util.Collections.emptyList(); } diff --git a/VotingPlugin/src/main/java/com/bencodez/votingplugin/votelog/VoteLogReadScope.java b/VotingPlugin/src/main/java/com/bencodez/votingplugin/votelog/VoteLogReadScope.java new file mode 100644 index 0000000000..66fa585a50 --- /dev/null +++ b/VotingPlugin/src/main/java/com/bencodez/votingplugin/votelog/VoteLogReadScope.java @@ -0,0 +1,27 @@ +package com.bencodez.votingplugin.votelog; + +import java.util.function.Supplier; + +/** Internal bridge for strict Control reads; legacy table callers retain their fallbacks. */ +public final class VoteLogReadScope { + private static final ThreadLocal FAILURE = new ThreadLocal<>(); + + private VoteLogReadScope() { } + + /** Runs synchronously on the inspection worker, restoring any enclosing scope on every exit. */ + public static T read(Supplier action, Runnable unavailable) { + Runnable previous = FAILURE.get(); + FAILURE.set(unavailable); + try { + return action.get(); + } finally { + if (previous == null) FAILURE.remove(); + else FAILURE.set(previous); + } + } + + static void queryFailed() { + Runnable unavailable = FAILURE.get(); + if (unavailable != null) unavailable.run(); + } +} diff --git a/VotingPlugin/src/test/java/com/bencodez/votingplugin/tests/control/VoteLogQueryFailureTest.java b/VotingPlugin/src/test/java/com/bencodez/votingplugin/tests/control/VoteLogQueryFailureTest.java new file mode 100644 index 0000000000..676d7a4f13 --- /dev/null +++ b/VotingPlugin/src/test/java/com/bencodez/votingplugin/tests/control/VoteLogQueryFailureTest.java @@ -0,0 +1,163 @@ +package com.bencodez.votingplugin.tests.control; + +import static org.junit.jupiter.api.Assertions.*; +import static org.mockito.ArgumentMatchers.*; +import static org.mockito.Mockito.*; + +import java.lang.reflect.Field; +import java.sql.Connection; +import java.sql.PreparedStatement; +import java.sql.ResultSet; +import java.sql.SQLException; +import java.util.List; +import java.util.concurrent.Executors; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import org.junit.jupiter.api.Test; +import com.bencodez.simpleapi.sql.mysql.MySQL; +import com.bencodez.votingplugin.VotingPluginMain; +import com.bencodez.votingplugin.control.ControlInspectionService; +import com.bencodez.votingplugin.votelog.VoteLogMysqlTable; +import com.bencodez.votingplugin.votelog.VoteLogReadScope; +import com.google.gson.JsonObject; +import com.google.gson.JsonParser; + +class VoteLogQueryFailureTest { + @Test void searchFailureAndRecovery() throws Exception { actualQueryFailureAfterSuccessfulProbeIsUnavailableAndRecoveryRetainsRows("vote-log-search"); } + @Test void traceFailureAndRecovery() throws Exception { actualQueryFailureAfterSuccessfulProbeIsUnavailableAndRecoveryRetainsRows("vote-trace"); } + + void actualQueryFailureAfterSuccessfulProbeIsUnavailableAndRecoveryRetainsRows(String kind) throws Exception { + Fixture f = new Fixture(); + JsonObject query = query(kind); + assertEquals(1, rows(f.service.inspect(query)).size()); + f.failAt = 1; + var failure = assertThrows(ControlInspectionService.InspectionUnavailableException.class, + () -> f.service.inspect(query)); + assertEquals("vote log query is unavailable", failure.getMessage()); + assertNull(failure.getCause()); + assertEquals(2, f.probes.get()); + assertEquals(1, f.queries.get()); + f.failAt = 0; + assertEquals("Example", rows(f.service.inspect(query)).get(0).getAsJsonObject().get("playerName").getAsString()); + f.empty = true; + assertEquals(0, rows(f.service.inspect(query)).size()); + } + + @Test void summaryFailures() throws Exception { + for (int stage = 1; stage <= 4; stage++) summaryRejectsFailureOfEachDependentAggregate(stage); + } + + void summaryRejectsFailureOfEachDependentAggregate(int failedQuery) throws Exception { + Fixture f = new Fixture(); + f.failAt = failedQuery; + assertThrows(ControlInspectionService.InspectionUnavailableException.class, + () -> f.service.inspect(query("vote-log-summary"))); + assertEquals(failedQuery, f.queries.get()); + f.failAt = 0; + assertEquals(1, f.service.inspect(query("vote-log-summary")).getAsJsonObject("result").get("total").getAsLong()); + } + + @Test void failedProbeIsUnavailableAndDoesNotRunDependentQuery() throws Exception { + Fixture f = new Fixture(); + f.failProbe = true; + assertThrows(ControlInspectionService.InspectionUnavailableException.class, + () -> f.service.inspect(query("vote-log-search"))); + assertEquals(0, f.queries.get()); + } + + @Test void healthAndLegacyReadsHaveDistinctFailureSemantics() throws Exception { + Fixture f = new Fixture(); + f.failAt = 1; + for (Runnable read : List.of(() -> f.table.getServiceHealth(30, 10), + () -> f.table.getServiceHealthForServices(30, List.of("example")))) { + f.queries.set(0); + assertThrows(IllegalStateException.class, () -> VoteLogReadScope.read(() -> { + read.run(); return null; + }, () -> { throw new IllegalStateException("unavailable"); })); + } + f.queries.set(0); + assertTrue(f.table.getRecent(30, null, 10).isEmpty()); + f.queries.set(0); + assertEquals(0, f.table.getCounts(30).total); + } + + @Test void nestedScopesRestoreAndConcurrentLegacyReaderIsUnaffected() throws Exception { + Fixture f = new Fixture(); + f.failAt = 1; + var worker = Executors.newSingleThreadExecutor(); + try { + VoteLogReadScope.read(() -> { + assertThrows(IllegalArgumentException.class, () -> VoteLogReadScope.read(() -> { + f.table.getRecent(30, null, 10); return null; + }, () -> { throw new IllegalArgumentException("inner"); })); + f.queries.set(0); + assertThrows(IllegalStateException.class, () -> f.table.getRecent(30, null, 10)); + f.queries.set(0); + try { + assertTrue(worker.submit(() -> f.table.getRecent(30, null, 10).isEmpty()).get(5, TimeUnit.SECONDS)); + } catch (Exception failure) { throw new AssertionError(failure); } + return null; + }, () -> { throw new IllegalStateException("outer"); }); + } finally { + worker.shutdownNow(); + assertTrue(worker.awaitTermination(5, TimeUnit.SECONDS)); + } + f.queries.set(0); + assertTrue(f.table.getRecent(30, null, 10).isEmpty()); + } + + private static com.google.gson.JsonArray rows(JsonObject envelope) { + JsonObject result = envelope.getAsJsonObject("result"); + return result.has("entries") ? result.getAsJsonArray("entries") : result.getAsJsonArray("events"); + } + + private static JsonObject query(String kind) { + JsonObject query = new JsonObject(); + query.addProperty("kind", kind); + query.add("filters", JsonParser.parseString(kind.equals("vote-trace") + ? "{\"voteId\":\"00000000-0000-0000-0000-000000000001\"}" : "{}")); + return query; + } + + private static final class Fixture { + final VoteLogMysqlTable table = mock(VoteLogMysqlTable.class, CALLS_REAL_METHODS); + final ControlInspectionService service; + final AtomicInteger probes = new AtomicInteger(); + final AtomicInteger queries = new AtomicInteger(); + int failAt; + boolean failProbe; + boolean empty; + + Fixture() throws Exception { + MySQL sql = mock(MySQL.class, RETURNS_DEEP_STUBS); + Field mysql = com.bencodez.simpleapi.sql.mysql.AbstractSqlTable.class.getDeclaredField("mysql"); + mysql.setAccessible(true); + mysql.set(table, sql); + doReturn("VoteLog").when(table).getTableName(); + Connection connection = mock(Connection.class); + when(sql.getConnectionManager().getConnection()).thenReturn(connection); + when(connection.prepareStatement(anyString())).thenAnswer(call -> { + boolean probe = call.getArgument(0).contains("WHERE 1=0"); + PreparedStatement statement = mock(PreparedStatement.class); + when(statement.executeQuery()).thenAnswer(ignored -> { + if (probe) { + probes.incrementAndGet(); + queries.set(0); + if (failProbe) throw new SQLException("synthetic unavailable"); + } else if (queries.incrementAndGet() == failAt) throw new SQLException("synthetic unavailable"); + ResultSet result = mock(ResultSet.class); + when(result.next()).thenReturn(!empty, false); + when(result.getString(anyString())).thenReturn("Example"); + when(result.getString("vote_id")).thenReturn("00000000-0000-0000-0000-000000000001"); + when(result.getLong(anyString())).thenReturn(1L); + return result; + }); + return statement; + }); + VotingPluginMain plugin = mock(VotingPluginMain.class, RETURNS_DEEP_STUBS); + when(plugin.getConfigFile().isVoteLoggingEnabled()).thenReturn(true); + when(plugin.getVoteLogMysqlTable()).thenReturn(table); + service = new ControlInspectionService(plugin); + } + } +} diff --git a/docs/control-agent-contract.md b/docs/control-agent-contract.md index fa36cb9259..2e316e69a1 100644 --- a/docs/control-agent-contract.md +++ b/docs/control-agent-contract.md @@ -229,11 +229,11 @@ Content-Type: application/json ``` A `204` means no work. A `200` task contains `deploymentId`, `artifactId`, lowercase SHA-256 `sha256`, byte -`size`, and `attemptId`. Artifact size is limited to 64 MiB. The node downloads the exact leased artifact with: +`size`, and `attemptId`. Artifact size is limited to 64 MiB. The node downloads the exact leased artifact using its +node-bound bearer authentication and these session/attempt headers: ```http GET /api/v1/nodes/{nodeId}/deployments/{deploymentId}/artifact -Authorization: Bearer X-Node-Session: X-Deployment-Attempt: ``` @@ -535,7 +535,7 @@ Untrustworthy task identifiers remain protocol failures and are never used for r ## VoteLog interpretation VoteLogging is optional and SQL-backed; a dependent query returns `UNAVAILABLE` when it is disabled, lacks an initialized -adapter, or fails its readability probe. The quick setup updates and reloads `Config.yml`, but it does not recreate or +adapter, fails its readability probe, or a subsequent bounded VoteLog query fails. The quick setup updates and reloads `Config.yml`, but it does not recreate or close the runtime VoteLog manager. A server restart is therefore required after either `VoteLogging.Enabled` transition. Until then, disabling immediately gates any stale adapter and reports unavailable/readable false, while enabling a previously disabled instance can report enabled true but available false. @@ -543,11 +543,12 @@ The exposed rows are selected **logged events**: `VOTE_RECEIVED`, `VOTEMILESTONE `TOP_VOTER_REWARD`, and `VOTESHOP_PURCHASE`. `IMMEDIATE` and `CACHED` describe recorded processing status. `overview`, `diagnostics`, and vote-site health distinguish configured, enabled-and-adapter-available, and currently readable state. -`voteLogReadable` runs a bounded probe with a 10-second JDBC statement timeout. Existing VoteLog table methods catch SQL -failures and return empty/zero values, so the inspection layer probes first: summary/search/trace fail `UNAVAILABLE` when -the probe fails, and health skips aggregates and labels each applicable row unavailable/unreadable. The probe is -point-in-time; a later SQL failure can still trigger a legacy empty/zero fallback, so it is not a transactional health -guarantee. +`voteLogReadable` runs a bounded probe with a 10-second JDBC statement timeout. The inspection layer probes first: summary/search/trace fail `UNAVAILABLE` when +the probe fails, and health skips aggregates and labels each applicable row unavailable/unreadable. During an inspection, +a later SQL read failure also returns `UNAVAILABLE` rather than serializing an empty list or zero aggregate as successful +data. The strict read scope is confined to the calling inspection worker and is restored on every exit; ordinary VoteLog +callers retain their existing empty/zero fallbacks. A genuine empty query remains a successful empty result. The probe +remains point-in-time and does not promise a transactional snapshot across multiple queries. A `voteId` correlates rows written with the same identifier. It is not a complete delivery trace: VoteLog does not promise an entry for every validation rejection, network hop, duplicate decision, reward command, command outcome, or expiry. UI