Skip to content
Merged
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
2 changes: 1 addition & 1 deletion replication/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ Per (database, remote_node) pair: a `Float64Array` over the audit store's `getUs
| 31 | `RECORD_LOCK_LEVEL_POSITION` |
| 32–63 | unused headroom |

The buffer is 64 `Float64` slots (512 bytes, `REPLICATION_SHARED_STATUS_SLOTS` in `sharedStatusSlots.ts`, re-exported from `knownNodes.ts`) — 0–31 are used as above (30 is the record-lock home-map digest agreement tri-state; 31 is the peer's exact advertised `recordLocks` level); 32–63 are headroom for the peer-scoped transport (harper-pro#884) and the ownership domain (harper-pro#886). **A new slot is added in `sharedStatusSlots.ts`, never hand-numbered in an owning module**: `unitTests/replication/sharedStatusSlots.test.mjs` walks the TypeScript AST of every file under `replication/` (recursively) for a `*_POSITION` variable declaration outside the registry, asserts every allocated position is distinct and in range, that the fire-counter block doesn't reach its neighbors, and that the allocator throws rather than silently exceeding capacity. Slots 0–12 are written concurrently by `replicationConnection.ts` without explicit synchronization (single-writer-per-field in practice) — **don't introduce read-modify-write patterns on those.** Slots 13–28 are the one deliberate exception; see the counter invariant below.
The buffer is 64 `Float64` slots (512 bytes, `REPLICATION_SHARED_STATUS_SLOTS` in `sharedStatusSlots.ts`, re-exported from `knownNodes.ts`) — 0–31 are used as above (30 is the record-lock home-map digest agreement tri-state; 31 is the peer's exact advertised `recordLocks` level); 32–63 are headroom for the peer-scoped transport (harper-pro#884) and the ownership domain (harper-pro#886). **A new slot is added in `sharedStatusSlots.ts`, never hand-numbered in an owning module**: `unitTests/replication/sharedStatusSlots.test.mjs` walks the TypeScript AST of every file under `replication/` (recursively) for a `*_POSITION`, `*_SLOT` or `*_INDEX` declaration outside the registry, asserts every allocated position is distinct and in range, that the fire-counter block doesn't reach its neighbors, and that the allocator throws rather than silently exceeding capacity. Slots 0–12 are written concurrently by `replicationConnection.ts` without explicit synchronization (single-writer-per-field in practice) — **don't introduce read-modify-write patterns on those.** Slots 13–28 are the one deliberate exception; see the counter invariant below.

The buffer size is fixed once, at this process's build, for the process's whole lifetime — nothing in this codebase resizes an existing (database, peer) buffer while a process runs, so growing the constant is safe across a restart. A **live** resize is not available: probed against both lmdb-js and `@harperfast/rocksdb-js`, a second `getUserSharedBuffer` for an already-registered key returns the **first** buffer at its original size and ignores the larger default — no throw, no resize — so writes past that length land outside the typed array and are silently dropped. The first registration of a key within a process therefore fixes its size for that process, and growing `REPLICATION_SHARED_STATUS_SLOTS` takes effect only on restart. Every caller must pass one size per key, which is why the capacity is read from the registry inside `getReplicationSharedStatus` rather than supplied by callers (`unitTests/replication/sharedStatusSlots.test.mjs` pins that).

Expand Down
57 changes: 48 additions & 9 deletions unitTests/replication/sharedStatusSlots.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,39 @@ import { getReplicationSharedStatus } from '#src/replication/knownNodes';

const REPLICATION_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'replication');
const REGISTRY_RELATIVE_PATH = 'sharedStatusSlots.ts';
// A slot named _SLOT or _INDEX would otherwise walk straight past an audit keyed on _POSITION alone.
const SLOT_NAME_SUFFIXES = ['_POSITION', '_SLOT', '_INDEX'];

function isLiteralName(node) {
if (node && ts.isParenthesizedExpression(node)) return isLiteralName(node.expression);
return node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node));
}

function literalNameText(node) {
return ts.isParenthesizedExpression(node) ? literalNameText(node.expression) : node.text;
}

function staticName(node) {
if (!node) return undefined;
if (ts.isIdentifier(node) || isLiteralName(node)) return node.text;
// Inside a computed key an identifier REFERENCES a constant rather than binding a name, so
// `{ [RECEIVED_VERSION_POSITION]: 'received' }` is a legitimate use of the registry, not a slot.
if (ts.isComputedPropertyName(node) && isLiteralName(node.expression)) return literalNameText(node.expression);
return undefined;
}

function declaredPositionNames(source, fileName) {
const names = [];
const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
const visit = (node) => {
const binds = ts.isVariableDeclaration(node) || ts.isBindingElement(node) || ts.isPropertyDeclaration(node);
if (binds && ts.isIdentifier(node.name) && SLOT_NAME_SUFFIXES.some((s) => node.name.text.endsWith(s))) {
names.push(node.name.text);
const binds =
ts.isVariableDeclaration(node) ||
ts.isBindingElement(node) ||
ts.isPropertyDeclaration(node) ||
ts.isPropertyAssignment(node) ||
ts.isEnumMember(node);
const name = binds ? staticName(node.name) : undefined;
if (name && SLOT_NAME_SUFFIXES.some((s) => name.endsWith(s))) {
names.push(name);
}
ts.forEachChild(node, visit);
};
Expand All @@ -38,9 +61,9 @@ function fakeAuditStore() {
}

describe('replication shared-status slot registry', () => {
const positionEntries = Object.entries(slots).filter(([name]) => name.endsWith('_POSITION'));
const positionEntries = Object.entries(slots).filter(([name]) => SLOT_NAME_SUFFIXES.some((x) => name.endsWith(x)));

it('assigns every *_POSITION export a distinct, in-range slot, reserving the fire-counter block whole', () => {
it('assigns every slot export a distinct, in-range slot, reserving the fire-counter block whole', () => {
expect(positionEntries.length).to.be.greaterThan(0);
const occupied = new Map();
const blockStart = slots.FIRE_COUNTER_BASE_POSITION;
Expand Down Expand Up @@ -88,6 +111,25 @@ describe('replication shared-status slot registry', () => {
expect(declaredPositionNames('const UNRELATED_OFFSET = 40;', 'a.ts')).to.deep.equal([]);
});

it('declaredPositionNames catches an object-literal slot however the key is spelled', () => {
expect(declaredPositionNames('const o = { PEER_POSITION: 30 };', 'a.ts')).to.deep.equal(['PEER_POSITION']);
expect(declaredPositionNames("const o = { 'PEER_POSITION': 30 };", 'a.ts')).to.deep.equal(['PEER_POSITION']);
expect(declaredPositionNames("const o = { ['PEER_SLOT']: 30 };", 'a.ts')).to.deep.equal(['PEER_SLOT']);
expect(declaredPositionNames('const o = { [`PEER_INDEX`]: 30 };', 'a.ts')).to.deep.equal(['PEER_INDEX']);
expect(declaredPositionNames("const o = { [('PEER_SLOT')]: 30 };", 'a.ts')).to.deep.equal(['PEER_SLOT']);
expect(declaredPositionNames('const o = { [dynamic]: 30 };', 'a.ts')).to.deep.equal([]);
});

it('declaredPositionNames catches an enum member slot too', () => {
expect(declaredPositionNames('enum E { PEER_POSITION = 30 }', 'a.ts')).to.deep.equal(['PEER_POSITION']);
expect(declaredPositionNames("enum E { 'PEER_SLOT' = 30 }", 'a.ts')).to.deep.equal(['PEER_SLOT']);
});

it("declaredPositionNames leaves a map keyed by the registry's own constants alone", () => {
expect(declaredPositionNames("const labels = { [PEER_SLOT]: 'peer' };", 'a.ts')).to.deep.equal([]);
expect(declaredPositionNames("const labels = { [RECEIVED_VERSION_POSITION]: 'v' };", 'a.ts')).to.deep.equal([]);
});

it('never hand-numbers a slot constant outside the registry, under any of its spellings', () => {
const offenders = [];
for (const file of readdirSync(REPLICATION_DIR, { withFileTypes: true, recursive: true })) {
Expand All @@ -108,9 +150,6 @@ describe('replication shared-status slot registry', () => {
expect(getReplicationSharedStatus(auditStore, 'data', 'peer')[topSlot]).to.equal(42);
});

// Probed against lmdb-js and @harperfast/rocksdb-js: a second request for a key already
// registered returns the FIRST buffer at its original size, with no throw, so writes past that
// length are silently dropped. Every caller must therefore pass one size per key.
it('getReplicationSharedStatus() always requests the registry capacity, never a caller-chosen size', () => {
const sizes = [];
const auditStore = {
Expand Down
Loading