@ouim/vectoriadb-server 0.1.2 → 0.1.4

package/README.md

@@ -113,13 +113,69 @@ const bobDocs = await db.query('my-collection', 'farewell', {
 
 ### Server Options
 
-| Option            | Description                            | Default    |
-| :---------------- | :------------------------------------- | :--------- |
-| `port`            | Server listening port                  | `3001`     |
-| `host`            | Server host address                    | `0.0.0.0`  |
-| `apiKey`          | Optional key for client authentication | `null`     |
-| `cors`            | Allowed origins (array)                | `[]` (All) |
-| `streamChunkSize` | Max results per chunk for streaming    | `500`      |
+| Option                    | Description                                                                            | Default    |
+| :------------------------ | :------------------------------------------------------------------------------------- | :--------- |
+| `port`                    | Server listening port                                                                  | `3001`     |
+| `host`                    | Server host address                                                                    | `0.0.0.0`  |
+| `apiKey`                  | Optional key for client authentication                                                 | `null`     |
+| `cors`                    | Allowed origins (array)                                                                | `[]` (All) |
+| `streamChunkSize`         | Max results per chunk for streaming                                                    | `500`      |
+| `autoSaveOnMutationBurst` | Enable automatic saveToStorage after a burst of mutation calls + idle                  | `true`     |
+| `autoSaveOnInactivity`    | Save to storage after `mutationInactivityMs` of no mutations (suitable for small apps) | `true`     |
+| `mutationBurstThreshold`  | Number of mutation calls within `mutationBurstWindowMs` to consider a burst            | `5`        |
+| `mutationBurstWindowMs`   | Time window (ms) used to count burst mutations                                         | `120000`   |
+| `mutationInactivityMs`    | Inactivity window (ms) after last mutation that triggers save                          | `30000`    |
+| `minSaveIntervalMs`       | Minimum time (ms) between automatic saves to avoid thrashing                           | `10000`    |
+
+Auto-save on mutation bursts
+
+A configurable mechanism that detects "mutation bursts" and automatically calls `saveToStorage()` after activity stops. This minimizes write amplification during heavy write periods while ensuring state is persisted shortly after the burst finishes.
+
+How it works:
+
+- A "burst" is detected when at least `mutationBurstThreshold` mutation operations occur within the `mutationBurstWindowMs` time window.
+- When a burst has been detected, the server starts (or resets) an inactivity timer of `mutationInactivityMs` after the last mutation.
+- If the inactivity timer expires and the recent mutation count still meets the threshold, the server calls `saveToStorage()` once.
+- `minSaveIntervalMs` prevents repeated auto-saves from occurring too frequently; overlapping saves are also avoided by an internal in-progress flag.
+- After the inactivity handler runs the mutation history is cleared until new activity occurs.
+
+Behavior timeline (concrete example):
+
+- Settings: `mutationBurstThreshold = 100`, `mutationBurstWindowMs = 120000` (2 min), `mutationInactivityMs = 30000` (30s).
+- If 120 mutations arrive between t=0 and t=90s (burst detected), and no further mutations occur after t=90s, the server waits 30s (inactivity window) and calls `saveToStorage()` at ~t=120s (provided `minSaveIntervalMs` allows it).
+
+Configuration example:
+
+```javascript
+const server = new VectoriaDBServer({
+  port: 3001,
+  autoSaveOnMutationBurst: true,
+  mutationBurstThreshold: 100, // # mutations within the window to mark a burst
+  mutationBurstWindowMs: 2 * 60 * 1000, // window length used to count mutations
+  mutationInactivityMs: 30 * 1000, // wait this long after last mutation before saving
+  minSaveIntervalMs: 10 * 1000, // never auto-save more often than this
+})
+```
+
+Log & testing notes:
+
+- When the auto-save runs the server logs: `[VectoriaDBServer] auto-saved storage (<reason>)` (e.g. `mutation-burst-inactivity` or `inactivity`).
+- To test: simulate mutation calls and assert `saveToStorage()` is invoked after `mutationInactivityMs`; verify `minSaveIntervalMs` prevents frequent saves.
+
+Inactivity-only mode (simpler)
+
+If your application is small or you prefer a simpler policy, enable `autoSaveOnInactivity: true`. With this enabled the server will call `saveToStorage()` after `mutationInactivityMs` of no mutation activity — regardless of how many mutations occurred before the idle period. The inactivity timer resets on each mutation.
+
+Example:
+
+```javascript
+const server = new VectoriaDBServer({
+  autoSaveOnInactivity: true,
+  mutationInactivityMs: 30 * 1000, // save 30s after last mutation
+})
+```
+
+### Client Options
 
 ### Client Options
 
@@ -189,15 +245,6 @@ A: The client SDK stringifies your filter function. The server then reconstructs
 
 ---
 
-## Future Roadmap
-
-- [ ] **JWT Authentication**: Add more robust auth options.
-- [ ] **Data Encryption**: Support for end-to-end encryption of metadata.
-- [ ] **Multi-Instance**: Support for multiple VectoriaDB instances managed by one server.
-- [ ] **Python Client**: A compatible SDK for Python applications.
-
----
-
 ## Credits
 
 This SDK builds on and integrates with [VectoriaDB](https://github.com/agentfront/vectoriadb). See the Vectoria product website at [https://agentfront.dev/vectoria](https://agentfront.dev/vectoria) for more information and additional resources.

package/index.js

@@ -1,23 +1,23 @@
 import VectoriaDBServer from './vectoriadb-server.js'
 import { FileStorageAdapter } from 'vectoriadb'
 
-// If run directly, start a demo server
-if (process.argv[1] && process.argv[1].endsWith('index.js')) {
-  const server = new VectoriaDBServer({
-    port: process.env.PORT ? Number(process.env.PORT) : 3001,
-    host: '0.0.0.0',
-    vectoriadbConfig: {
-      // default storage / model - user should override for production
-      storageAdapter: new FileStorageAdapter({ cacheDir: '/data/vectoriadb', namespace: 'default' }),
-    },
-    cors: ['http://localhost:3000'],
-  })
+// // If run directly, start a demo server
+// if (process.argv[1] && process.argv[1].endsWith('index.js')) {
+//   const server = new VectoriaDBServer({
+//     port: process.env.PORT ? Number(process.env.PORT) : 3001,
+//     host: '0.0.0.0',
+//     vectoriadbConfig: {
+//       // default storage / model - user should override for production
+//       storageAdapter: new FileStorageAdapter({ cacheDir: '/data/vectoriadb', namespace: 'default' }),
+//     },
+//     cors: ['http://localhost:3000'],
+//   })
 
-  server.listen().catch(err => {
-    console.error(err)
-    process.exit(1)
-  })
-}
+//   server.listen().catch(err => {
+//     console.error(err)
+//     process.exit(1)
+//   })
+// }
 
-export { VectoriaDBServer }
+export { VectoriaDBServer, FileStorageAdapter }
 export default VectoriaDBServer

package/listen-race-test.js

@@ -0,0 +1,28 @@
+import VectoriaDBServer from './vectoriadb-server.js'
+import { FileStorageAdapter } from 'vectoriadb'
+
+async function run() {
+  const server = new VectoriaDBServer({
+    port: 3002,
+    vectoriadbConfig: {
+      storageAdapter: new FileStorageAdapter({ cacheDir: './.cache/test-vectoriadb', namespace: 'test' }),
+    },
+  })
+
+  try {
+    // call listen() twice concurrently to reproduce the race if present
+    const results = await Promise.all([server.listen(), server.listen()])
+    console.log('listen() calls resolved, same instance:', results[0] === results[1])
+    console.log('server._started =', server._started)
+  } catch (err) {
+    console.error('concurrent listen failed:', err)
+    process.exitCode = 1
+  } finally {
+    await server.close()
+  }
+}
+
+run().catch(err => {
+  console.error(err)
+  process.exit(1)
+})

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@ouim/vectoriadb-server",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "main": "index.js",
   "scripts": {
     "start": "node index.js",
-    "demo": "node demo.js",
-    "publish": "npm publish --access public"
+    "demo": "node demo.js"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",

package/vectoriadb-server.js

@@ -14,68 +14,111 @@ export default class VectoriaDBServer {
     this.vectoriadbConfig = opts.vectoriadbConfig || {}
     this.streamChunkSize = opts.streamChunkSize || 500
 
+    // --- auto-save / burst-detection (configurable) ---
+    this.autoSaveOnMutationBurst = opts.autoSaveOnMutationBurst !== undefined ? !!opts.autoSaveOnMutationBurst : true
+    // when true the server will save after any inactivity period (see `mutationInactivityMs`) — useful for small apps
+    this.autoSaveOnInactivity = opts.autoSaveOnInactivity !== undefined ? !!opts.autoSaveOnInactivity : false
+    this.mutationBurstThreshold = Number(opts.mutationBurstThreshold) || 5
+    this.mutationBurstWindowMs = Number(opts.mutationBurstWindowMs) || 2 * 60 * 1000 // 2 minutes
+    this.mutationInactivityMs = Number(opts.mutationInactivityMs) || 30 * 1000 // 30s inactivity to trigger save
+    this.minSaveIntervalMs = Number(opts.minSaveIntervalMs) || 10 * 1000 // minimum time between auto-saves
+
+    // internal mutation-tracking state
+    this._mutationMethods = new Set(['add', 'addMany', 'update', 'remove', 'clear', 'insert', 'upsert', 'replace', 'put', 'delete'])
+    this._mutationTimestamps = []
+    this._inactivityTimer = null
+    this._lastBurstAt = 0
+    this._savingInProgress = false
+    this._lastSaveAt = 0
+
     this._http = null
     this._io = null
     this._vectoria = null
     this._sockets = new Set()
     this._started = false
+    this._startPromise = null
   }
 
   async listen() {
-    if (this._started) return
-    // Initialize VectoriaDB (loads models / storage as configured)
-    this._vectoria = new VectoriaDB(this.vectoriadbConfig)
-    if (typeof this._vectoria.initialize === 'function') {
-      await this._vectoria.initialize()
-    }
+    // fast-path: already started
+    if (this._started) return this
 
-    this._http = http.createServer((req, res) => {
-      res.writeHead(200, { 'Content-Type': 'text/plain' })
-      res.end('VectoriaDB Server')
-    })
+    // if a start is already in progress, return the same promise
+    if (this._startPromise) return this._startPromise
 
-    this._io = new IOServer(this._http, {
-      cors: { origin: this.cors.length ? this.cors : '*', methods: ['GET', 'POST'] },
-      maxHttpBufferSize: 1e7,
-    })
+    this._startPromise = (async () => {
+      try {
+        // Initialize VectoriaDB (loads models / storage as configured)
+        this._vectoria = new VectoriaDB(this.vectoriadbConfig)
+        if (typeof this._vectoria.initialize === 'function') {
+          await this._vectoria.initialize()
+        }
 
-    const nsp = this._io.of('/vectoriadb')
+        this._http = http.createServer((req, res) => {
+          res.writeHead(200, { 'Content-Type': 'text/plain' })
+          res.end('VectoriaDB Server')
+        })
 
-    nsp.use((socket, next) => {
-      // simple API key auth if configured
-      if (this.apiKey) {
-        const provided = socket.handshake.auth?.apiKey || socket.handshake.query?.apiKey
-        if (!provided || provided !== this.apiKey) {
-          return next(new Error('Unauthorized'))
-        }
-      }
-      next()
-    })
+        this._io = new IOServer(this._http, {
+          cors: { origin: this.cors.length ? this.cors : '*', methods: ['GET', 'POST'] },
+          maxHttpBufferSize: 1e7,
+        })
 
-    nsp.on('connection', socket => {
-      this._sockets.add(socket)
-      socket.on('disconnect', () => this._sockets.delete(socket))
+        const nsp = this._io.of('/vectoriadb')
 
-      socket.on('request', async payload => {
-        // payload: { id, method, params, collection, timestamp }
-        try {
-          await this._handleRequest(socket, payload)
-        } catch (err) {
-          socket.emit('response', { id: payload?.id ?? null, result: null, error: { message: err.message }, took: 0 })
-        }
-      })
+        nsp.use((socket, next) => {
+          // simple API key auth if configured
+          if (this.apiKey) {
+            const provided = socket.handshake.auth?.apiKey || socket.handshake.query?.apiKey
+            if (!provided || provided !== this.apiKey) {
+              return next(new Error('Unauthorized'))
+            }
+          }
+          next()
+        })
 
-      // allow ping from client
-      socket.on('health', cb => cb && cb({ ok: true, ts: Date.now() }))
-    })
+        nsp.on('connection', socket => {
+          this._sockets.add(socket)
+          socket.on('disconnect', () => this._sockets.delete(socket))
 
-    await new Promise((res, rej) => {
-      this._http.listen(this.port, this.host, err => (err ? rej(err) : res()))
-    })
+          socket.on('request', async payload => {
+            // payload: { id, method, params, collection, timestamp }
+            try {
+              await this._handleRequest(socket, payload)
+            } catch (err) {
+              socket.emit('response', { id: payload?.id ?? null, result: null, error: { message: err.message }, took: 0 })
+            }
+          })
+
+          // allow ping from client
+          socket.on('health', cb => cb && cb({ ok: true, ts: Date.now() }))
+        })
+
+        await new Promise((res, rej) => {
+          this._http.listen(this.port, this.host, err => (err ? rej(err) : res()))
+        })
+
+        this._started = true
+        console.log(`VectoriaDB Server listening on ${this.host}:${this.port}`)
+        return this
+      } catch (err) {
+        // cleanup partial resources on failure
+        try {
+          if (this._io) await this._io.close()
+        } catch (e) {}
+        try {
+          if (this._http) this._http.close(() => {})
+        } catch (e) {}
+        throw err
+      }
+    })()
 
-    this._started = true
-    console.log(`VectoriaDB Server listening on ${this.host}:${this.port}`)
-    return this
+    try {
+      return await this._startPromise
+    } finally {
+      // ensure the in-progress marker is cleared after attempt completes
+      this._startPromise = null
+    }
   }
 
   async _handleRequest(socket, payload) {
@@ -122,6 +165,15 @@ export default class VectoriaDBServer {
         new Promise((_, reject) => setTimeout(() => reject(new Error('ServerTimeout')), 30000)),
       ])
 
+      // record mutation activity (used to auto-flush after a burst + inactivity)
+      if (this.autoSaveOnMutationBurst && this._isMutationMethod(method)) {
+        try {
+          this._recordMutation()
+        } catch (e) {
+          /* swallow tracking errors */
+        }
+      }
+
       const took = Date.now() - start
 
       // streaming support for very large arrays
@@ -143,8 +195,86 @@ export default class VectoriaDBServer {
     }
   }
 
+  // --- Auto-save on mutation bursts (configurable) ---
+  _isMutationMethod(method) {
+    return this._mutationMethods.has(method)
+  }
+
+  _recordMutation() {
+    const now = Date.now()
+    this._mutationTimestamps.push(now)
+    // purge old timestamps outside the burst window
+    const cutoff = now - this.mutationBurstWindowMs
+    while (this._mutationTimestamps.length && this._mutationTimestamps[0] < cutoff) {
+      this._mutationTimestamps.shift()
+    }
+    if (this._mutationTimestamps.length >= this.mutationBurstThreshold) {
+      this._lastBurstAt = now
+    }
+    this._scheduleInactivityTimer()
+  }
+
+  _scheduleInactivityTimer() {
+    if (this._inactivityTimer) {
+      clearTimeout(this._inactivityTimer)
+    }
+    this._inactivityTimer = setTimeout(() => {
+      // fire-and-forget async
+      this._onInactivityTimeout().catch(err => console.warn('Inactivity flush error:', err.message))
+    }, this.mutationInactivityMs)
+    if (this._inactivityTimer.unref) this._inactivityTimer.unref()
+  }
+
+  async _onInactivityTimeout() {
+    this._inactivityTimer = null
+    const now = Date.now()
+
+    // Simple "inactivity-only" mode: save after any inactivity period if enabled.
+    if (this.autoSaveOnInactivity) {
+      if (this._mutationTimestamps.length > 0) {
+        await this._saveToStorage('inactivity')
+      }
+      // reset history and return early
+      this._mutationTimestamps = []
+      this._lastBurstAt = 0
+      return
+    }
+
+    // count mutations within the burst window (existing burst-detection behavior)
+    const cutoff = now - this.mutationBurstWindowMs
+    const recentCount = this._mutationTimestamps.filter(ts => ts >= cutoff).length
+    if (recentCount >= this.mutationBurstThreshold) {
+      await this._saveToStorage('mutation-burst-inactivity')
+    }
+    // reset history (we only track bursts between inactivity windows)
+    this._mutationTimestamps = []
+    this._lastBurstAt = 0
+  }
+
+  async _saveToStorage(reason = 'manual') {
+    if (!this._vectoria || typeof this._vectoria.saveToStorage !== 'function') return
+    const now = Date.now()
+    if (this._savingInProgress) return
+    if (now - this._lastSaveAt < this.minSaveIntervalMs) return
+    this._savingInProgress = true
+    try {
+      await this._vectoria.saveToStorage()
+      this._lastSaveAt = Date.now()
+      console.log(`[VectoriaDBServer] auto-saved storage (${reason})`)
+    } catch (err) {
+      console.warn('[VectoriaDBServer] auto-save failed:', err.message)
+    } finally {
+      this._savingInProgress = false
+    }
+  }
+
   async close() {
     if (!this._started) return
+    // stop any pending auto-save timer
+    if (this._inactivityTimer) {
+      clearTimeout(this._inactivityTimer)
+      this._inactivityTimer = null
+    }
     // disconnect sockets
     for (const s of Array.from(this._sockets)) {
       try {