@engjts/nexus 0.1.0

package/src/advanced/observability/StructuredLogger.ts

@@ -0,0 +1,154 @@
+import { LogEntry, LoggingOptions } from './types';
+
+/**
+ * Structured logger with masking support
+ */
+export class StructuredLogger {
+    private logs: LogEntry[] = [];
+    private options: LoggingOptions;
+    private maxLogs: number = 10000;
+    private levelPriority = { debug: 0, info: 1, warn: 2, error: 3 };
+
+    constructor(options: LoggingOptions = {}) {
+        this.options = options;
+    }
+
+    private shouldLog(level: LogEntry['level']): boolean {
+        const configuredLevel = this.options.level ?? 'info';
+        return this.levelPriority[level] >= this.levelPriority[configuredLevel];
+    }
+
+    private maskSensitiveData(obj: any): any {
+        if (!this.options.mask || typeof obj !== 'object' || obj === null) {
+            return obj;
+        }
+
+        const result = Array.isArray(obj) ? [...obj] : { ...obj };
+        const replacement = this.options.mask.replacement ?? '***REDACTED***';
+
+        for (const key of Object.keys(result)) {
+            // Check field names
+            if (this.options.mask.fields?.some(f => key.toLowerCase().includes(f.toLowerCase()))) {
+                result[key] = replacement;
+                continue;
+            }
+
+            // Check patterns on string values
+            if (typeof result[key] === 'string' && this.options.mask.patterns) {
+                for (const pattern of this.options.mask.patterns) {
+                    if (pattern.test(result[key])) {
+                        result[key] = replacement;
+                        break;
+                    }
+                }
+            }
+
+            // Recurse for nested objects
+            if (typeof result[key] === 'object' && result[key] !== null) {
+                result[key] = this.maskSensitiveData(result[key]);
+            }
+        }
+
+        return result;
+    }
+
+    private formatEntry(entry: LogEntry): string {
+        const masked = this.maskSensitiveData(entry);
+        if (this.options.format === 'json') {
+            return JSON.stringify(masked);
+        }
+
+        // Pretty format
+        const timestamp = new Date(masked.timestamp).toISOString();
+        const level = masked.level.toUpperCase().padEnd(5);
+        const correlationId = masked.correlationId ? `[${masked.correlationId}]` : '';
+        let msg = `${timestamp} ${level} ${correlationId} ${masked.message}`;
+        if (masked.context) {
+            msg += ` ${JSON.stringify(masked.context)}`;
+        }
+        if (masked.error) {
+            msg += `\n  Error: ${masked.error.message}`;
+            if (masked.error.stack) {
+                msg += `\n  ${masked.error.stack}`;
+            }
+        }
+        return msg;
+    }
+
+    log(level: LogEntry['level'], message: string, context?: Record<string, any>, correlationId?: string) {
+        if (!this.shouldLog(level)) return;
+
+        const entry: LogEntry = {
+            level,
+            message,
+            timestamp: Date.now(),
+            correlationId,
+            context
+        };
+
+        if (this.logs.length >= this.maxLogs) {
+            this.logs.shift();
+        }
+        this.logs.push(entry);
+
+        // Output to console
+        const formatted = this.formatEntry(entry);
+        switch (level) {
+            case 'error':
+                console.error(formatted);
+                break;
+            case 'warn':
+                console.warn(formatted);
+                break;
+            case 'debug':
+                console.debug(formatted);
+                break;
+            default:
+                console.log(formatted);
+        }
+    }
+
+    debug(message: string, context?: Record<string, any>, correlationId?: string) {
+        this.log('debug', message, context, correlationId);
+    }
+
+    info(message: string, context?: Record<string, any>, correlationId?: string) {
+        this.log('info', message, context, correlationId);
+    }
+
+    warn(message: string, context?: Record<string, any>, correlationId?: string) {
+        this.log('warn', message, context, correlationId);
+    }
+
+    error(message: string, error?: Error, context?: Record<string, any>, correlationId?: string) {
+        const entry: LogEntry = {
+            level: 'error',
+            message,
+            timestamp: Date.now(),
+            correlationId,
+            context,
+            error: error ? { message: error.message, stack: error.stack } : undefined
+        };
+
+        if (this.logs.length >= this.maxLogs) {
+            this.logs.shift();
+        }
+        this.logs.push(entry);
+
+        console.error(this.formatEntry(entry));
+    }
+
+    getLogs(filter?: { level?: LogEntry['level']; since?: number; limit?: number; }): LogEntry[] {
+        let result = this.logs;
+        if (filter?.level) {
+            result = result.filter(l => l.level === filter.level);
+        }
+        if (filter?.since) {
+            result = result.filter(l => l.timestamp >= filter.since!);
+        }
+        if (filter?.limit) {
+            result = result.slice(-filter.limit);
+        }
+        return result;
+    }
+}

package/src/advanced/observability/TracingManager.ts

@@ -0,0 +1,117 @@
+import { randomUUID } from 'crypto';
+import { performance } from 'perf_hooks';
+import { Span, TracingOptions } from './types';
+
+/**
+ * Distributed tracing manager
+ */
+export class TracingManager {
+    private spans: Span[] = [];
+    private activeSpans: Map<string, Span> = new Map();
+    private options: TracingOptions;
+    private maxSpans: number = 10000;
+
+    constructor(options: TracingOptions) {
+        this.options = options;
+    }
+
+    shouldSample(path: string): boolean {
+        if (this.options.alwaysTrace?.some(p => path.startsWith(p) || new RegExp(p).test(path))) {
+            return true;
+        }
+        return Math.random() < (this.options.sampleRate ?? 1);
+    }
+
+    startSpan(name: string, parentSpanId?: string, traceId?: string): Span {
+        const span: Span = {
+            traceId: traceId || randomUUID(),
+            spanId: randomUUID(),
+            parentSpanId,
+            name,
+            startTime: performance.now(),
+            status: 'unset',
+            attributes: {},
+            events: []
+        };
+        this.activeSpans.set(span.spanId, span);
+        return span;
+    }
+
+    endSpan(spanId: string, status: 'ok' | 'error' = 'ok', error?: Error) {
+        const span = this.activeSpans.get(spanId);
+        if (!span) return;
+
+        span.endTime = performance.now();
+        span.duration = span.endTime - span.startTime;
+        span.status = status;
+
+        if (error) {
+            span.attributes['error.message'] = error.message;
+            span.attributes['error.stack'] = error.stack;
+        }
+
+        this.activeSpans.delete(spanId);
+
+        // Limit stored spans
+        if (this.spans.length >= this.maxSpans) {
+            this.spans.shift();
+        }
+        this.spans.push(span);
+
+        // Export if configured
+        this.exportSpan(span);
+    }
+
+    addEvent(spanId: string, name: string, attributes?: Record<string, any>) {
+        const span = this.activeSpans.get(spanId);
+        if (span) {
+            span.events.push({ name, timestamp: performance.now(), attributes });
+        }
+    }
+
+    setAttributes(spanId: string, attributes: Record<string, any>) {
+        const span = this.activeSpans.get(spanId);
+        if (span) {
+            Object.assign(span.attributes, attributes);
+        }
+    }
+
+    getSpans(): Span[] {
+        return [...this.spans];
+    }
+
+    getActiveSpans(): Span[] {
+        return Array.from(this.activeSpans.values());
+    }
+
+    private exportSpan(span: Span) {
+        if (this.options.exporter === 'console') {
+            console.log('[TRACE]', JSON.stringify(span, null, 2));
+        }
+        // Other exporters would send to external services
+    }
+
+    /**
+     * Extract trace context from incoming headers (W3C Trace Context)
+     */
+    extractContext(headers: Record<string, string | string[] | undefined>): { traceId?: string; parentSpanId?: string; } {
+        const traceparent = headers['traceparent'];
+        if (!traceparent) return {};
+
+        const value = Array.isArray(traceparent) ? traceparent[0] : traceparent;
+        const parts = value.split('-');
+        if (parts.length >= 3) {
+            return { traceId: parts[1], parentSpanId: parts[2] };
+        }
+        return {};
+    }
+
+    /**
+     * Inject trace context into outgoing headers
+     */
+    injectContext(span: Span): Record<string, string> {
+        return {
+            traceparent: `00-${span.traceId}-${span.spanId}-01`
+        };
+    }
+}

package/src/advanced/observability/adapters.ts

@@ -0,0 +1,304 @@
+/**
+ * Alert Channel Adapters
+ * 
+ * Extensible adapter system for alert notification channels
+ */
+
+export interface AlertDefinition {
+  name: string;
+  condition: string;
+  window: string;
+  channels: string[];
+  threshold?: number;
+}
+
+/**
+ * Alert channel adapter interface
+ * Implement this to add custom notification channels
+ */
+export interface AlertChannelAdapter {
+  /**
+   * Send alert notification through the channel
+   * @param alert - Alert definition
+   * @param value - Current metric value
+   * @param config - Channel-specific configuration
+   */
+  send(alert: AlertDefinition, value: any, config: any): Promise<void>;
+
+  /**
+   * Validate channel configuration
+   * @returns true if config is valid
+   */
+  validate(config: any): boolean;
+}
+
+/**
+ * Slack alert adapter
+ */
+export class SlackAlertAdapter implements AlertChannelAdapter {
+  async send(alert: AlertDefinition, value: any, config: { webhookUrl: string }): Promise<void> {
+    if (!config.webhookUrl) {
+      throw new Error('Slack webhook URL is required');
+    }
+
+    const response = await fetch(config.webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        text: `🚨 Alert: ${alert.name}`,
+        blocks: [
+          {
+            type: 'section',
+            text: {
+              type: 'mrkdwn',
+              text: `*Alert:* ${alert.name}\n*Condition:* ${alert.condition}\n*Current Value:* ${value}`
+            }
+          }
+        ]
+      })
+    });
+
+    if (!response.ok) {
+      throw new Error(`Slack alert failed: ${response.statusText}`);
+    }
+  }
+
+  validate(config: { webhookUrl?: string }): boolean {
+    return !!(config.webhookUrl && typeof config.webhookUrl === 'string' && config.webhookUrl.startsWith('https://'));
+  }
+}
+
+/**
+ * Webhook alert adapter (generic HTTP endpoint)
+ */
+export class WebhookAlertAdapter implements AlertChannelAdapter {
+  async send(alert: AlertDefinition, value: any, config: { url: string }): Promise<void> {
+    if (!config.url) {
+      throw new Error('Webhook URL is required');
+    }
+
+    const response = await fetch(config.url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        alert: alert.name,
+        condition: alert.condition,
+        value,
+        timestamp: Date.now()
+      })
+    });
+
+    if (!response.ok) {
+      throw new Error(`Webhook alert failed: ${response.statusText}`);
+    }
+  }
+
+  validate(config: { url?: string }): boolean {
+    try {
+      if (!config.url) return false;
+      new URL(config.url);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Email alert adapter (console fallback - implement with real email service)
+ */
+export class EmailAlertAdapter implements AlertChannelAdapter {
+  async send(alert: AlertDefinition, value: any, config: { recipients: string[] }): Promise<void> {
+    if (!config.recipients || config.recipients.length === 0) {
+      throw new Error('Email recipients are required');
+    }
+
+    // TODO: Integrate with real email service (SendGrid, Mailgun, etc.)
+    console.log(`[EMAIL ALERT] To: ${config.recipients.join(', ')}`);
+    console.log(`[EMAIL ALERT] Subject: Alert: ${alert.name}`);
+    console.log(`[EMAIL ALERT] Body: ${alert.name} - Current Value: ${value}`);
+  }
+
+  validate(config: { recipients?: string[] }): boolean {
+    return !!(
+      config.recipients &&
+      Array.isArray(config.recipients) &&
+      config.recipients.length > 0 &&
+      config.recipients.every(r => typeof r === 'string' && r.includes('@'))
+    );
+  }
+}
+
+/**
+ * PagerDuty alert adapter
+ */
+export class PagerDutyAlertAdapter implements AlertChannelAdapter {
+  async send(alert: AlertDefinition, value: any, config: { routingKey: string }): Promise<void> {
+    if (!config.routingKey) {
+      throw new Error('PagerDuty routing key is required');
+    }
+
+    // TODO: Implement real PagerDuty Events API v2 integration
+    console.log(`[PAGERDUTY ALERT] Routing Key: ${config.routingKey}`);
+    console.log(`[PAGERDUTY ALERT] Event: ${alert.name} - Value: ${value}`);
+  }
+
+  validate(config: { routingKey?: string }): boolean {
+    return !!(config.routingKey && typeof config.routingKey === 'string' && config.routingKey.length > 0);
+  }
+}
+
+/**
+ * Telegram alert adapter
+ */
+export class TelegramAlertAdapter implements AlertChannelAdapter {
+  async send(alert: AlertDefinition, value: any, config: { botToken: string; chatId: string }): Promise<void> {
+    if (!config.botToken || !config.chatId) {
+      throw new Error('Telegram bot token and chat ID are required');
+    }
+
+    const message = `🚨 *Alert: ${alert.name}*\n\nCondition: ${alert.condition}\nCurrent Value: ${value}\nTime: ${new Date().toISOString()}`;
+
+    const response = await fetch(`https://api.telegram.org/bot${config.botToken}/sendMessage`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        chat_id: config.chatId,
+        text: message,
+        parse_mode: 'Markdown'
+      })
+    });
+
+    if (!response.ok) {
+      try {
+        const error = await response.json() as Record<string, any>;
+        throw new Error(`Telegram alert failed: ${error.description || response.statusText}`);
+      } catch {
+        throw new Error(`Telegram alert failed: ${response.statusText}`);
+      }
+    }
+  }
+
+  validate(config: { botToken?: string; chatId?: string }): boolean {
+    return !!(
+      config.botToken &&
+      typeof config.botToken === 'string' &&
+      config.botToken.length > 0 &&
+      config.chatId &&
+      typeof config.chatId === 'string' &&
+      config.chatId.length > 0
+    );
+  }
+}
+
+/**
+ * Discord alert adapter
+ */
+export class DiscordAlertAdapter implements AlertChannelAdapter {
+  async send(alert: AlertDefinition, value: any, config: { webhookUrl: string }): Promise<void> {
+    if (!config.webhookUrl) {
+      throw new Error('Discord webhook URL is required');
+    }
+
+    const response = await fetch(config.webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        content: `🚨 **Alert: ${alert.name}**`,
+        embeds: [
+          {
+            title: alert.name,
+            description: `**Condition:** ${alert.condition}\n**Current Value:** ${value}`,
+            color: 15158332, // Red
+            timestamp: new Date().toISOString()
+          }
+        ]
+      })
+    });
+
+    if (!response.ok) {
+      throw new Error(`Discord alert failed: ${response.statusText}`);
+    }
+  }
+
+  validate(config: { webhookUrl?: string }): boolean {
+    try {
+      if (!config.webhookUrl) return false;
+      const url = new URL(config.webhookUrl);
+      return url.hostname.includes('discord.com');
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Console alert adapter (for testing/logging)
+ */
+export class ConsoleAlertAdapter implements AlertChannelAdapter {
+  async send(alert: AlertDefinition, value: any, _config: any): Promise<void> {
+    const timestamp = new Date().toISOString();
+    console.log(`\n[ALERT] ${timestamp}`);
+    console.log(`  Name: ${alert.name}`);
+    console.log(`  Condition: ${alert.condition}`);
+    console.log(`  Current Value: ${value}\n`);
+  }
+
+  validate(_config: any): boolean {
+    return true; // Console adapter doesn't need config
+  }
+}
+
+/**
+ * Alert channel adapter registry
+ * Manages all available alert channel adapters
+ */
+export class AlertChannelAdapterRegistry {
+  private adapters: Map<string, AlertChannelAdapter> = new Map();
+
+  constructor() {
+    // Register built-in adapters
+    this.register('slack', new SlackAlertAdapter());
+    this.register('webhook', new WebhookAlertAdapter());
+    this.register('email', new EmailAlertAdapter());
+    this.register('pagerduty', new PagerDutyAlertAdapter());
+    this.register('telegram', new TelegramAlertAdapter());
+    this.register('discord', new DiscordAlertAdapter());
+    this.register('console', new ConsoleAlertAdapter());
+  }
+
+  /**
+   * Register a new alert channel adapter
+   */
+  register(name: string, adapter: AlertChannelAdapter): void {
+    this.adapters.set(name.toLowerCase(), adapter);
+  }
+
+  /**
+   * Get an adapter by name
+   */
+  get(name: string): AlertChannelAdapter | undefined {
+    return this.adapters.get(name.toLowerCase());
+  }
+
+  /**
+   * Get all registered adapter names
+   */
+  getNames(): string[] {
+    return Array.from(this.adapters.keys());
+  }
+
+  /**
+   * Check if an adapter is registered
+   */
+  has(name: string): boolean {
+    return this.adapters.has(name.toLowerCase());
+  }
+
+  /**
+   * Remove an adapter
+   */
+  unregister(name: string): boolean {
+    return this.adapters.delete(name.toLowerCase());
+  }
+}

package/src/advanced/observability/createObservabilityMiddleware.ts

@@ -0,0 +1,63 @@
+import { randomUUID } from 'crypto';
+import { performance } from 'perf_hooks';
+import { Middleware } from '../../core/types';
+import { ObservabilityCenter } from './ObservabilityCenter';
+import { ObservabilityOptions } from './types';
+
+/**
+ * Create observability middleware
+ */
+
+
+export function createObservabilityMiddleware(
+    center: ObservabilityCenter,
+    options: ObservabilityOptions
+): Middleware {
+    const correlationHeader = options.logging?.correlationId?.header ?? 'x-request-id';
+    const correlationGenerator = options.logging?.correlationId?.generator ?? (() => randomUUID());
+
+    return async (ctx, next, _deps) => {
+        // Set correlation ID
+        const correlationId = (ctx.headers[correlationHeader] as string) || correlationGenerator();
+        ctx.correlationId = correlationId;
+
+        // Start span if tracing is enabled
+        const span = center.startSpan(`${ctx.method} ${ctx.path}`, ctx);
+        if (span) {
+            ctx.spanId = span.spanId;
+            ctx.traceId = span.traceId;
+        }
+
+        const start = performance.now();
+        try {
+            const response = await next(ctx);
+            const duration = performance.now() - start;
+
+            center.recordRequest(ctx, response, duration);
+
+            if (span) {
+                center.setSpanAttributes(span.spanId, {
+                    'http.status_code': response.statusCode,
+                    'http.response_size': response.body?.length ?? 0
+                });
+                center.endSpan(span.spanId, response.statusCode < 400 ? 'ok' : 'error');
+            }
+
+            return response;
+        } catch (error) {
+            const duration = performance.now() - start;
+            center.recordRequest(
+                ctx,
+                { statusCode: 500, headers: {}, body: '' },
+                duration,
+                error as Error
+            );
+
+            if (span) {
+                center.endSpan(span.spanId, 'error', error as Error);
+            }
+
+            throw error;
+        }
+    };
+}

package/src/advanced/observability/index.ts

@@ -0,0 +1,11 @@
+export {
+    AlertChannelAdapter,
+    AlertChannelAdapterRegistry,
+    SlackAlertAdapter,
+    WebhookAlertAdapter,
+    EmailAlertAdapter,
+    PagerDutyAlertAdapter,
+    TelegramAlertAdapter,
+    DiscordAlertAdapter,
+    ConsoleAlertAdapter
+} from './adapters';