@anteros/core 0.0.19 → 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/decorator.ts

@@ -10,7 +10,7 @@ export function CheckIfCollectionExists(): any {
             return descriptor;
         }
         const originalMethod = descriptor.value;
-        descriptor.value = async function (...args: any[]) {
+        descriptor.value = async function (this: any, ...args: any[]) {
             let collection = args[0];
             let col = getCollection(collection, this.tenant_id)
             if (!col) {

package/database/mongodbadapter.ts

@@ -42,18 +42,22 @@ class MongoRest {
         if (options.session) {
             this.session = options.session;
         }
-        let tenant = getTenant(options?.tenant_id ?? '-')
-        if (options.tenant_id && tenant) {
+        // Resolve tenant: explicit tenant_id, else from request context
+        let tenantId = options.tenant_id;
+        if (!tenantId) {
+            tenantId = requestCtxStorage.get<string>('tenant_id');
+        }
+        let tenant = getTenant(tenantId ?? '-')
+        if (tenant) {
             this.#tenant = tenant;
             this.tenant_id = tenant.id;
             this.db = tenant.database.db as Db;
             this.client = tenant.database.client as MongoClient;
         }
-
     }
 
 
-    private _validate(options: { collection: string, action?: ActionsApiList, data?: any, update?: UpdateFilter<any> }) {
+    private _validate(options: { collection: string, action?: ActionsApiList, data?: any, update?: UpdateFilter<any> }): any {
         let col = getCollection(options.collection, this.#tenant.id)
         let schema = col?._schema_
         let partialSchema = col?._schemaPartial_
@@ -77,6 +81,7 @@ class MongoRest {
 
             if (options?.data) {
                 if (options.action == 'insertMany') {
+                    const sanitized: any[] = [];
                     for (let i = 0; i < options.data.length; i++) {
                         validationResult = schema.validate(options.data[i], { allowUnknown: false })
                         if (validationResult?.error) {
@@ -85,9 +90,9 @@ class MongoRest {
                                 status: 400
                             })
                         }
-                        // Apply Joi defaults (e.g., .default() values) back to data
-                        options.data[i] = validationResult.value
+                        sanitized.push(validationResult.value)
                     }
+                    return sanitized;
                 }
 
                 if (options.action == 'insertOne') {
@@ -98,8 +103,8 @@ class MongoRest {
                             status: 400
                         })
                     }
-                    // Persist Joi defaults back to data
-                    if (validationResult.value) options.data = validationResult.value
+                    // Return sanitized value (Joi defaults applied, unknown keys handled)
+                    return validationResult.value;
                 }
             }
 
@@ -117,22 +122,38 @@ class MongoRest {
                     validationResult = partialSchema.validate(options.update.$setOnInsert, { allowUnknown: false })
                 }
 
+                // Faille 9: updateOne/updateMany — unflatten dot-notation ("address.zip") before Joi validation
+                if ((options.action == 'updateOne' || options.action == 'updateMany') && options.update?.$set) {
+                    const unflattened = func.unflattenKeys(options.update.$set)
+                    validationResult = partialSchema.validate(unflattened, { allowUnknown: false })
+                    if (validationResult?.error) {
+                        throw new AppError(validationResult.error.message, {
+                            code: 'VALIDATION_ERROR',
+                            status: 400
+                        })
+                    }
+                    // Write sanitized (nested) value back — MongoDB accepts nested objects
+                    if (validationResult.value) {
+                        options.update.$set = validationResult.value
+                    }
+                }
+
                 if (validationResult?.error) {
                     throw new AppError(validationResult.error.message, {
                         code: 'VALIDATION_ERROR',
                         status: 400
                     })
                 }
+                return validationResult?.value;
             }
 
         }
-    }
-
-
 
+        // No schema or nothing to sanitize → pass the raw data through
+        return options.data;
     }
 
-    private async #logActivity(data: {
+    async #logActivity(data: {
         action: string,
         collection: string,
         input?: any,
@@ -189,7 +210,7 @@ class MongoRest {
         await this.audit.addActivities([activity])
     }
 
-    private async #executeWithAudit<T>(
+    async #executeWithAudit<T>(
         action: string,
         collection: string,
         input: any,
@@ -254,7 +275,17 @@ class MongoRest {
         try {
 
             const col = getCollection(collection, this.#tenant.id) as Collection
-            const isSafe = func.isSafeAggregatePipeline(pipeline);
+            // Faille 12: restrict $lookup targets to this tenant's declared collections
+            const allowedCollections = [
+                ...(cfg.collections ?? [])
+                    .filter(c => c._tenant_ === this.tenant_id)
+                    .map(c => c.slug),
+                ...(cfg.fileCollections ?? [])
+                    .filter(fc => fc._tenant_ === this.tenant_id)
+                    .map(fc => fc.slug),
+                '_activities_', '_locks_', '_workflows_',
+            ];
+            const isSafe = func.isSafeAggregatePipeline(pipeline, allowedCollections);
             if (!isSafe.isSafe) {
                 throw isSafe.error;
             }
@@ -362,7 +393,7 @@ class MongoRest {
                 await col.hooks.beforeOperation({ rest: this, io, action, meta })
             }
             // Validate AFTER hooks (they may fill required fields or apply Joi defaults)
-            this._validate({ collection, action: action, data: meta.data })
+            meta.data = this._validate({ collection, action: action, data: meta.data })
 
             await this.db.collection(collection).insertOne(func.toBson(meta.data, { col }) as any, {
                 session: this.session,
@@ -400,7 +431,7 @@ class MongoRest {
                 await col.hooks.beforeOperation({ rest: this, io, action, meta })
             }
             // Validate AFTER hooks (they may fill required fields or apply Joi defaults)
-            this._validate({ collection, action: action, data: meta.data })
+            meta.data = this._validate({ collection, action: action, data: meta.data })
 
             await this.db.collection(collection).insertMany(func.toBson(meta.data, { col }) as any, {
                 session: this.session,
@@ -429,15 +460,13 @@ class MongoRest {
             }
 
             update = await func.buildInput(update)
+            this._validate({ collection, action: action, update: update })
+            update = func.toBson(update, { col })
 
             const meta: any = { action, collection, update, id: _id }
             if (col.hooks?.beforeOperation) {
                 await col.hooks.beforeOperation({ rest: this, io, action, meta })
             }
-            // Validate and toBson AFTER hooks
-            update = meta.update;
-            this._validate({ collection, action: action, update: update })
-            update = func.toBson(update, { col })
 
             const data = await this.db.collection(collection).findOneAndUpdate(
                 { _id: new ObjectId(_id) },
@@ -493,18 +522,16 @@ class MongoRest {
             }
 
 
-            const meta: any = { action, collection, filter, update }
-            if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
-            }
-            // Validate and toBson AFTER hooks
-            update = meta.update;
-            filter = meta.filter;
             this._validate({ collection, action: action, update: update.$set })
             this._validate({ collection, action: action, update: update.$setOnInsert })
             update = func.toBson(update, { col })
             filter = func.toBson(filter, { col })
 
+            const meta: any = { action, collection, filter, update }
+            if (col.hooks?.beforeOperation) {
+                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+            }
+
             const data = await this.db.collection(collection).findOneAndUpdate(
                 filter,
                 {
@@ -536,15 +563,13 @@ class MongoRest {
                 update.$set = await func.buildInput(update.$set, { action: action, col: col })
             }
             update = await func.buildInput(update)
+            this._validate({ collection, action: action, update: update })
+            update = func.toBson(update, { col })
 
             const meta: any = { action, collection, update, ids: _ids }
             if (col.hooks?.beforeOperation) {
                 await col.hooks.beforeOperation({ rest: this, io, action, meta })
             }
-            // Validate and toBson AFTER hooks
-            update = meta.update;
-            this._validate({ collection, action: action, update: update })
-            update = func.toBson(update, { col })
 
             const result = await this.db.collection(collection).updateMany(
                 { _id: { $in: _ids.map(id => new ObjectId(id)) } },
@@ -761,14 +786,14 @@ class MongoRest {
 
         const token = requestCtxStorage.get<{ value: string | null, decoded: Record<string, unknown> | null, provided: boolean, expired: boolean }>('token')
 
-        return await col.actions?.[action]({
+        return await col.actions?.[action]?.({
             rest: this,
-                    io,
+            io,
             data,
             error: fn.error,
             jwt: func.jwt,
-            token: token ?? { value: null, decoded: null },
-        })
+            token: token ?? { value: null, decoded: null, provided: false, expired: false },
+        } as any)
     }
 
     async runService<T = any>(service: string, action: string, data?: any): Promise<T> {
@@ -785,15 +810,14 @@ class MongoRest {
 
         const token = requestCtxStorage.get<{ value: string | null, decoded: Record<string, unknown> | null, provided: boolean, expired: boolean }>('token')
 
-        return await serviceInstance.actions?.[action]({
+        return await serviceInstance.actions?.[action]?.({
             data,
             error: fn.error,
             io,
             jwt: func.jwt,
             token: token ?? { value: null, decoded: null, provided: false, expired: false },
             rest: this,
-                    io,
-        })
+        } as any)
     }
 
     async stats() {
@@ -910,8 +934,8 @@ class MongoRest {
 
         try {
             const result = await this.db.collection('_locks_').findOneAndUpdate(
-                { _id: id, expiresAt: { $lt: now } },
-                { $set: { _id: id, tid: this.tenant_id, name, acquiredAt: now, expiresAt } },
+                { _id: id as any, expiresAt: { $lt: now } },
+                { $set: { tid: this.tenant_id, name, acquiredAt: now, expiresAt } },
                 { upsert: true, returnDocument: 'after' }
             );
             if (!result) {

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
 }