Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,7 @@ public List<String> getDistinctServers(int days, int limit) {
return out;
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return java.util.Collections.emptyList();
}
Expand Down Expand Up @@ -262,6 +263,7 @@ public List<ServerCount> getTopServers(int days, int limit, VoteLogEvent eventFi
rs.close();
return out;
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return java.util.Collections.emptyList();
}
Expand Down Expand Up @@ -859,6 +861,7 @@ public List<String> getDistinctServices(int days, int limit) {
return out;
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return java.util.Collections.emptyList();
}
Expand Down Expand Up @@ -896,6 +899,7 @@ public List<ServiceHealth> getServiceHealth(int days, int limit) {
return List.copyOf(result);
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return List.of();
}
Expand Down Expand Up @@ -941,6 +945,7 @@ public List<ServiceHealth> getServiceHealthForServices(int days, List<String> se
return List.copyOf(result);
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return List.of();
}
Expand Down Expand Up @@ -1263,6 +1268,7 @@ public VoteLogCounts getCounts(int days, VoteLogEvent eventFilter) {
}
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
}

Expand Down Expand Up @@ -1311,6 +1317,7 @@ public long getUniqueVoters(int days, VoteLogEvent eventFilter) {
}
}
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
}
return 0;
Expand Down Expand Up @@ -1367,6 +1374,7 @@ public List<ServiceCount> getTopServices(int days, int limit, VoteLogEvent event
rs.close();
return out;
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return java.util.Collections.emptyList();
}
Expand Down Expand Up @@ -1404,6 +1412,7 @@ private List<VoteLogEntry> query(String sql, Object[] params) {
rs.close();
return out;
} catch (SQLException e) {
VoteLogReadScope.queryFailed();
debug(e);
return java.util.Collections.emptyList();
}
Expand Down
Original file line number Diff line number Diff line change
@@ -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();
}
}
Original file line number Diff line number Diff line change
@@ -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);
}
}
}
17 changes: 9 additions & 8 deletions docs/control-agent-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
```
Expand Down Expand Up @@ -535,19 +535,20 @@ 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.
The exposed rows are selected **logged events**: `VOTE_RECEIVED`, `VOTEMILESTONE`, `VOTE_STREAK_REWARD`,
`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
Expand Down
Loading