odac 1.4.8 → 1.4.10

package/test/Database/WriteBuffer/insert.test.js

@@ -0,0 +1,118 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests WriteBuffer.insert() nanoid auto-generation.
+ * Why: WriteBuffer bypasses the Database.js proxy QB nanoid injection.
+ * Rows must be populated with nanoid values before being queued to IPC,
+ * otherwise flush writes to DB with a null primary key and violates NOT NULL.
+ */
+
+let knexLib, db
+
+beforeEach(async () => {
+  jest.resetModules()
+
+  knexLib = require('knex')
+  db = knexLib({client: 'sqlite3', connection: {filename: ':memory:'}, useNullAsDefault: true})
+
+  await db.schema.createTable('activity', table => {
+    table.string('id', 21).primary().notNullable()
+    table.string('user', 255).notNullable()
+    table.string('action', 50).notNullable()
+  })
+
+  await db.schema.createTable('events', table => {
+    table.string('eid', 12).primary().notNullable()
+    table.string('name', 100)
+  })
+
+  Object.defineProperty(cluster, 'isPrimary', {value: true, configurable: true})
+
+  const Ipc = require('../../../src/Ipc')
+  global.Odac = {
+    Config: {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},
+    {
+      default: {
+        activity: [{column: 'id', size: 21}],
+        events: [{column: 'eid', size: 12}]
+      }
+    }
+  )
+
+  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('WriteBuffer.insert() - NanoID auto-generation', () => {
+  it('should auto-generate nanoid for a column when not provided', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.activity.buffer.insert({user: 'alice', action: 'login'})
+    await DB.activity.buffer.flush()
+
+    const rows = await db('activity').select()
+    expect(rows).toHaveLength(1)
+    expect(rows[0].id).toBeTruthy()
+    expect(rows[0].id).toHaveLength(21)
+  })
+
+  it('should not overwrite an explicitly provided id', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.activity.buffer.insert({id: 'my-custom-id-00000', user: 'bob', action: 'logout'})
+    await DB.activity.buffer.flush()
+
+    const row = await db('activity').first()
+    expect(row.id).toBe('my-custom-id-00000')
+  })
+
+  it('should respect custom nanoid length from schema metadata', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.events.buffer.insert({name: 'page_view'})
+    await DB.events.buffer.flush()
+
+    const row = await db('events').first()
+    expect(row.eid).toBeTruthy()
+    expect(row.eid).toHaveLength(12)
+  })
+
+  it('should generate unique ids for multiple buffered inserts', async () => {
+    const DB = require('../../../src/Database')
+
+    await DB.activity.buffer.insert({user: 'alice', action: 'login'})
+    await DB.activity.buffer.insert({user: 'bob', action: 'view'})
+    await DB.activity.buffer.insert({user: 'carol', action: 'logout'})
+    await DB.activity.buffer.flush()
+
+    const rows = await db('activity').select()
+    expect(rows).toHaveLength(3)
+
+    const ids = rows.map(r => r.id)
+    expect(new Set(ids).size).toBe(3) // all unique
+    ids.forEach(id => expect(id).toHaveLength(21))
+  })
+})

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

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}!`;
-}
-```