odac 1.4.7 → 1.4.9

package/test/Ipc/hset.test.js

@@ -0,0 +1,59 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests Ipc hash operations: hset() and hgetall().
+ * Why: Validates that hash merge semantics work correctly for Write-Behind Cache
+ * update coalescing (last-write-wins per field).
+ */
+
+let Ipc
+
+beforeEach(async () => {
+  jest.resetModules()
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  Ipc = require('../../src/Ipc')
+  global.Odac = {Config: {}}
+  await Ipc.init()
+})
+
+afterEach(async () => {
+  await Ipc.close()
+  delete global.Odac
+})
+
+describe('Ipc - hset()', () => {
+  it('should store and retrieve hash fields', async () => {
+    await Ipc.hset('hash:a', {title: 'Hello', views: 100})
+    const result = await Ipc.hgetall('hash:a')
+    expect(result).toEqual({title: 'Hello', views: 100})
+  })
+
+  it('should merge new fields into existing hash', async () => {
+    await Ipc.hset('hash:b', {title: 'First'})
+    await Ipc.hset('hash:b', {slug: 'first-post'})
+    const result = await Ipc.hgetall('hash:b')
+    expect(result).toEqual({title: 'First', slug: 'first-post'})
+  })
+
+  it('should overwrite existing fields (last-write-wins)', async () => {
+    await Ipc.hset('hash:c', {title: 'Old'})
+    await Ipc.hset('hash:c', {title: 'New'})
+    const result = await Ipc.hgetall('hash:c')
+    expect(result).toEqual({title: 'New'})
+  })
+
+  it('should return null for non-existent hash', async () => {
+    const result = await Ipc.hgetall('hash:nonexistent')
+    expect(result).toBeNull()
+  })
+
+  it('should be deletable via del()', async () => {
+    await Ipc.hset('hash:d', {title: 'Test'})
+    await Ipc.del('hash:d')
+    const result = await Ipc.hgetall('hash:d')
+    expect(result).toBeNull()
+  })
+})

package/test/Ipc/incrBy.test.js

@@ -0,0 +1,65 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests Ipc.incrBy() atomic counter operation.
+ * Why: Validates that concurrent increment operations are atomic and return
+ * accurate accumulated values, essential for Write-Behind Cache counters.
+ */
+
+let Ipc
+
+beforeEach(async () => {
+  jest.resetModules()
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  Ipc = require('../../src/Ipc')
+  global.Odac = {Config: {}}
+  await Ipc.init()
+})
+
+afterEach(async () => {
+  await Ipc.close()
+  delete global.Odac
+})
+
+describe('Ipc - incrBy()', () => {
+  it('should initialize and return delta on first call', async () => {
+    const result = await Ipc.incrBy('counter:a', 5)
+    expect(result).toBe(5)
+  })
+
+  it('should accumulate multiple increments', async () => {
+    await Ipc.incrBy('counter:b', 3)
+    await Ipc.incrBy('counter:b', 7)
+    const result = await Ipc.incrBy('counter:b', 2)
+    expect(result).toBe(12) // 3 + 7 + 2
+  })
+
+  it('should handle negative deltas (decrement)', async () => {
+    await Ipc.incrBy('counter:c', 10)
+    const result = await Ipc.incrBy('counter:c', -3)
+    expect(result).toBe(7)
+  })
+
+  it('should not interfere with different keys', async () => {
+    await Ipc.incrBy('counter:x', 5)
+    await Ipc.incrBy('counter:y', 10)
+
+    expect(await Ipc.get('counter:x')).toBe(5)
+    expect(await Ipc.get('counter:y')).toBe(10)
+  })
+
+  it('should be readable via get()', async () => {
+    await Ipc.incrBy('counter:d', 42)
+    const result = await Ipc.get('counter:d')
+    expect(result).toBe(42)
+  })
+
+  it('should work with decrBy()', async () => {
+    await Ipc.incrBy('counter:e', 10)
+    const result = await Ipc.decrBy('counter:e', 4)
+    expect(result).toBe(6)
+  })
+})

package/test/Ipc/lock.test.js

@@ -0,0 +1,62 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests Ipc distributed lock: lock() and unlock().
+ * Why: Validates that only one process can hold the flush lock at a time,
+ * preventing duplicate writes in horizontal scaling scenarios.
+ */
+
+let Ipc
+
+beforeEach(async () => {
+  jest.resetModules()
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  Ipc = require('../../src/Ipc')
+  global.Odac = {Config: {}}
+  await Ipc.init()
+})
+
+afterEach(async () => {
+  await Ipc.close()
+  delete global.Odac
+})
+
+describe('Ipc - lock()', () => {
+  it('should acquire lock and return true', async () => {
+    const result = await Ipc.lock('lock:a', 5)
+    expect(result).toBe(true)
+  })
+
+  it('should reject second acquisition (mutex)', async () => {
+    await Ipc.lock('lock:b', 5)
+    const result = await Ipc.lock('lock:b', 5)
+    expect(result).toBe(false)
+  })
+
+  it('should allow re-acquisition after unlock', async () => {
+    await Ipc.lock('lock:c', 5)
+    await Ipc.unlock('lock:c')
+    const result = await Ipc.lock('lock:c', 5)
+    expect(result).toBe(true)
+  })
+
+  it('should auto-expire after TTL', async () => {
+    await Ipc.lock('lock:d', 1) // 1 second TTL
+
+    // Wait for expiry
+    await new Promise(r => setTimeout(r, 1100))
+
+    // Lock should be available again
+    const result = await Ipc.lock('lock:d', 5)
+    expect(result).toBe(true)
+  })
+
+  it('should not interfere with different lock keys', async () => {
+    await Ipc.lock('lock:e', 5)
+    const result = await Ipc.lock('lock:f', 5)
+    expect(result).toBe(true)
+  })
+})

package/test/Ipc/rpush.test.js

@@ -0,0 +1,68 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests Ipc list operations: rpush() and lrange().
+ * Why: Validates that batch insert queue (Write-Behind Cache) correctly appends
+ * items and retrieves them in order.
+ */
+
+let Ipc
+
+beforeEach(async () => {
+  jest.resetModules()
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  Ipc = require('../../src/Ipc')
+  global.Odac = {Config: {}}
+  await Ipc.init()
+})
+
+afterEach(async () => {
+  await Ipc.close()
+  delete global.Odac
+})
+
+describe('Ipc - rpush()', () => {
+  it('should append items and return new length', async () => {
+    const len1 = await Ipc.rpush('list:a', {action: 'view'})
+    const len2 = await Ipc.rpush('list:a', {action: 'click'})
+    expect(len1).toBe(1)
+    expect(len2).toBe(2)
+  })
+
+  it('should append multiple items at once', async () => {
+    const len = await Ipc.rpush('list:b', {a: 1}, {a: 2}, {a: 3})
+    expect(len).toBe(3)
+  })
+})
+
+describe('Ipc - lrange()', () => {
+  it('should return all items with 0, -1', async () => {
+    await Ipc.rpush('list:c', 'first')
+    await Ipc.rpush('list:c', 'second')
+    await Ipc.rpush('list:c', 'third')
+
+    const result = await Ipc.lrange('list:c', 0, -1)
+    expect(result).toEqual(['first', 'second', 'third'])
+  })
+
+  it('should return a range of items', async () => {
+    await Ipc.rpush('list:d', 'a', 'b', 'c', 'd')
+    const result = await Ipc.lrange('list:d', 1, 2)
+    expect(result).toEqual(['b', 'c'])
+  })
+
+  it('should return empty array for non-existent list', async () => {
+    const result = await Ipc.lrange('list:nonexistent', 0, -1)
+    expect(result).toEqual([])
+  })
+
+  it('should clear list on del()', async () => {
+    await Ipc.rpush('list:e', 'item')
+    await Ipc.del('list:e')
+    const result = await Ipc.lrange('list:e', 0, -1)
+    expect(result).toEqual([])
+  })
+})

package/test/Ipc/sadd.test.js

@@ -0,0 +1,68 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests Ipc set operations: sadd(), smembers(), srem().
+ * Why: WriteBuffer uses index sets to track active counter/update/queue keys
+ * for efficient flush discovery without expensive SCAN operations.
+ */
+
+let Ipc
+
+beforeEach(async () => {
+  jest.resetModules()
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  Ipc = require('../../src/Ipc')
+  global.Odac = {Config: {}}
+  await Ipc.init()
+})
+
+afterEach(async () => {
+  await Ipc.close()
+  delete global.Odac
+})
+
+describe('Ipc - sadd()', () => {
+  it('should add members and return count of new additions', async () => {
+    const added = await Ipc.sadd('set:a', 'x', 'y', 'z')
+    expect(added).toBe(3)
+  })
+
+  it('should not duplicate existing members', async () => {
+    await Ipc.sadd('set:b', 'x', 'y')
+    const added = await Ipc.sadd('set:b', 'y', 'z')
+    expect(added).toBe(1) // Only 'z' is new
+  })
+})
+
+describe('Ipc - smembers()', () => {
+  it('should return all members', async () => {
+    await Ipc.sadd('set:c', 'a', 'b', 'c')
+    const members = await Ipc.smembers('set:c')
+    expect(members.sort()).toEqual(['a', 'b', 'c'])
+  })
+
+  it('should return empty array for non-existent set', async () => {
+    const result = await Ipc.smembers('set:nonexistent')
+    expect(result).toEqual([])
+  })
+})
+
+describe('Ipc - srem()', () => {
+  it('should remove specified members', async () => {
+    await Ipc.sadd('set:d', 'a', 'b', 'c')
+    const removed = await Ipc.srem('set:d', 'b')
+    expect(removed).toBe(1)
+
+    const remaining = await Ipc.smembers('set:d')
+    expect(remaining.sort()).toEqual(['a', 'c'])
+  })
+
+  it('should return 0 for non-existent members', async () => {
+    await Ipc.sadd('set:e', 'x')
+    const removed = await Ipc.srem('set:e', 'nonexistent')
+    expect(removed).toBe(0)
+  })
+})

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

package/test/WebSocket/Client/readyState.test.js

@@ -0,0 +1,154 @@
+const {WebSocketServer, WebSocketClient, READY_STATE} = require('../../../src/WebSocket.js')
+
+/**
+ * Helper: creates a mock TCP socket with the minimum interface
+ * required by WebSocketClient.
+ */
+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 readyState', () => {
+  let server
+
+  beforeEach(() => {
+    server = new WebSocketServer()
+  })
+
+  it('should expose static state constants matching READY_STATE enum', () => {
+    expect(WebSocketClient.CONNECTING).toBe(0)
+    expect(WebSocketClient.OPEN).toBe(1)
+    expect(WebSocketClient.CLOSING).toBe(2)
+    expect(WebSocketClient.CLOSED).toBe(3)
+  })
+
+  it('should export READY_STATE enum', () => {
+    expect(READY_STATE).toEqual({
+      CONNECTING: 0,
+      OPEN: 1,
+      CLOSING: 2,
+      CLOSED: 3
+    })
+  })
+
+  it('should start in CONNECTING state', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'rs-1')
+    expect(client.readyState).toBe(READY_STATE.CONNECTING)
+  })
+
+  it('should transition to OPEN on resume()', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'rs-2')
+
+    client.resume()
+
+    expect(client.readyState).toBe(READY_STATE.OPEN)
+    expect(socket.resume).toHaveBeenCalled()
+  })
+
+  it('should transition to CLOSED after close()', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'rs-3')
+    client.resume()
+
+    client.close()
+
+    expect(client.readyState).toBe(READY_STATE.CLOSED)
+    expect(socket.end).toHaveBeenCalled()
+  })
+
+  it('should be idempotent — second close() is a no-op', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'rs-4')
+    client.resume()
+
+    client.close()
+    client.close()
+
+    expect(socket.end).toHaveBeenCalledTimes(1)
+  })
+
+  it('should not send data when in CONNECTING state', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'rs-5')
+
+    client.send('hello')
+
+    expect(socket.write).not.toHaveBeenCalled()
+  })
+
+  it('should not send data when in CLOSED state', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'rs-6')
+    client.resume()
+    client.close()
+
+    client.send('hello')
+
+    // Only the close frame write should exist, no data frame
+    const writes = socket.write.mock.calls
+    const lastWrite = writes[writes.length - 1]
+    // Close frame starts with 0x88
+    expect(lastWrite[0][0]).toBe(0x88)
+  })
+
+  it('should not send ping when not OPEN', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'rs-7')
+
+    client.ping()
+
+    expect(socket.write).not.toHaveBeenCalled()
+  })
+
+  it('should not write when socket is not writable', () => {
+    const socket = createMockSocket()
+    socket.writable = false
+    const client = new WebSocketClient(socket, server, 'rs-8')
+    client.resume()
+
+    client.send('hello')
+
+    expect(socket.write).not.toHaveBeenCalled()
+  })
+
+  it('should transition to CLOSED when socket fires close event', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'rs-9')
+    server.clients.set('rs-9', client)
+    client.resume()
+
+    // Simulate socket 'close' event
+    const closeHandler = socket.on.mock.calls.find(c => c[0] === 'close')[1]
+    closeHandler()
+
+    expect(client.readyState).toBe(READY_STATE.CLOSED)
+  })
+
+  it('should emit close event only once on double cleanup', () => {
+    const socket = createMockSocket()
+    const client = new WebSocketClient(socket, server, 'rs-10')
+    server.clients.set('rs-10', client)
+    client.resume()
+
+    const closeSpy = jest.fn()
+    client.on('close', closeSpy)
+
+    client.close()
+
+    // Simulate socket 'close' event firing after close() already cleaned up
+    const closeHandler = socket.on.mock.calls.find(c => c[0] === 'close')
+    if (closeHandler) closeHandler[1]()
+
+    expect(closeSpy).toHaveBeenCalledTimes(1)
+  })
+})

package/docs/backend/10-authentication/01-user-logins-with-authjs.md

@@ -1,55 +0,0 @@
-## 🔐 User Logins with `Auth.js`
-
-The `Odac.Auth` service is your bouncer, managing who gets in and who stays out. It handles user login sessions for you.
-
-#### Letting a User In
-
-`Odac.Auth.login(userId, userData)`
-
-*   `userId`: A unique ID for the user (like their database ID).
-*   `userData`: An object with any user info you want to remember, like their username or role.
-
-When you call this, `Auth` creates a secure session for the user.
-
-> **💡 Enterprise Security:** ODAC automatically handles **Token Rotation** every 15 minutes (configurable) and includes built-in **CSRF protection** for all forms. Sessions are persistent across browser restarts by default.
-
-#### Checking the Guest List
-
-*   `Odac.Auth.isLogin()`: Is the current user logged in? Returns `true` or `false`.
-*   `Odac.Auth.getId()`: Gets the ID of the logged-in user.
-*   `Odac.Auth.get('some-key')`: Grabs a specific piece of info from the `userData` you stored.
-
-#### Showing a User Out
-
-*   `Odac.Auth.logout()`: Ends the user's session and logs them out.
-
-#### Example: A Login Flow
-```javascript
-// Controller for your login form
-module.exports = async function (Odac) {
-    const { username, password } = Odac.Request.post;
-
-    // IMPORTANT: You need to write your own code to find the user in your database!
-    const user = await yourDatabase.findUser(username, password);
-
-    if (user) {
-        // User is valid! Log them in.
-        Odac.Auth.login(user.id, { username: user.username });
-        return Odac.direct('/dashboard'); // Send them to their dashboard
-    } else {
-        // Bad credentials, send them back to the login page
-        return Odac.direct('/login?error=1');
-    }
-}
-
-// A protected dashboard page
-module.exports = function (Odac) {
-    // If they're not logged in, kick them back to the login page.
-    if (!Odac.Auth.isLogin()) {
-        return Odac.direct('/login');
-    }
-
-    const username = Odac.Auth.get('username');
-    return `Welcome back, ${username}!`;
-}
-```