synapse-mcp 1.0.0 → 1.0.2

package/dist/services/container-host-map-cache.js

@@ -0,0 +1,188 @@
+import pLimit from "p-limit";
+import { DEFAULT_CONTAINER_MAP_CONCURRENCY } from "../constants.js";
+import { logError } from "../utils/errors.js";
+import { LRUCacheLayer } from "./cache-layer.js";
+/**
+ * Cache for container-to-host mappings.
+ * Optimizes findContainerHost() by eliminating N+1 queries.
+ *
+ * Key features:
+ * - Parallel host scanning with configurable concurrency
+ * - Multiple index keys per container (ID, name, ID prefix)
+ * - TTL-based expiration (default: 5 minutes)
+ * - Automatic cache rebuild on miss
+ * - LRU eviction policy
+ *
+ * @example
+ * ```typescript
+ * const cache = new ContainerHostMapCache();
+ * await cache.buildMapping(hosts, dockerService);
+ *
+ * const result = await cache.findContainerHost("my-container", hosts, dockerService);
+ * // Returns { host, container } immediately without scanning all hosts
+ * ```
+ */
+export class ContainerHostMapCache {
+    cache;
+    concurrency;
+    /**
+     * Create a new container-to-host mapping cache.
+     *
+     * @param ttlMs - Time-to-live for cache entries in milliseconds (default: 5 minutes)
+     * @param maxSize - Maximum number of cache entries (default: 500)
+     * @param concurrency - Number of parallel host scans (default from constants)
+     */
+    constructor(ttlMs = 5 * 60 * 1000, maxSize = 500, concurrency = DEFAULT_CONTAINER_MAP_CONCURRENCY) {
+        this.cache = new LRUCacheLayer(maxSize, ttlMs);
+        this.concurrency = concurrency;
+    }
+    /**
+     * Build container-to-host mapping for all hosts in parallel.
+     * Uses concurrency control to avoid overwhelming the network.
+     *
+     * @param hosts - List of hosts to scan
+     * @param dockerService - Docker service to query containers
+     * @returns Promise that resolves when mapping is complete
+     */
+    async buildMapping(hosts, dockerService) {
+        const limit = pLimit(this.concurrency);
+        // Query each host in parallel with concurrency limit
+        const tasks = hosts.map((host) => limit(() => this.scanSingleHost(host, dockerService)));
+        await Promise.all(tasks);
+    }
+    /**
+     * Scan a single host and cache its containers.
+     * Returns true if the target container was found on this host.
+     *
+     * @param host - Host to scan
+     * @param dockerService - Docker service to query containers
+     * @param targetContainerId - Optional container ID/name to search for
+     * @returns Whether the target container was found on this host
+     */
+    async scanSingleHost(host, dockerService, targetContainerId) {
+        const timestamp = Date.now();
+        try {
+            const docker = await dockerService.getDockerClient(host);
+            const rawContainers = await docker.listContainers({ all: true });
+            let found = false;
+            for (const container of rawContainers) {
+                const mapping = {
+                    containerId: container.Id,
+                    shortId: container.Id.slice(0, 12),
+                    containerName: container.Names[0]?.replace(/^\//, "") || container.Id.slice(0, 12),
+                    hostName: host.name,
+                    host,
+                    container,
+                    timestamp,
+                };
+                this.cache.set(container.Id, mapping);
+                this.cache.set(mapping.containerName, mapping);
+                this.cache.set(mapping.shortId, mapping);
+                if (targetContainerId &&
+                    (container.Id === targetContainerId ||
+                        mapping.containerName === targetContainerId ||
+                        mapping.shortId === targetContainerId)) {
+                    found = true;
+                }
+            }
+            return found;
+        }
+        catch (error) {
+            logError(error, {
+                operation: "ContainerHostMapCache:scanHost",
+                metadata: { host: host.name },
+            });
+            return false;
+        }
+    }
+    /**
+     * Find which host a container is on, using cache with fallback.
+     * Supports full ID, short ID, or container name lookups.
+     *
+     * On cache miss, scans hosts incrementally (one at a time) instead of
+     * rebuilding the entire mapping. Stops as soon as the container is found,
+     * avoiding unnecessary network calls to remaining hosts.
+     *
+     * @param containerId - Container ID (full/short) or name
+     * @param hosts - Array of host configurations to search
+     * @param dockerService - Docker service for fallback queries
+     * @returns Host config and container info if found, null otherwise
+     */
+    async findContainerHost(containerId, hosts, dockerService) {
+        // Try cache lookup first
+        const cached = this.cache.get(containerId);
+        if (cached) {
+            // Cache hit - log for observability
+            console.error(`[ContainerHostMapCache] HIT: ${containerId}`);
+            return { host: cached.host, container: cached.container };
+        }
+        // Cache miss - scan hosts incrementally instead of full rebuild
+        console.error(`[ContainerHostMapCache] MISS: ${containerId} - scanning incrementally`);
+        for (const host of hosts) {
+            const found = await this.scanSingleHost(host, dockerService, containerId);
+            if (found) {
+                const result = this.cache.get(containerId);
+                if (result) {
+                    console.error(`[ContainerHostMapCache] Found ${containerId} on ${host.name} (scanned incrementally)`);
+                    return { host: result.host, container: result.container };
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Invalidate entire cache after container lifecycle changes.
+     * Call this after container state changes (start, stop, pause, resume, remove, create).
+     *
+     * Note: Clears the ENTIRE cache for all hosts. This is simpler than selective
+     * per-host invalidation and the cache will rebuild automatically on next query.
+     * For production use with many hosts, consider implementing per-host invalidation.
+     */
+    invalidateCache() {
+        const stats = this.cache.getStats();
+        console.error(`[ContainerHostMapCache] Invalidating entire cache (current size: ${stats.size})`);
+        // Clear entire cache - simpler than selective removal
+        // Cache will rebuild on next query
+        this.cache.clear();
+    }
+    /**
+     * Warm cache by pre-populating with all containers on startup.
+     * Reduces initial query latency.
+     *
+     * @param hosts - Array of host configurations
+     * @param dockerService - Docker service for API calls
+     */
+    async warmCache(hosts, dockerService) {
+        console.error("[ContainerHostMapCache] Warming cache...");
+        const start = Date.now();
+        await this.buildMapping(hosts, dockerService);
+        const stats = this.cache.getStats();
+        const elapsed = Date.now() - start;
+        console.error(`[ContainerHostMapCache] Cache warmed: ${stats.size} entries in ${elapsed}ms`);
+    }
+    /**
+     * Get cache statistics for monitoring and debugging.
+     * Returns metrics on hits, misses, size, and evictions.
+     *
+     * @returns Cache statistics object
+     */
+    getStats() {
+        return this.cache.getStats();
+    }
+    /**
+     * Log cache statistics to console.error for observability.
+     * Outputs formatted stats with hit rate calculation.
+     */
+    logStats() {
+        const stats = this.getStats();
+        const total = stats.hits + stats.misses;
+        const hitRate = total > 0 ? ((stats.hits / total) * 100).toFixed(2) : "0.00";
+        console.error(`[ContainerHostMapCache] Stats:
+  - Hits: ${stats.hits}
+  - Misses: ${stats.misses}
+  - Hit Rate: ${hitRate}%
+  - Size: ${stats.size}/${stats.maxSize}
+  - Evictions: ${stats.evictions}`);
+    }
+}
+//# sourceMappingURL=container-host-map-cache.js.map

package/dist/services/container-host-map-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-host-map-cache.js","sourceRoot":"","sources":["../../src/services/container-host-map-cache.ts"],"names":[],"mappings":"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"}

package/dist/services/container.d.ts

@@ -1,14 +1,64 @@
-import type { IDockerService, ISSHService, IComposeService, ISSHConnectionPool, IFileService } from "./interfaces.js";
+import { EventEmitter } from "../events/index.js";
+import { ComposeProjectCache } from "./compose-cache.js";
+import { ComposeDiscovery } from "./compose-discovery.js";
+import { ComposeScanner } from "./compose-scanner.js";
+import { ContainerHostMapCache } from "./container-host-map-cache.js";
+import type { IHostConfigRepository } from "./host-config-repository.js";
+import type { DockerOperations, IComposeProjectLister, IComposeService, IFileService, ILocalExecutorService, ISSHConnectionPool, ISSHService } from "./interfaces.js";
+/**
+ * Service lifecycle state
+ */
+export declare enum LifecycleState {
+    /** Container created but not initialized */
+    CREATED = "created",
+    /** Initialization in progress */
+    INITIALIZING = "initializing",
+    /** Fully initialized and ready */
+    READY = "ready",
+    /** Shutdown initiated */
+    SHUTTING_DOWN = "shutting_down",
+    /** Fully shut down */
+    SHUTDOWN = "shutdown"
+}
+/**
+ * Health check status for a DI-managed service dependency
+ */
+export interface ServiceContainerHealth {
+    /** Service name */
+    name: string;
+    /** Is service healthy? */
+    healthy: boolean;
+    /** Optional error message if unhealthy */
+    message?: string;
+    /** Response time in milliseconds (if applicable) */
+    responseTime?: number;
+}
 /**
  * Service container for dependency injection.
  * Manages service lifecycle and dependencies.
  *
- * Dependency chain:
+ * Lifecycle phases:
+ * 1. CREATED - Container instantiated
+ * 2. INITIALIZING - Services being initialized (async setup)
+ * 3. READY - All services ready, accepting requests
+ * 4. SHUTTING_DOWN - Graceful shutdown in progress
+ * 5. SHUTDOWN - All services stopped
+ *
+ * Dependency chain (no circular dependencies):
+ * - EventEmitter (no dependencies) - application-wide event bus
+ * - LocalExecutorService (no dependencies)
  * - SSHConnectionPool (no dependencies)
+ * - HostConfigRepository (no dependencies)
  * - SSHService (requires SSHConnectionPool)
- * - ComposeService (requires SSHService)
+ * - ComposeProjectLister (requires SSHService, LocalExecutorService)
+ * - ComposeProjectCache (no dependencies)
+ * - ComposeScanner (requires SSHService, LocalExecutorService)
+ * - ComposeDiscovery (requires ComposeProjectLister, ComposeProjectCache, ComposeScanner)
+ * - ComposeService (requires SSHService, LocalExecutorService, ComposeDiscovery as IComposePathResolver)
  * - FileService (requires SSHService)
  * - DockerService (no dependencies)
+ * - HostConfigs (loaded once at startup with 60s TTL cache)
+ * - ContainerHostMapCache (no dependencies)
  */
 export declare class ServiceContainer {
     private dockerService?;
@@ -16,14 +66,26 @@ export declare class ServiceContainer {
     private composeService?;
     private sshPool?;
     private fileService?;
+    private localExecutor?;
+    private composeProjectLister?;
+    private composeCache?;
+    private composeScanner?;
+    private composeDiscovery?;
+    private hostConfigRepository?;
+    private containerHostMapCache?;
+    private eventEmitter;
+    /** Current lifecycle state */
+    private lifecycleState;
+    /** Shutdown timeout in milliseconds */
+    private shutdownTimeout;
     /**
      * Get Docker service instance (lazy initialization)
      */
-    getDockerService(): IDockerService;
+    getDockerService(): DockerOperations;
     /**
      * Set Docker service instance (for testing/overrides)
      */
-    setDockerService(service: IDockerService): void;
+    setDockerService(service: DockerOperations): void;
     /**
      * Get SSH connection pool instance (lazy initialization)
      */
@@ -41,7 +103,22 @@ export declare class ServiceContainer {
      */
     setSSHService(service: ISSHService): void;
     /**
-     * Get Compose service instance (lazy initialization with dependencies)
+     * Get Local executor service instance (lazy initialization)
+     */
+    getLocalExecutor(): ILocalExecutorService;
+    /**
+     * Set Local executor service instance (for testing/overrides)
+     */
+    setLocalExecutor(service: ILocalExecutorService): void;
+    /**
+     * Get Compose project lister instance (lazy initialization).
+     * Standalone service for `docker compose ls` - used by ComposeDiscovery
+     * to break the former circular dependency.
+     */
+    getComposeProjectLister(): IComposeProjectLister;
+    /**
+     * Get Compose service instance (lazy initialization with dependencies).
+     * ComposeDiscovery is injected as path resolver via constructor (no setter injection).
      */
     getComposeService(): IComposeService;
     /**
@@ -56,9 +133,120 @@ export declare class ServiceContainer {
      * Set File service instance (for testing/overrides)
      */
     setFileService(service: IFileService): void;
+    /**
+     * Get Compose project cache instance (lazy initialization)
+     */
+    getComposeCache(): ComposeProjectCache;
+    /**
+     * Get Compose scanner instance (lazy initialization with dependencies)
+     */
+    getComposeScanner(): ComposeScanner;
+    /**
+     * Get Compose discovery instance (lazy initialization with dependencies).
+     * Uses ComposeProjectLister (not ComposeService) to avoid circular dependency.
+     * Dependency chain: ProjectLister -> Discovery -> ComposeService (linear, no cycle).
+     */
+    getComposeDiscovery(): ComposeDiscovery;
+    /**
+     * Get Host config repository instance (lazy initialization)
+     */
+    getHostConfigRepository(): IHostConfigRepository;
+    /**
+     * Set Host config repository instance (for testing/overrides)
+     */
+    setHostConfigRepository(repository: IHostConfigRepository): void;
+    /**
+     * Get Container host map cache instance (lazy initialization)
+     */
+    getContainerHostMapCache(): ContainerHostMapCache;
+    /**
+     * Set Container host map cache instance (for testing/overrides)
+     */
+    setContainerHostMapCache(cache: ContainerHostMapCache): void;
+    /**
+     * Get EventEmitter instance (application-wide event bus).
+     * Use this to emit or subscribe to application events.
+     */
+    getEventEmitter(): EventEmitter;
+    /**
+     * Get current lifecycle state
+     */
+    getLifecycleState(): LifecycleState;
+    /**
+     * Check if container is ready to accept requests
+     */
+    isReady(): boolean;
+    /**
+     * Initialize container and perform async service setup
+     *
+     * Performs:
+     * 1. Preload host configurations
+     * 2. Start SSH connection pool health checks
+     * 3. Emit lifecycle events
+     *
+     * @throws {Error} If already initialized or shutting down
+     *
+     * @example
+     * ```typescript
+     * const container = new ServiceContainer();
+     * await container.initialize();
+     * // Container is now ready to use
+     * ```
+     */
+    initialize(): Promise<void>;
+    /**
+     * Perform health checks on all initialized services
+     *
+     * Returns health status for each service. Useful for monitoring
+     * and graceful degradation.
+     *
+     * @returns Array of service health statuses
+     *
+     * @example
+     * ```typescript
+     * const health = await container.healthCheck();
+     * const unhealthy = health.filter(h => !h.healthy);
+     * if (unhealthy.length > 0) {
+     *   console.error('Unhealthy services:', unhealthy);
+     * }
+     * ```
+     */
+    healthCheck(): Promise<ServiceContainerHealth[]>;
+    /**
+     * Gracefully shut down container and all services
+     *
+     * Performs ordered shutdown:
+     * 1. Stop accepting new requests (set state to SHUTTING_DOWN)
+     * 2. Wait for in-flight operations (via timeout)
+     * 3. Close all connections
+     * 4. Clear caches
+     * 5. Emit shutdown complete event
+     *
+     * @param timeout - Maximum time to wait for graceful shutdown (ms)
+     * @throws {Error} If shutdown times out
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown with 30s timeout
+     * await container.shutdown();
+     *
+     * // Custom timeout
+     * await container.shutdown(10000); // 10 seconds
+     * ```
+     */
+    shutdown(timeout?: number): Promise<void>;
+    /**
+     * Close connections and clear caches without removing event listeners.
+     * Used internally by shutdown() which handles listener cleanup after
+     * emitting the final shutdown event.
+     */
+    private performCleanup;
     /**
      * Cleanup all services and close connections.
      * Call during shutdown to ensure clean termination.
+     *
+     * @deprecated Use shutdown() for graceful shutdown with timeout.
+     * This method is kept for backward compatibility but performs immediate cleanup.
      */
     cleanup(): Promise<void>;
 }

package/dist/services/container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/services/container.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,YAAY,EACb,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,aAAa,CAAC,CAAiB;IACvC,OAAO,CAAC,UAAU,CAAC,CAAc;IACjC,OAAO,CAAC,cAAc,CAAC,CAAkB;IACzC,OAAO,CAAC,OAAO,CAAC,CAAqB;IACrC,OAAO,CAAC,WAAW,CAAC,CAAe;IAEnC;;OAEG;IACH,gBAAgB,IAAI,cAAc;IAKlC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAI/C;;OAEG;IACH,oBAAoB,IAAI,kBAAkB;IAK1C;;OAEG;IACH,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI;IAIpD;;OAEG;IACH,aAAa,IAAI,WAAW;IAK5B;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAIzC;;OAEG;IACH,iBAAiB,IAAI,eAAe;IAKpC;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAIjD;;OAEG;IACH,cAAc,IAAI,YAAY;IAK9B;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAI3C;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAM/B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAEzD"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/services/container.ts"],"names":[],"mappings":"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"}