perf(localdb): dereg API, O(1) backlog depth, byte-budget batching, prepare-once apply (0.2.0)
WP3.3 of the ScadaBridge architectural-review remediation. Six changes, all wire-compatible with 0.1.x peers — no proto change, no lib_schema_version bump. The on-disk bookkeeping schema goes to v2 and is upgraded in place when a file is opened. DeregisterReplicated(table). There was no way to stop capturing once a file had been registered, so a node that does not replicate kept paying three triggers inside every write transaction, appending to an oplog nothing would ever drain. Drops the triggers and prunes the table's oplog + row-version rows in one transaction; idempotent, and deliberately usable on a table this process never registered, since stale triggers left by an EARLIER build are the primary case. Deregistration must be symmetric across a pair, and already is enforced: the handshake compares registered-table digests fail-closed, so a node that drops a table its peer still replicates stops syncing loudly rather than diverging. RegisterReplicated(table, baselineExistingRows: true). Closes the late-opt-in hole: the snapshot streamer pages from __localdb_row_version, which only triggers populate, so a node that started replicating LATE never sent its pre-existing rows — silently, forever. Seeding alone would not have fixed it, because a node whose oplog starts at seq 1 presents no gap at the handshake and is told it needs no snapshot; the seed therefore also flags needs_snapshot, and the existing resync machinery carries the rows. The floor is HLC 0 stamped with this node's id: every genuine HLC is a UTC millisecond shifted left 16 bits and so is strictly greater, which makes a baselined row lose every comparison against a real remote write and win only where the peer has no version of that key at all. Two nodes baselining the same key both hold 0 and resolve by the node-id tie-break — convergent, and nothing better is available for two rows of unordered antiquity. Opt-in, so the documented CDC contract is unchanged unless asked. Pruning the ledger on deregister is safe precisely because re-registration can re-baseline; the two APIs are a pair. O(1) backlog depth. GetOplogDepth ran COUNT(*) over the entire unacked backlog, once a minute from maintenance AND on every metrics scrape — a full scan of a million rows exactly when a node is already behind. Now MAX(seq) - MAX(last_acked_seq, MIN(seq) - 1), floored at 0: three b-tree seeks, measured at 58 VM steps against 100,020 for the count on a 50k backlog. Exact, because seq is AUTOINCREMENT and every prune path removes a prefix (ack pruning by watermark, the row cap by count, the age cap by an HLC cutoff that rises with seq). The MIN clamp is what keeps it exact after a cap prune has moved the horizon above a stalled watermark — without it the caps would re-flag on every tick forever. Byte-budget batching. MaxBatchSize was the only cap on an outbound message, which made it a proxy for a byte budget that consumers had to tune against their widest row: ScadaBridge pinned it to 16 because 70 KB config_json times the 500 default is ~35 MB against a 4 MB gRPC limit. MaxBatchBytes (default 2 MB) now bounds delta and snapshot messages by summed serialized size, with the row count demoted to a secondary cap. A row larger than the budget is sent alone rather than stalling the stream on it. Since more, smaller messages would otherwise mean more apply transactions and more acks, inbound delta batches and acks ALREADY queued are coalesced — one transaction and one ack per burst, bounded by the sender's own caps, and a no-op under a trickle. LwwApplier prepares each statement once. It went through the generic transaction façade, which builds a fresh SqliteCommand per call: three SQL parses per applied row, on the path that drains a reconnect backlog. Statements are now held for the batch and rebound. Dropped __localdb_oplog_hlc. It indexed (table_name, pk_json, hlc), which no query has ever used — every oplog access path is by seq or a full hlc-predicate delete — while costing a b-tree insert inside every captured consumer write. 184/184 tests pass (was 149). New coverage: schema upgrade drops the index and preserves identity/watermarks/data, deregistration idempotency and trigger absence and cross-process cleanup, baseline seeding at the floor with LWW safety proved through the real applier, depth asserted equal to the counting query across every prune scenario plus a constant-time assertion over a 200k backlog, byte-budget chunking including the one-giant-row edge on both the delta and snapshot paths, prepare-once statement counting, and coalescing that must not swallow the message that ends its run. Version 0.2.0.
This commit is contained in:
Joseph Doherty
@@ -212,6 +212,137 @@ public sealed class OplogStoreTests : IDisposable
|
||||
Assert.Equal("{\"id\":2}", remaining[0].PkJson);
|
||||
}
|
||||
|
||||
// ---- O(1) backlog depth --------------------------------------------------------------
|
||||
|
||||
// The definition the O(1) formula has to reproduce. Every scenario below is asserted against
|
||||
// this, not against a hand-computed number, so the two can never drift apart.
|
||||
private static async Task<long> CountingDepth(SqliteLocalDb db) =>
|
||||
(await db.QueryAsync(
|
||||
"SELECT COUNT(*) FROM __localdb_oplog WHERE seq > (SELECT last_acked_seq FROM __localdb_peer_state WHERE id = 1)",
|
||||
r => r.GetInt64(0)))[0];
|
||||
|
||||
private static async Task AssertDepthMatchesCount(SqliteLocalDb db, OplogStore store)
|
||||
{
|
||||
var expected = await CountingDepth(db);
|
||||
Assert.Equal(expected, await store.GetOplogDepthAsync(default));
|
||||
Assert.Equal(expected, store.GetOplogDepthSync());
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OplogDepth_Empty_IsZero()
|
||||
{
|
||||
using var db = await NewOrdersDb();
|
||||
var store = new OplogStore(db, new ReplicationOptions());
|
||||
|
||||
await AssertDepthMatchesCount(db, store);
|
||||
Assert.Equal(0, await store.GetOplogDepthAsync(default));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OplogDepth_AllAcked_EmptiesToZero_NotToTheSeqRange()
|
||||
{
|
||||
using var db = await NewOrdersDb();
|
||||
await WriteRows(db, 5);
|
||||
var store = new OplogStore(db, new ReplicationOptions());
|
||||
await store.RecordPeerAckAsync(await store.GetMaxSeqAsync(default), default);
|
||||
|
||||
await AssertDepthMatchesCount(db, store);
|
||||
Assert.Equal(0, await store.GetOplogDepthAsync(default));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OplogDepth_AfterCapPrune_ReportsRetainedRows_NotTheWholeSeqRange()
|
||||
{
|
||||
// The reason the formula clamps its floor to MIN(seq) - 1. A cap prune leaves the retained
|
||||
// rows far above an ack watermark that never moved, so a naive MAX(seq) - last_acked would
|
||||
// report the entire seq range forever and re-flag the cap on every maintenance tick.
|
||||
using var db = await NewOrdersDb();
|
||||
await WriteRows(db, 40);
|
||||
var store = new OplogStore(db, new ReplicationOptions { MaxOplogRows = 5 });
|
||||
|
||||
Assert.True(await store.EnforceCapsAsync(default));
|
||||
|
||||
await AssertDepthMatchesCount(db, store);
|
||||
Assert.Equal(5, await store.GetOplogDepthAsync(default));
|
||||
// And the next tick is clean: depth is not over cap any more.
|
||||
Assert.False(await store.EnforceCapsAsync(default));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OplogDepth_AfterAgePrune_MatchesCount()
|
||||
{
|
||||
using var db = await NewOrdersDb();
|
||||
await WriteRows(db, 6);
|
||||
// Backdate the oldest three past the age cap; HLCs rise with seq, so this is a prefix.
|
||||
var expired = DateTimeOffset.UtcNow.AddDays(-30).ToUnixTimeMilliseconds() << 16;
|
||||
await db.ExecuteAsync(
|
||||
"UPDATE __localdb_oplog SET hlc = @h WHERE seq IN (SELECT seq FROM __localdb_oplog ORDER BY seq LIMIT 3)",
|
||||
new { h = expired });
|
||||
var store = new OplogStore(db, new ReplicationOptions());
|
||||
|
||||
Assert.True(await store.EnforceCapsAsync(default));
|
||||
|
||||
await AssertDepthMatchesCount(db, store);
|
||||
Assert.Equal(3, await store.GetOplogDepthAsync(default));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OplogDepth_PartialAck_MatchesCount()
|
||||
{
|
||||
using var db = await NewOrdersDb();
|
||||
await WriteRows(db, 9);
|
||||
var store = new OplogStore(db, new ReplicationOptions());
|
||||
var batch = await store.ReadBatchAboveAsync(0, 100, default);
|
||||
|
||||
await store.RecordPeerAckAsync(batch[3].Seq, default);
|
||||
|
||||
await AssertDepthMatchesCount(db, store);
|
||||
Assert.Equal(5, await store.GetOplogDepthAsync(default));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OplogDepth_AckPruneThenMoreWrites_MatchesCount()
|
||||
{
|
||||
using var db = await NewOrdersDb();
|
||||
await WriteRows(db, 4);
|
||||
var store = new OplogStore(db, new ReplicationOptions());
|
||||
await store.RecordPeerAckAsync(await store.GetMaxSeqAsync(default), default);
|
||||
|
||||
// The steady state of a converged pair: oplog pruned empty, watermark high, new writes above it.
|
||||
await db.ExecuteAsync("INSERT INTO orders (id, sku, qty) VALUES (91,'S',1),(92,'S',2)");
|
||||
|
||||
await AssertDepthMatchesCount(db, store);
|
||||
Assert.Equal(2, await store.GetOplogDepthAsync(default));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OplogDepth_LargeBacklog_IsConstantTime()
|
||||
{
|
||||
// 200k rows: a COUNT(*) over the backlog runs ~200k VM steps per call (measured: 100,020 at
|
||||
// 50k rows), the seek-based formula runs 58 regardless of size. The loop below costs tens of
|
||||
// milliseconds at seek shape and seconds at scan shape, so the budget separates them by a
|
||||
// wide margin in both directions.
|
||||
using var db = await NewOrdersDb();
|
||||
await db.ExecuteAsync(
|
||||
"INSERT INTO __localdb_oplog (table_name, pk_json, row_json, hlc, node_id, is_tombstone) " +
|
||||
"WITH RECURSIVE c(x) AS (SELECT 1 UNION ALL SELECT x + 1 FROM c WHERE x < 200000) " +
|
||||
"SELECT 'orders', '{\"id\":' || x || '}', '{\"id\":' || x || '}', x << 16, 'n', 0 FROM c");
|
||||
var store = new OplogStore(db, new ReplicationOptions());
|
||||
|
||||
Assert.Equal(200_000, await store.GetOplogDepthAsync(default));
|
||||
|
||||
using var conn = db.CreateConnection();
|
||||
using var cmd = conn.CreateCommand();
|
||||
cmd.CommandText = OplogStore.DepthSql;
|
||||
var sw = System.Diagnostics.Stopwatch.StartNew();
|
||||
for (var i = 0; i < 2_000; i++)
|
||||
Assert.Equal(200_000L, (long)cmd.ExecuteScalar()!);
|
||||
sw.Stop();
|
||||
|
||||
Assert.True(sw.ElapsedMilliseconds < 1_500,
|
||||
$"2000 depth reads over a 200k backlog took {sw.ElapsedMilliseconds} ms — that is scan-shaped, not seek-shaped.");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task PeerState_RoundTrips()
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user