@anteros/core 0.0.20 → 0.0.21

package/README.md

@@ -1,4 +1,4 @@
-# @dnax/core
+# @anteros/core
 
 Server core for **multi-tenant** apps: generic **MongoDB** REST API, **Joi** validation, hooks, JWT auth, custom routes, and boot scripts. Built for **Bun** with **Hono** and **Socket.io**.
 
@@ -11,7 +11,7 @@ Server core for **multi-tenant** apps: generic **MongoDB** REST API, **Joi** val
 ## Installation
 
 ```bash
-bun add @dnax/core@0.0.0-rc.13
+bun add @anteros/core@latest
 ```
 
 ## Quick start
@@ -19,10 +19,9 @@ bun add @dnax/core@0.0.0-rc.13
 Typical entrypoint in your app (working directory = project root that contains tenant folders):
 
 ```ts
-import { app, define } from "@dnax/core";
+import { app, define } from "@anteros/core";
 
 await app.boot({
-  clusterMode: false,
   server: {
     port: 5000,
     jwt: {
@@ -57,6 +56,7 @@ On boot, the server syncs tenants, loads collections (`*.model.ts`), registers r
 | `app` | `{ boot }` — starts the application |
 | `useRest` | REST client / per-tenant Mongo access (programmatic use or in handlers) |
 | `v` | **Joi** (re-export), for schemas in models |
+| `cache` | Native caching: `useMemoryCache`, `useFilesystemCache`, `useRedisCache` (Bun.Redis) |
 | `utils` | Internal utilities exposed by the package |
 
 ## Folder layout (per tenant)
@@ -116,11 +116,96 @@ Per collection, `api.access` allows or denies each action (`boolean` or async fu
 
 When `api.auth.enabled` is set, define `onLogin` / `onLogout` on the model. The JWT secret is read from `server.jwt.secret` or the **`JWT_SECRET`** environment variable.
 
+## Health & metrics
+
+The server exposes a built-in **`GET /health`** endpoint (zero dependency) reporting live process metrics:
+
+```json
+{
+  "pid": 10047,
+  "startedAt": 1720000000000,
+  "uptime": 3600,
+  "env": "production",
+  "connections": 0,
+  "pendingRequests": 3,
+  "pendingWebSockets": 7,
+  "requests": {
+    "total": 1523,
+    "active": 3,
+    "errors": 2,
+    "byMethod": { "GET": 1200, "POST": 323 },
+    "byStatus": { "200": 1500, "201": 21, "500": 2 }
+  },
+  "memory": { "rss": 13778944, "heapUsed": 112384, "heapTotal": 521216, "external": 10624 },
+  "cpu": { "percent": 12.5, "cores": 8, "user": 120000, "system": 80000 }
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `pid` / `uptime` | Process id / seconds since boot |
+| `requests.total` / `requests.errors` | Total requests served / responses ≥ 500 |
+| `requests.byMethod` / `requests.byStatus` | Counters split by HTTP method / status |
+| `memory` | V8 heap + RSS usage (bytes) |
+| `pendingRequests` | Requests currently being processed |
+| `pendingWebSockets` | Active WebSocket connections |
+| `cpu.percent` | % of a single core over the last sample window |
+
+With `reusePort`, each process exposes its **own** metrics — useful to see per-worker load.
+
+## Cluster (reusePort + multiple processes)
+
+Set `server.reusePort: true` to enable Bun's `SO_REUSEPORT`. The framework then acts as a **master**:
+
+- Spawns N workers (`server.workers`, default = CPU count)
+- Each worker serves the main port (the OS round-robins connections)
+- Workers report metrics to the master **via IPC** every 5s
+- The master **restarts any worker that crashes** (auto-respawn)
+- The master exposes an **aggregated `/health`** on `server.metricsPort` (default: `port + 1`)
+
+```typescript
+await app.boot({
+  server: {
+    port: 5000,
+    reusePort: true,     // cluster mode
+    workers: 4,          // optional, default = CPU count
+    metricsPort: 5001,   // optional, default = port + 1
+  },
+  // ...
+});
+```
+
+```bash
+curl http://localhost:5001/health   # aggregated across all workers
+```
+
+```json
+{
+  "status": "ok",
+  "master": { "pid": 1000 },
+  "workers": 4,
+  "uptime": { "min": 12, "max": 15 },
+  "requests": {
+    "total": 1523,
+    "active": 11,
+    "errors": 2,
+    "perSecond": 101,
+    "byMethod": { "GET": 1200, "POST": 323 },
+    "byStatus": { "200": 1500, "201": 21, "500": 2 }
+  },
+  "memory": { "rss": 54067200, "heapUsed": 589294 },
+  "cpu": { "percent": 25.5, "cores": 8 },
+  "pids": [1001, 1002, 1003, 1004]
+}
+```
+
+> ⚠️ Each process has its own memory — use **Redis** for shared cache / Socket.io state.
+
 ## Server configuration
 
 Common options when calling `app.boot`:
 
-- `clusterMode` — Bun `reusePort` for multiple workers
+- `server.reusePort` — Bun `SO_REUSEPORT` (share the port across multiple processes)
 - `server.port`, `server.name`
 - `server.cors` — origins, credentials, headers, and methods
 - `server.ipRestriction` — allow/deny lists (Hono)

package/database/mongodbadapter.ts

@@ -148,6 +148,9 @@ class MongoRest {
             }
 
         }
+
+        // No schema or nothing to sanitize → pass the raw data through
+        return options.data;
     }
 
     async #logActivity(data: {

package/index.ts

@@ -11,7 +11,7 @@ import * as crypto from "./utils/crypto";
 
 
 
-// Imort bentocache use as cache
+// BentoCache-based caching (memory L1 + filesystem/Redis L2)
 import { useMemoryCache, useFilesystemCache, useRedisCache } from "./utils/cache";
 const cache = {
     useMemoryCache,

package/lib/define.ts

@@ -1,14 +1,15 @@
 import type { ServerConfig } from "../types/config";
-import type { Collection } from "../types/collection";
+import type { Collection, CollectionAction } from "../types/collection";
+import type { CollectionHook } from "../types/hook";
 import type { FileCollection } from "../types/file";
 import type { Script } from "../types/scripts";
 import type { Route } from "../types/route";
 import type { Service } from "../types/service";
 import type { WebSocketHandler } from "../types/websocket";
 import type { TenantMiddlewareConfig, GlobalMiddlewareConfig } from "../types/middleware";
+import type { McpTool, McpResource } from "../types/mcp";
 import { file } from "bun";
 function Server(config: ServerConfig) {
-    config.clusterMode = config?.clusterMode ?? true;
     config.server = {
         ...config?.server,
     }
@@ -32,6 +33,58 @@ function Collection(collection: Collection): Collection {
     }
 }
 
+/**
+ * Defines a custom action on a collection — usable in `define.Collection({ actions: { ... } })`.
+ *
+ * @example
+ * ```ts
+ * const processOrder = define.Action(async ({ rest, data, error }) => {
+ *   const order = await rest.findOne("orders", data.orderId);
+ *   if (!order) throw error("Order not found", { status: 404 });
+ *   return { ok: true };
+ * });
+ *
+ * define.Collection({ slug: "orders", actions: { processOrder } })
+ * ```
+ */
+function Action(action: CollectionAction): CollectionAction & { _isAction_: true } {
+    return Object.assign(action, { _isAction_: true }) as CollectionAction & { _isAction_: true };
+}
+
+/**
+ * Defines a collection hook — usable as `beforeOperation` / `afterOperation`.
+ *
+ * @example
+ * ```ts
+ * const softDelete = define.Hook(async ({ rest, action, meta }) => {
+ *   if (action === 'deleteOne' && meta.id) {
+ *     await rest.updateOne("items", meta.id, { $set: { deletedAt: new Date().toISOString() } });
+ *   }
+ * });
+ *
+ * define.Collection({ slug: "items", hooks: { beforeOperation: softDelete } })
+ * ```
+ */
+function Hook(hook: CollectionHook): CollectionHook & { _isHook_: true } {
+    return Object.assign(hook, { _isHook_: true }) as CollectionHook & { _isHook_: true };
+}
+
+function McpTool(tool: McpTool): McpTool {
+    return {
+        ...tool,
+        enabled: tool.enabled ?? true,
+        _isMcpTool_: true,
+    }
+}
+
+function McpResource(resource: McpResource): McpResource {
+    return {
+        ...resource,
+        enabled: resource.enabled ?? true,
+        _isMcpResource_: true,
+    }
+}
+
 function FileCollection(collection: FileCollection): FileCollection {
     return {
         ...collection,
@@ -103,6 +156,8 @@ export const define = {
     Server: Server,
     App: Server,
     Collection,
+    Action,
+    Hook,
     FileCollection,
     Script,
     Route,
@@ -110,5 +165,7 @@ export const define = {
   Workflow,
   TenantMiddleware,
   Middleware,
-  WebSocket
+  WebSocket,
+  McpTool,
+  McpResource
 }

package/lib/files.ts

@@ -2,6 +2,7 @@ import { getFileCollection } from "../database/file";
 import { useRest } from "../database/rest";
 import { cfg } from "../server/config";
 import { AppError } from "./error";
+import { S3Client } from "bun";
 import type { FileCollection } from "../types/file";
 import path from "path";
 import fs from "fs/promises";
@@ -84,6 +85,14 @@ export type S3Config = {
 };
 
 export function createS3Storage(config: S3Config): FileStorage {
+  const client = new S3Client({
+    region: config.region,
+    bucket: config.bucket,
+    accessKeyId: config.accessKeyId,
+    secretAccessKey: config.secretAccessKey,
+    ...(config.endpoint ? { endpoint: config.endpoint } : {}),
+  });
+
   return {
     async save(tenant_id, collection, file, meta) {
       const { subpath } = meta;
@@ -91,42 +100,21 @@ export function createS3Storage(config: S3Config): FileStorage {
       const filename = `${meta.id}${ext}`;
       const key = subpath ? `${subpath}/${filename}` : `${tenant_id}/${collection}/${filename}`;
       const buffer = await file.arrayBuffer();
-      // S3 upload via fetch (AWS S3 REST API)
-      const url = config.endpoint
-        ? `${config.endpoint}/${config.bucket}/${key}`
-        : `https://${config.bucket}.s3.${config.region}.amazonaws.com/${key}`;
-      const response = await fetch(url, {
-        method: 'PUT',
-        headers: {
-          'Content-Type': meta.mimetype,
-          'Content-Length': String(buffer.byteLength),
-        },
-        body: buffer,
-      });
-      if (!response.ok) {
-        throw new AppError(`S3 upload failed: ${response.statusText}`, {
-          code: 'S3_UPLOAD_ERROR', status: 500,
-        });
-      }
+      // Native Bun S3 client (handles multipart, retries, signing)
+      await client.write(key, buffer, { type: meta.mimetype });
       return { path: key, size: buffer.byteLength };
     },
 
     async getStream(tenant_id, collection, fileId, filename, subpath) {
       const key = subpath ? `${subpath}/${filename}` : `${tenant_id}/${collection}/${filename}`;
-      const url = config.endpoint
-        ? `${config.endpoint}/${config.bucket}/${key}`
-        : `https://${config.bucket}.s3.${config.region}.amazonaws.com/${key}`;
-      const response = await fetch(url);
-      if (!response.ok) return null;
-      return response.body;
+      const s3file = client.file(key);
+      if (!(await s3file.exists())) return null;
+      return s3file.stream();
     },
 
     async delete(tenant_id, collection, fileId, filename, subpath) {
       const key = subpath ? `${subpath}/${filename}` : `${tenant_id}/${collection}/${filename}`;
-      const url = config.endpoint
-        ? `${config.endpoint}/${config.bucket}/${key}`
-        : `https://${config.bucket}.s3.${config.region}.amazonaws.com/${key}`;
-      await fetch(url, { method: 'DELETE' });
+      await client.delete(key).catch(() => {});
     },
   };
 }

package/lib/mcp.ts

@@ -0,0 +1,59 @@
+import { Glob } from "bun"
+import { cfg } from "../server/config"
+import path from "path"
+import fs from "fs/promises"
+import type { McpTool, McpResource } from "../types/mcp"
+
+/**
+ * Load MCP tools & resources from each tenant's `mcp/` folder:
+ *   {tenant.dir}/mcp/tools/**\/*.tool.ts        → tools
+ *   {tenant.dir}/mcp/resources/**\/*.resource.ts → resources
+ */
+async function syncMcpTools() {
+    try {
+        const tools: McpTool[] = []
+        const resources: McpResource[] = []
+        for (let tenant of cfg.tenants ?? []) {
+            const TENANT_PATH = path.join(process.cwd(), tenant.dir)
+            const MCP_PATH = path.join(TENANT_PATH, 'mcp')
+            let exist = await fs.exists(MCP_PATH)
+            if (!exist) continue;
+            const isDirectory = await (await fs.stat(MCP_PATH)).isDirectory()
+            if (!isDirectory) continue;
+
+            // tools: mcp/tools/**/*.tool.ts
+            const TOOLS_PATH = path.join(MCP_PATH, 'tools')
+            if (await fs.exists(TOOLS_PATH)) {
+                const toolsGlob = new Glob(path.join(TOOLS_PATH, '**/*.tool.ts'))
+                for await (let file of toolsGlob.scan('.')) {
+                    let module = await import(file)
+                    if (module?.default?._isMcpTool_ && module?.default?.enabled !== false) {
+                        tools.push({ ...module?.default, _tenant_: tenant.id })
+                    }
+                }
+            }
+
+            // resources: mcp/resources/**/*.resource.ts
+            const RESOURCES_PATH = path.join(MCP_PATH, 'resources')
+            if (await fs.exists(RESOURCES_PATH)) {
+                const resourcesGlob = new Glob(path.join(RESOURCES_PATH, '**/*.resource.ts'))
+                for await (let file of resourcesGlob.scan('.')) {
+                    let module = await import(file)
+                    if (module?.default?._isMcpResource_ && module?.default?.enabled !== false) {
+                        resources.push({ ...module?.default, _tenant_: tenant.id })
+                    }
+                }
+            }
+        }
+
+        cfg.mcpTools = tools
+        cfg.mcpResources = resources
+
+    } catch (err: any) {
+        console.error(err?.message)
+    }
+}
+
+export {
+    syncMcpTools
+}

package/lib/scriptWorker.ts

@@ -0,0 +1,76 @@
+import { cfg } from "../server/config";
+import { useRest } from "../database/rest";
+import { syncTenants } from "../database/tenant";
+import { syncCollections } from "../database/collection";
+import { syncFileCollections } from "../database/file";
+import { asyncContextStorage, requestCtxStorage } from "./asyncContextStorage";
+
+// ─── Heavy-script worker entrypoint ─────────────────────────────────────────
+// Spawned by runScripts() for scripts marked `heavy: true`.
+//
+//   bun run lib/scriptWorker.ts <absolute-script-path>
+//
+// The tenant config (id, dir, database.uri…) is received as JSON on **stdin**
+// (never argv, to avoid leaking credentials in `ps`). The worker rebuilds the
+// minimal app context — tenant DB connection + collection schemas — then runs
+// the script and reports progress via IPC (process.send).
+
+async function main() {
+    const scriptPath = process.argv[2];
+    if (!scriptPath) {
+        console.error('[script-worker] usage: scriptWorker <scriptPath>');
+        process.exit(1);
+    }
+
+    // Read the tenant config from stdin (written by the parent)
+    let tenant: any;
+    try {
+        const input = (await new Response(process.stdin).json()) as { tenant?: any };
+        tenant = input?.tenant;
+    } catch (err: any) {
+        console.error('[script-worker] failed to read tenant config from stdin:', err?.message);
+        process.exit(1);
+    }
+    if (!tenant?.id || !tenant?.database?.uri) {
+        console.error('[script-worker] missing tenant config (id / database.uri)');
+        process.exit(1);
+    }
+
+    try {
+        // Rebuild the app context, same as boot: connect DB, load collection schemas
+        cfg.tenants = [tenant];
+        await syncTenants();
+        await syncCollections();
+        await syncFileCollections();
+    } catch (err: any) {
+        console.error('[script-worker] failed to bootstrap context:', err?.message);
+        process.exit(1);
+    }
+
+    const module = await import(scriptPath);
+    const script = module?.default;
+    if (!script?._isScript_ || !script.enabled) {
+        console.error(`[script-worker] '${scriptPath}' is not an enabled script`);
+        process.exit(1);
+    }
+
+    const rest = new useRest({ tenant_id: tenant.id });
+    const progress = (percent: number, info?: any) =>
+        process.send?.({ type: 'progress', percent, info });
+
+    try {
+        await asyncContextStorage.run(new Map(), async () => {
+            requestCtxStorage.set('trace', { id: crypto.randomUUID() });
+            requestCtxStorage.set('internal', true);
+            await script.exec({ rest, progress, tenant });
+        });
+        process.send?.({ type: 'done' });
+        process.exit(0);
+    } catch (err: any) {
+        process.send?.({ type: 'error', message: err?.message });
+        console.error('[script-worker] script failed:', err);
+        process.exit(1);
+    }
+}
+
+main();

package/lib/scripts.ts

@@ -3,12 +3,70 @@ import { cfg } from "../server/config"
 import path from "path"
 import fs from "fs/promises"
 import type { Script } from "../types/scripts"
+import type { Tenant } from "../types/tenant"
 import { useRest } from "../database/rest"
 import { asyncContextStorage, requestCtxStorage } from "./asyncContextStorage"
 
 
+// Path of the heavy-script worker entrypoint (spawned as its own Bun process)
+const WORKER_PATH = path.join(import.meta.dir, 'scriptWorker.ts');
+
+/**
+ * Run a `heavy` script in a separate Bun process so it never blocks the HTTP
+ * server. The worker reconnects the tenant DB and rebuilds collection schemas.
+ * Progress is reported back via IPC when the script calls `progress(...)`.
+ */
+async function runHeavyScript(file: string, tenant: Tenant, timeout?: number): Promise<void> {
+    const scriptPath = path.resolve(file);
+    const proc = Bun.spawn(['bun', 'run', WORKER_PATH, scriptPath], {
+        env: { ...process.env },
+        stdin: 'pipe',
+        stdout: 'inherit',
+        stderr: 'inherit',
+        ipc: (message: any) => {
+            if (message?.type === 'progress') {
+                console.log(`[script:${path.basename(file)}] ${message.percent}%`, message.info ?? '');
+            } else if (message?.type === 'error') {
+                console.error(`[script:${path.basename(file)}]`, message?.message);
+            }
+        },
+    });
+
+    // Send the serializable tenant config (uri/options only — never client/db
+    // Mongo instances, which are not JSON-serializable)
+    const payload = JSON.stringify({
+        tenant: {
+            id: tenant.id,
+            name: tenant.name,
+            description: tenant.description,
+            dir: tenant.dir,
+            routes: tenant.routes,
+            database: {
+                uri: tenant.database?.uri,
+                options: tenant.database?.options,
+            },
+        },
+    });
+    proc.stdin.write(payload);
+    proc.stdin.end();
+
+    // Optional hard timeout — kills the worker if it exceeds it
+    const timer = timeout ? setTimeout(() => {
+        console.error(`[script:${path.basename(file)}] timed out after ${timeout}ms — killing`);
+        proc.kill();
+    }, timeout) : null;
+
+    const code = await proc.exited;
+    if (timer) clearTimeout(timer);
+    if (code !== 0) {
+        console.error(`[script:${path.basename(file)}] exited with code ${code}`);
+    }
+}
+
+
 async function runScripts() {
-    let scripts: (Script & { rest: InstanceType<typeof useRest> })[] = []
+    type ScriptEntry = { script: Script; file: string; tenant: Tenant };
+    const entries: ScriptEntry[] = [];
     for (let tenant of cfg.tenants ?? []) {
         const TENANT_PATH = path.join(process.cwd(), tenant.dir)
         const SCRIPTS_PATH = path.join(TENANT_PATH, 'scripts')
@@ -20,28 +78,35 @@ async function runScripts() {
             for await (let file of glob.scan('.')) {
                 let scriptModule = await import(file)
                 if (scriptModule?.default?._isScript_ && scriptModule?.default?.enabled) {
-                    scripts.push({
-                        ...scriptModule?.default,
-                        rest: new useRest({
-                            tenant_id: tenant.id,
-                        })
-                    })
+                    entries.push({ script: scriptModule.default, file, tenant })
                 }
             }
         }
     }
 
-    for (let script of scripts) {
-        asyncContextStorage.run(new Map(), async () => {
+    const heavyTasks: Promise<void>[] = [];
+    for (const { script, file, tenant } of entries) {
+        if (script.heavy) {
+            // Heavy scripts run in a subprocess — never block the server
+            heavyTasks.push(runHeavyScript(file, tenant, script.timeout));
+            continue;
+        }
+
+        await asyncContextStorage.run(new Map(), async () => {
             requestCtxStorage.set('trace', { id: crypto.randomUUID() })
             requestCtxStorage.set('internal', true)
-
             await script.exec({
-                rest: script.rest
+                rest: new useRest({ tenant_id: tenant.id }),
+                tenant,
             })
         })
     }
+
+    // Wait for all heavy subprocesses (they keep running after this resolves)
+    if (heavyTasks.length) {
+        await Promise.allSettled(heavyTasks);
+    }
 }
 export {
     runScripts
-}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anteros/core",
   "module": "index.ts",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "type": "module",
   "description": "Anteros Core",
   "private": false,
@@ -17,6 +17,8 @@
   },
   "dependencies": {
     "@colors/colors": "1.6.0",
+    "@hono/mcp": "^0.3.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@socket.io/bun-engine": "0.1.1",
     "bentocache": "1.6.1",
     "boxen": "^8.0.1",
@@ -27,6 +29,7 @@
     "jose": "6.2.8",
     "mongodb": "7.5.0",
     "socket.io": "4.8.3",
-    "ufo": "1.6.4"
+    "ufo": "1.6.4",
+    "zod": "^4.4.3"
   }
 }

package/probe-cache.ts

@@ -0,0 +1,16 @@
+import { Cache } from "./utils/cache";
+
+async function probe() {
+    const c = new Cache("memory");
+    const v = await c.get({ key: "k" });
+    const p = await c.pull({ key: "p" });
+    const g = await c.getOrSet({ key: "g", factory: () => 42 });
+    const s = await c.set({ key: "a", value: 1 });
+    const h = await c.has({ key: "a" });
+    const i: unknown = v;
+    const j: unknown = p;
+    const k: unknown = g;
+    console.log(typeof v, typeof p, typeof g, s, h);
+    void i; void j; void k;
+}
+void probe;

package/server/api.ts

@@ -351,7 +351,10 @@ function initializeApi(app: Hono<{ Variables: HonoVariables }>) {
 
             // ── Execute action ──
             if (col.actions?.[action]) {
-                response = await col.actions[action]({ rest, data: body?.data, error: fn.error });
+                response = await col.actions[action]({
+                    rest, data: body?.data, error: fn.error,
+                    io, jwt: func.jwt, token: accessToken,
+                });
             } else {
                 const handler = crudHandlers[action];
                 if (!handler) throw new AppError('Action `' + action + '` not found', { status: 400, code: 'ACTION_NOT_FOUND' });