vectra 0.12.2 → 0.14.0

package/src/server/VectraServer.spec.ts

@@ -0,0 +1,303 @@
+import * as assert from 'assert';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as grpc from '@grpc/grpc-js';
+import * as protoLoader from '@grpc/proto-loader';
+import { VectraServer } from './VectraServer';
+
+const TEST_ROOT = path.join(__dirname, '..', '..', '.test-server-root');
+const PROTO_PATH = path.join(__dirname, '..', '..', 'proto', 'vectra_service.proto');
+
+function loadClient(port: number): any {
+    const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+        keepCase: true,
+        longs: Number,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+    });
+    const proto = grpc.loadPackageDefinition(packageDefinition) as any;
+    return new proto.vectra.VectraService(
+        `127.0.0.1:${port}`,
+        grpc.credentials.createInsecure()
+    );
+}
+
+function rpc(client: any, method: string, request: any): Promise<any> {
+    return new Promise((resolve, reject) => {
+        client[method](request, (err: any, response: any) => {
+            if (err) reject(err);
+            else resolve(response);
+        });
+    });
+}
+
+function cleanTestDir() {
+    if (fs.existsSync(TEST_ROOT)) {
+        fs.rmSync(TEST_ROOT, { recursive: true });
+    }
+    fs.mkdirSync(TEST_ROOT, { recursive: true });
+}
+
+describe('VectraServer', function () {
+    this.timeout(30000);
+
+    let server: VectraServer;
+    let client: any;
+    let port: number;
+
+    before(async () => {
+        cleanTestDir();
+        server = new VectraServer({
+            port: 0, // random available port
+            rootDir: TEST_ROOT,
+            scanInterval: 500,
+        });
+        port = await server.start();
+        client = loadClient(port);
+    });
+
+    after(async () => {
+        if (client) {
+            client.close();
+        }
+        if (server) {
+            await server.shutdown();
+        }
+        if (fs.existsSync(TEST_ROOT)) {
+            fs.rmSync(TEST_ROOT, { recursive: true });
+        }
+    });
+
+    describe('Lifecycle RPCs', () => {
+        it('should respond to Healthcheck', async () => {
+            const res = await rpc(client, 'Healthcheck', {});
+            assert.strictEqual(res.status, 'ok');
+            assert.strictEqual(typeof res.uptime_seconds, 'number');
+            assert.strictEqual(typeof res.loaded_indexes, 'number');
+        });
+    });
+
+    describe('Index Management RPCs', () => {
+        it('should create an index', async () => {
+            await rpc(client, 'CreateIndex', {
+                index_name: 'test-index',
+                format: 'json',
+                is_document_index: false,
+            });
+
+            const list = await rpc(client, 'ListIndexes', {});
+            const names = list.indexes.map((i: any) => i.name);
+            assert.ok(names.includes('test-index'), `Expected test-index in ${JSON.stringify(names)}`);
+        });
+
+        it('should fail to create a duplicate index', async () => {
+            try {
+                await rpc(client, 'CreateIndex', {
+                    index_name: 'test-index',
+                    format: 'json',
+                    is_document_index: false,
+                });
+                assert.fail('Expected ALREADY_EXISTS error');
+            } catch (err: any) {
+                assert.strictEqual(err.code, grpc.status.ALREADY_EXISTS);
+            }
+        });
+
+        it('should list indexes', async () => {
+            const res = await rpc(client, 'ListIndexes', {});
+            assert.ok(Array.isArray(res.indexes));
+            assert.ok(res.indexes.length >= 1);
+        });
+    });
+
+    describe('Item Operations RPCs', () => {
+        const testVector = new Array(3).fill(0).map((_, i) => (i + 1) * 0.1);
+
+        it('should insert an item', async () => {
+            const res = await rpc(client, 'InsertItem', {
+                index_name: 'test-index',
+                vector: testVector,
+                metadata: {
+                    category: { string_value: 'test' },
+                    score: { number_value: 0.95 },
+                },
+                id: 'item-1',
+            });
+            assert.strictEqual(res.id, 'item-1');
+        });
+
+        it('should get an item by id', async () => {
+            const res = await rpc(client, 'GetItem', {
+                index_name: 'test-index',
+                id: 'item-1',
+            });
+            assert.ok(res.item);
+            assert.strictEqual(res.item.id, 'item-1');
+            assert.ok(res.item.vector.length > 0);
+        });
+
+        it('should return NOT_FOUND for missing item', async () => {
+            try {
+                await rpc(client, 'GetItem', {
+                    index_name: 'test-index',
+                    id: 'nonexistent',
+                });
+                assert.fail('Expected NOT_FOUND error');
+            } catch (err: any) {
+                assert.strictEqual(err.code, grpc.status.NOT_FOUND);
+            }
+        });
+
+        it('should upsert an item', async () => {
+            const newVector = new Array(3).fill(0).map((_, i) => (i + 1) * 0.2);
+            const res = await rpc(client, 'UpsertItem', {
+                index_name: 'test-index',
+                id: 'item-1',
+                vector: newVector,
+                metadata: {
+                    category: { string_value: 'updated' },
+                },
+            });
+            assert.strictEqual(res.id, 'item-1');
+
+            // Verify update
+            const getRes = await rpc(client, 'GetItem', {
+                index_name: 'test-index',
+                id: 'item-1',
+            });
+            assert.strictEqual(getRes.item.metadata.category.string_value, 'updated');
+        });
+
+        it('should batch insert items', async () => {
+            const res = await rpc(client, 'BatchInsertItems', {
+                index_name: 'test-index',
+                items: [
+                    { vector: [0.1, 0.2, 0.3], metadata: { tag: { string_value: 'a' } }, id: 'batch-1' },
+                    { vector: [0.4, 0.5, 0.6], metadata: { tag: { string_value: 'b' } }, id: 'batch-2' },
+                ],
+            });
+            assert.strictEqual(res.ids.length, 2);
+            assert.ok(res.ids.includes('batch-1'));
+            assert.ok(res.ids.includes('batch-2'));
+        });
+
+        it('should list items', async () => {
+            const res = await rpc(client, 'ListItems', {
+                index_name: 'test-index',
+            });
+            assert.ok(res.items.length >= 3); // item-1, batch-1, batch-2
+        });
+
+        it('should delete an item', async () => {
+            await rpc(client, 'DeleteItem', {
+                index_name: 'test-index',
+                id: 'batch-2',
+            });
+
+            // Verify it's gone
+            try {
+                await rpc(client, 'GetItem', {
+                    index_name: 'test-index',
+                    id: 'batch-2',
+                });
+                assert.fail('Expected NOT_FOUND');
+            } catch (err: any) {
+                assert.strictEqual(err.code, grpc.status.NOT_FOUND);
+            }
+        });
+    });
+
+    describe('Query RPCs', () => {
+        it('should query items by vector', async () => {
+            const res = await rpc(client, 'QueryItems', {
+                index_name: 'test-index',
+                vector: [0.1, 0.2, 0.3],
+                top_k: 5,
+            });
+            assert.ok(Array.isArray(res.results));
+            assert.ok(res.results.length > 0);
+            // Results should have scores
+            assert.ok(typeof res.results[0].score === 'number');
+        });
+    });
+
+    describe('Stats RPCs', () => {
+        it('should get index stats', async () => {
+            const res = await rpc(client, 'GetIndexStats', {
+                index_name: 'test-index',
+            });
+            assert.strictEqual(res.version, 1);
+            assert.strictEqual(res.format, 'json');
+            assert.ok(typeof res.item_count === 'number');
+        });
+    });
+
+    describe('Error handling', () => {
+        it('should return NOT_FOUND for unknown index', async () => {
+            try {
+                await rpc(client, 'GetIndexStats', {
+                    index_name: 'no-such-index',
+                });
+                assert.fail('Expected NOT_FOUND');
+            } catch (err: any) {
+                assert.strictEqual(err.code, grpc.status.NOT_FOUND);
+            }
+        });
+
+        it('should return INVALID_ARGUMENT for missing required fields', async () => {
+            try {
+                await rpc(client, 'InsertItem', {
+                    index_name: 'test-index',
+                    // no text or vector
+                });
+                assert.fail('Expected INVALID_ARGUMENT');
+            } catch (err: any) {
+                assert.strictEqual(err.code, grpc.status.INVALID_ARGUMENT);
+            }
+        });
+
+        it('should return FAILED_PRECONDITION for non-document index on document ops', async () => {
+            try {
+                await rpc(client, 'ListDocuments', {
+                    index_name: 'test-index',
+                });
+                assert.fail('Expected FAILED_PRECONDITION');
+            } catch (err: any) {
+                assert.strictEqual(err.code, grpc.status.FAILED_PRECONDITION);
+            }
+        });
+    });
+
+    describe('Index deletion', () => {
+        it('should delete an index', async () => {
+            await rpc(client, 'DeleteIndex', {
+                index_name: 'test-index',
+            });
+
+            const list = await rpc(client, 'ListIndexes', {});
+            const names = list.indexes.map((i: any) => i.name);
+            assert.ok(!names.includes('test-index'));
+        });
+    });
+
+    describe('Auto-detect new indexes', () => {
+        it('should detect indexes created on disk', async function () {
+            // Create an index directly on disk (outside the gRPC API)
+            const indexDir = path.join(TEST_ROOT, 'auto-detected');
+            fs.mkdirSync(indexDir, { recursive: true });
+            fs.writeFileSync(path.join(indexDir, 'index.json'), JSON.stringify({
+                version: 1,
+                metadata_config: {},
+                items: [],
+            }));
+
+            // Wait for the scanner to pick it up
+            await new Promise(r => setTimeout(r, 1500));
+
+            const list = await rpc(client, 'ListIndexes', {});
+            const names = list.indexes.map((i: any) => i.name);
+            assert.ok(names.includes('auto-detected'), `Expected auto-detected in ${JSON.stringify(names)}`);
+        });
+    });
+});

package/src/server/VectraServer.ts

@@ -0,0 +1,156 @@
+import * as path from 'path';
+import * as grpc from '@grpc/grpc-js';
+import * as protoLoader from '@grpc/proto-loader';
+import { IndexManager, IndexManagerConfig } from './IndexManager';
+import { EmbeddingsModel } from '../types';
+import {
+    createIndexHandlers,
+    createItemHandlers,
+    createQueryHandlers,
+    createDocumentHandlers,
+    createStatsHandlers,
+    createLifecycleHandlers,
+} from './handlers';
+
+export interface VectraServerConfig {
+    /** Port to bind the gRPC server on (default: 50051). */
+    port?: number;
+    /** Single index path (mutually exclusive with rootDir). */
+    indexPath?: string;
+    /** Root directory containing multiple index subdirectories. */
+    rootDir?: string;
+    /** Embeddings model for server-side embedding computation. */
+    embeddings?: EmbeddingsModel;
+    /** Polling interval in ms for auto-detecting new indexes (default: 3000). */
+    scanInterval?: number;
+}
+
+const DRAIN_TIMEOUT_MS = 5000;
+
+/**
+ * gRPC server that exposes Vectra indexes over the VectraService proto.
+ */
+export class VectraServer {
+    private readonly _config: VectraServerConfig;
+    private readonly _indexManager: IndexManager;
+    private _server?: grpc.Server;
+    private _startTime: number = 0;
+    private _shutdownPromise?: Promise<void>;
+
+    constructor(config: VectraServerConfig) {
+        this._config = config;
+        const managerConfig: IndexManagerConfig = {
+            indexPath: config.indexPath,
+            rootDir: config.rootDir,
+            embeddings: config.embeddings,
+            scanInterval: config.scanInterval,
+        };
+        this._indexManager = new IndexManager(managerConfig);
+    }
+
+    /** The underlying IndexManager. */
+    public get indexManager(): IndexManager {
+        return this._indexManager;
+    }
+
+    /** The underlying gRPC server instance. */
+    public get server(): grpc.Server | undefined {
+        return this._server;
+    }
+
+    /**
+     * Starts the gRPC server and loads indexes.
+     * @returns The port the server is listening on.
+     */
+    public async start(): Promise<number> {
+        this._startTime = Date.now();
+
+        // Load proto definition
+        const protoPath = path.resolve(__dirname, '..', '..', 'proto', 'vectra_service.proto');
+        const packageDefinition = protoLoader.loadSync(protoPath, {
+            keepCase: true,
+            longs: Number,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+        });
+        const protoDescriptor = grpc.loadPackageDefinition(packageDefinition) as any;
+        const vectraService = protoDescriptor.vectra.VectraService;
+
+        // Initialize index manager
+        await this._indexManager.initialize();
+
+        // Create gRPC server
+        this._server = new grpc.Server();
+
+        // Register all handler groups
+        const indexHandlers = createIndexHandlers(this._indexManager);
+        const itemHandlers = createItemHandlers(this._indexManager, this._config.embeddings);
+        const queryHandlers = createQueryHandlers(this._indexManager, this._config.embeddings);
+        const documentHandlers = createDocumentHandlers(this._indexManager);
+        const statsHandlers = createStatsHandlers(this._indexManager);
+        const lifecycleHandlers = createLifecycleHandlers(
+            this._indexManager,
+            this._startTime,
+            () => this.shutdown()
+        );
+
+        this._server.addService(vectraService.service, {
+            ...indexHandlers,
+            ...itemHandlers,
+            ...queryHandlers,
+            ...documentHandlers,
+            ...statsHandlers,
+            ...lifecycleHandlers,
+        });
+
+        // Bind to localhost only
+        const port = this._config.port ?? 50051;
+        const boundPort = await new Promise<number>((resolve, reject) => {
+            this._server!.bindAsync(
+                `127.0.0.1:${port}`,
+                grpc.ServerCredentials.createInsecure(),
+                (err, actualPort) => {
+                    if (err) {
+                        reject(err);
+                    } else {
+                        resolve(actualPort);
+                    }
+                }
+            );
+        });
+
+        return boundPort;
+    }
+
+    /**
+     * Gracefully shuts down the server with a 5s draining timeout.
+     */
+    public async shutdown(): Promise<void> {
+        if (this._shutdownPromise) return this._shutdownPromise;
+
+        this._shutdownPromise = (async () => {
+            // Stop index manager scanning
+            await this._indexManager.shutdown();
+
+            if (!this._server) return;
+
+            // Try graceful shutdown with timeout
+            await new Promise<void>((resolve) => {
+                const timer = setTimeout(() => {
+                    this._server!.forceShutdown();
+                    resolve();
+                }, DRAIN_TIMEOUT_MS);
+
+                this._server!.tryShutdown((err) => {
+                    clearTimeout(timer);
+                    resolve();
+                });
+            });
+
+            this._server = undefined;
+        })();
+
+        return this._shutdownPromise;
+    }
+}

package/src/server/handlers/documentHandlers.ts

@@ -0,0 +1,59 @@
+import * as grpc from '@grpc/grpc-js';
+import { IndexManager } from '../IndexManager';
+import { wrapHandler, grpcError, fromProtoMetadata } from './helpers';
+
+export function createDocumentHandlers(manager: IndexManager) {
+    return {
+        UpsertDocument: wrapHandler(async (call: grpc.ServerUnaryCall<any, any>) => {
+            const req = call.request;
+            if (!req.index_name) {
+                throw grpcError(grpc.status.INVALID_ARGUMENT, 'index_name is required');
+            }
+            if (!req.uri) {
+                throw grpcError(grpc.status.INVALID_ARGUMENT, 'uri is required');
+            }
+            if (!req.text) {
+                throw grpcError(grpc.status.INVALID_ARGUMENT, 'text is required');
+            }
+            const { docIndex } = manager.requireDocumentIndex(req.index_name);
+            const metadata = fromProtoMetadata(req.metadata);
+            const metadataArg = Object.keys(metadata).length > 0 ? metadata : undefined;
+
+            const doc = await docIndex.upsertDocument(
+                req.uri,
+                req.text,
+                req.doc_type || undefined,
+                metadataArg
+            );
+            return { document_id: doc.id };
+        }),
+
+        DeleteDocument: wrapHandler(async (call: grpc.ServerUnaryCall<any, any>) => {
+            const req = call.request;
+            if (!req.index_name) {
+                throw grpcError(grpc.status.INVALID_ARGUMENT, 'index_name is required');
+            }
+            if (!req.uri) {
+                throw grpcError(grpc.status.INVALID_ARGUMENT, 'uri is required');
+            }
+            const { docIndex } = manager.requireDocumentIndex(req.index_name);
+            await docIndex.deleteDocument(req.uri);
+            return {};
+        }),
+
+        ListDocuments: wrapHandler(async (call: grpc.ServerUnaryCall<any, any>) => {
+            const req = call.request;
+            if (!req.index_name) {
+                throw grpcError(grpc.status.INVALID_ARGUMENT, 'index_name is required');
+            }
+            const { docIndex } = manager.requireDocumentIndex(req.index_name);
+            const docs = await docIndex.listDocuments();
+            return {
+                documents: docs.map(doc => ({
+                    uri: doc.uri,
+                    document_id: doc.id,
+                })),
+            };
+        }),
+    };
+}

package/src/server/handlers/helpers.ts

@@ -0,0 +1,93 @@
+import * as grpc from '@grpc/grpc-js';
+import { MetadataTypes } from '../../types';
+
+/**
+ * Converts proto MetadataValue map to a plain JS record.
+ */
+export function fromProtoMetadata(protoMeta: Record<string, any> | undefined): Record<string, MetadataTypes> {
+    const result: Record<string, MetadataTypes> = {};
+    if (!protoMeta) return result;
+    for (const [key, val] of Object.entries(protoMeta)) {
+        if (val && typeof val === 'object') {
+            if ('string_value' in val || 'stringValue' in val) {
+                result[key] = val.string_value ?? val.stringValue;
+            } else if ('number_value' in val || 'numberValue' in val) {
+                result[key] = val.number_value ?? val.numberValue;
+            } else if ('bool_value' in val || 'boolValue' in val) {
+                result[key] = val.bool_value ?? val.boolValue;
+            }
+        }
+    }
+    return result;
+}
+
+/**
+ * Converts a plain JS metadata record to proto MetadataValue map.
+ */
+export function toProtoMetadata(meta: Record<string, MetadataTypes> | undefined): Record<string, any> {
+    const result: Record<string, any> = {};
+    if (!meta) return result;
+    for (const [key, val] of Object.entries(meta)) {
+        if (typeof val === 'string') {
+            result[key] = { string_value: val };
+        } else if (typeof val === 'number') {
+            result[key] = { number_value: val };
+        } else if (typeof val === 'boolean') {
+            result[key] = { bool_value: val };
+        }
+    }
+    return result;
+}
+
+/**
+ * Parses the filter_json field from a MetadataFilter proto message.
+ */
+export function parseFilterJson(filter: any): Record<string, any> | undefined {
+    if (!filter || !filter.filter_json || filter.filter_json === '') {
+        return undefined;
+    }
+    try {
+        return JSON.parse(filter.filter_json);
+    } catch {
+        throw grpcError(grpc.status.INVALID_ARGUMENT, 'Invalid filter_json: must be valid JSON');
+    }
+}
+
+/**
+ * Creates a gRPC ServiceError with the given status code and message.
+ */
+export function grpcError(code: grpc.status, message: string): grpc.ServiceError {
+    const err = new Error(message) as grpc.ServiceError;
+    err.code = code;
+    err.details = message;
+    err.metadata = new grpc.Metadata();
+    return err;
+}
+
+/**
+ * Wraps an async handler function with standard error mapping.
+ */
+export function wrapHandler<TReq, TRes>(
+    handler: (call: grpc.ServerUnaryCall<TReq, TRes>) => Promise<TRes>
+): grpc.handleUnaryCall<TReq, TRes> {
+    return (call, callback) => {
+        handler(call)
+            .then(result => callback(null, result))
+            .catch(err => {
+                if (err && typeof err.code === 'number') {
+                    callback(err);
+                } else {
+                    const message = err?.message || 'Internal server error';
+                    if (message.includes('not found') || message.includes('does not exist')) {
+                        callback(grpcError(grpc.status.NOT_FOUND, message));
+                    } else if (message.includes('already exists')) {
+                        callback(grpcError(grpc.status.ALREADY_EXISTS, message));
+                    } else if (message.includes('not a document index')) {
+                        callback(grpcError(grpc.status.FAILED_PRECONDITION, message));
+                    } else {
+                        callback(grpcError(grpc.status.INTERNAL, message));
+                    }
+                }
+            });
+    };
+}

package/src/server/handlers/index.ts

@@ -0,0 +1,7 @@
+export { createIndexHandlers } from './indexHandlers';
+export { createItemHandlers } from './itemHandlers';
+export { createQueryHandlers } from './queryHandlers';
+export { createDocumentHandlers } from './documentHandlers';
+export { createStatsHandlers } from './statsHandlers';
+export { createLifecycleHandlers } from './lifecycleHandlers';
+export { grpcError, wrapHandler, fromProtoMetadata, toProtoMetadata, parseFilterJson } from './helpers';

package/src/server/handlers/indexHandlers.ts

@@ -0,0 +1,44 @@
+import * as grpc from '@grpc/grpc-js';
+import { IndexManager } from '../IndexManager';
+import { wrapHandler, grpcError } from './helpers';
+
+export function createIndexHandlers(manager: IndexManager) {
+    return {
+        CreateIndex: wrapHandler(async (call: grpc.ServerUnaryCall<any, any>) => {
+            const req = call.request;
+            if (!req.index_name) {
+                throw grpcError(grpc.status.INVALID_ARGUMENT, 'index_name is required');
+            }
+            const format = req.format || 'json';
+            const isDoc = req.is_document_index || false;
+            const docConfig = req.document_config ? {
+                version: req.document_config.version || 1,
+                chunkSize: req.document_config.chunk_size || 512,
+                chunkOverlap: req.document_config.chunk_overlap || 0,
+            } : undefined;
+
+            await manager.createIndex(req.index_name, format, isDoc, docConfig);
+            return {};
+        }),
+
+        DeleteIndex: wrapHandler(async (call: grpc.ServerUnaryCall<any, any>) => {
+            const req = call.request;
+            if (!req.index_name) {
+                throw grpcError(grpc.status.INVALID_ARGUMENT, 'index_name is required');
+            }
+            await manager.deleteIndex(req.index_name);
+            return {};
+        }),
+
+        ListIndexes: wrapHandler(async (_call: grpc.ServerUnaryCall<any, any>) => {
+            const indexes = manager.listIndexes();
+            return {
+                indexes: indexes.map(idx => ({
+                    name: idx.name,
+                    format: idx.format,
+                    is_document_index: idx.isDocumentIndex,
+                })),
+            };
+        }),
+    };
+}