@lastshotlabs/bunshot 0.0.25 → 0.0.28

package/dist/src/framework/persistence/wsMessages.js

@@ -0,0 +1,296 @@
+// ---------------------------------------------------------------------------
+// Memory
+// ---------------------------------------------------------------------------
+export function createMemoryWsMessageRepository() {
+    // key: "endpoint\0room"
+    const store = new Map();
+    function scopeKey(endpoint, room) {
+        return `${endpoint}\0${room}`;
+    }
+    return {
+        async persist(message, config) {
+            const key = scopeKey(message.endpoint, message.room);
+            if (!store.has(key))
+                store.set(key, []);
+            const msgs = store.get(key);
+            msgs.push(message);
+            if (msgs.length > config.maxCount) {
+                msgs.splice(0, msgs.length - config.maxCount);
+            }
+            return message;
+        },
+        async getHistory(endpoint, room, opts) {
+            const key = scopeKey(endpoint, room);
+            const msgs = store.get(key) ?? [];
+            const limit = opts?.limit ?? 50;
+            let filtered = msgs.slice();
+            if (opts?.before) {
+                const idx = filtered.findIndex(m => m.id === opts.before);
+                if (idx > 0)
+                    filtered = filtered.slice(0, idx);
+            }
+            else if (opts?.after) {
+                const idx = filtered.findIndex(m => m.id === opts.after);
+                if (idx >= 0)
+                    filtered = filtered.slice(idx + 1);
+            }
+            return filtered.slice(-limit);
+        },
+        async clear() {
+            store.clear();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Redis
+// ---------------------------------------------------------------------------
+export function createRedisWsMessageRepository(redis) {
+    const knownKeys = new Set();
+    function rkey(endpoint, room) {
+        return `wsmsg:${endpoint}\0${room}`;
+    }
+    return {
+        async persist(message, config) {
+            const key = rkey(message.endpoint, message.room);
+            knownKeys.add(key);
+            const serialized = JSON.stringify(message);
+            await redis.lpush(key, serialized);
+            await redis.ltrim(key, 0, config.maxCount - 1);
+            await redis.expire(key, config.ttlSeconds);
+            return message;
+        },
+        async getHistory(endpoint, room, opts) {
+            const key = rkey(endpoint, room);
+            const limit = opts?.limit ?? 50;
+            const raw = await redis.lrange(key, 0, -1);
+            let msgs = raw.map(s => JSON.parse(s)).reverse(); // oldest-first
+            if (opts?.before) {
+                const idx = msgs.findIndex(m => m.id === opts.before);
+                if (idx > 0)
+                    msgs = msgs.slice(0, idx);
+            }
+            else if (opts?.after) {
+                const idx = msgs.findIndex(m => m.id === opts.after);
+                if (idx >= 0)
+                    msgs = msgs.slice(idx + 1);
+            }
+            return msgs.slice(-limit);
+        },
+        async clear() {
+            if (knownKeys.size === 0)
+                return;
+            await redis.del(...knownKeys);
+            knownKeys.clear();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// MongoDB
+// ---------------------------------------------------------------------------
+const DEFAULT_TTL_SECONDS = 86_400;
+export function createMongoWsMessageRepository(conn, mongoosePkg) {
+    let model = null;
+    function getModel() {
+        if (model)
+            return model;
+        const mongoose = mongoosePkg;
+        const schema = new mongoose.Schema({
+            _id: { type: String, default: () => crypto.randomUUID() },
+            endpoint: { type: String, required: true },
+            room: { type: String, required: true },
+            senderId: { type: String, default: null },
+            payload: { type: mongoose.Schema.Types.Mixed },
+            createdAt: { type: Number, required: true },
+        }, { collection: 'ws_messages' });
+        schema.index({ endpoint: 1, room: 1, createdAt: -1, _id: -1 });
+        schema.index({ createdAt: 1 }, { expireAfterSeconds: DEFAULT_TTL_SECONDS });
+        model = conn.model('WsMessage', schema);
+        return model;
+    }
+    return {
+        async persist(message, config) {
+            const Model = getModel();
+            await Model.create({
+                _id: message.id,
+                endpoint: message.endpoint,
+                room: message.room,
+                senderId: message.senderId,
+                payload: message.payload,
+                createdAt: message.createdAt,
+            });
+            const count = await Model.countDocuments({ endpoint: message.endpoint, room: message.room });
+            if (count > config.maxCount) {
+                const oldest = await Model.find({ endpoint: message.endpoint, room: message.room })
+                    .sort({ createdAt: 1, _id: 1 })
+                    .limit(count - config.maxCount)
+                    .select('_id');
+                if (oldest.length > 0) {
+                    await Model.deleteMany({ _id: { $in: oldest.map((d) => d._id) } });
+                }
+            }
+            return message;
+        },
+        async getHistory(endpoint, room, opts) {
+            const Model = getModel();
+            const limit = opts?.limit ?? 50;
+            const filter = { endpoint, room };
+            if (opts?.before) {
+                const cursor = await Model.findById(opts.before).lean();
+                if (cursor) {
+                    filter.$or = [
+                        { createdAt: { $lt: cursor.createdAt } },
+                        { createdAt: cursor.createdAt, _id: { $lt: opts.before } },
+                    ];
+                }
+            }
+            else if (opts?.after) {
+                const cursor = await Model.findById(opts.after).lean();
+                if (cursor) {
+                    filter.$or = [
+                        { createdAt: { $gt: cursor.createdAt } },
+                        { createdAt: cursor.createdAt, _id: { $gt: opts.after } },
+                    ];
+                }
+            }
+            const docs = await Model.find(filter).sort({ createdAt: -1, _id: -1 }).limit(limit).lean();
+            return docs.reverse().map((d) => ({
+                id: d._id,
+                endpoint: d.endpoint,
+                room: d.room,
+                senderId: d.senderId,
+                payload: d.payload,
+                createdAt: d.createdAt,
+            }));
+        },
+        async clear() {
+            // Mongo clear — drop all documents. Used for test isolation.
+            try {
+                await getModel().deleteMany({});
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// SQLite
+// ---------------------------------------------------------------------------
+export function createSqliteWsMessageRepository(db) {
+    let initialized = false;
+    const trimCounters = new Map();
+    function scopeKey(endpoint, room) {
+        return `${endpoint}\0${room}`;
+    }
+    function ensureTable() {
+        if (initialized)
+            return;
+        db.run(`
+      CREATE TABLE IF NOT EXISTS ws_messages (
+        id         TEXT PRIMARY KEY,
+        endpoint   TEXT NOT NULL,
+        room       TEXT NOT NULL,
+        sender_id  TEXT,
+        payload    TEXT,
+        created_at INTEGER NOT NULL
+      )
+    `);
+        db.run('CREATE INDEX IF NOT EXISTS idx_ws_messages_scope ON ws_messages (endpoint, room, created_at DESC)');
+        initialized = true;
+    }
+    return {
+        async persist(message, config) {
+            ensureTable();
+            db.run('INSERT INTO ws_messages (id, endpoint, room, sender_id, payload, created_at) VALUES (?, ?, ?, ?, ?, ?)', [
+                message.id,
+                message.endpoint,
+                message.room,
+                message.senderId,
+                JSON.stringify(message.payload),
+                message.createdAt,
+            ]);
+            // Modulo-based trimming
+            const key = scopeKey(message.endpoint, message.room);
+            const counter = (trimCounters.get(key) ?? 0) + 1;
+            const trimInterval = Math.max(10, Math.floor(config.maxCount * 0.1));
+            trimCounters.set(key, counter);
+            if (counter >= trimInterval) {
+                trimCounters.set(key, 0);
+                db.run(`DELETE FROM ws_messages WHERE endpoint = ? AND room = ? AND id NOT IN (
+            SELECT id FROM ws_messages WHERE endpoint = ? AND room = ? ORDER BY created_at DESC, id DESC LIMIT ?
+          )`, [message.endpoint, message.room, message.endpoint, message.room, config.maxCount]);
+                const ttlMs = config.ttlSeconds * 1000;
+                db.run('DELETE FROM ws_messages WHERE endpoint = ? AND room = ? AND created_at < ?', [
+                    message.endpoint,
+                    message.room,
+                    Date.now() - ttlMs,
+                ]);
+            }
+            return message;
+        },
+        async getHistory(endpoint, room, opts) {
+            ensureTable();
+            const limit = opts?.limit ?? 50;
+            let sql;
+            let params;
+            if (opts?.before) {
+                sql = `
+          SELECT * FROM ws_messages
+          WHERE endpoint = ? AND room = ? AND (created_at, id) < (
+            (SELECT created_at FROM ws_messages WHERE id = ?), ?
+          )
+          ORDER BY created_at DESC, id DESC LIMIT ?
+        `;
+                params = [endpoint, room, opts.before, opts.before, limit];
+            }
+            else if (opts?.after) {
+                sql = `
+          SELECT * FROM ws_messages
+          WHERE endpoint = ? AND room = ? AND (created_at, id) > (
+            (SELECT created_at FROM ws_messages WHERE id = ?), ?
+          )
+          ORDER BY created_at ASC, id ASC LIMIT ?
+        `;
+                params = [endpoint, room, opts.after, opts.after, limit];
+            }
+            else {
+                sql =
+                    'SELECT * FROM ws_messages WHERE endpoint = ? AND room = ? ORDER BY created_at DESC, id DESC LIMIT ?';
+                params = [endpoint, room, limit];
+            }
+            const rows = db.query(sql).all(...params);
+            if (!opts?.after)
+                rows.reverse();
+            return rows.map((r) => ({
+                id: r.id,
+                endpoint: r.endpoint,
+                room: r.room,
+                senderId: r.sender_id,
+                payload: JSON.parse(r.payload),
+                createdAt: r.created_at,
+            }));
+        },
+        async clear() {
+            try {
+                ensureTable();
+                db.run('DELETE FROM ws_messages');
+                trimCounters.clear();
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+}
+export const wsMessageFactories = {
+    memory: () => createMemoryWsMessageRepository(),
+    sqlite: infra => createSqliteWsMessageRepository(infra.getSqliteDb()),
+    redis: infra => createRedisWsMessageRepository(infra.getRedis()),
+    mongo: infra => {
+        const { conn, mg } = infra.getMongo();
+        return createMongoWsMessageRepository(conn, mg);
+    },
+    // TODO: implement a native postgres WS message store.
+    // For now postgres deployments fall back to in-memory (no cross-process fan-out).
+    postgres: () => createMemoryWsMessageRepository(),
+};

package/dist/src/framework/preloadSchemas.d.ts

@@ -0,0 +1,24 @@
+export interface ModelSchemasConfig {
+    /**
+     * One or more absolute directory paths or glob patterns containing shared Zod schemas.
+     * All matching .ts files are imported before routes so schemas are registered first.
+     * Optional when registration is "explicit" — in that case your registerSchema /
+     * registerSchemas calls run at the time each schema file is imported by a route.
+     * Examples:
+     *   import.meta.dir + "/schemas"
+     *   [import.meta.dir + "/schemas", import.meta.dir + "/models"]
+     *   import.meta.dir + "/models/**\/*.schema.ts"
+     */
+    paths?: string | string[];
+    /**
+     * How schemas found in the files are registered in `components/schemas`.
+     * - "auto" (default): exported Zod schemas are registered automatically. The export
+     *   name is used as the schema name, with a trailing "Schema" suffix stripped
+     *   (e.g. `LedgerItemSchema` → `"LedgerItem"`). Schemas already registered via
+     *   `registerSchema` or `registerSchemas` inside the file are never overwritten.
+     * - "explicit": files are imported but registration is entirely up to the user —
+     *   call `registerSchema` or `registerSchemas` inside each file.
+     */
+    registration?: 'auto' | 'explicit';
+}
+export declare function preloadModelSchemas(modelSchemas: string | string[] | ModelSchemasConfig | undefined): Promise<void>;

package/dist/src/framework/preloadSchemas.js

@@ -0,0 +1,42 @@
+/**
+ * Schema pre-loading — extracted from createApp().
+ *
+ * Imports shared Zod schema files before route discovery so registerSchema /
+ * registerSchemas calls run first, guaranteeing $ref instead of inline shapes.
+ */
+import { maybeAutoRegister } from './lib/createRoute';
+export async function preloadModelSchemas(modelSchemas) {
+    if (!modelSchemas)
+        return;
+    const { paths, registration = 'auto' } = typeof modelSchemas === 'string' || Array.isArray(modelSchemas)
+        ? { paths: modelSchemas, registration: 'auto' }
+        : modelSchemas;
+    const pathArray = paths ? (Array.isArray(paths) ? paths : [paths]) : [];
+    for (const entry of pathArray) {
+        // Normalize to forward slashes so splitting works on both Windows and Unix.
+        const normalized = entry.replaceAll('\\', '/');
+        // Split glob patterns: everything before the first wildcard segment is the cwd.
+        let cwd;
+        let pattern;
+        if (!normalized.includes('*')) {
+            cwd = normalized;
+            pattern = '**/*.ts';
+        }
+        else {
+            const parts = normalized.split('/');
+            const starIdx = parts.findIndex(p => p.includes('*'));
+            cwd = parts.slice(0, starIdx).join('/');
+            pattern = parts.slice(starIdx).join('/');
+        }
+        const schemaGlob = new Bun.Glob(pattern);
+        for await (const file of schemaGlob.scan({ cwd })) {
+            const mod = await import(`${cwd}/${file}`);
+            if (registration === 'auto') {
+                for (const [exportName, value] of Object.entries(mod)) {
+                    maybeAutoRegister(exportName, value);
+                }
+            }
+            // "explicit": file imported; any registerSchema/registerSchemas calls inside already ran
+        }
+    }
+}

package/dist/src/framework/registerBoundaryAdapters.d.ts

@@ -0,0 +1,23 @@
+import type { Connection } from 'mongoose';
+import { type CacheAdapter, type CoreRegistrar, type FingerprintBuilder, type RateLimitAdapter } from '../../packages/bunshot-core/src/index.js';
+import type { StoreType } from '../../packages/bunshot-core/src/index.js';
+export interface RegisterBoundaryAdaptersOptions {
+    /** Whether Redis is connected and available. */
+    redisEnabled: boolean;
+    /** Mongo connection mode — false means no Mongo. */
+    mongoMode: 'single' | 'separate' | false;
+    /** Redis client handle, or null when Redis is disabled. */
+    redis: import('ioredis').default | null;
+    /** App Mongo connection, or null when Mongo is disabled. */
+    appConnection: Connection | null;
+    /** SQLite database handle, or null when SQLite is not configured. */
+    sqliteDb: import('bun:sqlite').Database | null;
+}
+export interface BoundaryAdaptersSnapshot {
+    readonly rateLimitAdapter: RateLimitAdapter;
+    readonly fingerprintBuilder: FingerprintBuilder;
+    readonly cacheAdapters: ReadonlyMap<StoreType, CacheAdapter>;
+}
+export declare function resolveBoundaryAdapters(options: RegisterBoundaryAdaptersOptions): Promise<BoundaryAdaptersSnapshot>;
+export declare function applyBoundaryAdapters(registrar: CoreRegistrar, boundaryAdapters: BoundaryAdaptersSnapshot): void;
+export declare function registerBoundaryAdapters(registrar: CoreRegistrar, options: RegisterBoundaryAdaptersOptions): Promise<void>;

package/dist/src/framework/registerBoundaryAdapters.js

@@ -0,0 +1,46 @@
+/**
+ * Auth boundary adapter assembly.
+ *
+ * Resolves the default rate limiter, fingerprint builder, and cache adapters
+ * for a single app instance. Plugins may still override these defaults
+ * through the registrar during setupMiddleware.
+ */
+import { boundaryCacheFactories } from './boundaryAdapters';
+import { createDefaultFingerprintBuilder, createMemoryRateLimitAdapter, } from '../../packages/bunshot-core/src/index.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+async function resolveOptionalCacheAdapters(options) {
+    const redisClient = options.redisEnabled && options.redis ? options.redis : null;
+    const context = {
+        redis: redisClient,
+        mongo: options.mongoMode !== false ? options.appConnection : null,
+        sqliteDb: options.sqliteDb,
+    };
+    const stores = ['memory'];
+    if (context.redis)
+        stores.push('redis');
+    if (context.sqliteDb)
+        stores.push('sqlite');
+    if (context.mongo)
+        stores.push('mongo');
+    const resolved = await Promise.all(stores.map(async (store) => [store, await boundaryCacheFactories[store](context)]));
+    return new Map(resolved);
+}
+export async function resolveBoundaryAdapters(options) {
+    return {
+        rateLimitAdapter: createMemoryRateLimitAdapter(),
+        fingerprintBuilder: createDefaultFingerprintBuilder(),
+        cacheAdapters: await resolveOptionalCacheAdapters(options),
+    };
+}
+export function applyBoundaryAdapters(registrar, boundaryAdapters) {
+    registrar.setRateLimitAdapter(boundaryAdapters.rateLimitAdapter);
+    registrar.setFingerprintBuilder(boundaryAdapters.fingerprintBuilder);
+    for (const [store, adapter] of boundaryAdapters.cacheAdapters) {
+        registrar.addCacheAdapter(store, adapter);
+    }
+}
+export async function registerBoundaryAdapters(registrar, options) {
+    applyBoundaryAdapters(registrar, await resolveBoundaryAdapters(options));
+}

package/dist/src/framework/routes/admin.d.ts

@@ -0,0 +1,9 @@
+import type { AppEnv } from "../../lib/context";
+export interface AdminApiConfig {
+    enabled: boolean;
+    /** Default: "admin" */
+    adminRole?: string;
+    /** Default: "/admin" */
+    mountPath?: string;
+}
+export declare function createAdminRouter(config: AdminApiConfig): import("@hono/zod-openapi").OpenAPIHono<AppEnv, {}, "/">;