odac 1.4.8 → 1.4.9

package/test/Database/ReadCache/invalidate.test.js

@@ -0,0 +1,103 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests ReadCache.invalidate() — table-level cache purge.
+ * Why: Validates that all cached queries for a table are removed on invalidation,
+ * and that unrelated tables remain unaffected.
+ */
+
+let knexLib, db
+
+beforeEach(async () => {
+  jest.resetModules()
+
+  knexLib = require('knex')
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+
+  await db.schema.createTable('posts', table => {
+    table.integer('id').primary()
+    table.string('title', 255)
+  })
+
+  await db.schema.createTable('users', table => {
+    table.integer('id').primary()
+    table.string('name', 255)
+  })
+
+  await db('posts').insert([
+    {id: 1, title: 'Post A'},
+    {id: 2, title: 'Post B'}
+  ])
+
+  await db('users').insert([{id: 1, name: 'Alice'}])
+
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  const Ipc = require('../../../src/Ipc')
+  global.Odac = {
+    Config: {cache: {ttl: 60, maxKeys: 10000}},
+    Ipc
+  }
+  await Ipc.init()
+})
+
+afterEach(async () => {
+  await Odac.Ipc.close()
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('ReadCache.invalidate()', () => {
+  let readCache
+
+  beforeEach(() => {
+    readCache = require('../../../src/Database/ReadCache')
+    readCache.init()
+  })
+
+  it('should purge all cached queries for the specified table', async () => {
+    // Cache two different queries on posts
+    const qb1 = db('posts').where({id: 1}).first()
+    const qb2 = db('posts').where({id: 2}).first()
+    await readCache.get('default', 'posts', qb1, () => qb1.then(r => r), 60)
+    await readCache.get('default', 'posts', qb2, () => qb2.then(r => r), 60)
+
+    const cachedKeys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(cachedKeys).toHaveLength(2)
+
+    // Invalidate
+    await readCache.invalidate('default', 'posts')
+
+    const keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+
+    // Verify cache entries are actually deleted
+    for (const key of cachedKeys) {
+      const val = await Odac.Ipc.get(key)
+      expect(val).toBeNull()
+    }
+  })
+
+  it('should not affect cache of other tables', async () => {
+    const qbPosts = db('posts').where({id: 1}).first()
+    const qbUsers = db('users').where({id: 1}).first()
+    await readCache.get('default', 'posts', qbPosts, () => qbPosts.then(r => r), 60)
+    await readCache.get('default', 'users', qbUsers, () => qbUsers.then(r => r), 60)
+
+    // Invalidate only posts
+    await readCache.invalidate('default', 'posts')
+
+    const postKeys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    const userKeys = await Odac.Ipc.smembers('rc:idx:default:users')
+
+    expect(postKeys).toHaveLength(0)
+    expect(userKeys).toHaveLength(1)
+  })
+
+  it('should be a no-op when no cache exists for the table', async () => {
+    // Should not throw
+    await expect(readCache.invalidate('default', 'nonexistent')).resolves.toBeUndefined()
+  })
+})

package/test/Database/ReadCache/proxy.test.js

@@ -0,0 +1,184 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests the cache chain API exposed via Database.js proxy.
+ * Why: Validates that Odac.DB.posts.cache(60).where(...).select(...) pattern
+ * correctly delegates to ReadCache, and that write operations auto-invalidate.
+ */
+
+let knexLib, db
+
+beforeEach(async () => {
+  jest.resetModules()
+
+  knexLib = require('knex')
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+
+  await db.schema.createTable('posts', table => {
+    table.integer('id').primary()
+    table.string('title', 255)
+    table.integer('views').defaultTo(0)
+    table.boolean('active').defaultTo(true)
+  })
+
+  await db('posts').insert([
+    {id: 1, title: 'First Post', views: 100, active: true},
+    {id: 2, title: 'Second Post', views: 200, active: true},
+    {id: 3, title: 'Draft', views: 0, active: false}
+  ])
+
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  const Ipc = require('../../../src/Ipc')
+  global.Odac = {
+    Config: {
+      cache: {ttl: 60, maxKeys: 10000},
+      buffer: {flushInterval: 999999, checkpointInterval: 999999}
+    },
+    Storage: {
+      isReady: () => false,
+      put: jest.fn(),
+      remove: jest.fn(),
+      getRange: () => []
+    },
+    Ipc
+  }
+  await Ipc.init()
+
+  const writeBuffer = require('../../../src/Database/WriteBuffer')
+  await writeBuffer.init({default: db})
+
+  const readCache = require('../../../src/Database/ReadCache')
+  readCache.init()
+
+  const DB = require('../../../src/Database')
+  DB.connections = {default: db}
+})
+
+afterEach(async () => {
+  const writeBuffer = require('../../../src/Database/WriteBuffer')
+  await writeBuffer.close()
+  await Odac.Ipc.close()
+  await db.destroy()
+  delete global.Odac
+})
+
+describe('Database.js Proxy - cache(ttl).where().select()', () => {
+  it('should cache SELECT results with specified TTL', async () => {
+    const DB = require('../../../src/Database')
+
+    const result1 = await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    expect(result1).toHaveLength(2)
+
+    // Modify DB directly
+    await db('posts').where({id: 1}).update({title: 'Modified'})
+
+    // Should return cached (stale) data
+    const result2 = await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    expect(result2[0].title).toBe('First Post')
+  })
+
+  it('should cache with default TTL when called without argument', async () => {
+    const DB = require('../../../src/Database')
+
+    const result = await DB.posts.cache().where({id: 1}).first()
+    expect(result.title).toBe('First Post')
+
+    // Verify cached
+    const keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+  })
+})
+
+describe('Database.js Proxy - cache.clear()', () => {
+  it('should manually clear table cache via Odac.DB.posts.cache.clear()', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    await DB.posts.cache.clear()
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+  })
+})
+
+describe('Database.js Proxy - automatic invalidation on write', () => {
+  it('should invalidate cache after update()', async () => {
+    const DB = require('../../../src/Database')
+
+    // Cache a query
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    // Update via proxy — should auto-invalidate
+    await DB.posts.where({id: 1}).update({title: 'Updated'})
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+
+    // Next cache() call should fetch fresh data
+    const result = await DB.posts.cache(60).where({id: 1}).first()
+    expect(result.title).toBe('Updated')
+  })
+
+  it('should invalidate cache after insert()', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    await DB.posts.insert({id: 4, title: 'New Post', views: 0, active: true})
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+  })
+
+  it('should invalidate cache after delete()', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    await DB.posts.where({id: 3}).delete()
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+  })
+
+  it('should invalidate cache after del() (alias)', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    await DB.posts.where({id: 3}).del()
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+  })
+})
+
+describe('Database.js Proxy - global cache.clear()', () => {
+  it('should clear cache via Odac.DB.cache.clear(connection, table)', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.posts.cache(60).where({active: true}).select('id', 'title')
+    let keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(1)
+
+    await DB.cache.clear('default', 'posts')
+
+    keys = await Odac.Ipc.smembers('rc:idx:default:posts')
+    expect(keys).toHaveLength(0)
+  })
+})

package/test/Database/insert.test.js

@@ -0,0 +1,98 @@
+'use strict'
+
+const knexLib = require('knex')
+
+/**
+ * Tests the wrapWithInvalidation thenable returned by write operations (insert/update/delete/truncate).
+ * Why: Ensures the thenable is fully Promise-compatible — supporting both await and .catch() chaining.
+ * This prevents TypeError when consumers call .insert(...).catch() or .update(...).catch().
+ */
+
+let db
+
+beforeEach(async () => {
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+  await db.schema.createTable('tokens', table => {
+    table.string('id', 21).primary()
+    table.string('user', 100)
+    table.string('token_x', 64)
+  })
+})
+
+afterEach(async () => {
+  await db.destroy()
+  jest.resetModules()
+})
+
+describe('Database.js - wrapWithInvalidation thenable', () => {
+  it('insert().catch() should be a function', () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    const result = DB.tokens.insert({id: 'test1', user: 'u1', token_x: 'tx1'})
+    expect(typeof result.catch).toBe('function')
+  })
+
+  it('insert().catch() should resolve on success', async () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    const result = await DB.tokens.insert({id: 'test2', user: 'u2', token_x: 'tx2'}).catch(() => false)
+    expect(result).not.toBe(false)
+
+    const rows = await db('tokens').where('id', 'test2')
+    expect(rows).toHaveLength(1)
+    expect(rows[0].user).toBe('u2')
+  })
+
+  it('insert().catch() should catch errors gracefully', async () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    // Insert first row
+    await DB.tokens.insert({id: 'dup1', user: 'u1', token_x: 'tx1'})
+
+    // Duplicate primary key — should trigger catch
+    const result = await DB.tokens.insert({id: 'dup1', user: 'u2', token_x: 'tx2'}).catch(() => 'caught')
+    expect(result).toBe('caught')
+  })
+
+  it('update().catch() should be a function', () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    const result = DB.tokens.where('id', 'x').update({user: 'new'})
+    expect(typeof result.catch).toBe('function')
+  })
+
+  it('delete().catch() should be a function', () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    const result = DB.tokens.where('id', 'x').delete()
+    expect(typeof result.catch).toBe('function')
+  })
+
+  it('insert() should work with await (no .catch)', async () => {
+    const DB = require('../../src/Database')
+    DB.connections = {default: db}
+    db._odacConnectionKey = 'default'
+    DB._nanoidColumns = {}
+
+    await DB.tokens.insert({id: 'await1', user: 'u_await', token_x: 'tx_await'})
+
+    const rows = await db('tokens').where('id', 'await1')
+    expect(rows).toHaveLength(1)
+    expect(rows[0].user).toBe('u_await')
+  })
+})

package/test/WebSocket/Client/fragmentation.test.js

@@ -0,0 +1,130 @@
+const {WebSocketServer, WebSocketClient} = require('../../../src/WebSocket.js')
+
+/**
+ * Builds a masked WebSocket frame from raw payload bytes.
+ * Uses a zero mask key for deterministic test output.
+ */
+function buildFrame(opcode, payload, fin = true) {
+  const buf = Buffer.isBuffer(payload) ? payload : Buffer.from(payload)
+  const maskKey = Buffer.alloc(4) // zero mask — XOR is identity
+  const masked = Buffer.from(buf)
+
+  const finBit = fin ? 0x80 : 0x00
+  const header = Buffer.alloc(2 + 4 + buf.length)
+  header[0] = finBit | opcode
+  header[1] = 0x80 | buf.length // masked bit + length
+  maskKey.copy(header, 2)
+  masked.copy(header, 6)
+
+  return header
+}
+
+function createMockSocket() {
+  return {
+    pause: jest.fn(),
+    resume: jest.fn(),
+    on: jest.fn(),
+    write: jest.fn(),
+    end: jest.fn(),
+    removeAllListeners: jest.fn(),
+    writable: true
+  }
+}
+
+describe('WebSocketClient Fragmentation', () => {
+  let server
+
+  beforeEach(() => {
+    server = new WebSocketServer()
+  })
+
+  it('should reassemble fragmented text messages', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'frag-1')
+    client.resume()
+
+    const messages = []
+    client.on('message', msg => messages.push(msg))
+
+    const dataHandler = socket.on.mock.calls.find(c => c[0] === 'data')[1]
+
+    // Fragment 1: TEXT opcode, fin=false
+    dataHandler(buildFrame(0x1, 'hel', false))
+    // Fragment 2: CONTINUATION opcode, fin=false
+    dataHandler(buildFrame(0x0, 'lo ', false))
+    // Fragment 3: CONTINUATION opcode, fin=true
+    dataHandler(buildFrame(0x0, 'world', true))
+
+    expect(messages).toEqual(['hello world'])
+  })
+
+  it('should reassemble fragmented binary messages', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'frag-2')
+    client.resume()
+
+    const messages = []
+    client.on('message', msg => messages.push(msg))
+
+    const dataHandler = socket.on.mock.calls.find(c => c[0] === 'data')[1]
+
+    const part1 = Buffer.from([0x01, 0x02])
+    const part2 = Buffer.from([0x03, 0x04])
+
+    // Fragment 1: BINARY opcode, fin=false
+    dataHandler(buildFrame(0x2, part1, false))
+    // Fragment 2: CONTINUATION opcode, fin=true
+    dataHandler(buildFrame(0x0, part2, true))
+
+    expect(messages.length).toBe(1)
+    expect(Buffer.isBuffer(messages[0])).toBe(true)
+    expect(messages[0]).toEqual(Buffer.from([0x01, 0x02, 0x03, 0x04]))
+  })
+
+  it('should close with 1002 on unexpected continuation frame', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'frag-3')
+    client.resume()
+
+    const dataHandler = socket.on.mock.calls.find(c => c[0] === 'data')[1]
+
+    // Send CONTINUATION without a preceding TEXT/BINARY
+    dataHandler(buildFrame(0x0, 'orphan', true))
+
+    expect(socket.end).toHaveBeenCalled()
+  })
+
+  it('should handle single unfragmented message normally', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'frag-4')
+    client.resume()
+
+    const messages = []
+    client.on('message', msg => messages.push(msg))
+
+    const dataHandler = socket.on.mock.calls.find(c => c[0] === 'data')[1]
+
+    // Single complete frame: TEXT, fin=true
+    dataHandler(buildFrame(0x1, 'complete', true))
+
+    expect(messages).toEqual(['complete'])
+  })
+
+  it('should discard fragment buffer on close', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'frag-5')
+    client.resume()
+
+    const messages = []
+    client.on('message', msg => messages.push(msg))
+
+    const dataHandler = socket.on.mock.calls.find(c => c[0] === 'data')[1]
+
+    // Start a fragmented message but close before completion
+    dataHandler(buildFrame(0x1, 'partial', false))
+    client.close()
+
+    // No message should have been emitted
+    expect(messages).toEqual([])
+  })
+})

package/test/WebSocket/Client/limits.test.js

@@ -11,12 +11,15 @@ describe('WebSocketClient Limits', () => {
     it('should close connection if payload exceeds limit', () => {
       const socket = {
         pause: jest.fn(),
+        resume: jest.fn(),
         on: jest.fn(),
         write: jest.fn(),
         end: jest.fn(),
-        removeAllListeners: jest.fn()
+        removeAllListeners: jest.fn(),
+        writable: true
       }
-      new WebSocketClient(socket, server, 'test-id', {maxPayload: 10})
+      const client = new WebSocketClient(socket, server, 'test-id', {maxPayload: 10})
+      client.resume()
 
       const buffer = Buffer.alloc(100)
       buffer[0] = 0x81
@@ -32,12 +35,15 @@ describe('WebSocketClient Limits', () => {
     it('should close connection if rate limit exceeded', () => {
       const socket = {
         pause: jest.fn(),
+        resume: jest.fn(),
         on: jest.fn(),
         write: jest.fn(),
         end: jest.fn(),
-        removeAllListeners: jest.fn()
+        removeAllListeners: jest.fn(),
+        writable: true
       }
-      new WebSocketClient(socket, server, 'test-id', {rateLimit: {max: 2, window: 1000}})
+      const client = new WebSocketClient(socket, server, 'test-id', {rateLimit: {max: 2, window: 1000}})
+      client.resume()
 
       const buffer = Buffer.alloc(7)
       buffer[0] = 0x81