@devms/livetail 0.0.2

package/dist/console-capture.service.js

@@ -0,0 +1,166 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var ConsoleCaptureService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleCaptureService = void 0;
+const common_1 = require("@nestjs/common");
+const rxjs_1 = require("rxjs");
+const livetail_interface_1 = require("./interfaces/livetail.interface");
+// Matches ANSI SGR + cursor/erase escape sequences.
+const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]/g;
+/**
+ * Tees process.stdout / process.stderr into an in-memory ring buffer
+ * and an observable stream, without altering what reaches the real
+ * terminal. The original write always runs first and its result is
+ * returned unchanged — a failure in capture can never break the app's
+ * own output.
+ *
+ * Overhead with no subscribers is a string split + ring buffer push
+ * per write. Broadcasting cost only exists while clients are tailing.
+ */
+let ConsoleCaptureService = ConsoleCaptureService_1 = class ConsoleCaptureService {
+    constructor(config) {
+        this.logger = new common_1.Logger(ConsoleCaptureService_1.name);
+        this.lineSubject = new rxjs_1.Subject();
+        this.ringIndex = 0;
+        this.ringCount = 0;
+        this.seq = 0;
+        // Patch state
+        this.started = false;
+        this.capturing = false; // re-entrancy guard
+        this.carry = {
+            stdout: '',
+            stderr: '',
+        };
+        this.cfg = (0, livetail_interface_1.normalizeConsoleCaptureConfig)(config?.captureConsole);
+        this.ring = new Array(Math.max(this.cfg.bufferSize, 1));
+    }
+    onModuleInit() {
+        if (!this.cfg.enabled)
+            return;
+        this.start();
+        this.logger.log(`Console capture started (buffer: ${this.cfg.bufferSize} lines, batch: ${this.cfg.batchInterval}ms${this.cfg.token ? ', token-protected' : ''})`);
+    }
+    onModuleDestroy() {
+        this.stop();
+        this.lineSubject.complete();
+    }
+    /** Live stream of captured lines. */
+    get lines$() {
+        return this.lineSubject.asObservable();
+    }
+    get enabled() {
+        return this.cfg.enabled;
+    }
+    get options() {
+        return this.cfg;
+    }
+    /** Total lines captured since process start. */
+    get totalCaptured() {
+        return this.seq;
+    }
+    /**
+     * Recent lines from the ring buffer, oldest first.
+     * @param limit Return at most this many of the newest lines.
+     */
+    getHistory(limit) {
+        const size = this.ring.length;
+        const n = limit && limit > 0 ? Math.min(limit, this.ringCount) : this.ringCount;
+        const out = new Array(n);
+        for (let i = 0; i < n; i++) {
+            out[i] = this.ring[(this.ringIndex - n + i + 2 * size) % size];
+        }
+        return out;
+    }
+    clear() {
+        this.ringIndex = 0;
+        this.ringCount = 0;
+        this.ring.fill(undefined);
+    }
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.originalStdout = process.stdout.write.bind(process.stdout);
+        this.originalStderr = process.stderr.write.bind(process.stderr);
+        process.stdout.write = this.tee('stdout', this.originalStdout);
+        process.stderr.write = this.tee('stderr', this.originalStderr);
+    }
+    stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        if (this.originalStdout)
+            process.stdout.write = this.originalStdout;
+        if (this.originalStderr)
+            process.stderr.write = this.originalStderr;
+    }
+    tee(stream, original) {
+        return (chunk, encoding, cb) => {
+            const result = original(chunk, encoding, cb);
+            if (this.capturing)
+                return result;
+            this.capturing = true;
+            try {
+                const text = typeof chunk === 'string'
+                    ? chunk
+                    : Buffer.isBuffer(chunk)
+                        ? chunk.toString('utf8')
+                        : String(chunk);
+                this.ingest(stream, text);
+            }
+            catch {
+                // Capture must never throw into the app's write path.
+            }
+            finally {
+                this.capturing = false;
+            }
+            return result;
+        };
+    }
+    ingest(stream, text) {
+        const data = this.carry[stream] + text;
+        const parts = data.split('\n');
+        this.carry[stream] = parts.pop() ?? '';
+        // Force-flush a partial line that grows beyond the limit
+        if (this.carry[stream].length > this.cfg.maxLineLength) {
+            parts.push(this.carry[stream]);
+            this.carry[stream] = '';
+        }
+        const ts = new Date().toISOString();
+        for (const raw of parts) {
+            let line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+            if (line.length === 0)
+                continue;
+            if (this.cfg.stripAnsi)
+                line = line.replace(ANSI_RE, '');
+            if (line.length > this.cfg.maxLineLength) {
+                line = line.slice(0, this.cfg.maxLineLength) + ' …[truncated]';
+            }
+            const event = { seq: ++this.seq, stream, line, ts };
+            this.ring[this.ringIndex] = event;
+            this.ringIndex = (this.ringIndex + 1) % this.ring.length;
+            if (this.ringCount < this.ring.length)
+                this.ringCount++;
+            this.lineSubject.next(event);
+        }
+    }
+};
+exports.ConsoleCaptureService = ConsoleCaptureService;
+exports.ConsoleCaptureService = ConsoleCaptureService = ConsoleCaptureService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(livetail_interface_1.LIVETAIL_CONFIG)),
+    __metadata("design:paramtypes", [Object])
+], ConsoleCaptureService);

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { LiveTailModule } from './livetail.module';
+export { LiveTailService } from './livetail.service';
+export { LiveTailGateway } from './livetail.gateway';
+export { ConsoleCaptureService } from './console-capture.service';
+export { LiveTailConfig, LIVETAIL_CONFIG, LiveTailLogEvent, LiveTailFilter, LiveTailEnvContext, LogLevel, ConsoleCaptureConfig, ConsoleLineEvent, ConsoleStream, ConsoleSubscribePayload, } from './interfaces/livetail.interface';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIVETAIL_CONFIG = exports.ConsoleCaptureService = exports.LiveTailGateway = exports.LiveTailService = exports.LiveTailModule = void 0;
+// Module
+var livetail_module_1 = require("./livetail.module");
+Object.defineProperty(exports, "LiveTailModule", { enumerable: true, get: function () { return livetail_module_1.LiveTailModule; } });
+// Service (inject this to broadcast logs)
+var livetail_service_1 = require("./livetail.service");
+Object.defineProperty(exports, "LiveTailService", { enumerable: true, get: function () { return livetail_service_1.LiveTailService; } });
+// Gateway (auto-registered by the module)
+var livetail_gateway_1 = require("./livetail.gateway");
+Object.defineProperty(exports, "LiveTailGateway", { enumerable: true, get: function () { return livetail_gateway_1.LiveTailGateway; } });
+// Console capture (raw stdout/stderr streaming)
+var console_capture_service_1 = require("./console-capture.service");
+Object.defineProperty(exports, "ConsoleCaptureService", { enumerable: true, get: function () { return console_capture_service_1.ConsoleCaptureService; } });
+// Interfaces & types
+var livetail_interface_1 = require("./interfaces/livetail.interface");
+Object.defineProperty(exports, "LIVETAIL_CONFIG", { enumerable: true, get: function () { return livetail_interface_1.LIVETAIL_CONFIG; } });

package/dist/interfaces/livetail.interface.d.ts

@@ -0,0 +1,156 @@
+export declare const LIVETAIL_CONFIG: unique symbol;
+export interface LiveTailConfig {
+    /**
+     * WebSocket namespace (default: '/live-tail')
+     */
+    namespace?: string;
+    /**
+     * CORS origin for WebSocket connections (default: '*')
+     */
+    cors?: string | string[] | boolean;
+    /**
+     * Max connected clients (0 = unlimited, default: 0).
+     * New connections are rejected when the limit is reached.
+     */
+    maxClients?: number;
+    /**
+     * Ping interval in ms (default: 25000)
+     */
+    pingInterval?: number;
+    /**
+     * Ping timeout in ms (default: 20000)
+     */
+    pingTimeout?: number;
+    /**
+     * Disable the live tail gateway entirely (default: false).
+     * Useful for environments where real-time streaming is not needed.
+     */
+    disabled?: boolean;
+    /**
+     * Capture the process stdout/stderr and stream it to subscribed
+     * clients — like `docker logs -f` for this application.
+     *
+     * Pass `true` for defaults, or an object for fine-grained control.
+     * Disabled by default.
+     */
+    captureConsole?: boolean | ConsoleCaptureConfig;
+}
+export interface ConsoleCaptureConfig {
+    /**
+     * Enable console capture (default: true when this object is provided).
+     */
+    enabled?: boolean;
+    /**
+     * Number of recent lines kept in the in-memory ring buffer and
+     * replayed to clients on subscribe (default: 2000).
+     */
+    bufferSize?: number;
+    /**
+     * Lines longer than this are truncated (default: 8192 chars).
+     */
+    maxLineLength?: number;
+    /**
+     * Lines are batched and flushed to clients on this interval in ms
+     * (default: 150). Keeps overhead low under heavy log volume.
+     */
+    batchInterval?: number;
+    /**
+     * Optional shared secret. When set, clients must send the same
+     * token in the `subscribe-console` payload or they are rejected.
+     * Strongly recommended in production — raw console output can
+     * contain secrets.
+     */
+    token?: string;
+    /**
+     * Strip ANSI escape codes before buffering/streaming
+     * (default: false — colors are kept and rendered by the dashboard).
+     */
+    stripAnsi?: boolean;
+}
+export type ConsoleStream = 'stdout' | 'stderr';
+/**
+ * A single captured console line.
+ */
+export interface ConsoleLineEvent {
+    /** Monotonic sequence number (per process lifetime). */
+    seq: number;
+    stream: ConsoleStream;
+    /** Raw line content. May contain ANSI color codes unless `stripAnsi` is set. */
+    line: string;
+    /** ISO 8601 capture timestamp. */
+    ts: string;
+}
+/**
+ * Payload a client sends with the `subscribe-console` message.
+ */
+export interface ConsoleSubscribePayload {
+    /** Required when the server is configured with a console token. */
+    token?: string;
+    /** Replay at most this many recent lines (default: full buffer). */
+    tail?: number;
+}
+export declare function normalizeConsoleCaptureConfig(input?: boolean | ConsoleCaptureConfig): Required<ConsoleCaptureConfig>;
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export interface LiveTailLogEvent {
+    id?: string;
+    environmentId: string;
+    level: LogLevel;
+    category: string;
+    action: string;
+    message?: string;
+    metadata?: any;
+    userId?: string;
+    duration?: number;
+    tags?: string[];
+    createdAt: string;
+    /**
+     * NestJS-style context label (e.g. 'AppController', 'AuthGuard').
+     * Falls back to `category` when not provided.
+     */
+    context?: string;
+    /**
+     * Process ID from the source application.
+     */
+    pid?: number;
+    /**
+     * HTTP request method (e.g. 'GET', 'POST', 'PUT', 'DELETE').
+     */
+    method?: string;
+    /**
+     * HTTP request path (e.g. '/api/users', '/auth/login').
+     */
+    path?: string;
+    /**
+     * HTTP response status code (e.g. 200, 404, 500).
+     */
+    statusCode?: number;
+    orgId?: string;
+    orgName?: string;
+    appId?: string;
+    appName?: string;
+    envName?: string;
+}
+export interface LiveTailFilter {
+    environmentId?: string;
+    appId?: string;
+    orgId?: string;
+    level?: LogLevel | LogLevel[];
+    category?: string;
+    action?: string;
+    userId?: string;
+    search?: string;
+    tags?: string[];
+}
+/**
+ * Context from the authenticated environment.
+ * Pass this to broadcastMany/broadcast to enrich log events
+ * with organization, application, and environment names.
+ */
+export interface LiveTailEnvContext {
+    environmentId: string;
+    envName?: string;
+    appId?: string;
+    appName?: string;
+    orgId?: string;
+    orgName?: string;
+}

package/dist/interfaces/livetail.interface.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIVETAIL_CONFIG = void 0;
+exports.normalizeConsoleCaptureConfig = normalizeConsoleCaptureConfig;
+exports.LIVETAIL_CONFIG = Symbol('LIVETAIL_CONFIG');
+const CONSOLE_CAPTURE_DEFAULTS = {
+    enabled: false,
+    bufferSize: 2000,
+    maxLineLength: 8192,
+    batchInterval: 150,
+    token: '',
+    stripAnsi: false,
+};
+function normalizeConsoleCaptureConfig(input) {
+    if (input === true)
+        return { ...CONSOLE_CAPTURE_DEFAULTS, enabled: true };
+    if (!input)
+        return { ...CONSOLE_CAPTURE_DEFAULTS };
+    return {
+        ...CONSOLE_CAPTURE_DEFAULTS,
+        ...input,
+        enabled: input.enabled !== false,
+    };
+}

package/dist/livetail.gateway.d.ts

@@ -0,0 +1,59 @@
+import { OnModuleInit } from '@nestjs/common';
+import { OnGatewayConnection, OnGatewayDisconnect } from '@nestjs/websockets';
+import { Server, Socket } from 'socket.io';
+import { LiveTailService } from './livetail.service';
+import { ConsoleCaptureService } from './console-capture.service';
+import { ConsoleSubscribePayload, LiveTailConfig, LiveTailFilter } from './interfaces/livetail.interface';
+export declare class LiveTailGateway implements OnModuleInit, OnGatewayConnection, OnGatewayDisconnect {
+    private readonly liveTailService;
+    private readonly config;
+    private readonly consoleCapture?;
+    private readonly logger;
+    private readonly clients;
+    private subscription;
+    private consoleSubscription;
+    private readonly consoleSubscribers;
+    private consolePending;
+    private consoleDropped;
+    private consoleFlushTimer;
+    server: Server;
+    constructor(liveTailService: LiveTailService, config: LiveTailConfig, consoleCapture?: ConsoleCaptureService);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    handleConnection(client: Socket): void;
+    handleDisconnect(client: Socket): void;
+    /**
+     * Client subscribes with filters.
+     * Example payload:
+     * { environmentId: "xxx", level: ["error", "fatal"], category: "auth" }
+     */
+    handleSubscribe(client: Socket, filter: LiveTailFilter): void;
+    /**
+     * Client updates filters without disconnecting.
+     */
+    handleUpdateFilter(client: Socket, filter: LiveTailFilter): void;
+    /**
+     * Client pauses the stream (still connected but no logs sent).
+     */
+    handlePause(client: Socket): void;
+    /**
+     * Client resumes the stream.
+     */
+    handleResume(client: Socket): void;
+    /**
+     * Client subscribes to the raw stdout/stderr stream.
+     * Replays the ring buffer (chunked), then streams live lines
+     * batched on `console-lines` events.
+     *
+     * Payload: { token?: string, tail?: number }
+     */
+    handleSubscribeConsole(client: Socket, payload?: ConsoleSubscribePayload): void;
+    handleUnsubscribeConsole(client: Socket): void;
+    private queueConsoleLine;
+    private flushConsolePending;
+    private startConsoleFlusher;
+    private stopConsoleFlusher;
+    private stopConsoleFlusherIfIdle;
+    private broadcastToClients;
+    private matchesFilter;
+}