Compare commits

...
Author SHA1 Message Date
Codex 403ee8ff36 Align VoteLog inspection maintainer guidance 2026-11-16 23:59:52 +00:00
Codex 60ca55555a Preserve VoteLog query failures in Control inspections 2026-11-16 23:56:06 +00:00
6 changed files with 214 additions and 12 deletions

No files matched your search

+4 -2
View File
@@ -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
@@ -75,7 +75,7 @@ public final class ControlInspectionService {
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 final class ControlInspectionService {
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);
@@ -181,6 +181,7 @@ public abstract class VoteLogMysqlTable extends AbstractSqlTable {
return out;
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return java.util.Collections.emptyList();
}
@@ -262,6 +263,7 @@ public abstract class VoteLogMysqlTable extends AbstractSqlTable {
rs.close();
return out;
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return java.util.Collections.emptyList();
}
@@ -859,6 +861,7 @@ public abstract class VoteLogMysqlTable extends AbstractSqlTable {
return out;
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return java.util.Collections.emptyList();
}
@@ -896,6 +899,7 @@ public abstract class VoteLogMysqlTable extends AbstractSqlTable {
return List.copyOf(result);
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return List.of();
}
@@ -941,6 +945,7 @@ public abstract class VoteLogMysqlTable extends AbstractSqlTable {
return List.copyOf(result);
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return List.of();
}
@@ -1263,6 +1268,7 @@ public abstract class VoteLogMysqlTable extends AbstractSqlTable {
}
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
}
@@ -1311,6 +1317,7 @@ public abstract class VoteLogMysqlTable extends AbstractSqlTable {
}
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
}
return 0;
@@ -1367,6 +1374,7 @@ public abstract class VoteLogMysqlTable extends AbstractSqlTable {
rs.close();
return out;
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return java.util.Collections.emptyList();
}
@@ -1404,6 +1412,7 @@ public abstract class VoteLogMysqlTable extends AbstractSqlTable {
rs.close();
return out;
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return java.util.Collections.emptyList();
}
@@ -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<Runnable> FAILURE = new ThreadLocal<>();
private VoteLogReadScope() { }
/** Runs synchronously on the inspection worker, restoring any enclosing scope on every exit. */
public static <T> T read(Supplier<T> 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();
}
}
@@ -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.<Runnable>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.<String>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);
}
}
}
+9 -8
View File
@@ -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 <node credential>
X-Node-Session: <connector-session-uuid>
X-Deployment-Attempt: <attemptId>
```
@@ -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