postbase 0.1.0

package/backend/lib/postbase/tests/rtdb.ws.test.js

@@ -0,0 +1,113 @@
+import WebSocket from 'ws';
+import request from 'supertest';
+import { startTestServer } from './testServer.js';
+
+let srv;
+let wsClients = [];
+
+// Start the server before all tests
+beforeAll(async () => {
+    srv = await startTestServer(); // should return { http server, wss, wsUrl }
+});
+
+// Close all WS clients after each test
+afterEach(() => {
+    wsClients.forEach(ws => {
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.close();
+        }
+    });
+    wsClients.length = 0;
+});
+
+// Stop the server after all tests
+afterAll(() => {
+    if (srv.wss) srv.wss.close();
+    if (srv.server) srv.server.close();
+});
+
+// Helper to connect WebSocket and wait for 'open'
+function connectWS(url) {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        wsClients.push(ws);
+        ws.once('open', () => resolve(ws));
+        ws.once('error', reject);
+    });
+}
+
+function waitForMessage(ws) {
+    return new Promise(res => {
+        ws.once('message', m => res(JSON.parse(m)));
+    });
+}
+
+test('exact path listener fires', async () => {
+    const ws = await connectWS(srv.wsUrl);
+
+    ws.send(JSON.stringify({ type: 'sub', path: 'users/u2' }));
+
+    const msgPromise = waitForMessage(ws);
+
+    await request(srv.url)
+        .put('/rtdb/users/u2')
+        .send({ online: true });
+
+    const msg = await msgPromise;
+    expect(msg.path).toBe('users/u2');
+    expect(msg.value.online).toBe(true);
+});
+
+test('prefix listener fires for subtree', async () => {
+    const ws = await connectWS(srv.wsUrl);
+
+    ws.send(JSON.stringify({
+        type: 'sub',
+        path: 'users/u3',
+        prefix: true,
+    }));
+
+    const msgPromise = waitForMessage(ws);
+
+    await request(srv.url)
+        .put('/rtdb/users/u3/profile')
+        .send({ name: 'Bob' });
+
+    const msg = await msgPromise;
+    expect(msg.path).toBe('users/u3/profile');
+});
+
+test('field listener fires only on change', async () => {
+    const ws = await connectWS(srv.wsUrl);
+
+    ws.send(JSON.stringify({
+        type: 'sub',
+        path: 'users/u4',
+        field: 'status',
+    }));
+
+    let msgPromise = waitForMessage(ws);
+
+    await request(srv.url)
+        .put('/rtdb/users/u4')
+        .send({ status: 'offline' });
+
+    let msg = await msgPromise;
+
+    expect(msg.value).toBe('offline');
+
+    msgPromise = waitForMessage(ws);
+
+    // same value → should NOT fire
+    await request(srv.url)
+        .patch('/rtdb/users/u4')
+        .send({ status: 'offline' });
+
+    // change → should fire
+    await request(srv.url)
+        .patch('/rtdb/users/u4')
+        .send({ status: 'online' });
+
+    msg = await msgPromise;
+    expect(msg.value).toBe('online');
+});

package/backend/lib/postbase/tests/rules.js

@@ -0,0 +1,26 @@
+// backend/postbase_rtdb_rules.js
+export default {
+    paths: {
+        "/users/$uid": {
+            read: () => true,
+            write: () => true,
+            delete: () => true,
+        },
+
+        "/users/$uid/posts": {
+            read: () => true,
+            write: () => true,
+        },
+
+        "/users/$uid/profile": {
+            read: () => true,
+            write: () => true,
+        }
+    },
+
+    default: {
+        read: false,
+        write: false,
+        delete: false,
+    }
+};

package/backend/lib/postbase/tests/testServer.js

@@ -0,0 +1,46 @@
+import express from 'express';
+import http from 'http';
+import { WebSocketServer } from 'ws';
+import bodyParser from 'body-parser';
+
+import { pool, resetDb } from './db.js';
+import { authMiddleware } from '../middlewares/auth.js';
+import { createRtdbRouter } from '../rtdb/router.js';
+import { createRtdbWs } from '../rtdb/ws.js';
+import rules from './rules.js';
+
+export async function startTestServer() {
+    await resetDb();
+
+    const app = express();
+    app.use(bodyParser.json());
+
+    const server = http.createServer(app);
+    const wss = new WebSocketServer({ server });
+
+    const authenticate = authMiddleware(pool);
+    const rtdbWs = createRtdbWs(wss);
+
+    app.use(
+        '/rtdb',
+        authenticate,
+        createRtdbRouter({
+            pool,
+            notify: rtdbWs.notify,
+            rulesModule: rules,
+        })
+    );
+
+    await new Promise(res => server.listen(0, res));
+
+    const port = server.address().port;
+
+    return {
+        app,
+        server,
+        wss,
+        url: `http://localhost:${port}`,
+        wsUrl: `ws://localhost:${port}`,
+        close: () => server.close(),
+    };
+}

package/backend/lib/postbase/websocket.js

@@ -0,0 +1,131 @@
+import { WebSocketServer } from 'ws';
+
+import { createPool } from './db.js';
+import { makePostbaseAdminClient } from './adminClient.js';
+
+// FIXME: should not need to create a pool and db just to use db.buildWhere and db.buildOrder
+const pool = createPool({
+    connectionString: process.env.DATABASE_URL
+});
+
+const db = makePostbaseAdminClient({ pool });
+
+export function setupWebsocket({ server }) {
+    const wss = new WebSocketServer({
+        noServer: true, // https://stackoverflow.com/a/65034250/355507
+    });
+
+    // Upgrade HTTP → WS when path matches /api/db/<fullPath>/stream
+    server.on('upgrade', (req, socket, head) => {
+        console.log('wss upgrade url:', req.url);
+
+        // Match everything after /api/db/ up to optional /stream
+        const match = req.url.match(/^\/api\/db\/(.+?)\/stream$/);
+        if (!match) {
+            console.log('No match, destroying socket');
+            return socket.destroy();
+        }
+
+        const fullPath = decodeURIComponent(match[1]); // e.g., "users/u1/posts"
+        console.log('Matched collection path:', fullPath);
+
+        // Extract last segment as collection name, rest as parent path
+        const segments = fullPath.split('/');
+        const collectionName = segments[segments.length - 1];       // "posts"
+        const parentPath = segments.slice(0, -1).join('/');         // "users/u1"
+
+        // Pass fullPath or collectionName + parentPath to your connection handler
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            wss.emit('connection', ws, { collectionName, parentPath, fullPath });
+        });
+    });
+
+    wss.on('connection', async (ws, { collectionName, parentPath, fullPath }) => {
+        console.log(`WebSocket connected for table: ${collectionName}`);
+
+        console.log('Connecting pool...');
+        const client = await pool.connect();
+        console.log('Connected to pool');
+        // Each connection gets its own PG client to LISTEN
+        console.log(`LISTEN changes_${collectionName}`);
+        await client.query(`LISTEN changes_${collectionName}`);
+
+        // Receive the initial query definition from the client
+        console.log('Attaching ws.once(\'message\')');
+        ws.once('message', async (msg) => {
+            try {
+                const query = JSON.parse(msg.toString());
+                console.log('query', query);
+                // If subscribing to a subcollection, the client must send parent info:
+                // { parent: { collectionName, id, path } }
+                if (query.parent && typeof query.parent === 'object') {
+                    query.filters = query.filters || [];
+                    // Convert DocumentReference object to a path string
+                    const parentPath =
+                        query.parent.path ||
+                        `${query.parent.collectionName}/${query.parent.id}`;
+
+                    // FIX: Provide fake collectionName & id so buildWhere recognizes it
+                    query.filters.push({
+                        field: 'parent',
+                        op: '==',
+                        value: {
+                            path: parentPath,
+                            collectionName: query.parent.collectionName ?? null,
+                            id: query.parent.id ?? null,
+                        },
+                    });
+                }
+
+                ws.query = query;
+
+                const { filters = [], order = [], limit = 100, offset = 0 } = query;
+
+                // Send initial data
+                const { whereSql, params } = db.buildWhere(filters);
+                const orderSql = db.buildOrder(order);
+                const sql = `
+                SELECT id, data, created_at, updated_at
+                FROM "${collectionName}"
+                ${whereSql} ${orderSql}
+                LIMIT ${limit} OFFSET ${offset}`;
+                console.log('sql, params', sql, params);
+                const res = await client.query(sql, params);
+                console.log('res.rows', res.rows);
+                console.log('Sending result back to client');
+                ws.send(JSON.stringify({ type: 'init', data: res.rows.map(r => ({ id: r.id, ...r.data })) }));
+            } catch (err) {
+                console.error('Error processing web socket message', err);
+                console.log('Sending response back to client');
+                ws.send(JSON.stringify({ type: 'error', error: err.message || err }));
+            }
+        });
+
+        // Handle Postgres notifications
+        console.log('Attaching client.on(\'notification\')');
+        client.on('notification', async (msg) => {
+            console.log('postgres notification received');
+            console.log('web socket read state is:', ws.readyState);
+            if (ws.readyState !== WebSocket.OPEN) return;
+            const payload = JSON.parse(msg.payload);
+            console.log('payload from postgres', payload);
+            // Only send relevant changes for this subcollection parent
+            if (ws.query?.filters?.some(f => f.field === 'parent' && f.value?.path)) {
+                const parentFilter = ws.query.filters.find(f => f.field === 'parent');
+                if (!payload.data?.parent?.path) return;
+                if (payload.data.parent.path !== parentFilter.value.path) return;
+            }
+            console.log('Sending change event to the client with payload');
+            ws.send(JSON.stringify({ type: 'change', data: payload }));
+        });
+
+        console.log('Attaching ws.on(\'close\')');
+        ws.on('close', () => {
+            console.log(`UNLISTEN changes_${collectionName}`);
+            client.query(`UNLISTEN changes_${collectionName}`).catch(console.error);
+            client.release();
+        });
+    });
+
+    return wss;
+}

package/backend/local.js

@@ -0,0 +1,6 @@
+import './env.js'; // for loading .env file
+
+import { app } from "./app.js";
+
+const PORT = process.env.POSTBASE_BACKEND_HTTP_PORT || 8081;
+app.listen(PORT, () => console.log(`Postbase backend listening on http://0.0.0.0:${PORT}`));

package/backend/main.js

@@ -0,0 +1,20 @@
+import './env.js';
+import fs from 'node:fs';
+import https from 'node:https';
+
+import { app } from './app.js';
+import { setupWebsocket } from './lib/postbase/websocket.js';
+
+const httpsOptions = {
+    key: fs.readFileSync(process.env.LETSENCRYPT_KEY),
+    cert: fs.readFileSync(process.env.LETSENCRYPT_CERT)
+};
+
+const HTTPS_PORT = process.env.POSTBASE_BACKEND_HTTPS_PORT || 4431;
+
+const server = https.createServer(httpsOptions, app);
+
+server.listen(HTTPS_PORT,
+    () => console.log(`Postbase backend listening on https://0.0.0.0:${HTTPS_PORT}`));
+
+const wss = setupWebsocket({ server });

package/backend/middlewares/auth_middleware.js

@@ -0,0 +1,10 @@
+// server/middleware/auth.js
+import { createPool } from '../lib/postbase/db.js';
+import { authMiddleware } from '../lib/postbase/middlewares/auth.js';
+
+// Initialize DB pool using env variables
+const pool = createPool({
+    connectionString: process.env.DATABASE_URL
+});
+
+export const authenticate = authMiddleware(pool);

package/backend/migrations/1762137399366-init.sql

@@ -0,0 +1,98 @@
+--
+-- PostgreSQL Better-Auth initial migration
+--
+
+-- Enable extensions if needed
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+
+-- ===== user table =====
+CREATE TABLE IF NOT EXISTS public."user" (
+    id text PRIMARY KEY,
+    name text NOT NULL,
+    email text NOT NULL,
+    "emailVerified" boolean NOT NULL,
+    image text,
+    "createdAt" timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    "updatedAt" timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL
+);
+
+-- Unique constraint
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'user_email_key'
+    ) THEN
+        ALTER TABLE public."user" ADD CONSTRAINT user_email_key UNIQUE (email);
+    END IF;
+END$$;
+
+-- ===== account table =====
+CREATE TABLE IF NOT EXISTS public.account (
+    id text PRIMARY KEY,
+    "accountId" text NOT NULL,
+    "providerId" text NOT NULL,
+    "userId" text NOT NULL,
+    "accessToken" text,
+    "refreshToken" text,
+    "idToken" text,
+    "accessTokenExpiresAt" timestamptz,
+    "refreshTokenExpiresAt" timestamptz,
+    scope text,
+    password text,
+    "createdAt" timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    "updatedAt" timestamptz NOT NULL
+);
+
+-- Foreign key
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'account_userId_fkey'
+    ) THEN
+        ALTER TABLE public.account
+        ADD CONSTRAINT account_userId_fkey FOREIGN KEY ("userId") REFERENCES public."user"(id) ON DELETE CASCADE;
+    END IF;
+END$$;
+
+-- ===== session table =====
+CREATE TABLE IF NOT EXISTS public.session (
+    id text PRIMARY KEY,
+    "expiresAt" timestamptz NOT NULL,
+    token text NOT NULL,
+    "createdAt" timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    "updatedAt" timestamptz NOT NULL,
+    "ipAddress" text,
+    "userAgent" text,
+    "userId" text NOT NULL
+);
+
+-- Unique token
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'session_token_key'
+    ) THEN
+        ALTER TABLE public.session ADD CONSTRAINT session_token_key UNIQUE (token);
+    END IF;
+END$$;
+
+-- Foreign key
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'session_userId_fkey'
+    ) THEN
+        ALTER TABLE public.session
+        ADD CONSTRAINT session_userId_fkey FOREIGN KEY ("userId") REFERENCES public."user"(id) ON DELETE CASCADE;
+    END IF;
+END$$;
+
+-- ===== verification table =====
+CREATE TABLE IF NOT EXISTS public.verification (
+    id text PRIMARY KEY,
+    identifier text NOT NULL,
+    value text NOT NULL,
+    "expiresAt" timestamptz NOT NULL,
+    "createdAt" timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    "updatedAt" timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL
+);

package/backend/migrations/1762137399367_init_jsonb_schema.js

@@ -0,0 +1,68 @@
+/**
+ * @file 1762137399367_init_jsonb_schema.js
+ * Adds JSONB Firestore-like tables alongside Better-Auth.
+ */
+
+export const shorthands = undefined;
+
+export const up = async (pgm) => {
+    // enable UUID extension for gen_random_uuid()
+    await pgm.sql(`CREATE EXTENSION IF NOT EXISTS "pgcrypto";`);
+
+    // Trigger function to update updated_at
+    await pgm.sql(`
+    CREATE OR REPLACE FUNCTION set_updated_at()
+    RETURNS TRIGGER AS $$
+    BEGIN
+      NEW.updated_at = now();
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+  `);
+
+    const createJsonTable = async (name) => {
+        pgm.createTable(name, {
+            id: {
+                type: 'text',
+                primaryKey: true,
+                default: pgm.func('gen_random_uuid()'),
+            },
+            data: {
+                type: 'jsonb',
+                notNull: true,
+                default: '{}',
+            },
+            created_at: {
+                type: 'timestamptz',
+                notNull: true,
+                default: pgm.func('now()'),
+            },
+            updated_at: {
+                type: 'timestamptz',
+                notNull: true,
+                default: pgm.func('now()'),
+            },
+        });
+
+        await pgm.sql(`
+      CREATE TRIGGER ${name}_updated_at
+      BEFORE UPDATE ON "${name}"
+      FOR EACH ROW
+      EXECUTE FUNCTION set_updated_at();
+    `);
+    };
+
+    // Create the Firestore-style JSONB collections
+    await createJsonTable('users');
+    await createJsonTable('reviews');
+
+    // Optional: indexes on JSONB ids
+    pgm.createIndex('users', 'id');
+    pgm.createIndex('reviews', 'id');
+};
+
+export const down = async (pgm) => {
+    pgm.dropTable('users');
+    pgm.dropTable('reviews');
+    pgm.sql(`DROP FUNCTION IF EXISTS set_updated_at() CASCADE;`);
+};

package/backend/migrations/1762149999999_enable_realtime_changes.js

@@ -0,0 +1,48 @@
+/**
+ * @file 1762149999999_enable_realtime_changes.js
+ * Adds realtime triggers (pg_notify) for Firestore-style JSONB tables.
+ */
+
+export const shorthands = undefined;
+
+export const up = async (pgm) => {
+    // --- Shared trigger function for realtime updates ---
+    await pgm.sql(`
+    CREATE OR REPLACE FUNCTION notify_table_change() RETURNS trigger AS $$
+    DECLARE
+      payload JSON;
+    BEGIN
+      IF (TG_OP = 'DELETE') THEN
+        payload = json_build_object('op', TG_OP, 'id', OLD.id);
+      ELSE
+        payload = json_build_object('op', TG_OP, 'id', NEW.id, 'data', NEW.data);
+      END IF;
+      PERFORM pg_notify('changes_' || TG_TABLE_NAME, payload::text);
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+  `);
+
+    // --- Helper function to create trigger for a table ---
+    const createRealtimeTrigger = async (tableName) => {
+        await pgm.sql(`
+      CREATE TRIGGER ${tableName}_change
+      AFTER INSERT OR UPDATE OR DELETE ON "${tableName}"
+      FOR EACH ROW
+      EXECUTE FUNCTION notify_table_change();
+    `);
+    };
+
+    // --- Create triggers for each table ---
+    await createRealtimeTrigger('users');
+    await createRealtimeTrigger('reviews');
+};
+
+export const down = async (pgm) => {
+    // Drop all triggers explicitly
+    await pgm.sql(`DROP TRIGGER IF EXISTS users_change ON "users" CASCADE;`);
+    await pgm.sql(`DROP TRIGGER IF EXISTS reviews_change ON "reviews" CASCADE;`);
+
+    // Drop shared trigger function
+    await pgm.sql(`DROP FUNCTION IF EXISTS notify_table_change() CASCADE;`);
+};

package/backend/migrations/1765224247654_rtdb-nodes.js

@@ -0,0 +1,93 @@
+/**
+ * @type {import('node-pg-migrate').ColumnDefinitions | undefined}
+ */
+export const shorthands = undefined;
+
+/**
+ * @param pgm {import('node-pg-migrate').MigrationBuilder}
+ * @param run {() => void | undefined}
+ * @returns {Promise<void> | void}
+ */
+export const up = (pgm) => {
+    // ---- Extensions ----
+    pgm.createExtension('ltree', { ifNotExists: true });
+
+    // ---- Table ----
+    pgm.createTable('rtdb_nodes', {
+        path: {
+            type: 'text',
+            primaryKey: true,
+            notNull: true,
+        },
+
+        parent_path: {
+            type: 'text',
+            notNull: false,
+        },
+
+        key: {
+            type: 'text',
+            notNull: true,
+        },
+
+        value: {
+            type: 'jsonb',
+            notNull: true,
+        },
+
+        version: {
+            type: 'bigint',
+            notNull: true,
+            default: 1,
+        },
+
+        updated_at: {
+            type: 'timestamptz',
+            notNull: true,
+            default: pgm.func('now()'),
+        },
+
+        // Generated ltree column for fast subtree queries
+        path_ltree: {
+            type: 'ltree',
+            generated: {
+                as: "replace(path, '/', '.')::ltree",
+                stored: true,
+            },
+        },
+    });
+
+    // ---- Indexes ----
+
+    // Fast exact + prefix lookups (LIKE 'a/b/%')
+    pgm.createIndex('rtdb_nodes', 'parent_path', {
+        name: 'rtdb_nodes_parent_idx',
+    });
+
+    pgm.createIndex('rtdb_nodes', 'value', {
+        name: 'rtdb_nodes_value_gin_idx',
+        method: 'gin',
+    });
+
+    pgm.createIndex('rtdb_nodes', 'path_ltree', {
+        name: 'rtdb_nodes_ltree_idx',
+        method: 'gist',
+    });
+
+    // ✅ PREFIX INDEX (RAW SQL – avoids TS error)
+    pgm.sql(`
+        CREATE INDEX rtdb_nodes_path_prefix_idx
+        ON rtdb_nodes (path text_pattern_ops)
+    `);
+};
+
+/**
+ * @param pgm {import('node-pg-migrate').MigrationBuilder}
+ * @param run {() => void | undefined}
+ * @returns {Promise<void> | void}
+ */
+export const down = (pgm) => {
+    pgm.sql(`DROP INDEX IF EXISTS rtdb_nodes_path_prefix_idx`);
+    pgm.dropTable('rtdb_nodes', { ifExists: true });
+    pgm.dropExtension('ltree', { ifExists: true });
+};