@anteros/core 0.0.24 → 0.0.26

package/index.ts

@@ -13,6 +13,7 @@ import * as crypto from "./utils/crypto";
 
 // BentoCache-based caching (memory L1 + filesystem/Redis L2)
 import { useMemoryCache, useFilesystemCache, useRedisCache } from "./utils/cache";
+import { logger } from "./utils/logger";
 const cache = {
     useMemoryCache,
     useFilesystemCache,
@@ -31,4 +32,5 @@ export {
     utils,
     cache,
     crypto,
+    logger,
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anteros/core",
   "module": "index.ts",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "type": "module",
   "description": "Anteros Core",
   "private": false,
@@ -10,7 +10,8 @@
     "bun": ">=1.3.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14"
+    "@types/bun": "^1.3.14",
+    "@types/tcp-port-used": "^1.0.4"
   },
   "peerDependencies": {
     "typescript": "6.0.3"
@@ -29,6 +30,7 @@
     "jose": "6.2.8",
     "mongodb": "7.5.0",
     "socket.io": "4.8.3",
+    "tcp-port-used": "^1.0.3",
     "ufo": "1.6.4",
     "zod": "^4.4.3"
   }

package/server/api.ts

@@ -174,7 +174,7 @@ type CrudHandler = (rest: InstanceType<typeof useRest>, collection: string, body
 
 const crudHandlers: Record<string, CrudHandler> = {
     aggregate:       (rest, collection, body) => rest.aggregate(collection, body?.pipeline || []),
-    find:            (rest, collection, body) => rest.find(collection, body?.params || {}),
+    find:            (rest, collection, body) => rest.find(collection, body?.params || {}, { useCache: body?.options?.useCache }),
     findOne:         (rest, collection, body) => rest.findOne(collection, body?.id, body?.params || {}),
     insertOne:       (rest, collection, body) => rest.insertOne(collection, body?.data),
     insertMany:      (rest, collection, body) => rest.insertMany(collection, body?.data),

package/server/boot.ts

@@ -1,5 +1,5 @@
 
-import { createApp } from './hono'
+import { createApp, collectHeaders } from './hono'
 import type { ServerConfig } from '../types/config'
 import dayjs from 'dayjs';
 import pkg from '../package.json';
@@ -22,18 +22,8 @@ import crypto from 'node:crypto';
 import os from 'node:os';
 import { registerMetrics, getMetrics, trackRequest } from './metrics';
 import { startMaster, aggregateMetrics } from './cluster';
-
-/** Check if a TCP port is already bound */
-async function isPortInUse(port: number): Promise<boolean> {
-    try {
-        const proc = Bun.spawn(['lsof', '-ti', `:${port}`], { stdout: 'pipe' });
-        const output = await new Response(proc.stdout).text();
-        await proc.exited;
-        return output.trim().length > 0;
-    } catch {
-        return false;
-    }
-}
+import tcpPortUsed from 'tcp-port-used';
+import { logger } from '../utils/logger';
 
 type BootAppOptions = ServerConfig & {
 
@@ -45,6 +35,15 @@ async function bootApp(options: BootAppOptions = {} as BootAppOptions) {
         // Load required resources
         //******************************* */
         options = formatConfig(options);
+
+        // Logging: configure from cfg.server.logging (console + file, e.g. logs/anteros.log)
+        logger.configure(cfg.server.logging);
+        logger.info('Starting Anteros server', {
+            name: cfg.server.name ?? process.env.APP_NAME ?? 'SERVER',
+            port: cfg.server.port ?? 4000,
+            env: process.env.NODE_ENV || Bun.env.NODE_ENV || 'dev',
+            tenants: cfg.tenants?.map((t) => t.id),
+        });
         await syncTenants(); // sync tenants and connect to database
         await syncCollections(); // sync collections and create collections on database
         await syncFileCollections(); // sync file collections
@@ -117,14 +116,38 @@ async function bootApp(options: BootAppOptions = {} as BootAppOptions) {
 
             console.log(`[cluster] Aggregated /health → http://localhost:${metricsPort}/health`.gray);
 
+            // Graceful shutdown: stop workers + metrics server so a restart
+            // (e.g. bun --watch) never leaves the port occupied
+            const shutdownCluster = (signal: string) => {
+                console.log(`\n${signal} received — shutting down workers…`.gray);
+                try { master.shutdown(); } catch {}
+                try { metricsServer.stop(true); } catch {}
+                for (const tenant of cfg.tenants ?? []) {
+                    try { tenant.database?.client?.close(); } catch {}
+                }
+                process.exit(0);
+            };
+            process.once('SIGINT', () => shutdownCluster('SIGINT'));
+            process.once('SIGTERM', () => shutdownCluster('SIGTERM'));
+
             // Keep the master alive
             return { master, metricsServer } as any;
         }
 
-        // Detect zombie: check if port is already in use when NOT sharing the port
+        // Detect zombie: check if port is already in use when NOT sharing the port.
+        // tcp-port-used probes with a real TCP connection — only a listening server
+        // counts (a connected client never triggers a false positive) and it works
+        // on any platform (no lsof dependency). Grace period: after a restart the
+        // previous process may still be releasing the port (Mongo / Socket.IO
+        // shutdown) — wait before declaring a zombie.
         if (!reusePort && env === 'dev') {
-            const occupied = await isPortInUse(PORT);
-            if (occupied) {
+            if (await tcpPortUsed.check(PORT)) {
+                console.log(`⏳ Port ${PORT} is still held, waiting for the previous process to release it (~2.5s)…`.gray);
+            }
+            try {
+                // ~2.5s grace (5 × 500ms); rejects if the port stays occupied
+                await tcpPortUsed.waitUntilFree(PORT, 500, 2500);
+            } catch {
                 console.error(`\n⚠ Port ${PORT} is already in use. Possible zombie server.\n  → Kill it: lsof -ti :${PORT} | xargs kill -9\n`.red.bold);
                 process.exit(1);
             }
@@ -147,7 +170,39 @@ async function bootApp(options: BootAppOptions = {} as BootAppOptions) {
                     });
 
                 if (url.pathname === "/socket.io/") {
-                    return respond(engineIo.handleRequest(req, server));
+                    const start = performance.now();
+                    return respond(engineIo.handleRequest(req, server)).then((res) => {
+                        // Access log for the Socket.IO upgrade path (handled outside Hono) —
+                        // same Caddy-compatible structure as the API access log
+                        const remote: any = (server as any).requestIP?.(req);
+                        const remoteIp = remote?.address ?? null;
+                        const remotePort = remote?.port ?? null;
+                        logger.info(`${req.method} ${url.pathname}${url.search} → ${res.status}`, {
+                            logger: 'http.log.access',
+                            status: res.status,
+                            duration: Math.round((performance.now() - start) * 10) / 10,
+                            method: req.method,
+                            uri: url.pathname + url.search,
+                            remote_ip: remoteIp,
+                            bytes_read: Number(req.headers.get('content-length')) || 0,
+                            size: Number(res.headers.get('content-length')) || 0,
+                            user_id: '',
+                            ip: remoteIp ?? 'unknown',
+                            traceId: null,
+                            tenant: null,
+                            request: {
+                                headers: collectHeaders(req.headers),
+                                client_ip: remoteIp ?? 'unknown',
+                                host: req.headers.get('host') ?? '',
+                                method: req.method,
+                                remote_ip: remoteIp,
+                                remote_port: remotePort,
+                                uri: url.pathname + url.search,
+                            },
+                            resp_headers: collectHeaders(res.headers),
+                        });
+                        return res;
+                    });
                 }
                 return respond(app.fetch(req, server));
             },
@@ -158,6 +213,19 @@ async function bootApp(options: BootAppOptions = {} as BootAppOptions) {
         // Register server for built-in metrics (GET /health)
         registerMetrics(server);
 
+        // Graceful shutdown: release the port & DB connections so restarts
+        // (e.g. bun --watch) never hit a zombie / EADDRINUSE
+        const shutdownServer = (signal: string) => {
+            console.log(`\n${signal} received — shutting down…`.gray);
+            try { server.stop(true); } catch {}
+            for (const tenant of cfg.tenants ?? []) {
+                try { tenant.database?.client?.close(); } catch {}
+            }
+            process.exit(0);
+        };
+        process.once('SIGINT', () => shutdownServer('SIGINT'));
+        process.once('SIGTERM', () => shutdownServer('SIGTERM'));
+
         // ── WORKER (cluster): report metrics to the master via IPC ──
         if (isWorker && typeof process.send === 'function') {
             setInterval(() => {
@@ -198,8 +266,29 @@ async function bootApp(options: BootAppOptions = {} as BootAppOptions) {
 
         }, 150);
 
+        // Boot event — recorded in the log file only (the console banner already
+        // shows name / PID / role / URL, so this line would be redundant on screen)
+        logger.file('Server started', {
+            name: NAME,
+            pid: process.pid,
+            role,
+            url: `http://localhost:${PORT}`,
+            env: env || 'dev',
+            logFile: logger.filePath || undefined,
+        });
+
+        // Uncaught errors → log file (MongoDB-style), then exit
+        process.on('uncaughtException', (err) => {
+            logger.error('Uncaught exception', { message: err?.message, stack: err?.stack });
+            process.exit(1);
+        });
+        process.on('unhandledRejection', (reason: any) => {
+            logger.error('Unhandled rejection', { message: reason?.message ?? String(reason), stack: reason?.stack });
+        });
+
         return server;
     } catch (err: any) {
+        logger.error('Failed to boot server', cfg.debug ? { error: err, message: err?.message } : { message: err?.message });
         console.error('Failed to boot server', cfg.debug ? err : err?.message);
         process.exit(1);
     }

package/server/hono.ts

@@ -18,8 +18,24 @@ import { getGlobalMiddlewares } from "../lib/middleware";
 import { jwt } from "../utils/func";
 import { AppError } from "../lib/error";
 import { getMetrics } from "./metrics";
+import { logger } from "../utils/logger";
 import type { HonoVariables } from "./env";
 
+/**
+ * Caddy-style header collection (array values); sensitive headers stripped
+ * (`authorization`, `cookie`, `proxy-authorization`, `set-cookie`).
+ */
+export function collectHeaders(h: Headers): Record<string, string[]> {
+    const EXCLUDE = ['authorization', 'cookie', 'proxy-authorization', 'set-cookie'];
+    const out: Record<string, string[]> = {};
+    for (const [name, value] of h.entries()) {
+        const key = name.toLowerCase();
+        if (EXCLUDE.includes(key)) continue;
+        out[key] = [value];
+    }
+    return out;
+}
+
 // ─── Redis-backed rate limiting (C3) ─────────────────────────────────────────
 // Lazy singleton: created once per process and reused across createApp() calls.
 // Each increment falls back to the in-memory store if Redis is unavailable,
@@ -200,6 +216,51 @@ function createApp(): Hono<{ Variables: HonoVariables }> {
         await next();
     });
 
+    // Access log — registered before /health & routes so EVERY request is logged.
+    // Runs around the async-context middleware, so traceId/tenant are readable here.
+    // Caddy-compatible JSONL payload: `request`/`resp_headers` blocks + flat fields.
+    app.use(async (c, next) => {
+        const start = performance.now();
+        try {
+            await next();
+        } finally {
+            const duration = performance.now() - start;
+            const trace = requestCtxStorage.get<{ id: string }>('trace');
+            const conn = c.get('connInfo');
+            const token = c.get('token');
+            const url = new URL(c.req.raw.url);
+            const uri = url.pathname + url.search;
+            const ip = c.get('clientIp') ?? 'unknown';
+            const remoteIp = conn?.remote?.address ?? null;
+            const remotePort = conn?.remote?.port ?? null;
+
+            logger.info(`${c.req.method} ${uri} → ${c.res.status}`, {
+                logger: 'http.log.access',
+                status: c.res.status,
+                duration: Math.round(duration * 10) / 10,
+                method: c.req.method,
+                uri,
+                remote_ip: remoteIp,
+                bytes_read: Number(c.req.header('content-length')) || 0,
+                size: Number(c.res.headers.get('content-length')) || 0,
+                user_id: (token?.decoded as Record<string, unknown> | null)?.['sub'] as string ?? '',
+                ip,
+                traceId: trace?.id ?? crypto.randomUUID(),
+                tenant: requestCtxStorage.get<string>('tenant_id') ?? null,
+                request: {
+                    headers: collectHeaders(c.req.raw.headers),
+                    client_ip: ip,
+                    host: c.req.header('host') ?? '',
+                    method: c.req.method,
+                    remote_ip: remoteIp,
+                    remote_port: remotePort,
+                    uri,
+                },
+                resp_headers: collectHeaders(c.res.headers),
+            });
+        }
+    });
+
     // Reuse the cached connInfo instead of re-querying the socket per middleware
     const cachedGetConnInfo: GetConnInfo = (c) =>
         (c as Context<{ Variables: HonoVariables }>).get('connInfo') ?? safeGetConnInfo(c);
@@ -320,6 +381,8 @@ function createApp(): Hono<{ Variables: HonoVariables }> {
                 c.set('token', emptyToken);
             }
 
+            // (access log is a dedicated middleware registered earlier — see top of createApp)
+
             return await next();
         })
     })

package/server/mcp.ts

@@ -13,6 +13,7 @@ import { StreamableHTTPTransport } from "@hono/mcp";
 import type Joi from "joi";
 import { cfg } from "./config";
 import { useRest } from "../database/rest";
+import { logger } from "../utils/logger";
 import type { McpTool, McpResource } from "../types/mcp";
 import type { HonoVariables } from "./env";
 
@@ -113,24 +114,32 @@ function buildServer(tenantId: string, tools: McpTool[], resources: McpResource[
         { capabilities: { tools: {}, resources: {} } }
     );
 
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: tools.map((t) => ({
+    const ms = (start: number) => Math.round((performance.now() - start) * 10) / 10;
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const start = performance.now();
+        const toolsList = tools.map((t) => ({
             name: t.name,
             title: t.name,
             description: t.description,
             inputSchema: joiToJsonSchema(t.inputSchema),
-        })),
-    }));
+        }));
+        logger.info('MCP tools/list', { method: 'tools/list', tenant: tenantId, count: toolsList.length, duration: ms(start) });
+        return { tools: toolsList };
+    });
 
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const start = performance.now();
         const tool = tools.find((t) => t.name === req.params.name);
         if (!tool) {
+            logger.warn('MCP tools/call', { method: 'tools/call', tenant: tenantId, tool: req.params.name, error: 'unknown tool', duration: ms(start) });
             throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${req.params.name}`);
         }
 
         const raw = req.params.arguments ?? {};
         const { error, value } = tool.inputSchema.validate(raw, { allowUnknown: false });
         if (error) {
+            logger.warn('MCP tools/call', { method: 'tools/call', tenant: tenantId, tool: req.params.name, args: raw, error: 'invalid arguments', duration: ms(start) });
             return {
                 content: [{ type: 'text' as const, text: `Invalid arguments: ${error.message}` }],
                 isError: true,
@@ -140,10 +149,13 @@ function buildServer(tenantId: string, tools: McpTool[], resources: McpResource[
         const rest = new useRest({ tenant_id: tenantId });
         try {
             const result = await tool.exec({ c: undefined as any, rest, args: value });
+            const isError = !!(result as any)?.isError;
+            logger[isError ? 'warn' : 'info']('MCP tools/call', { method: 'tools/call', tenant: tenantId, tool: req.params.name, args: value, isError, duration: ms(start) });
             if (result && Array.isArray(result.content)) return result;
             const text = typeof result === 'string' ? result : JSON.stringify(result);
             return { content: [{ type: 'text' as const, text }] };
         } catch (err: any) {
+            logger.warn('MCP tools/call', { method: 'tools/call', tenant: tenantId, tool: req.params.name, args: value, error: err?.message ?? 'unknown', duration: ms(start) });
             return {
                 content: [{ type: 'text' as const, text: `Error: ${err?.message ?? 'unknown'}` }],
                 isError: true,
@@ -151,32 +163,40 @@ function buildServer(tenantId: string, tools: McpTool[], resources: McpResource[
         }
     });
 
-    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-        resources: resources
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const start = performance.now();
+        const resourcesList = resources
             .filter((r) => !r.uri.includes('{')) // static only; templates are listed separately
             .map((r) => ({
                 uri: r.uri,
                 name: r.name,
                 description: r.description,
                 mimeType: r.mimeType,
-            })),
-    }));
+            }));
+        logger.info('MCP resources/list', { method: 'resources/list', tenant: tenantId, count: resourcesList.length, duration: ms(start) });
+        return { resources: resourcesList };
+    });
 
-    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
-        resourceTemplates: resources
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+        const start = performance.now();
+        const templates = resources
             .filter((r) => r.uri.includes('{'))
             .map((r) => ({
                 uriTemplate: r.uri,
                 name: r.name,
                 description: r.description,
                 mimeType: r.mimeType,
-            })),
-    }));
+            }));
+        logger.info('MCP resources/templates/list', { method: 'resources/templates/list', tenant: tenantId, count: templates.length, duration: ms(start) });
+        return { resourceTemplates: templates };
+    });
 
     server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        const start = performance.now();
         const uri = req.params.uri;
         const matched = matchUri(uri, resources);
         if (!matched) {
+            logger.warn('MCP resources/read', { method: 'resources/read', tenant: tenantId, uri, error: 'unknown uri', duration: ms(start) });
             throw new McpError(ErrorCode.InvalidParams, `Unknown resource URI: ${uri}`);
         }
 
@@ -188,8 +208,10 @@ function buildServer(tenantId: string, tools: McpTool[], resources: McpResource[
                 params: matched.params,
                 uri,
             });
+            logger.info('MCP resources/read', { method: 'resources/read', tenant: tenantId, uri, resource: matched.resource.name, params: matched.params, duration: ms(start) });
             return result;
         } catch (err: any) {
+            logger.warn('MCP resources/read', { method: 'resources/read', tenant: tenantId, uri, error: err?.message ?? 'unknown', duration: ms(start) });
             throw new McpError(ErrorCode.InternalError, `Failed to read resource: ${err?.message ?? 'unknown'}`);
         }
     });

package/server/routes.ts

@@ -4,6 +4,7 @@ import path from "path";
 import { jwt } from "../utils/func";
 import { useRest } from "../database/rest";
 import { io } from "./io";
+import { requestCtxStorage } from "../lib/asyncContextStorage";
 import type { HonoVariables } from "./env";
 
 function initializeRoutes(app: Hono<{ Variables: HonoVariables }>) {
@@ -12,10 +13,17 @@ function initializeRoutes(app: Hono<{ Variables: HonoVariables }>) {
           let method = route.method.toLocaleLowerCase();
           let routePath = path.posix.join(route._prefix_, route.path);
 
+            // Resolve the tenant in the request context so the access log,
+            // nested useRest() calls and audit see the right tenant_id
+            const resolveTenant = () => {
+                requestCtxStorage.set('tenant_id', route._tenant_);
+            };
+
 
 
             if (route.method == "GET") {
                 app.get(routePath, async (c) => { //
+                    resolveTenant();
                     return route.handler({
                         c,
                         rest: new useRest({
@@ -29,6 +37,7 @@ function initializeRoutes(app: Hono<{ Variables: HonoVariables }>) {
 
             if (route.method == 'POST') {
                 app.post(routePath, async (c) => {
+                    resolveTenant();
                     return route.handler({
                         c,
                         rest: new useRest({
@@ -42,6 +51,7 @@ function initializeRoutes(app: Hono<{ Variables: HonoVariables }>) {
 
             if (route.method == "PUT") {
                 app.put(routePath, async (c) => { //
+                    resolveTenant();
                     return route.handler({
                         c,
                         rest: new useRest({