@devms/livetail 0.0.2

package/README.md

@@ -0,0 +1,511 @@
+# @devms/livetail
+
+NestJS WebSocket module for **real-time log streaming**. Drop it into any NestJS application to broadcast structured logs to connected clients via Socket.IO — like `tail -f` for your application logs.
+
+---
+
+## Installation
+
+```bash
+pnpm add @devms/livetail
+# or
+npm install @devms/livetail
+```
+
+**Peer dependencies** (install if not already present):
+
+```bash
+pnpm add @nestjs/websockets @nestjs/platform-socket.io
+```
+
+---
+
+## Quick Start
+
+### 1. Register the module
+
+```typescript
+// app.module.ts
+import { LiveTailModule } from '@devms/livetail';
+
+@Module({
+  imports: [
+    LiveTailModule.register(),
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Broadcast logs from your service
+
+```typescript
+import { LiveTailService } from '@devms/livetail';
+
+@Injectable()
+export class LogIngestionService {
+  constructor(private readonly liveTail: LiveTailService) {}
+
+  async ingestLog(log: CreateLogDto) {
+    // Save to database
+    await this.db.logs.create({ data: log });
+
+    // Broadcast to live tail clients
+    this.liveTail.broadcast({
+      environmentId: log.environmentId,
+      level: log.level,
+      category: log.category,
+      action: log.action,
+      message: log.message,
+      metadata: log.metadata,
+      userId: log.userId,
+      duration: log.duration,
+      tags: log.tags,
+      createdAt: new Date().toISOString(),
+    });
+  }
+}
+```
+
+### 3. Connect from the browser
+
+```typescript
+import { io } from 'socket.io-client';
+
+const socket = io('http://localhost:3000/live-tail');
+
+socket.on('connected', ({ clientId }) => {
+  console.log('Connected:', clientId);
+
+  // Subscribe with filters
+  socket.emit('subscribe', {
+    environmentId: 'env-abc-123',
+    level: ['error', 'fatal'],
+  });
+});
+
+socket.on('log', (log) => {
+  console.log(`[${log.level}] ${log.category}/${log.action}: ${log.message}`);
+});
+```
+
+---
+
+## Configuration
+
+### Static config
+
+```typescript
+LiveTailModule.register({
+  namespace: '/live-tail',     // WebSocket namespace (default: '/live-tail')
+  cors: '*',                   // CORS origin (default: '*')
+  maxClients: 100,             // Max simultaneous connections, 0 = unlimited (default: 0)
+  pingInterval: 25000,         // Ping interval in ms (default: 25000)
+  pingTimeout: 20000,          // Ping timeout in ms (default: 20000)
+  disabled: false,             // Disable the gateway entirely (default: false)
+})
+```
+
+### Async config (with ConfigService)
+
+```typescript
+LiveTailModule.registerAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    cors: config.get('LIVETAIL_CORS_ORIGIN', '*'),
+    maxClients: parseInt(config.get('LIVETAIL_MAX_CLIENTS', '0')),
+    disabled: config.get('LIVETAIL_DISABLED') === 'true',
+  }),
+})
+```
+
+### Environment-specific usage
+
+Disable live tail in environments where it's not needed:
+
+```typescript
+LiveTailModule.register({
+  disabled: process.env.NODE_ENV === 'test',
+})
+```
+
+### Configuration options
+
+| Option         | Type                          | Default        | Description                                                    |
+|----------------|-------------------------------|----------------|----------------------------------------------------------------|
+| `namespace`    | `string`                      | `'/live-tail'` | WebSocket namespace path                                       |
+| `cors`         | `string \| string[] \| bool`  | `'*'`          | CORS origin for WebSocket connections                          |
+| `maxClients`   | `number`                      | `0`            | Max simultaneous clients (0 = unlimited)                       |
+| `pingInterval` | `number`                      | `25000`        | Socket.IO ping interval in ms                                  |
+| `pingTimeout`  | `number`                      | `20000`        | Socket.IO ping timeout in ms                                   |
+| `disabled`     | `boolean`                     | `false`        | Disable the gateway (service still injectable but no-ops)      |
+
+---
+
+## Environment Context (Enrichment)
+
+When broadcasting logs, you can pass an environment context to enrich each log event with organization, application, and environment names. This allows the UI to display human-readable labels without additional API calls.
+
+```typescript
+import { LiveTailService, LiveTailEnvContext } from '@devms/livetail';
+
+@Injectable()
+export class AppLogService {
+  constructor(private readonly liveTail: LiveTailService) {}
+
+  async ingestLogs(envId: string, logs: LogDto[], ctx: LiveTailEnvContext) {
+    await this.db.appLog.createMany({ data: logs });
+
+    // Broadcast with enriched context
+    this.liveTail.broadcastMany(
+      logs.map((log) => ({
+        environmentId: envId,
+        level: log.level,
+        category: log.category,
+        action: log.action,
+        message: log.message,
+        createdAt: new Date().toISOString(),
+      })),
+      ctx, // <-- enriches each log with orgName, appName, envName, etc.
+    );
+  }
+}
+```
+
+### LiveTailEnvContext
+
+```typescript
+interface LiveTailEnvContext {
+  environmentId: string;
+  envName?: string;
+  appId?: string;
+  appName?: string;
+  orgId?: string;
+  orgName?: string;
+}
+```
+
+---
+
+## WebSocket Protocol
+
+### Endpoint
+
+```
+ws://<host>:<port>/live-tail
+```
+
+### Client events (send to server)
+
+| Event          | Payload          | Description                                        |
+|----------------|------------------|----------------------------------------------------|
+| `subscribe`    | `LiveTailFilter` | Start receiving logs matching the given filter      |
+| `updateFilter` | `LiveTailFilter` | Update filters without reconnecting                |
+| `pause`        | —                | Pause the stream (stay connected, no logs sent)    |
+| `resume`       | —                | Resume receiving logs                              |
+
+### Server events (receive from server)
+
+| Event           | Payload                                        | Description                      |
+|-----------------|------------------------------------------------|----------------------------------|
+| `connected`     | `{ clientId, message, connectedClients }`      | Connection confirmed             |
+| `subscribed`    | `{ filter }`                                   | Subscription confirmed           |
+| `filterUpdated` | `{ filter }`                                   | Filter update confirmed          |
+| `paused`        | —                                              | Stream paused                    |
+| `resumed`       | —                                              | Stream resumed                   |
+| `log`           | `LiveTailLogEvent`                             | A log entry matching your filter |
+| `error`         | `{ message }`                                  | Connection error (e.g. max clients reached) |
+
+### LiveTailFilter
+
+All fields are optional. Omit a field to accept all values for that dimension.
+
+```typescript
+interface LiveTailFilter {
+  environmentId?: string;              // Filter by specific environment
+  appId?: string;                      // Filter by application
+  orgId?: string;                      // Filter by organization
+  level?: LogLevel | LogLevel[];       // 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+  category?: string;                   // Exact match on category
+  action?: string;                     // Contains match (case-insensitive)
+  userId?: string;                     // Exact match on userId
+  search?: string;                     // Full-text search in message, action, category
+  tags?: string[];                     // Log must have at least one matching tag
+}
+```
+
+### LiveTailLogEvent
+
+```typescript
+interface LiveTailLogEvent {
+  id?: string;
+  environmentId: string;
+  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  category: string;
+  action: string;
+  message?: string;
+  metadata?: any;
+  userId?: string;
+  duration?: number;          // milliseconds
+  tags?: string[];
+  createdAt: string;          // ISO 8601
+
+  // Enriched fields (from environment context)
+  orgId?: string;
+  orgName?: string;
+  appId?: string;
+  appName?: string;
+  envName?: string;
+}
+```
+
+---
+
+## Integration Examples
+
+### NestJS (Monitoring API)
+
+```typescript
+// app.module.ts
+import { LiveTailModule } from '@devms/livetail';
+
+@Module({
+  imports: [
+    LiveTailModule.register({
+      cors: ['https://dashboard.example.com'],
+      maxClients: 200,
+    }),
+  ],
+})
+export class AppModule {}
+
+// app-log.controller.ts
+@Post('ingest')
+@UseGuards(ClientCredentialsGuard)
+async ingest(@Body() dto: IngestDto, @EnvContext() ctx: EnvironmentContext) {
+  return this.appLogService.ingestLogs(ctx.environment.id, dto.logs, {
+    environmentId: ctx.environment.id,
+    envName: ctx.environment.name,
+    appId: ctx.application.id,
+    appName: ctx.application.name,
+    orgId: ctx.organization.id,
+    orgName: ctx.organization.name,
+  });
+}
+
+// app-log.service.ts
+import { LiveTailService, LiveTailEnvContext } from '@devms/livetail';
+
+@Injectable()
+export class AppLogService {
+  constructor(
+    private readonly prisma: PrismaService,
+    @Optional() private readonly liveTail?: LiveTailService,
+  ) {}
+
+  async ingestLogs(envId: string, logs: AppLogDto[], ctx?: LiveTailEnvContext) {
+    const result = await this.prisma.appLog.createMany({ data: logs });
+
+    this.liveTail?.broadcastMany(
+      logs.map((log) => ({
+        environmentId: envId,
+        level: log.level as any,
+        category: log.category,
+        action: log.action,
+        message: log.message,
+        metadata: log.metadata,
+        userId: log.userId,
+        duration: log.duration,
+        tags: log.tags ?? [],
+        createdAt: new Date().toISOString(),
+      })),
+      ctx,
+    );
+
+    return { ingested: result.count };
+  }
+}
+```
+
+### React / Next.js (Browser Client)
+
+```typescript
+import { useEffect, useRef, useState } from 'react';
+import { io, Socket } from 'socket.io-client';
+
+function useLiveTail(apiUrl: string) {
+  const [logs, setLogs] = useState([]);
+  const [status, setStatus] = useState('disconnected');
+  const socketRef = useRef<Socket | null>(null);
+
+  const connect = (filter = {}) => {
+    const socket = io(`${apiUrl}/live-tail`, {
+      transports: ['websocket', 'polling'],
+    });
+
+    socket.on('connect', () => {
+      setStatus('connected');
+      socket.emit('subscribe', filter);
+    });
+
+    socket.on('disconnect', () => setStatus('disconnected'));
+
+    socket.on('log', (log) => {
+      setLogs((prev) => [log, ...prev].slice(0, 500));
+    });
+
+    socketRef.current = socket;
+  };
+
+  const disconnect = () => {
+    socketRef.current?.disconnect();
+    setStatus('disconnected');
+  };
+
+  useEffect(() => () => { socketRef.current?.disconnect(); }, []);
+
+  return { logs, status, connect, disconnect };
+}
+```
+
+### Python (WebSocket Client)
+
+```python
+import socketio
+
+sio = socketio.Client()
+
+@sio.on('connected', namespace='/live-tail')
+def on_connect(data):
+    print(f"Connected: {data['clientId']}")
+    sio.emit('subscribe', {
+        'environmentId': 'env-abc-123',
+        'level': ['error', 'fatal'],
+    }, namespace='/live-tail')
+
+@sio.on('log', namespace='/live-tail')
+def on_log(data):
+    print(f"[{data['level']}] {data['category']}/{data['action']}: {data.get('message', '')}")
+
+sio.connect('http://localhost:5002', namespaces=['/live-tail'])
+sio.wait()
+```
+
+### cURL (WebSocket test with wscat)
+
+```bash
+# Install wscat
+npm install -g wscat
+
+# Connect (note: Socket.IO uses its own protocol, wscat is for raw WS)
+# For Socket.IO, use a proper client. For testing, use the browser console:
+# const socket = io('http://localhost:5002/live-tail');
+# socket.on('log', console.log);
+# socket.emit('subscribe', { level: ['error'] });
+```
+
+---
+
+## Console Capture (raw stdout/stderr streaming)
+
+Stream the **raw terminal output** of your application — everything the
+process writes to stdout/stderr (NestJS `Logger`, `console.log`, crash stack
+traces, third-party output, ANSI colors included) — like `docker logs -f`,
+but over the same `/live-tail` socket. Nothing is persisted; lines are held
+in an in-memory ring buffer and replayed to clients on subscribe.
+
+### Enable it
+
+```typescript
+// app.module.ts
+LiveTailModule.register({
+  captureConsole: true, // defaults: 2000-line buffer, 150ms batching
+})
+```
+
+Or with options:
+
+```typescript
+LiveTailModule.register({
+  captureConsole: {
+    bufferSize: 2000,      // lines kept in memory & replayed on subscribe
+    maxLineLength: 8192,   // longer lines are truncated
+    batchInterval: 150,    // ms between batched pushes to clients
+    token: process.env.LIVETAIL_CONSOLE_TOKEN, // require a shared secret
+    stripAnsi: false,      // keep colors (dashboard renders them)
+  },
+})
+```
+
+That's it — no logger changes needed. The module tees `process.stdout` /
+`process.stderr`; your terminal/PM2/Docker output is untouched.
+
+### Client protocol
+
+```typescript
+const socket = io('http://localhost:5002/live-tail');
+
+// Subscribe (replays the buffer, then streams live)
+socket.emit('subscribe-console', { token: '...', tail: 1000 });
+
+socket.on('console-subscribed', ({ pid, bufferSize, historyCount }) => {});
+socket.on('console-history', ({ lines, done }) => {});      // chunked replay
+socket.on('console-lines', ({ lines, dropped }) => {});      // live batches
+socket.on('console-error', ({ code, message }) => {});       // disabled / bad token
+
+socket.emit('unsubscribe-console');
+```
+
+Each line: `{ seq: number, stream: 'stdout' | 'stderr', line: string, ts: string }`.
+
+### Performance & safety
+
+- **Zero subscribers → near-zero cost.** Lines only go to the ring buffer;
+  nothing is broadcast.
+- **Batched delivery.** Live lines are flushed every `batchInterval` ms as a
+  single frame, and the pending queue is hard-capped (oldest dropped, with a
+  `dropped` count reported) so a slow consumer can never grow memory.
+- **Crash-safe tee.** The original write always executes first; any error in
+  capture is swallowed and can never break the app's own output.
+- **Security.** Raw console output can contain secrets (connection strings,
+  error dumps). Set `token` in production and restrict `cors`.
+
+---
+
+## Environment Variables
+
+| Variable                 | Description                                | Default |
+|--------------------------|--------------------------------------------|---------|
+| `LIVETAIL_CORS_ORIGIN`   | Allowed CORS origins (comma-separated)    | `*`     |
+| `LIVETAIL_MAX_CLIENTS`   | Max simultaneous WebSocket connections     | `0`     |
+| `LIVETAIL_DISABLED`      | Set to `true` to disable the gateway      | `false` |
+
+---
+
+## Architecture
+
+```
+┌──────────────┐     HTTP POST      ┌──────────────┐     save      ┌──────────────┐
+│  Client App  │ ──────────────────▶│   NestJS API │ ────────────▶│  PostgreSQL  │
+│  (any lang)  │   /app-logs/ingest │              │              │              │
+└──────────────┘                    │  AppLogSvc   │              └──────────────┘
+                                    │      │       │
+                                    │      ▼       │
+                                    │ LiveTailSvc  │
+                                    │  broadcast() │
+                                    │      │       │
+                                    │      ▼       │
+                                    │ LiveTailGW   │   WebSocket
+                                    │ (Socket.IO)  │ ◀──────────── Browser / CLI
+                                    └──────────────┘   /live-tail
+```
+
+1. **Client apps** send logs via HTTP to the API (using `@devms/applog-client` or raw HTTP)
+2. **API** saves logs to the database, then calls `liveTailService.broadcast()`
+3. **LiveTailGateway** pushes matching logs to connected WebSocket clients in real-time
+4. **Browser/CLI** connects to `/live-tail` namespace, subscribes with filters, receives logs instantly
+
+---
+
+## License
+
+MIT

package/dist/console-capture.service.d.ts

@@ -0,0 +1,46 @@
+import { OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { ConsoleCaptureConfig, ConsoleLineEvent, LiveTailConfig } from './interfaces/livetail.interface';
+/**
+ * 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.
+ */
+export declare class ConsoleCaptureService implements OnModuleInit, OnModuleDestroy {
+    private readonly logger;
+    private readonly cfg;
+    private readonly lineSubject;
+    private readonly ring;
+    private ringIndex;
+    private ringCount;
+    private seq;
+    private started;
+    private capturing;
+    private originalStdout?;
+    private originalStderr?;
+    private readonly carry;
+    constructor(config?: LiveTailConfig);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    /** Live stream of captured lines. */
+    get lines$(): Observable<ConsoleLineEvent>;
+    get enabled(): boolean;
+    get options(): Readonly<Required<ConsoleCaptureConfig>>;
+    /** Total lines captured since process start. */
+    get totalCaptured(): number;
+    /**
+     * Recent lines from the ring buffer, oldest first.
+     * @param limit Return at most this many of the newest lines.
+     */
+    getHistory(limit?: number): ConsoleLineEvent[];
+    clear(): void;
+    start(): void;
+    stop(): void;
+    private tee;
+    private ingest;
+}