proteum 2.1.0-2 → 2.1.0-3

package/docs/request-tracing.md

@@ -0,0 +1,115 @@
+# Request Tracing
+
+Proteum ships with a dev-only in-memory request trace buffer so routing, controller execution, SSR, and render behavior can be inspected without attaching a debugger or scattering temporary logs through the runtime.
+
+## Scope
+
+- tracing is available only when the app runs with `profile: dev`
+- traces are exposed through `proteum trace` and the dev-only `__proteum/trace` HTTP endpoints
+- production requests are not traced by this feature
+
+## Main Commands
+
+```bash
+proteum trace requests
+proteum trace latest
+proteum trace show <requestId>
+proteum trace arm --capture deep
+proteum trace export <requestId>
+proteum trace latest --url http://127.0.0.1:3010
+```
+
+Typical debugging flow:
+
+```bash
+proteum trace arm --capture deep --port 3103
+# reproduce the failing request once
+proteum trace requests --port 3103
+proteum trace show <requestId> --port 3103
+```
+
+Use `--url http://host:port` when the dev server is reachable on a non-standard host and `--port` is not enough.
+
+## What Gets Recorded
+
+Depending on capture mode, traces can include:
+
+- request start, finish, user identity, status code, and duration
+- direct controller route matches
+- route resolution start, match, and deep-mode skip reasons
+- controller start and result shape
+- created router/context keys
+- setup output keys and page data summaries
+- SSR payload shape and serialized byte size
+- render start/end timings and document output sizes
+- normalized request errors
+
+## Capture Modes
+
+- `summary`: smallest capture, focused on request lifecycle and high-signal events
+- `resolve`: adds route matching, controller, setup, and context milestones
+- `deep`: adds route skip reasons and deeper summarized payload inspection for one request
+
+Use `deep` selectively. It is for one-off investigation, not continuous capture.
+
+## Configuration
+
+Add trace settings in `env.yaml`:
+
+```yaml
+trace:
+  enable: true
+  requestsLimit: 200
+  eventsLimit: 800
+  capture: resolve
+  persistOnError: true
+```
+
+Notes:
+
+- `enable` and `persistOnError` still remain dev-only in the current runtime
+- `capture` defaults to `resolve`
+- `requestsLimit` defaults to `200`
+- `eventsLimit` defaults to `800`
+
+## Memory Model
+
+Traces are kept in memory per Node process.
+
+- requests are stored in a ring buffer capped by `requestsLimit`
+- the oldest request traces are evicted first
+- each request is capped by `eventsLimit`
+- once the event cap is reached, extra events are dropped and counted in `droppedEvents`
+- payloads are summarized rather than stored as raw objects
+
+Current summarization rules:
+
+- arrays keep at most 10 sampled items
+- objects keep at most 20 keys per level
+- deep capture stops at depth 3
+- long strings are truncated
+
+## Redaction
+
+Sensitive values are redacted before they enter the trace store.
+
+This includes keys such as:
+
+- `cookie`
+- `authorization`
+- `password`
+- token-like fields such as `accessToken`, `refreshToken`, `apiKey`, `jwt`, and similar names
+- `rawBody`
+
+The goal is to make traces useful for debugging without turning the dev server into a secret dump.
+
+## Dev HTTP Endpoints
+
+These endpoints back the CLI:
+
+- `GET /__proteum/trace/requests`
+- `GET /__proteum/trace/latest`
+- `GET /__proteum/trace/requests/:id`
+- `POST /__proteum/trace/arm`
+
+The CLI should be the primary interface. Use the HTTP endpoints when you need direct machine access from another local dev tool.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.1.0-2",
+	"version": "2.1.0-3",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/server/app/container/config.ts

@@ -67,6 +67,13 @@ export type TEnvConfig = {
 
     router: { port: number; domains: TDomainsList };
     console: { enable: boolean; debug: boolean; bufferLimit: number; level: TLogProfile };
+    trace: {
+        enable: boolean;
+        requestsLimit: number;
+        eventsLimit: number;
+        capture: 'summary' | 'resolve' | 'deep';
+        persistOnError: boolean;
+    };
 };
 
 type AppIdentityConfig = {
@@ -126,9 +133,17 @@ export default class ConfigParser {
         const envFileName = this.appDir + '/env.yaml';
         const envFile = this.loadYaml(envFileName);
         const routerPortOverride = getRouterPortOverride();
+        const traceConfig = envFile.trace || {};
         return {
             ...envFile,
             router: routerPortOverride === undefined ? envFile.router : { ...envFile.router, port: routerPortOverride },
+            trace: {
+                enable: traceConfig.enable ?? envFile.profile === 'dev',
+                requestsLimit: traceConfig.requestsLimit ?? 200,
+                eventsLimit: traceConfig.eventsLimit ?? 800,
+                capture: traceConfig.capture ?? 'resolve',
+                persistOnError: traceConfig.persistOnError ?? envFile.profile === 'dev',
+            },
             version: BUILD_DATE,
         };
     }

package/server/app/container/index.ts

@@ -15,6 +15,7 @@ import type { StartedServicesIndex } from '../service';
 import Services, { ServicesContainer } from '../service/container';
 import ConfigParser, { TEnvConfig } from './config';
 import Console from './console';
+import Trace from './trace';
 import type ServerRequest from '@server/services/router/request';
 
 /*----------------------------------
@@ -29,6 +30,7 @@ export class ApplicationContainer<TServicesIndex extends StartedServicesIndex =
     public Environment: TEnvConfig;
     public Identity: Config.Identity;
     public Console: Console;
+    public Trace: Trace;
 
     public application?: Application;
 
@@ -52,6 +54,7 @@ export class ApplicationContainer<TServicesIndex extends StartedServicesIndex =
         this.Environment = configParser.env();
         this.Identity = configParser.identity();
         this.Console = new Console(this, this.Environment.console);
+        this.Trace = new Trace(this, this.Environment.trace);
     }
 
     /*----------------------------------

package/server/app/container/trace/index.ts

@@ -0,0 +1,284 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import type ApplicationContainer from '..';
+import {
+    traceCaptureModes,
+    type TTraceCaptureMode,
+    type TTraceEvent,
+    type TTraceEventType,
+    type TTraceSummaryValue,
+    type TRequestTrace,
+    type TRequestTraceListItem,
+} from '@common/dev/requestTrace';
+
+export type Config = {
+    enable: boolean;
+    requestsLimit: number;
+    eventsLimit: number;
+    capture: TTraceCaptureMode;
+    persistOnError: boolean;
+};
+
+type TTraceInspectable = object | PrimitiveValue | bigint | symbol | null | undefined | (() => void);
+type TTraceDetails = { [key: string]: TTraceInspectable };
+
+const capturePriority: Record<TTraceCaptureMode, number> = { summary: 0, resolve: 1, deep: 2 };
+const sensitiveKeyPattern =
+    /(^|\.)(authorization|cookie|set-cookie|password|pass|pwd|secret|token|refreshToken|accessToken|apiKey|apiSecret|secretAccessKey|accessKeyId|privateKey|session|jwt|rawBody)$/i;
+const maxStringLength = 240;
+
+const isTraceCaptureMode = (value: string): value is TTraceCaptureMode =>
+    traceCaptureModes.includes(value as TTraceCaptureMode);
+
+const isSensitiveKeyPath = (keyPath: string[]) => sensitiveKeyPattern.test(keyPath.join('.'));
+
+const summarizeString = (value: string) =>
+    value.length <= maxStringLength ? value : `${value.slice(0, maxStringLength)}…`;
+
+const summarizeError = (error: Error): TTraceSummaryValue => ({
+    kind: 'error',
+    name: error.name,
+    message: error.message,
+    stack: error.stack?.split('\n').slice(0, 5).join('\n'),
+});
+
+const summarizeValue = (
+    value: TTraceInspectable,
+    depth: number,
+    seen: WeakSet<object>,
+    keyPath: string[],
+): TTraceSummaryValue => {
+    if (isSensitiveKeyPath(keyPath)) return { kind: 'redacted', reason: `Sensitive key ${keyPath[keyPath.length - 1] || 'value'}` };
+    if (value === undefined) return { kind: 'undefined' };
+    if (value === null) return null;
+
+    const primitiveType = typeof value;
+    if (primitiveType === 'string') return summarizeString(value);
+    if (primitiveType === 'number' || primitiveType === 'boolean') return value;
+    if (primitiveType === 'bigint') return { kind: 'bigint', value: value.toString() };
+    if (primitiveType === 'symbol') return { kind: 'symbol', value: value.toString() };
+    if (primitiveType === 'function') return { kind: 'function', name: value.name || 'anonymous' };
+
+    if (value instanceof Date) return { kind: 'date', value: value.toISOString() };
+    if (value instanceof Error) return summarizeError(value);
+    if (Buffer.isBuffer(value)) return { kind: 'buffer', byteLength: value.byteLength };
+    if (value instanceof Map) return { kind: 'map', size: value.size };
+    if (value instanceof Set) return { kind: 'set', size: value.size };
+
+    if (seen.has(value)) {
+        return {
+            kind: 'object',
+            constructorName: value.constructor?.name || 'Object',
+            keys: [],
+            entries: {},
+            truncated: true,
+        };
+    }
+
+    seen.add(value);
+
+    if (Array.isArray(value)) {
+        if (depth <= 0) return { kind: 'array', length: value.length, items: [], truncated: value.length > 0 };
+
+        const items = value
+            .slice(0, 10)
+            .map((item, index) => summarizeValue(item as TTraceInspectable, depth - 1, seen, [...keyPath, `[${index}]`]));
+        return { kind: 'array', length: value.length, items, truncated: value.length > items.length };
+    }
+
+    const constructorName = value.constructor?.name || 'Object';
+    const keys = Object.keys(value);
+    if (depth <= 0) {
+        return { kind: 'object', constructorName, keys, entries: {}, truncated: keys.length > 0 };
+    }
+
+    const entries: { [key: string]: TTraceSummaryValue } = {};
+    for (const key of keys.slice(0, 20)) {
+        const record = value as Record<string, TTraceInspectable>;
+        entries[key] = summarizeValue(record[key], depth - 1, seen, [...keyPath, key]);
+    }
+
+    return { kind: 'object', constructorName, keys, entries, truncated: keys.length > Object.keys(entries).length };
+};
+
+const summarizeDetails = (details: TTraceDetails, capture: TTraceCaptureMode) => {
+    const depth = capture === 'deep' ? 3 : 1;
+    const summarized: { [key: string]: TTraceSummaryValue } = {};
+
+    for (const key of Object.keys(details)) {
+        summarized[key] = summarizeValue(details[key], depth, new WeakSet<object>(), [key]);
+    }
+
+    return summarized;
+};
+
+const nowIso = () => new Date().toISOString();
+
+export default class Trace {
+    private requests = new Map<string, TRequestTrace>();
+    private order: string[] = [];
+    private armedCapture?: TTraceCaptureMode;
+
+    public constructor(
+        private container: typeof ApplicationContainer,
+        private config: Config,
+    ) {}
+
+    public isEnabled() {
+        return this.config.enable && this.container.Environment.profile === 'dev';
+    }
+
+    public armNextRequest(capture: string) {
+        if (!isTraceCaptureMode(capture)) {
+            throw new Error(`Unsupported trace capture mode "${capture}". Expected one of: ${traceCaptureModes.join(', ')}.`);
+        }
+
+        this.armedCapture = capture;
+        return capture;
+    }
+
+    public startRequest(input: { id: string; method: string; path: string; url: string; headers: object; data: object }) {
+        if (!this.isEnabled()) return;
+
+        const capture = this.armedCapture ?? this.config.capture;
+        this.armedCapture = undefined;
+
+        const trace: TRequestTrace = {
+            id: input.id,
+            method: input.method,
+            path: input.path,
+            url: input.url,
+            capture,
+            startedAt: nowIso(),
+            droppedEvents: 0,
+            events: [],
+        };
+
+        this.requests.set(trace.id, trace);
+        this.order.push(trace.id);
+        this.trimRequestBuffer();
+
+        this.record(trace.id, 'request.start', { method: input.method, path: input.path, url: input.url, headers: input.headers, data: input.data });
+    }
+
+    public setRequestUser(requestId: string, user?: string) {
+        const trace = this.requests.get(requestId);
+        if (!trace) return;
+
+        trace.user = user;
+        if (user) this.record(requestId, 'request.user', { user });
+    }
+
+    public getCapture(requestId: string) {
+        return this.requests.get(requestId)?.capture;
+    }
+
+    public shouldCapture(requestId: string, minimumCapture: TTraceCaptureMode) {
+        const capture = this.getCapture(requestId);
+        if (!capture) return false;
+
+        return capturePriority[capture] >= capturePriority[minimumCapture];
+    }
+
+    public record(requestId: string, type: TTraceEventType, details: TTraceDetails, minimumCapture: TTraceCaptureMode = 'summary') {
+        const trace = this.requests.get(requestId);
+        if (!trace || !this.shouldCapture(requestId, minimumCapture)) return;
+
+        if (trace.events.length >= this.config.eventsLimit) {
+            trace.droppedEvents++;
+            return;
+        }
+
+        const event: TTraceEvent = {
+            index: trace.events.length,
+            at: nowIso(),
+            elapsedMs: Math.max(0, Date.now() - Date.parse(trace.startedAt)),
+            type,
+            details: summarizeDetails(details, trace.capture),
+        };
+
+        trace.events.push(event);
+    }
+
+    public finishRequest(requestId: string, output: { statusCode: number; user?: string; errorMessage?: string }) {
+        const trace = this.requests.get(requestId);
+        if (!trace) return;
+
+        if (output.user) trace.user = output.user;
+        trace.statusCode = output.statusCode;
+        trace.errorMessage = output.errorMessage;
+
+        this.record(
+            requestId,
+            'request.finish',
+            { statusCode: output.statusCode, user: output.user || '', errorMessage: output.errorMessage || '' },
+            'summary',
+        );
+
+        trace.finishedAt = nowIso();
+        trace.durationMs = Math.max(0, Date.parse(trace.finishedAt) - Date.parse(trace.startedAt));
+
+        if (this.config.persistOnError && trace.statusCode >= 500) {
+            trace.persistedFilepath = this.exportRequest(requestId);
+        }
+    }
+
+    public listRequests(limit = 20): TRequestTraceListItem[] {
+        return [...this.order]
+            .reverse()
+            .slice(0, limit)
+            .map((requestId) => this.requests.get(requestId))
+            .filter((trace): trace is TRequestTrace => trace !== undefined)
+            .map((trace) => ({
+                id: trace.id,
+                method: trace.method,
+                path: trace.path,
+                url: trace.url,
+                capture: trace.capture,
+                startedAt: trace.startedAt,
+                finishedAt: trace.finishedAt,
+                durationMs: trace.durationMs,
+                statusCode: trace.statusCode,
+                user: trace.user,
+                droppedEvents: trace.droppedEvents,
+                persistedFilepath: trace.persistedFilepath,
+                errorMessage: trace.errorMessage,
+                eventCount: trace.events.length,
+            }));
+    }
+
+    public getLatestRequest() {
+        const latestRequestId = this.order[this.order.length - 1];
+        return latestRequestId ? this.requests.get(latestRequestId) : undefined;
+    }
+
+    public getRequest(requestId: string) {
+        return this.requests.get(requestId);
+    }
+
+    public exportRequest(requestId: string, filepath?: string) {
+        const trace = this.requests.get(requestId);
+        if (!trace) throw new Error(`Trace ${requestId} was not found.`);
+
+        const outputFilepath =
+            filepath ||
+            path.join(this.container.path.var, 'traces', trace.startedAt.slice(0, 10), `${trace.id}.json`);
+
+        fs.ensureDirSync(path.dirname(outputFilepath));
+        fs.writeJSONSync(outputFilepath, trace, { spaces: 2 });
+
+        trace.persistedFilepath = outputFilepath;
+
+        return outputFilepath;
+    }
+
+    private trimRequestBuffer() {
+        const overflow = this.order.length - this.config.requestsLimit;
+        if (overflow <= 0) return;
+
+        for (const requestId of this.order.splice(0, overflow)) {
+            this.requests.delete(requestId);
+        }
+    }
+}

package/server/services/prisma/index.ts

@@ -23,6 +23,62 @@ import { NotFound } from '@common/errors';
 
 export type SqlQuery = ReturnType<ModelsManager['SQL']>;
 
+type DecimalLike = {
+    constructor?: { name?: string };
+    equals: (value: number) => boolean;
+    toNumber: () => number;
+    toString: () => string;
+};
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+const isDecimalLike = (value: object): value is DecimalLike =>
+    'constructor' in value &&
+    'equals' in value &&
+    'toNumber' in value &&
+    'toString' in value &&
+    typeof value.constructor === 'function' &&
+    value.constructor.name === 'Decimal' &&
+    typeof value.equals === 'function' &&
+    typeof value.toNumber === 'function' &&
+    typeof value.toString === 'function';
+
+const isPlainObject = (value: object) => {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+
+const normalizeBigInt = (value: bigint) => {
+    const number = Number(value);
+    return Number.isSafeInteger(number) ? number : value.toString();
+};
+
+const normalizeDecimal = (value: DecimalLike) => {
+    const number = value.toNumber();
+    return Number.isFinite(number) && value.equals(number) ? number : value.toString();
+};
+
+const normalizeSqlScalar = (value: bigint | DecimalLike) =>
+    typeof value === 'bigint' ? normalizeBigInt(value) : normalizeDecimal(value);
+
+const normalizeSqlResult = <T>(value: T): T => {
+    if (typeof value === 'bigint') return normalizeSqlScalar(value) as T;
+
+    if (Array.isArray(value)) return value.map((item) => normalizeSqlResult(item)) as T;
+
+    if (value === null || value === undefined || typeof value !== 'object' || value instanceof Date) return value;
+
+    if (isDecimalLike(value)) return normalizeSqlScalar(value) as T;
+
+    if (!isPlainObject(value)) return value;
+
+    return Object.fromEntries(
+        Object.entries(value).map(([key, nestedValue]) => [key, normalizeSqlResult(nestedValue)]),
+    ) as T;
+};
+
 /*----------------------------------
 - SERVICE CONFIG
 ----------------------------------*/
@@ -35,8 +91,7 @@ export type Services = {};
 
 // Fix: Do not know how to serialize a BigInt
 BigInt.prototype.toJSON = function () {
-    const int = Number.parseInt(this.toString());
-    return int ?? this.toString();
+    return normalizeBigInt(this.valueOf());
 };
 
 /*----------------------------------
@@ -80,9 +135,10 @@ export default class ModelsManager extends Service<Config, Hooks, Application, A
     public SQL<TRowData extends {} | number | string>(strings: TemplateStringsArray, ...data: any[]) {
         const string = this.string(strings, ...data);
 
-        const query = () => {
-            return this.client.$queryRawUnsafe(string) as Promise<TRowData[]>;
-        };
+        const query = () =>
+            this.client.$queryRawUnsafe(string).then((resultatRequetes) => normalizeSqlResult(resultatRequetes)) as Promise<
+                TRowData[]
+            >;
 
         query.all = query;
         query.value = <TValue extends any = number>() =>

package/server/services/router/http/index.ts

@@ -206,6 +206,7 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
             }),
         );
 
+        this.registerDevTraceRoutes(routes);
         routes.use(routeRequest);
 
         /*----------------------------------
@@ -227,4 +228,43 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
     public async cleanup() {
         this.http.close();
     }
+
+    private registerDevTraceRoutes(routes: express.Express) {
+        if (!this.app.container.Trace.isEnabled()) return;
+
+        routes.get('/__proteum/trace/requests', (req, res) => {
+            const rawLimit = Array.isArray(req.query.limit) ? req.query.limit[0] : req.query.limit;
+            const parsedLimit = typeof rawLimit === 'string' ? Number.parseInt(rawLimit, 10) : NaN;
+            const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 20;
+
+            res.json({ requests: this.app.container.Trace.listRequests(limit) });
+        });
+
+        routes.get('/__proteum/trace/latest', (_req, res) => {
+            const request = this.app.container.Trace.getLatestRequest();
+            if (!request) {
+                res.status(404).json({ error: 'No request trace is available yet.' });
+                return;
+            }
+
+            res.json({ request });
+        });
+
+        routes.get('/__proteum/trace/requests/:id', (req, res) => {
+            const request = this.app.container.Trace.getRequest(req.params.id);
+            if (!request) {
+                res.status(404).json({ error: `Trace ${req.params.id} was not found.` });
+                return;
+            }
+
+            res.json({ request });
+        });
+
+        routes.post('/__proteum/trace/arm', (req, res) => {
+            const rawCapture = typeof req.body.capture === 'string' ? req.body.capture : 'deep';
+            const capture = this.app.container.Trace.armNextRequest(rawCapture);
+
+            res.json({ armed: true, capture });
+        });
+    }
 }