@lincoln504/pi-research 0.1.12 → 1.0.0

package/src/infrastructure/metrics-service.ts

@@ -0,0 +1,129 @@
+/**
+ * Metrics Service
+ *
+ * Service wrapper that exposes the session-scoped metrics singleton through
+ * the service registry. All methods delegate to the global `metrics` export.
+ * The service owns no state of its own; metrics belong to the process lifetime
+ * and are managed by the SessionMetrics class in utils/metrics.ts.
+ */
+
+import type { IService } from '../core/service-registry.ts';
+import { ServiceLifecycle } from '../core/service-registry.ts';
+import { logger } from '../logger.ts';
+import { metrics } from '../utils/metrics.ts';
+import type { Labels, IMetricHistogram, IMetricsSnapshot } from '../utils/metrics.ts';
+import { ServiceNames } from '../core/interfaces/service-names.ts';
+
+export class MetricsService implements IService {
+  readonly name = ServiceNames.METRICS;
+  lifecycle = ServiceLifecycle.UNINITIALIZED;
+
+  async initialize(): Promise<void> {
+    if (this.lifecycle === ServiceLifecycle.INITIALIZED) return;
+    this.lifecycle = ServiceLifecycle.INITIALIZING;
+    logger.debug('[MetricsService] Initializing...');
+    this.lifecycle = ServiceLifecycle.INITIALIZED;
+    logger.debug('[MetricsService] Initialized');
+  }
+
+  async dispose(): Promise<void> {
+    if (this.lifecycle === ServiceLifecycle.DISPOSED) return;
+    this.lifecycle = ServiceLifecycle.DISPOSING;
+    logger.debug('[MetricsService] Disposing...');
+    // Session metrics belong to the process lifetime, not this service.
+    // Nothing to clean up — the process is exiting and memory is freed.
+    this.lifecycle = ServiceLifecycle.DISPOSED;
+    logger.debug('[MetricsService] Disposed');
+  }
+
+  increment(name: string, value: number = 1, labels?: Labels): void {
+    metrics.increment(name, value, labels);
+  }
+
+  setGauge(name: string, value: number, labels?: Labels): void {
+    metrics.setGauge(name, value, labels);
+  }
+
+  observe(name: string, value: number, labels?: Labels): void {
+    metrics.observe(name, value, labels);
+  }
+
+  async measure<T>(name: string, action: () => Promise<T>, labels?: Labels): Promise<T> {
+    return metrics.measure(name, action, labels);
+  }
+
+  getSnapshot(): IMetricsSnapshot {
+    return metrics.getSessionSnapshot();
+  }
+
+  clear(): void {
+    metrics.clearSession();
+  }
+
+  getCounters(): Record<string, number> {
+    return metrics.getSessionSnapshot().counters ?? {};
+  }
+
+  getGauges(): Record<string, number> {
+    return metrics.getSessionSnapshot().gauges ?? {};
+  }
+
+  getHistograms(): Record<string, IMetricHistogram> {
+    return metrics.getSessionSnapshot().histograms ?? {};
+  }
+
+  getCounter(name: string, labels?: Labels): number {
+    const counters = this.getCounters();
+    if (!labels) return counters[name] ?? 0;
+    const keys = Object.keys(labels).sort();
+    const labelStr = keys.map(k => `${k}="${labels[k]}"`).join(',');
+    const key = labelStr ? `${name}{${labelStr}}` : name;
+    return counters[key] ?? 0;
+  }
+
+  getGauge(name: string, labels?: Labels): number {
+    const gauges = this.getGauges();
+    if (!labels) return gauges[name] ?? 0;
+    const keys = Object.keys(labels).sort();
+    const labelStr = keys.map(k => `${k}="${labels[k]}"`).join(',');
+    const key = labelStr ? `${name}{${labelStr}}` : name;
+    return gauges[key] ?? 0;
+  }
+
+  getHistogramStats(name: string, labels?: Labels): IMetricHistogram | null {
+    const histograms = this.getHistograms();
+    if (!labels) return histograms[name] ?? null;
+    const keys = Object.keys(labels).sort();
+    const labelStr = keys.map(k => `${k}="${labels[k]}"`).join(',');
+    const key = labelStr ? `${name}{${labelStr}}` : name;
+    return histograms[key] ?? null;
+  }
+
+  exportPrometheus(): string {
+    const snapshot = metrics.getSessionSnapshot();
+    const lines: string[] = [];
+
+    for (const [key, value] of Object.entries(snapshot.counters ?? {})) {
+      lines.push(`${key} ${value}`);
+    }
+    for (const [key, value] of Object.entries(snapshot.gauges ?? {})) {
+      lines.push(`${key} ${value}`);
+    }
+    for (const [key, s] of Object.entries(snapshot.histograms ?? {})) {
+      lines.push(`${key}_count ${s.count}`);
+      lines.push(`${key}_sum ${(s.avg * s.count).toFixed(2)}`);
+      lines.push(`${key}_min ${s.min}`);
+      lines.push(`${key}_max ${s.max}`);
+      lines.push(`${key}_avg ${s.avg.toFixed(2)}`);
+      lines.push(`${key}_p50 ${s.p50.toFixed(2)}`);
+      lines.push(`${key}_p90 ${s.p90.toFixed(2)}`);
+      lines.push(`${key}_p95 ${s.p95.toFixed(2)}`);
+      lines.push(`${key}_p99 ${s.p99.toFixed(2)}`);
+    }
+
+    return lines.join('\n');
+  }
+}
+
+// Re-export for consumers that import from this module
+export { type Labels, MetricsRegistry } from '../utils/metrics.ts';

package/src/infrastructure/process-lifecycle-service.ts

@@ -0,0 +1,253 @@
+/**
+ * Process Lifecycle Service
+ *
+ * Provides PID checks and process monitoring functionality.
+ * Stateless service for checking if processes are alive.
+ */
+
+import * as fs from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import type { IProcessLifecycle } from '../core/interfaces/process-interfaces.ts';
+import { ServiceLifecycle } from '../core/service-registry.ts';
+import { ServiceNames } from '../core/interfaces/service-names.ts';
+
+/**
+ * Process Lifecycle Service
+ *
+ * Provides utilities for checking process liveness and monitoring.
+ */
+export class ProcessLifecycleService implements IProcessLifecycle {
+  readonly name = ServiceNames.PROCESS_LIFECYCLE;
+  lifecycle = ServiceLifecycle.UNINITIALIZED;
+
+  private cachedStartTime: number | null = null;
+
+  async initialize(): Promise<void> {
+    this.lifecycle = ServiceLifecycle.INITIALIZED;
+  }
+
+  async dispose(): Promise<void> {
+    // Stateless service
+  }
+
+  /**
+   * Get the start time of a process (Linux only).
+   * Combined with PID, this provides a globally unique identifier for a process
+   * even if PIDs are recycled by the OS.
+   * 
+   * @param pid Process ID
+   * @returns Start time identifier (Linux: jiffies; cross-platform: epoch seconds) or null
+   */
+  async getProcessStartTime(pid: number): Promise<number | null> {
+    // Linux: read from /proc/{pid}/stat (field 22 = starttime in jiffies)
+    if (process.platform === 'linux') {
+      try {
+        const stat = await fs.readFile(`/proc/${pid}/stat`, 'utf8');
+        const lastParenIndex = stat.lastIndexOf(')');
+        if (lastParenIndex === -1) return null;
+        const partsAfterName = stat.substring(lastParenIndex + 2).trim().split(/\s+/);
+        const startTimeStr = partsAfterName[19];
+        return startTimeStr ? parseInt(startTimeStr, 10) : null;
+      } catch (_err) {
+        // ENOENT is common if process just died
+        return null;
+      }
+    }
+
+    // Windows: use powershell to get process creation time
+    if (process.platform === 'win32') {
+      try {
+        const output = await new Promise<string>((resolve, reject) => {
+          const child = execFile(
+            'powershell', 
+            ['-NoProfile', '-Command', `[Math]::Floor(([DateTimeOffset](Get-Process -Id ${pid} -ErrorAction Stop).StartTime).ToUnixTimeSeconds())`],
+            { encoding: 'utf8', timeout: 5000 },
+            (err, stdout) => err ? reject(err) : resolve(stdout),
+          );
+          child.unref?.();
+        });
+        if (!output || !output.trim()) return null;
+        const startTime = parseInt(output.trim(), 10);
+        return isNaN(startTime) ? null : startTime;
+      } catch {
+        return null;
+      }
+    }
+
+    // Cross-platform fallback (macOS/Unix): `ps -o etimes=` returns elapsed seconds.
+    try {
+      const output = await new Promise<string>((resolve, reject) => {
+        const child = execFile(
+          'ps', ['-o', 'etimes=', '-p', String(pid)],
+          { encoding: 'utf8', timeout: 3000 },
+          (err, stdout) => err ? reject(err) : resolve(stdout),
+        );
+        child.unref?.();
+      });
+      if (!output || !output.trim()) return null;
+      const elapsedSec = parseInt(output.trim(), 10);
+      if (isNaN(elapsedSec)) return null;
+      return Math.floor(Date.now() / 1000) - elapsedSec;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get the start time for the current process
+   */
+  async getCurrentProcessStartTime(): Promise<number | null> {
+    if (this.cachedStartTime !== null) return this.cachedStartTime;
+    this.cachedStartTime = await this.getProcessStartTime(process.pid);
+    return this.cachedStartTime;
+  }
+
+  /**
+   * Check if a process is alive by sending signal 0.
+   * Optionally verifies that the start time matches to prevent PID reuse races.
+   *
+   * @param pid Process ID to check
+   * @param expectedStartTime Optional start time to verify (from getProcessStartTime)
+   * @returns true if process is alive (and matches start time if provided)
+   */
+  async isProcessAlive(pid: number, expectedStartTime?: number | null): Promise<boolean> {
+    try {
+      // 1. Basic liveness check via signal 0
+      process.kill(pid, 0);
+      
+      // 2. If start time verification requested, check it
+      if (expectedStartTime !== undefined && expectedStartTime !== null) {
+        const actualStartTime = await this.getProcessStartTime(pid);
+        if (actualStartTime === null) {
+          // If we can't get start time but expected it, we can't be sure it's the same process
+          // On Linux this usually means the process just exited between the signal and the read.
+          return false;
+        }
+        // Allow ±1s slack. The macOS/BSD fallback derives start time as
+        // floor(Date.now()/1000) - `ps etimes` (elapsed whole seconds); both terms are
+        // independently quantized, so the SAME process can compute start times 1s apart
+        // across two reads. A strict === there makes a live lock/leader owner read as
+        // dead → the lock is reclaimed from under a live writer (lost update). PID reuse
+        // within a 1s window at the identical PID is not a realistic false-match.
+        return Math.abs(actualStartTime - expectedStartTime) <= 1;
+      }
+      
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Sync version of basic liveness check (no start-time verification)
+   */
+  isProcessAliveSync(pid: number): boolean {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if a process is alive with optional scheduler ID verification.
+   * This method is designed to work with state that contains scheduler information.
+   *
+   * @param pid Process ID to check
+   * @param expectedSchedulerId Optional scheduler ID to verify
+   * @param getState Function to retrieve current state for scheduler ID verification
+   * @param skipLock If true, skip locking when retrieving state (useful to prevent deadlocks)
+   * @returns true if process is alive and (if provided) matches expected scheduler ID
+   */
+  async isPidAlive<TState>(
+    pid: number,
+    expectedSchedulerId?: string,
+    options?: {
+      getState?: (skipLock?: boolean) => Promise<TState>;
+      skipLock?: boolean;
+      getSchedulerIdFromState?: (state: TState) => string | undefined;
+      expectedStartTime?: number | null;
+    }
+  ): Promise<boolean> {
+    const alive = await this.isProcessAlive(pid, options?.expectedStartTime);
+    if (!alive) return false;
+
+    if (expectedSchedulerId && options?.getState && options?.getSchedulerIdFromState) {
+      // Use skipLock if true to prevent deadlocks when called inside updateState
+      const state = await options.getState(options.skipLock);
+      const schedulerId = options.getSchedulerIdFromState(state);
+      return schedulerId === expectedSchedulerId;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get the current process ID
+   */
+  getCurrentPid(): number {
+    return process.pid;
+  }
+
+  /**
+   * Wait for a process to terminate
+   *
+   * @param pid Process ID to wait for
+   * @param timeoutMs Maximum time to wait in milliseconds
+   * @param checkIntervalMs Interval between checks in milliseconds
+   * @param expectedStartTime Optional start time to verify
+   * @returns true if process terminated, false if timeout
+   */
+  async waitForProcessTermination(
+    pid: number,
+    timeoutMs: number = 5000,
+    checkIntervalMs: number = 100,
+    expectedStartTime?: number | null
+  ): Promise<boolean> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeoutMs) {
+      if (!(await this.isProcessAlive(pid, expectedStartTime))) {
+        return true;
+      }
+      await this.sleep(checkIntervalMs);
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if the current process is the one with the given PID
+   *
+   * @param pid Process ID to check
+   * @returns true if the current process has the given PID
+   */
+  isCurrentProcess(pid: number): boolean {
+    return process.pid === pid;
+  }
+
+  /**
+   * Get process information (platform-specific)
+   *
+   * @param pid Process ID to get information for
+   * @returns Process information or null if not available
+   */
+  async getProcessInfo(pid: number): Promise<{ pid: number; alive: boolean; startTime?: number | null } | null> {
+    const startTime = await this.getProcessStartTime(pid);
+    const alive = await this.isProcessAlive(pid, startTime);
+    return {
+      pid,
+      alive,
+      startTime,
+    };
+  }
+
+  /**
+   * Sleep for a specified number of milliseconds
+   * @param ms The number of milliseconds to sleep
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise<void>((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/infrastructure/scheduler-factory-service.ts

@@ -0,0 +1,58 @@
+/**
+ * Scheduler Factory Service
+ *
+ * Implements the ISchedulerFactory interface for creating scheduler instances.
+ * This module lives in the Infrastructure layer and provides concrete implementations
+ * of scheduler creation logic.
+ */
+
+import type { Config } from '../config.ts';
+import { ServiceLifecycle, getServiceContainer, type ServiceContainer } from '../core/service-registry.ts';
+import type { IService } from '../core/service-registry.ts';
+import type { ISchedulerFactory, IScheduler } from '../core/scheduler-factory.ts';
+import { getScheduler as _getScheduler, forceSchedulerRestart as _forceSchedulerRestart, disposeBrowserInitLock } from './browser/scheduler-factory.ts';
+import { getSchedulerVersion as _getSchedulerVersion } from './browser/config.ts';
+import { ServiceNames } from '../core/interfaces/service-names.ts';
+
+/**
+ * Scheduler Factory Service Implementation
+ */
+export class SchedulerFactoryService implements ISchedulerFactory, IService {
+  readonly name = ServiceNames.SCHEDULER_FACTORY;
+  lifecycle = ServiceLifecycle.UNINITIALIZED;
+  private container: ServiceContainer = getServiceContainer();
+
+  async initialize(ctx?: any): Promise<void> {
+    if (ctx?.container) {
+      this.container = ctx.container;
+    }
+    this.lifecycle = ServiceLifecycle.INITIALIZED;
+  }
+
+  async dispose(): Promise<void> {
+    await disposeBrowserInitLock(this.container);
+    this.lifecycle = ServiceLifecycle.DISPOSED;
+  }
+
+  /**
+   * Get or create a scheduler instance.
+   * Handles leader election and client/server mode switching.
+   */
+  async getScheduler(config?: Config): Promise<IScheduler> {
+    return _getScheduler(config, this.container);
+  }
+
+  /**
+   * Get the current scheduler version string.
+   */
+  getSchedulerVersion(config?: Config): string {
+    return _getSchedulerVersion(config);
+  }
+
+  /**
+   * Force a restart of the scheduler by clearing the global cache and state.
+   */
+  async forceSchedulerRestart(forceClearRemoteState?: boolean): Promise<void> {
+    return _forceSchedulerRestart(forceClearRemoteState, this.container);
+  }
+}