refactor(8.0)!: remove distributed clustering subsystem — inert/orphaned, scale is single-process + native provider
The distributed-clustering subsystem never ran in production: it was inert, orphaned dead code (faked consensus, stub replication, no live wiring, and it did not interoperate with the 8.0 Db API). Brainy 8.0 is a single-process library. Scale is single-process + the optional native provider (@soulcraft/cortex, on-disk DiskANN to 10B+ vectors) + per-tenant pools + horizontal read scaling (many reader processes, one writer). Removed: - src/distributed/ entirely (coordinator, shardManager, cacheSync, readWriteSeparation, queryPlanner, healthMonitor, configManager, hashPartitioner, shardMigration, domainDetector, storageDiscovery, http/network transports). ReaderMode/HybridMode relocated to src/storage/operationalModes.ts (slimmed to the live surface). - src/types/distributedTypes.ts; config.distributed field + JSDoc; coreTypes distributedConfig; memoryStorage distributedConfig persistence. - DistributedRole enum + src/config/distributedPresets.ts and the orphaned src/config/extensibleConfig.ts (config/augmentation registry built on removed cloud adapters + distributed presets), plus their src/index.ts re-exports. - 13 BRAINY_* cluster env vars; the storage setDistributedComponents hook; enableDistributedSearch (dead config flag); the metadata partition field; the distributed_ reserved key prefix. - Orphaned src/storage/readOnlyOptimizations.ts (zero importers). - Tests targeting the subsystem: distributed-demo, distributed-cluster helper, distributed-transactions, sharding-transactions. - Docs: EXTENDING_STORAGE.md (deleted); scrubbed distributed/cluster/Raft/ shard-manager/multi-node prose from v3-features, enterprise-for-everyone, augmentations-actual, complete-feature-list, vfs/README, vfs/ROADMAP, vfs/VFS_CORE, capacity-planning, transactions, MIGRATION-V3-TO-V4, storage-architecture; reframed scale prose to the 8.0 model. Kept: src/storage/sharding.ts (local-disk 256-bucket directory sharding via getShardIdFromUuid — used live by baseStorage, unrelated to clustering); the multi-process mode: 'reader' | 'writer' roles; semantic/HNSW clustering. RELEASES.md: added a removed-surfaces row documenting the cut and the 8.0 scale model.
This commit is contained in:
parent
f8e0079d3f
commit
00d3203d68
51 changed files with 153 additions and 9889 deletions
|
|
@ -1,202 +0,0 @@
|
|||
/**
|
||||
* Distributed Brainy Demo Test
|
||||
*
|
||||
* Demonstrates the complete distributed features:
|
||||
* - Zero-config discovery via S3
|
||||
* - Automatic sharding
|
||||
* - Load balancing
|
||||
* - Shard migration
|
||||
* - Distributed queries
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeAll, afterAll } from 'vitest'
|
||||
import { Brainy } from '../src/brainy.js'
|
||||
|
||||
describe('Distributed Brainy Demo', () => {
|
||||
let node1: Brainy
|
||||
let node2: Brainy
|
||||
let node3: Brainy
|
||||
|
||||
beforeAll(async () => {
|
||||
// Node 1: First node starts cluster
|
||||
node1 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
s3Storage: {
|
||||
bucket: process.env.S3_BUCKET || 'brainy-test',
|
||||
region: process.env.AWS_REGION || 'us-east-1'
|
||||
}
|
||||
},
|
||||
distributed: true, // That's it! Everything else is automatic
|
||||
logging: { verbose: true }
|
||||
})
|
||||
|
||||
await node1.init()
|
||||
console.log('Node 1 started - became cluster leader')
|
||||
|
||||
// Node 2: Automatically discovers and joins
|
||||
node2 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
s3Storage: {
|
||||
bucket: process.env.S3_BUCKET || 'brainy-test',
|
||||
region: process.env.AWS_REGION || 'us-east-1'
|
||||
}
|
||||
},
|
||||
distributed: true,
|
||||
logging: { verbose: true }
|
||||
})
|
||||
|
||||
await node2.init()
|
||||
console.log('Node 2 started - automatically joined cluster')
|
||||
|
||||
// Node 3: Also joins automatically
|
||||
node3 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
s3Storage: {
|
||||
bucket: process.env.S3_BUCKET || 'brainy-test',
|
||||
region: process.env.AWS_REGION || 'us-east-1'
|
||||
}
|
||||
},
|
||||
distributed: true,
|
||||
logging: { verbose: true }
|
||||
})
|
||||
|
||||
await node3.init()
|
||||
console.log('Node 3 started - automatically joined cluster')
|
||||
|
||||
// Give nodes time to discover each other
|
||||
await new Promise(resolve => setTimeout(resolve, 2000))
|
||||
})
|
||||
|
||||
afterAll(async () => {
|
||||
await Promise.all([
|
||||
node1?.close(),
|
||||
node2?.close(),
|
||||
node3?.close()
|
||||
])
|
||||
})
|
||||
|
||||
it('should automatically distribute data across nodes', async () => {
|
||||
// Add data from different nodes - automatically sharded
|
||||
const doc1 = await node1.add('First document about AI', 'document')
|
||||
const doc2 = await node2.add('Second document about machine learning', 'document')
|
||||
const doc3 = await node3.add('Third document about neural networks', 'document')
|
||||
|
||||
console.log('Added documents:', { doc1, doc2, doc3 })
|
||||
|
||||
// Each node can find all documents (distributed query)
|
||||
const results1 = await node1.find('AI machine learning')
|
||||
const results2 = await node2.find('AI machine learning')
|
||||
const results3 = await node3.find('AI machine learning')
|
||||
|
||||
// All nodes should see the same results
|
||||
expect(results1.length).toBeGreaterThan(0)
|
||||
expect(results2.length).toBe(results1.length)
|
||||
expect(results3.length).toBe(results1.length)
|
||||
|
||||
console.log(`All nodes found ${results1.length} documents`)
|
||||
})
|
||||
|
||||
it('should handle node failures gracefully', async () => {
|
||||
// Add a document
|
||||
const docId = await node1.add('Important data that must not be lost', 'critical')
|
||||
|
||||
// Simulate node 2 going down
|
||||
await node2.close()
|
||||
console.log('Node 2 went offline')
|
||||
|
||||
// Data should still be accessible from other nodes
|
||||
const result = await node1.get(docId)
|
||||
expect(result).toBeDefined()
|
||||
expect(result.data).toContain('Important data')
|
||||
|
||||
console.log('Data still accessible after node failure')
|
||||
})
|
||||
|
||||
it('should automatically rebalance when nodes join', async () => {
|
||||
// Start a new node
|
||||
const node4 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
s3Storage: {
|
||||
bucket: process.env.S3_BUCKET || 'brainy-test',
|
||||
region: process.env.AWS_REGION || 'us-east-1'
|
||||
}
|
||||
},
|
||||
distributed: true
|
||||
})
|
||||
|
||||
await node4.init()
|
||||
console.log('Node 4 joined - automatic rebalancing started')
|
||||
|
||||
// Give time for rebalancing
|
||||
await new Promise(resolve => setTimeout(resolve, 3000))
|
||||
|
||||
// Node 4 should now handle queries
|
||||
const results = await node4.find('data')
|
||||
expect(results.length).toBeGreaterThan(0)
|
||||
|
||||
console.log('Node 4 successfully serving queries after rebalancing')
|
||||
|
||||
await node4.close()
|
||||
})
|
||||
|
||||
it('should support complex distributed operations', async () => {
|
||||
// Parallel writes from all nodes
|
||||
const promises = []
|
||||
for (let i = 0; i < 10; i++) {
|
||||
promises.push(node1.add(`Document ${i} from node 1`, 'batch'))
|
||||
promises.push(node3.add(`Document ${i} from node 3`, 'batch'))
|
||||
}
|
||||
|
||||
await Promise.all(promises)
|
||||
console.log('Added 20 documents in parallel from 2 nodes')
|
||||
|
||||
// Complex query executed across all shards
|
||||
const results = await node1.find('document', 5)
|
||||
expect(results.length).toBe(5)
|
||||
|
||||
// Triple Intelligence works across distributed data
|
||||
const triple = await node1.tripleSearch(
|
||||
'node', // Subject
|
||||
'creates', // Verb
|
||||
'document' // Object
|
||||
)
|
||||
|
||||
expect(triple.results).toBeDefined()
|
||||
console.log('Triple Intelligence query executed across cluster')
|
||||
})
|
||||
})
|
||||
|
||||
// Usage Example for Documentation
|
||||
export function distributedExample() {
|
||||
return `
|
||||
// Zero-Config Distributed Setup
|
||||
const brain = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
s3Storage: {
|
||||
bucket: 'my-data',
|
||||
region: 'us-east-1'
|
||||
}
|
||||
},
|
||||
distributed: true // That's it!
|
||||
})
|
||||
|
||||
await brain.init()
|
||||
|
||||
// Everything else is automatic:
|
||||
// ✅ Nodes discover each other via S3
|
||||
// ✅ Data automatically sharded across nodes
|
||||
// ✅ Queries automatically distributed
|
||||
// ✅ Automatic failover and recovery
|
||||
// ✅ Zero-downtime scaling
|
||||
|
||||
// Add data - automatically distributed
|
||||
await brain.add('My document', 'doc')
|
||||
|
||||
// Query - automatically searches all nodes
|
||||
const results = await brain.find('search term')
|
||||
|
||||
// Nodes can join/leave anytime
|
||||
// Data automatically rebalances
|
||||
// No configuration needed!
|
||||
`
|
||||
}
|
||||
|
|
@ -1,300 +0,0 @@
|
|||
import { GenericContainer, StartedTestContainer, Wait } from 'testcontainers';
|
||||
import { Brainy } from '../../src/brainy';
|
||||
|
||||
export interface DistributedTestNode {
|
||||
id: string;
|
||||
brain: Brainy;
|
||||
port: number;
|
||||
}
|
||||
|
||||
export interface DistributedClusterConfig {
|
||||
nodeCount: number;
|
||||
redisHost?: string;
|
||||
redisPort?: number;
|
||||
useTestContainers?: boolean;
|
||||
}
|
||||
|
||||
export class DistributedTestCluster {
|
||||
private nodes: DistributedTestNode[] = [];
|
||||
private redisContainer?: StartedTestContainer;
|
||||
private config: DistributedClusterConfig;
|
||||
private redisEndpoint?: { host: string; port: number };
|
||||
|
||||
constructor(config: DistributedClusterConfig) {
|
||||
this.config = {
|
||||
useTestContainers: config.useTestContainers !== false,
|
||||
...config,
|
||||
nodeCount: config.nodeCount || 3
|
||||
};
|
||||
}
|
||||
|
||||
async start(): Promise<void> {
|
||||
console.log(`Starting distributed test cluster with ${this.config.nodeCount} nodes...`);
|
||||
|
||||
// Start Redis if using test containers
|
||||
if (this.config.useTestContainers && !this.config.redisHost) {
|
||||
await this.startRedis();
|
||||
} else {
|
||||
this.redisEndpoint = {
|
||||
host: this.config.redisHost || 'localhost',
|
||||
port: this.config.redisPort || 6379
|
||||
};
|
||||
}
|
||||
|
||||
// Start cluster nodes
|
||||
await this.startNodes();
|
||||
|
||||
// Wait for nodes to discover each other
|
||||
await this.waitForClusterFormation();
|
||||
|
||||
console.log(`Distributed cluster ready with ${this.nodes.length} nodes`);
|
||||
}
|
||||
|
||||
private async startRedis(): Promise<void> {
|
||||
console.log('Starting Redis test container...');
|
||||
|
||||
this.redisContainer = await new GenericContainer('redis:7-alpine')
|
||||
.withExposedPorts(6379)
|
||||
.withCommand(['redis-server', '--appendonly', 'yes'])
|
||||
.withWaitStrategy(Wait.forLogMessage('Ready to accept connections'))
|
||||
.start();
|
||||
|
||||
this.redisEndpoint = {
|
||||
host: this.redisContainer.getHost(),
|
||||
port: this.redisContainer.getMappedPort(6379)
|
||||
};
|
||||
|
||||
console.log(`Redis started on ${this.redisEndpoint.host}:${this.redisEndpoint.port}`);
|
||||
}
|
||||
|
||||
private async startNodes(): Promise<void> {
|
||||
const basePort = 8000;
|
||||
|
||||
for (let i = 0; i < this.config.nodeCount; i++) {
|
||||
const nodeId = `node-${i + 1}`;
|
||||
const port = basePort + i;
|
||||
|
||||
console.log(`Starting ${nodeId} on port ${port}...`);
|
||||
|
||||
const brain = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'memory'
|
||||
}
|
||||
// distributed config is not part of BrainyConfig
|
||||
// distributed: {
|
||||
// enabled: true,
|
||||
// nodeId: nodeId,
|
||||
// redis: {
|
||||
// host: this.redisEndpoint!.host,
|
||||
// port: this.redisEndpoint!.port
|
||||
// },
|
||||
// server: {
|
||||
// port: port,
|
||||
// host: '0.0.0.0'
|
||||
// },
|
||||
// discovery: {
|
||||
// interval: 1000,
|
||||
// timeout: 500
|
||||
// },
|
||||
// sharding: {
|
||||
// enabled: true,
|
||||
// replicas: 2
|
||||
// },
|
||||
// consensus: {
|
||||
// enabled: true,
|
||||
// quorum: Math.floor(this.config.nodeCount / 2) + 1
|
||||
// }
|
||||
// }
|
||||
});
|
||||
|
||||
await brain.init();
|
||||
|
||||
this.nodes.push({
|
||||
id: nodeId,
|
||||
brain: brain,
|
||||
port: port
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private async waitForClusterFormation(): Promise<void> {
|
||||
console.log('Waiting for cluster formation...');
|
||||
|
||||
const maxAttempts = 30;
|
||||
const delayMs = 1000;
|
||||
|
||||
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
||||
const allNodesDiscovered = await this.checkClusterHealth();
|
||||
|
||||
if (allNodesDiscovered) {
|
||||
console.log('All nodes have discovered each other');
|
||||
return;
|
||||
}
|
||||
|
||||
await new Promise(resolve => setTimeout(resolve, delayMs));
|
||||
}
|
||||
|
||||
throw new Error('Cluster formation timeout - nodes failed to discover each other');
|
||||
}
|
||||
|
||||
private async checkClusterHealth(): Promise<boolean> {
|
||||
for (const node of this.nodes) {
|
||||
const health = await node.brain.health();
|
||||
|
||||
if (!health.distributed || !health.distributed.connectedNodes) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Each node should see all other nodes
|
||||
const expectedNodeCount = this.config.nodeCount - 1;
|
||||
if (health.distributed.connectedNodes.length < expectedNodeCount) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
async stop(): Promise<void> {
|
||||
console.log('Stopping distributed test cluster...');
|
||||
|
||||
// Stop all nodes
|
||||
for (const node of this.nodes) {
|
||||
try {
|
||||
if (node.brain.close) {
|
||||
await node.brain.close();
|
||||
}
|
||||
console.log(`Stopped ${node.id}`);
|
||||
} catch (error) {
|
||||
console.warn(`Failed to stop ${node.id}:`, error);
|
||||
}
|
||||
}
|
||||
|
||||
// Stop Redis container
|
||||
if (this.redisContainer) {
|
||||
await this.redisContainer.stop();
|
||||
console.log('Redis container stopped');
|
||||
}
|
||||
|
||||
this.nodes = [];
|
||||
console.log('Distributed cluster stopped');
|
||||
}
|
||||
|
||||
getNodes(): DistributedTestNode[] {
|
||||
return this.nodes;
|
||||
}
|
||||
|
||||
getNode(index: number): DistributedTestNode {
|
||||
if (index < 0 || index >= this.nodes.length) {
|
||||
throw new Error(`Invalid node index: ${index}`);
|
||||
}
|
||||
return this.nodes[index];
|
||||
}
|
||||
|
||||
getPrimaryNode(): DistributedTestNode {
|
||||
return this.nodes[0];
|
||||
}
|
||||
|
||||
getSecondaryNodes(): DistributedTestNode[] {
|
||||
return this.nodes.slice(1);
|
||||
}
|
||||
|
||||
async executeOnAllNodes<T>(fn: (brain: Brainy) => Promise<T>): Promise<T[]> {
|
||||
return Promise.all(this.nodes.map(node => fn(node.brain)));
|
||||
}
|
||||
|
||||
async executeOnNode<T>(index: number, fn: (brain: Brainy) => Promise<T>): Promise<T> {
|
||||
const node = this.getNode(index);
|
||||
return fn(node.brain);
|
||||
}
|
||||
|
||||
async simulateNodeFailure(index: number): Promise<void> {
|
||||
const node = this.getNode(index);
|
||||
console.log(`Simulating failure of ${node.id}...`);
|
||||
|
||||
if (node.brain.close) {
|
||||
await node.brain.close();
|
||||
}
|
||||
|
||||
// Remove from active nodes
|
||||
this.nodes.splice(index, 1);
|
||||
}
|
||||
|
||||
async addNode(): Promise<DistributedTestNode> {
|
||||
const nodeId = `node-${this.nodes.length + 1}`;
|
||||
const port = 8000 + this.nodes.length;
|
||||
|
||||
console.log(`Adding new node ${nodeId} on port ${port}...`);
|
||||
|
||||
const brain = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'memory'
|
||||
}
|
||||
// distributed config is not part of BrainyConfig
|
||||
// distributed: {
|
||||
// enabled: true,
|
||||
// nodeId: nodeId,
|
||||
// redis: {
|
||||
// host: this.redisEndpoint!.host,
|
||||
// port: this.redisEndpoint!.port
|
||||
// },
|
||||
// server: {
|
||||
// port: port,
|
||||
// host: '0.0.0.0'
|
||||
// },
|
||||
// discovery: {
|
||||
// interval: 1000,
|
||||
// timeout: 500
|
||||
// },
|
||||
// sharding: {
|
||||
// enabled: true,
|
||||
// replicas: 2
|
||||
// }
|
||||
// }
|
||||
});
|
||||
|
||||
await brain.init();
|
||||
|
||||
const newNode = { id: nodeId, brain, port };
|
||||
this.nodes.push(newNode);
|
||||
|
||||
// Wait for new node to join cluster
|
||||
await this.waitForNodeDiscovery(nodeId);
|
||||
|
||||
return newNode;
|
||||
}
|
||||
|
||||
private async waitForNodeDiscovery(nodeId: string): Promise<void> {
|
||||
console.log(`Waiting for ${nodeId} to join cluster...`);
|
||||
|
||||
const maxAttempts = 10;
|
||||
const delayMs = 1000;
|
||||
|
||||
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
||||
const discovered = await this.isNodeDiscovered(nodeId);
|
||||
|
||||
if (discovered) {
|
||||
console.log(`${nodeId} has joined the cluster`);
|
||||
return;
|
||||
}
|
||||
|
||||
await new Promise(resolve => setTimeout(resolve, delayMs));
|
||||
}
|
||||
|
||||
throw new Error(`Timeout waiting for ${nodeId} to join cluster`);
|
||||
}
|
||||
|
||||
private async isNodeDiscovered(nodeId: string): Promise<boolean> {
|
||||
// Check if other nodes can see the new node
|
||||
for (const node of this.nodes) {
|
||||
if (node.id === nodeId) continue;
|
||||
|
||||
const health = await node.brain.health();
|
||||
if (health.distributed?.connectedNodes?.includes(nodeId)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
|
@ -67,7 +67,7 @@ echo ""
|
|||
|
||||
echo "📦 Batch 10: Other Tests"
|
||||
echo "------------------------"
|
||||
npm test -- --run tests/distributed*.test.ts tests/cli.test.ts tests/brainy-chat.test.ts tests/pagination.test.ts tests/vector-operations.test.ts tests/error-handling.test.ts tests/specialized-scenarios.test.ts tests/multi-environment.test.ts tests/statistics.test.ts tests/type-utils.test.ts 2>&1 | tee batch10.log | grep -E "✓|×|↓" | tail -20
|
||||
npm test -- --run tests/cli.test.ts tests/brainy-chat.test.ts tests/pagination.test.ts tests/vector-operations.test.ts tests/error-handling.test.ts tests/specialized-scenarios.test.ts tests/multi-environment.test.ts tests/statistics.test.ts tests/type-utils.test.ts 2>&1 | tee batch10.log | grep -E "✓|×|↓" | tail -20
|
||||
echo ""
|
||||
|
||||
# Aggregate results
|
||||
|
|
|
|||
|
|
@ -1,393 +0,0 @@
|
|||
/**
|
||||
* Distributed + Transactions Integration Tests
|
||||
*
|
||||
* Verifies that transactions work correctly with distributed storage:
|
||||
* - Remote storage adapters (S3, Azure, GCS)
|
||||
* - Distributed coordination
|
||||
* - Cache coherence
|
||||
* - Read/write separation
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
|
||||
import { Brainy } from '../../../src/brainy.js'
|
||||
import { NounType, VerbType } from '../../../src/types/graphTypes.js'
|
||||
import { tmpdir } from 'os'
|
||||
import { join } from 'path'
|
||||
import { mkdirSync, rmSync } from 'fs'
|
||||
|
||||
describe('Transactions + Distributed Storage Integration', () => {
|
||||
let brain: Brainy
|
||||
let testDir: string
|
||||
|
||||
beforeEach(async () => {
|
||||
testDir = join(tmpdir(), `brainy-distributed-test-${Date.now()}`)
|
||||
mkdirSync(testDir, { recursive: true })
|
||||
|
||||
// Use filesystem as proxy for distributed storage
|
||||
// (In production, this would be S3, Azure, GCS, etc.)
|
||||
brain = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
path: testDir
|
||||
}
|
||||
})
|
||||
|
||||
await brain.init()
|
||||
})
|
||||
|
||||
afterEach(async () => {
|
||||
if (brain) {
|
||||
await brain.shutdown()
|
||||
}
|
||||
if (testDir) {
|
||||
rmSync(testDir, { recursive: true, force: true })
|
||||
}
|
||||
})
|
||||
|
||||
describe('Remote Storage Adapters', () => {
|
||||
it('should handle transactions with filesystem storage (proxy for remote)', async () => {
|
||||
// Add entity (atomic operation)
|
||||
const id = await brain.add({
|
||||
data: { name: 'Remote Entity', location: 'cloud' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
expect(id).toBeTruthy()
|
||||
|
||||
// Verify entity persisted to storage
|
||||
const entity = await brain.get(id)
|
||||
expect(entity).toBeTruthy()
|
||||
expect(entity?.data.name).toBe('Remote Entity')
|
||||
})
|
||||
|
||||
it('should rollback failed operations with remote storage', async () => {
|
||||
// Add first entity (succeeds)
|
||||
const id1 = await brain.add({
|
||||
data: { name: 'Entity 1' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Attempt to add with invalid data (fails)
|
||||
let failed = false
|
||||
try {
|
||||
await brain.add({
|
||||
data: null as any,
|
||||
type: NounType.Thing
|
||||
})
|
||||
} catch (e) {
|
||||
failed = true
|
||||
}
|
||||
|
||||
expect(failed).toBe(true)
|
||||
|
||||
// First entity should still exist
|
||||
const entity1 = await brain.get(id1)
|
||||
expect(entity1).toBeTruthy()
|
||||
})
|
||||
|
||||
it('should handle update operations with remote storage atomically', async () => {
|
||||
// Add entity
|
||||
const id = await brain.add({
|
||||
data: { name: 'Original', version: 1 },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Update atomically
|
||||
await brain.update({
|
||||
id,
|
||||
data: { name: 'Updated', version: 2 }
|
||||
})
|
||||
|
||||
// Verify update persisted
|
||||
const entity = await brain.get(id)
|
||||
expect(entity?.data.version).toBe(2)
|
||||
})
|
||||
})
|
||||
|
||||
describe('Write Coordinator Atomicity', () => {
|
||||
it('should ensure atomicity at write coordinator level', async () => {
|
||||
// Simulate write coordinator scenario
|
||||
// (Single Brainy instance coordinating writes)
|
||||
|
||||
const entities: string[] = []
|
||||
|
||||
// Multiple atomic writes
|
||||
for (let i = 0; i < 5; i++) {
|
||||
const id = await brain.add({
|
||||
data: { name: `Entity ${i}`, index: i },
|
||||
type: NounType.Thing
|
||||
})
|
||||
entities.push(id)
|
||||
}
|
||||
|
||||
// Create relationships (atomic)
|
||||
for (let i = 0; i < entities.length - 1; i++) {
|
||||
await brain.relate({
|
||||
from: entities[i],
|
||||
to: entities[i + 1],
|
||||
type: VerbType.RelatesTo
|
||||
})
|
||||
}
|
||||
|
||||
// Verify all operations succeeded
|
||||
for (let i = 0; i < entities.length; i++) {
|
||||
const entity = await brain.get(entities[i])
|
||||
expect(entity).toBeTruthy()
|
||||
expect(entity?.data.index).toBe(i)
|
||||
}
|
||||
|
||||
// Verify relationships
|
||||
for (let i = 0; i < entities.length - 1; i++) {
|
||||
const relations = await brain.related({ from: entities[i] })
|
||||
expect(relations).toHaveLength(1)
|
||||
}
|
||||
})
|
||||
|
||||
it('should handle batch operations atomically on write coordinator', async () => {
|
||||
const batchSize = 20
|
||||
const ids: string[] = []
|
||||
|
||||
// Batch add operations
|
||||
for (let i = 0; i < batchSize; i++) {
|
||||
const id = await brain.add({
|
||||
data: { name: `Batch Entity ${i}`, batch: true },
|
||||
type: NounType.Thing
|
||||
})
|
||||
ids.push(id)
|
||||
}
|
||||
|
||||
// Verify all entities persisted
|
||||
let count = 0
|
||||
for (const id of ids) {
|
||||
const entity = await brain.get(id)
|
||||
if (entity) count++
|
||||
}
|
||||
|
||||
expect(count).toBe(batchSize)
|
||||
})
|
||||
})
|
||||
|
||||
describe('Read-After-Write Consistency', () => {
|
||||
it('should ensure read-after-write consistency', async () => {
|
||||
// Write entity
|
||||
const id = await brain.add({
|
||||
data: { name: 'RAW Test', timestamp: Date.now() },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Immediate read (should see the write)
|
||||
const entity = await brain.get(id)
|
||||
expect(entity).toBeTruthy()
|
||||
expect(entity?.data.name).toBe('RAW Test')
|
||||
})
|
||||
|
||||
it('should maintain consistency after update', async () => {
|
||||
const id = await brain.add({
|
||||
data: { name: 'Original', counter: 0 },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Multiple updates
|
||||
for (let i = 1; i <= 5; i++) {
|
||||
await brain.update({
|
||||
id,
|
||||
data: { name: `Updated ${i}`, counter: i }
|
||||
})
|
||||
|
||||
// Read immediately after each update
|
||||
const entity = await brain.get(id)
|
||||
expect(entity?.data.counter).toBe(i)
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
describe('Concurrent Write Handling', () => {
|
||||
it('should handle sequential writes correctly', async () => {
|
||||
const ids: string[] = []
|
||||
|
||||
// Sequential writes (simulating distributed writes to coordinator)
|
||||
for (let i = 0; i < 10; i++) {
|
||||
const id = await brain.add({
|
||||
data: { name: `Sequential ${i}`, order: i },
|
||||
type: NounType.Thing
|
||||
})
|
||||
ids.push(id)
|
||||
}
|
||||
|
||||
// Verify all writes succeeded
|
||||
for (let i = 0; i < ids.length; i++) {
|
||||
const entity = await brain.get(ids[i])
|
||||
expect(entity?.data.order).toBe(i)
|
||||
}
|
||||
})
|
||||
|
||||
it('should handle interleaved operations atomically', async () => {
|
||||
// Create entities
|
||||
const id1 = await brain.add({
|
||||
data: { name: 'Entity A', value: 100 },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
const id2 = await brain.add({
|
||||
data: { name: 'Entity B', value: 200 },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Interleaved updates
|
||||
await brain.update({ id: id1, data: { value: 150 } })
|
||||
await brain.update({ id: id2, data: { value: 250 } })
|
||||
await brain.update({ id: id1, data: { value: 175 } })
|
||||
|
||||
// Verify final state
|
||||
const entity1 = await brain.get(id1)
|
||||
const entity2 = await brain.get(id2)
|
||||
|
||||
expect(entity1?.data.value).toBe(175)
|
||||
expect(entity2?.data.value).toBe(250)
|
||||
})
|
||||
})
|
||||
|
||||
describe('Delete Operations with Distributed Storage', () => {
|
||||
it('should handle delete operations atomically', async () => {
|
||||
// Create entity
|
||||
const id = await brain.add({
|
||||
data: { name: 'To Delete', status: 'active' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Verify exists
|
||||
let entity = await brain.get(id)
|
||||
expect(entity).toBeTruthy()
|
||||
|
||||
// Delete atomically
|
||||
await brain.remove(id)
|
||||
|
||||
// Verify deleted
|
||||
entity = await brain.get(id)
|
||||
expect(entity).toBeNull()
|
||||
})
|
||||
|
||||
it('should handle delete with relationships atomically', async () => {
|
||||
// Create entities and relationships
|
||||
const id1 = await brain.add({
|
||||
data: { name: 'Entity 1' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
const id2 = await brain.add({
|
||||
data: { name: 'Entity 2' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
await brain.relate({
|
||||
from: id1,
|
||||
to: id2,
|
||||
type: VerbType.RelatesTo
|
||||
})
|
||||
|
||||
// Delete first entity (should delete relationships)
|
||||
await brain.remove(id1)
|
||||
|
||||
// Verify entity deleted
|
||||
const entity1 = await brain.get(id1)
|
||||
expect(entity1).toBeNull()
|
||||
|
||||
// Verify relationships deleted
|
||||
const relations = await brain.related({ from: id1 })
|
||||
expect(relations).toHaveLength(0)
|
||||
|
||||
// Entity 2 should still exist
|
||||
const entity2 = await brain.get(id2)
|
||||
expect(entity2).toBeTruthy()
|
||||
})
|
||||
})
|
||||
|
||||
describe('Storage Adapter Transparency', () => {
|
||||
it('should work transparently with any storage adapter', async () => {
|
||||
// This test verifies that transactions don't make assumptions
|
||||
// about the underlying storage implementation
|
||||
|
||||
// Add entity
|
||||
const id = await brain.add({
|
||||
data: { name: 'Adapter Test', adapter: 'filesystem' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Update entity
|
||||
await brain.update({
|
||||
id,
|
||||
data: { name: 'Updated via Adapter', adapter: 'filesystem' }
|
||||
})
|
||||
|
||||
// Query entity
|
||||
const entity = await brain.get(id)
|
||||
expect(entity).toBeTruthy()
|
||||
expect(entity?.data.name).toBe('Updated via Adapter')
|
||||
|
||||
// Delete entity
|
||||
await brain.remove(id)
|
||||
const deletedEntity = await brain.get(id)
|
||||
expect(deletedEntity).toBeNull()
|
||||
})
|
||||
|
||||
it('should maintain atomicity regardless of storage latency', async () => {
|
||||
// Simulate scenario with storage latency
|
||||
// (In distributed setup, network latency is a factor)
|
||||
|
||||
const startTime = Date.now()
|
||||
|
||||
// Operations that might have latency
|
||||
const id1 = await brain.add({
|
||||
data: { name: 'Latency Test 1' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
const id2 = await brain.add({
|
||||
data: { name: 'Latency Test 2' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
await brain.relate({
|
||||
from: id1,
|
||||
to: id2,
|
||||
type: VerbType.RelatesTo
|
||||
})
|
||||
|
||||
const endTime = Date.now()
|
||||
const duration = endTime - startTime
|
||||
|
||||
// Verify all operations succeeded (regardless of latency)
|
||||
const entity1 = await brain.get(id1)
|
||||
const entity2 = await brain.get(id2)
|
||||
const relations = await brain.related({ from: id1 })
|
||||
|
||||
expect(entity1).toBeTruthy()
|
||||
expect(entity2).toBeTruthy()
|
||||
expect(relations).toHaveLength(1)
|
||||
|
||||
// Should complete in reasonable time (even with storage latency)
|
||||
expect(duration).toBeLessThan(5000)
|
||||
})
|
||||
})
|
||||
|
||||
describe('Transaction Statistics with Distributed Storage', () => {
|
||||
it('should track transaction statistics accurately', async () => {
|
||||
// Get transaction manager stats
|
||||
const stats = (brain as any).transactionManager?.getStats()
|
||||
|
||||
if (stats) {
|
||||
const initialTotal = stats.totalTransactions
|
||||
|
||||
// Perform operations
|
||||
await brain.add({
|
||||
data: { name: 'Stats Test' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Check stats updated
|
||||
const updatedStats = (brain as any).transactionManager?.getStats()
|
||||
expect(updatedStats.totalTransactions).toBeGreaterThan(initialTotal)
|
||||
}
|
||||
})
|
||||
})
|
||||
})
|
||||
|
|
@ -1,295 +0,0 @@
|
|||
/**
|
||||
* Sharding + Transactions Integration Tests
|
||||
*
|
||||
* Verifies that transactions work correctly with sharded storage:
|
||||
* - Cross-shard atomicity
|
||||
* - Shard-aware routing
|
||||
* - Rollback across shards
|
||||
* - UUID-based shard distribution
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
|
||||
import { Brainy } from '../../../src/brainy.js'
|
||||
import { NounType, VerbType } from '../../../src/types/graphTypes.js'
|
||||
import { tmpdir } from 'os'
|
||||
import { join } from 'path'
|
||||
import { mkdirSync, rmSync } from 'fs'
|
||||
|
||||
describe('Transactions + Sharding Integration', () => {
|
||||
let brain: Brainy
|
||||
let testDir: string
|
||||
|
||||
beforeEach(async () => {
|
||||
testDir = join(tmpdir(), `brainy-shard-test-${Date.now()}`)
|
||||
mkdirSync(testDir, { recursive: true })
|
||||
|
||||
brain = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
path: testDir
|
||||
}
|
||||
})
|
||||
|
||||
await brain.init()
|
||||
})
|
||||
|
||||
afterEach(async () => {
|
||||
if (brain) {
|
||||
await brain.shutdown()
|
||||
}
|
||||
if (testDir) {
|
||||
rmSync(testDir, { recursive: true, force: true })
|
||||
}
|
||||
})
|
||||
|
||||
describe('Cross-Shard Operations', () => {
|
||||
it('should handle atomic operations across multiple shards', async () => {
|
||||
// Create entities with different UUID prefixes (different shards)
|
||||
const id1 = 'aaa00000-1111-4111-8111-111111111111' // Shard: aaa
|
||||
const id2 = 'bbb00000-2222-4222-8222-222222222222' // Shard: bbb
|
||||
|
||||
// Add entities to different shards (atomic)
|
||||
await brain.add({
|
||||
id: id1,
|
||||
data: { name: 'Entity in Shard A', shard: 'aaa' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
await brain.add({
|
||||
id: id2,
|
||||
data: { name: 'Entity in Shard B', shard: 'bbb' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Create relationship across shards (atomic)
|
||||
const relationId = await brain.relate({
|
||||
from: id1,
|
||||
to: id2,
|
||||
type: VerbType.RelatesTo
|
||||
})
|
||||
|
||||
// Verify all entities exist
|
||||
const entity1 = await brain.get(id1)
|
||||
const entity2 = await brain.get(id2)
|
||||
const relations = await brain.related({ from: id1 })
|
||||
|
||||
expect(entity1).toBeTruthy()
|
||||
expect(entity2).toBeTruthy()
|
||||
expect(relations).toHaveLength(1)
|
||||
expect(relations[0].targetId).toBe(id2)
|
||||
})
|
||||
|
||||
it('should rollback operations across multiple shards', async () => {
|
||||
const id1 = 'ccc00000-1111-4111-8111-111111111111' // Shard: ccc
|
||||
const id2 = 'ddd00000-2222-4222-8222-222222222222' // Shard: ddd
|
||||
|
||||
// Add first entity (succeeds)
|
||||
await brain.add({
|
||||
id: id1,
|
||||
data: { name: 'Entity in Shard C' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Attempt to add second entity with invalid data (fails)
|
||||
let failed = false
|
||||
try {
|
||||
await brain.add({
|
||||
id: id2,
|
||||
data: null as any, // Invalid
|
||||
type: NounType.Thing
|
||||
})
|
||||
} catch (e) {
|
||||
failed = true
|
||||
}
|
||||
|
||||
expect(failed).toBe(true)
|
||||
|
||||
// First entity should still exist (in shard C)
|
||||
const entity1 = await brain.get(id1)
|
||||
expect(entity1).toBeTruthy()
|
||||
|
||||
// Second entity should not exist (rollback in shard D)
|
||||
const entity2 = await brain.get(id2)
|
||||
expect(entity2).toBeNull()
|
||||
})
|
||||
|
||||
it('should handle updates across shards atomically', async () => {
|
||||
const id1 = 'eee00000-1111-4111-8111-111111111111'
|
||||
const id2 = 'fff00000-2222-4222-8222-222222222222'
|
||||
|
||||
// Add entities
|
||||
await brain.add({
|
||||
id: id1,
|
||||
data: { name: 'Original E', version: 1 },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
await brain.add({
|
||||
id: id2,
|
||||
data: { name: 'Original F', version: 1 },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Update both entities (different shards)
|
||||
await brain.update({
|
||||
id: id1,
|
||||
data: { name: 'Updated E', version: 2 }
|
||||
})
|
||||
|
||||
await brain.update({
|
||||
id: id2,
|
||||
data: { name: 'Updated F', version: 2 }
|
||||
})
|
||||
|
||||
// Verify updates in both shards
|
||||
const entity1 = await brain.get(id1)
|
||||
const entity2 = await brain.get(id2)
|
||||
|
||||
expect(entity1?.data.version).toBe(2)
|
||||
expect(entity2?.data.version).toBe(2)
|
||||
})
|
||||
})
|
||||
|
||||
describe('Shard Distribution', () => {
|
||||
it('should distribute entities across shards based on UUID', async () => {
|
||||
// Create entities with various UUID prefixes
|
||||
const ids = [
|
||||
'aaa00000-1111-4111-8111-111111111111',
|
||||
'bbb00000-2222-4222-8222-222222222222',
|
||||
'ccc00000-3333-4333-8333-333333333333',
|
||||
'ddd00000-4444-4444-8444-444444444444'
|
||||
]
|
||||
|
||||
// Add entities to different shards
|
||||
for (let i = 0; i < ids.length; i++) {
|
||||
await brain.add({
|
||||
id: ids[i],
|
||||
data: { name: `Entity ${i}`, index: i },
|
||||
type: NounType.Thing
|
||||
})
|
||||
}
|
||||
|
||||
// Verify all entities can be retrieved (regardless of shard)
|
||||
for (let i = 0; i < ids.length; i++) {
|
||||
const entity = await brain.get(ids[i])
|
||||
expect(entity).toBeTruthy()
|
||||
expect(entity?.data.index).toBe(i)
|
||||
}
|
||||
})
|
||||
|
||||
it('should handle relationships between different shard combinations', async () => {
|
||||
const entities = [
|
||||
{ id: 'aaa00000-1111-4111-8111-111111111111', name: 'A' },
|
||||
{ id: 'bbb00000-2222-4222-8222-222222222222', name: 'B' },
|
||||
{ id: 'ccc00000-3333-4333-8333-333333333333', name: 'C' }
|
||||
]
|
||||
|
||||
// Add all entities
|
||||
for (const e of entities) {
|
||||
await brain.add({
|
||||
id: e.id,
|
||||
data: { name: e.name },
|
||||
type: NounType.Thing
|
||||
})
|
||||
}
|
||||
|
||||
// Create relationships across all shards
|
||||
await brain.relate({
|
||||
from: entities[0].id,
|
||||
to: entities[1].id,
|
||||
type: VerbType.RelatesTo
|
||||
})
|
||||
|
||||
await brain.relate({
|
||||
from: entities[1].id,
|
||||
to: entities[2].id,
|
||||
type: VerbType.RelatesTo
|
||||
})
|
||||
|
||||
await brain.relate({
|
||||
from: entities[2].id,
|
||||
to: entities[0].id,
|
||||
type: VerbType.RelatesTo
|
||||
})
|
||||
|
||||
// Verify all relationships exist
|
||||
const relations0 = await brain.related({ from: entities[0].id })
|
||||
const relations1 = await brain.related({ from: entities[1].id })
|
||||
const relations2 = await brain.related({ from: entities[2].id })
|
||||
|
||||
expect(relations0).toHaveLength(1)
|
||||
expect(relations1).toHaveLength(1)
|
||||
expect(relations2).toHaveLength(1)
|
||||
})
|
||||
})
|
||||
|
||||
describe('Delete Operations Across Shards', () => {
|
||||
it('should delete entities and relationships across shards atomically', async () => {
|
||||
const id1 = 'ggg00000-1111-4111-8111-111111111111'
|
||||
const id2 = 'hhh00000-2222-4222-8222-222222222222'
|
||||
|
||||
// Add entities in different shards
|
||||
await brain.add({
|
||||
id: id1,
|
||||
data: { name: 'Entity G' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
await brain.add({
|
||||
id: id2,
|
||||
data: { name: 'Entity H' },
|
||||
type: NounType.Thing
|
||||
})
|
||||
|
||||
// Create relationship
|
||||
await brain.relate({
|
||||
from: id1,
|
||||
to: id2,
|
||||
type: VerbType.RelatesTo
|
||||
})
|
||||
|
||||
// Delete first entity (should also delete relationship)
|
||||
await brain.remove(id1)
|
||||
|
||||
// Verify entity deleted from shard G
|
||||
const entity1 = await brain.get(id1)
|
||||
expect(entity1).toBeNull()
|
||||
|
||||
// Entity H should still exist in shard H
|
||||
const entity2 = await brain.get(id2)
|
||||
expect(entity2).toBeTruthy()
|
||||
|
||||
// Relationship should be deleted
|
||||
const relations = await brain.related({ from: id1 })
|
||||
expect(relations).toHaveLength(0)
|
||||
})
|
||||
})
|
||||
|
||||
describe('Batch Operations Across Shards', () => {
|
||||
it('should handle batch adds across multiple shards atomically', async () => {
|
||||
const entities = [
|
||||
{ id: 'shard1-00-1111-4111-8111-111111111111', data: { name: 'S1-E1' } },
|
||||
{ id: 'shard2-00-2222-4222-8222-222222222222', data: { name: 'S2-E1' } },
|
||||
{ id: 'shard3-00-3333-4333-8333-333333333333', data: { name: 'S3-E1' } },
|
||||
{ id: 'shard1-00-4444-4444-8444-444444444444', data: { name: 'S1-E2' } },
|
||||
{ id: 'shard2-00-5555-4555-8555-555555555555', data: { name: 'S2-E2' } }
|
||||
]
|
||||
|
||||
// Add all entities (distributed across shards)
|
||||
for (const e of entities) {
|
||||
await brain.add({
|
||||
id: e.id,
|
||||
data: e.data,
|
||||
type: NounType.Thing
|
||||
})
|
||||
}
|
||||
|
||||
// Verify all entities exist in their respective shards
|
||||
for (const e of entities) {
|
||||
const entity = await brain.get(e.id)
|
||||
expect(entity).toBeTruthy()
|
||||
expect(entity?.data.name).toBe(e.data.name)
|
||||
}
|
||||
})
|
||||
})
|
||||
})
|
||||
Loading…
Add table
Add a link
Reference in a new issue