agent-web-interface 4.1.1 → 4.2.0

package/dist/src/worker/lease-manager.js

@@ -0,0 +1,334 @@
+/**
+ * Lease Manager
+ *
+ * Manages exclusive leases for worker access.
+ * Each tenant can hold at most one lease at a time.
+ */
+import { randomUUID } from 'crypto';
+import { WorkerError } from './errors/index.js';
+import { createLogger } from '../shared/services/logging.service.js';
+const logger = createLogger('LeaseManager');
+/**
+ * Manages exclusive leases for tenant workers.
+ *
+ * @example
+ * ```typescript
+ * const leaseManager = new LeaseManager({ defaultTtlMs: 300000 });
+ *
+ * // Acquire a lease
+ * const result = leaseManager.acquire('tenant-a', 'controller-1', 'w-123');
+ * if (result.success) {
+ *   console.log(`Lease acquired: ${result.lease.leaseId}`);
+ * }
+ *
+ * // Refresh the lease before it expires
+ * leaseManager.refresh('tenant-a');
+ *
+ * // Release when done
+ * leaseManager.release('tenant-a');
+ * ```
+ */
+export class LeaseManager {
+    defaultTtlMs;
+    leases = new Map();
+    cleanupIntervalId = null;
+    /** Callbacks for lease expiration */
+    onLeaseExpiredCallbacks = [];
+    /** Callbacks for lease revocation */
+    onLeaseRevokedCallbacks = [];
+    constructor(config) {
+        this.defaultTtlMs = config.defaultTtlMs;
+        // Start cleanup interval if specified
+        if (config.cleanupIntervalMs && config.cleanupIntervalMs > 0) {
+            this.startCleanupInterval(config.cleanupIntervalMs);
+        }
+    }
+    /**
+     * Get number of active leases
+     */
+    get leaseCount() {
+        return this.leases.size;
+    }
+    /**
+     * Acquire a lease for a tenant
+     *
+     * @param tenantId - Tenant identifier
+     * @param controllerId - Controller/session identifier
+     * @param workerId - Worker to lease
+     * @param ttlMs - Optional custom TTL (uses default if not specified)
+     * @returns Lease acquisition result
+     */
+    acquire(tenantId, controllerId, workerId, ttlMs) {
+        const existingLease = this.leases.get(tenantId);
+        // Check if lease already exists
+        if (existingLease) {
+            // If same controller, just refresh
+            if (existingLease.controllerId === controllerId) {
+                this.refreshLease(existingLease, ttlMs);
+                return {
+                    success: true,
+                    lease: existingLease,
+                    workerId: existingLease.workerId,
+                };
+            }
+            // Different controller - check if lease is still active
+            if (existingLease.status === 'active' && existingLease.expiresAt > Date.now()) {
+                logger.debug('Lease acquisition blocked - held by different controller', {
+                    tenantId,
+                    controllerId,
+                    heldBy: existingLease.controllerId,
+                });
+                return {
+                    success: false,
+                    error: 'Lease is held by another controller',
+                    errorCode: 'LEASE_ALREADY_HELD',
+                };
+            }
+            // Lease expired - clean it up and allow new acquisition
+            this.leases.delete(tenantId);
+        }
+        // Create new lease
+        const now = Date.now();
+        const lease = {
+            leaseId: randomUUID(),
+            tenantId,
+            workerId,
+            controllerId,
+            acquiredAt: now,
+            expiresAt: now + (ttlMs ?? this.defaultTtlMs),
+            status: 'active',
+        };
+        this.leases.set(tenantId, lease);
+        logger.info('Lease acquired', {
+            leaseId: lease.leaseId,
+            tenantId,
+            controllerId,
+            workerId,
+            ttlMs: ttlMs ?? this.defaultTtlMs,
+        });
+        return {
+            success: true,
+            lease,
+            workerId,
+        };
+    }
+    /**
+     * Release a lease
+     *
+     * @param tenantId - Tenant identifier
+     * @param controllerId - Optional controller ID to validate ownership
+     * @returns true if lease was released
+     */
+    release(tenantId, controllerId) {
+        const lease = this.leases.get(tenantId);
+        if (!lease) {
+            return false;
+        }
+        // Validate controller ownership if specified
+        if (controllerId && lease.controllerId !== controllerId) {
+            logger.debug('Lease release rejected - wrong controller', {
+                tenantId,
+                controllerId,
+                actualController: lease.controllerId,
+            });
+            return false;
+        }
+        this.leases.delete(tenantId);
+        logger.info('Lease released', {
+            leaseId: lease.leaseId,
+            tenantId,
+            controllerId: lease.controllerId,
+        });
+        return true;
+    }
+    /**
+     * Refresh a lease to extend its TTL
+     *
+     * @param tenantId - Tenant identifier
+     * @param ttlMs - Optional new TTL (uses default if not specified)
+     * @returns true if lease was refreshed
+     * @throws WorkerError if lease not found or expired
+     */
+    refresh(tenantId, ttlMs) {
+        const lease = this.leases.get(tenantId);
+        if (!lease) {
+            throw WorkerError.leaseNotFound(tenantId);
+        }
+        if (lease.status !== 'active') {
+            throw WorkerError.leaseExpired(tenantId, lease.expiresAt);
+        }
+        if (lease.expiresAt <= Date.now()) {
+            lease.status = 'expired';
+            throw WorkerError.leaseExpired(tenantId, lease.expiresAt);
+        }
+        this.refreshLease(lease, ttlMs);
+        return true;
+    }
+    /**
+     * Revoke a lease (typically on worker crash)
+     *
+     * @param tenantId - Tenant identifier
+     * @param reason - Reason for revocation
+     */
+    revoke(tenantId, reason) {
+        const lease = this.leases.get(tenantId);
+        if (!lease) {
+            return;
+        }
+        lease.status = 'revoked';
+        this.leases.delete(tenantId);
+        logger.info('Lease revoked', {
+            leaseId: lease.leaseId,
+            tenantId,
+            reason,
+        });
+        // Notify callbacks
+        for (const callback of this.onLeaseRevokedCallbacks) {
+            try {
+                callback(lease, reason);
+            }
+            catch (err) {
+                logger.error('Error in lease revoked callback', err instanceof Error ? err : undefined, {
+                    errorMessage: String(err),
+                });
+            }
+        }
+    }
+    /**
+     * Check if a tenant has an active lease
+     */
+    hasLease(tenantId) {
+        const lease = this.leases.get(tenantId);
+        if (!lease)
+            return false;
+        // Check if expired
+        if (lease.expiresAt <= Date.now()) {
+            lease.status = 'expired';
+            return false;
+        }
+        return lease.status === 'active';
+    }
+    /**
+     * Get the lease for a tenant (if any)
+     */
+    getLease(tenantId) {
+        return this.leases.get(tenantId);
+    }
+    /**
+     * Get the lease holder (controller) for a tenant
+     */
+    getLeaseHolder(tenantId) {
+        const lease = this.leases.get(tenantId);
+        return lease?.controllerId;
+    }
+    /**
+     * Check if a specific controller holds the lease for a tenant
+     */
+    isLeaseHeldBy(tenantId, controllerId) {
+        const lease = this.leases.get(tenantId);
+        if (!lease)
+            return false;
+        if (lease.expiresAt <= Date.now()) {
+            return false;
+        }
+        return lease.status === 'active' && lease.controllerId === controllerId;
+    }
+    /**
+     * Get the worker ID for a tenant's lease
+     */
+    getWorkerIdForTenant(tenantId) {
+        const lease = this.leases.get(tenantId);
+        if (lease?.status !== 'active' || lease.expiresAt <= Date.now()) {
+            return undefined;
+        }
+        return lease.workerId;
+    }
+    /**
+     * Register a callback for lease expiration
+     */
+    onLeaseExpired(callback) {
+        this.onLeaseExpiredCallbacks.push(callback);
+    }
+    /**
+     * Register a callback for lease revocation
+     */
+    onLeaseRevoked(callback) {
+        this.onLeaseRevokedCallbacks.push(callback);
+    }
+    /**
+     * Clean up expired leases
+     */
+    cleanupExpired() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [tenantId, lease] of this.leases.entries()) {
+            if (lease.status === 'active' && lease.expiresAt <= now) {
+                lease.status = 'expired';
+                this.leases.delete(tenantId);
+                cleaned++;
+                logger.info('Lease expired', {
+                    leaseId: lease.leaseId,
+                    tenantId,
+                    controllerId: lease.controllerId,
+                });
+                // Notify callbacks
+                for (const callback of this.onLeaseExpiredCallbacks) {
+                    try {
+                        callback(lease);
+                    }
+                    catch (err) {
+                        logger.error('Error in lease expired callback', err instanceof Error ? err : undefined, {
+                            errorMessage: String(err),
+                        });
+                    }
+                }
+            }
+        }
+        return cleaned;
+    }
+    /**
+     * Get all active leases
+     */
+    getAllLeases() {
+        return Array.from(this.leases.values());
+    }
+    /**
+     * Clear all leases
+     */
+    clear() {
+        this.leases.clear();
+    }
+    /**
+     * Stop the cleanup interval
+     */
+    stop() {
+        if (this.cleanupIntervalId) {
+            clearInterval(this.cleanupIntervalId);
+            this.cleanupIntervalId = null;
+        }
+    }
+    /**
+     * Internal: refresh lease TTL
+     */
+    refreshLease(lease, ttlMs) {
+        const now = Date.now();
+        lease.expiresAt = now + (ttlMs ?? this.defaultTtlMs);
+        logger.debug('Lease refreshed', {
+            leaseId: lease.leaseId,
+            tenantId: lease.tenantId,
+            newExpiresAt: lease.expiresAt,
+        });
+    }
+    /**
+     * Internal: start cleanup interval
+     */
+    startCleanupInterval(intervalMs) {
+        this.cleanupIntervalId = setInterval(() => {
+            const cleaned = this.cleanupExpired();
+            if (cleaned > 0) {
+                logger.debug('Cleaned up expired leases', { count: cleaned });
+            }
+        }, intervalMs);
+    }
+}
+//# sourceMappingURL=lease-manager.js.map

package/dist/src/worker/lease-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-manager.js","sourceRoot":"","sources":["../../../src/worker/lease-manager.ts"],"names":[],"mappings":"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"}

package/dist/src/worker/multi-tenant-config.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Multi-Tenant Configuration
+ *
+ * Parses and validates environment variables for multi-tenant mode.
+ */
+import { type WorkerManagerConfig } from './types.js';
+/**
+ * Multi-tenant mode configuration
+ */
+export interface MultiTenantConfig {
+    /** Whether multi-tenant mode is enabled */
+    enabled: boolean;
+    /** Tenant identifier (required when enabled) */
+    tenantId: string;
+    /** Controller/session identifier (auto-generated if not provided) */
+    controllerId: string;
+    /** WorkerManager configuration */
+    workerConfig: WorkerManagerConfig;
+}
+/**
+ * Parse and validate multi-tenant configuration from environment variables.
+ *
+ * Environment variables:
+ * - MULTI_TENANT_MODE: Enable multi-tenant mode (true/false)
+ * - TENANT_ID: Unique tenant identifier (required when enabled)
+ * - CONTROLLER_ID: Session/controller ID (auto-generated if not provided)
+ * - WORKER_PROFILE_DIR: Base directory for Chrome profiles (default: /tmp/athena-workers)
+ * - WORKER_IDLE_TIMEOUT_MS: Idle worker timeout (default: 300000 = 5 min)
+ * - WORKER_HARD_TTL_MS: Max worker runtime (default: 7200000 = 2 hrs)
+ * - WORKER_LEASE_TTL_MS: Lease TTL (default: 300000 = 5 min)
+ * - WORKER_HEALTH_CHECK_INTERVAL_MS: Health check interval (default: 30000 = 30 sec)
+ * - WORKER_PORT_MIN: Minimum CDP port (default: 9300)
+ * - WORKER_PORT_MAX: Maximum CDP port (default: 9399)
+ * - WORKER_MAX_COUNT: Maximum concurrent workers (default: 100)
+ * - CHROME_PATH: Path to Chrome executable (auto-detected if not set)
+ *
+ * @returns Multi-tenant configuration
+ * @throws Error if MULTI_TENANT_MODE is true but TENANT_ID is not provided
+ */
+export declare function getMultiTenantConfig(): MultiTenantConfig;
+/**
+ * Validate that multi-tenant config is properly set up.
+ * Logs warnings for common misconfigurations.
+ */
+export declare function validateMultiTenantConfig(config: MultiTenantConfig): void;
+//# sourceMappingURL=multi-tenant-config.d.ts.map

package/dist/src/worker/multi-tenant-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-tenant-config.d.ts","sourceRoot":"","sources":["../../../src/worker/multi-tenant-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAyB,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CA8CxD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAiBzE"}

package/dist/src/worker/multi-tenant-config.js

@@ -0,0 +1,94 @@
+/**
+ * Multi-Tenant Configuration
+ *
+ * Parses and validates environment variables for multi-tenant mode.
+ */
+import { randomUUID } from 'crypto';
+import { DEFAULT_WORKER_CONFIG } from './types.js';
+/**
+ * Parse integer from environment variable with default
+ */
+function parseIntEnv(name, defaultValue) {
+    const value = process.env[name];
+    if (!value)
+        return defaultValue;
+    const parsed = parseInt(value, 10);
+    return isNaN(parsed) ? defaultValue : parsed;
+}
+/**
+ * Parse and validate multi-tenant configuration from environment variables.
+ *
+ * Environment variables:
+ * - MULTI_TENANT_MODE: Enable multi-tenant mode (true/false)
+ * - TENANT_ID: Unique tenant identifier (required when enabled)
+ * - CONTROLLER_ID: Session/controller ID (auto-generated if not provided)
+ * - WORKER_PROFILE_DIR: Base directory for Chrome profiles (default: /tmp/athena-workers)
+ * - WORKER_IDLE_TIMEOUT_MS: Idle worker timeout (default: 300000 = 5 min)
+ * - WORKER_HARD_TTL_MS: Max worker runtime (default: 7200000 = 2 hrs)
+ * - WORKER_LEASE_TTL_MS: Lease TTL (default: 300000 = 5 min)
+ * - WORKER_HEALTH_CHECK_INTERVAL_MS: Health check interval (default: 30000 = 30 sec)
+ * - WORKER_PORT_MIN: Minimum CDP port (default: 9300)
+ * - WORKER_PORT_MAX: Maximum CDP port (default: 9399)
+ * - WORKER_MAX_COUNT: Maximum concurrent workers (default: 100)
+ * - CHROME_PATH: Path to Chrome executable (auto-detected if not set)
+ *
+ * @returns Multi-tenant configuration
+ * @throws Error if MULTI_TENANT_MODE is true but TENANT_ID is not provided
+ */
+export function getMultiTenantConfig() {
+    const enabled = process.env.MULTI_TENANT_MODE === 'true';
+    if (!enabled) {
+        return {
+            enabled: false,
+            tenantId: '',
+            controllerId: '',
+            workerConfig: {
+                profileBaseDir: '/tmp/athena-workers',
+                ...DEFAULT_WORKER_CONFIG,
+            },
+        };
+    }
+    const tenantId = process.env.TENANT_ID;
+    if (!tenantId) {
+        throw new Error('TENANT_ID environment variable is required when MULTI_TENANT_MODE is enabled');
+    }
+    const controllerId = process.env.CONTROLLER_ID ?? `ctrl-${randomUUID().substring(0, 8)}`;
+    const profileBaseDir = process.env.WORKER_PROFILE_DIR ?? '/tmp/athena-workers';
+    const workerConfig = {
+        profileBaseDir,
+        idleTimeoutMs: parseIntEnv('WORKER_IDLE_TIMEOUT_MS', DEFAULT_WORKER_CONFIG.idleTimeoutMs),
+        hardTtlMs: parseIntEnv('WORKER_HARD_TTL_MS', DEFAULT_WORKER_CONFIG.hardTtlMs),
+        leaseTtlMs: parseIntEnv('WORKER_LEASE_TTL_MS', DEFAULT_WORKER_CONFIG.leaseTtlMs),
+        healthCheckIntervalMs: parseIntEnv('WORKER_HEALTH_CHECK_INTERVAL_MS', DEFAULT_WORKER_CONFIG.healthCheckIntervalMs),
+        portRange: {
+            min: parseIntEnv('WORKER_PORT_MIN', DEFAULT_WORKER_CONFIG.portRange.min),
+            max: parseIntEnv('WORKER_PORT_MAX', DEFAULT_WORKER_CONFIG.portRange.max),
+        },
+        maxWorkers: parseIntEnv('WORKER_MAX_COUNT', DEFAULT_WORKER_CONFIG.maxWorkers),
+        chromePath: process.env.CHROME_PATH,
+    };
+    return {
+        enabled,
+        tenantId,
+        controllerId,
+        workerConfig,
+    };
+}
+/**
+ * Validate that multi-tenant config is properly set up.
+ * Logs warnings for common misconfigurations.
+ */
+export function validateMultiTenantConfig(config) {
+    if (!config.enabled)
+        return;
+    // Check port range validity
+    if (config.workerConfig.portRange.min > config.workerConfig.portRange.max) {
+        throw new Error(`Invalid port range: WORKER_PORT_MIN (${config.workerConfig.portRange.min}) > WORKER_PORT_MAX (${config.workerConfig.portRange.max})`);
+    }
+    // Check maxWorkers fits in port range
+    const portCapacity = config.workerConfig.portRange.max - config.workerConfig.portRange.min + 1;
+    if (config.workerConfig.maxWorkers > portCapacity) {
+        console.warn(`[WARN] WORKER_MAX_COUNT (${config.workerConfig.maxWorkers}) exceeds port range capacity (${portCapacity}). Effective limit will be ${portCapacity}.`);
+    }
+}
+//# sourceMappingURL=multi-tenant-config.js.map

package/dist/src/worker/multi-tenant-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-tenant-config.js","sourceRoot":"","sources":["../../../src/worker/multi-tenant-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,qBAAqB,EAA4B,MAAM,YAAY,CAAC;AAgB7E;;GAEG;AACH,SAAS,WAAW,CAAC,IAAY,EAAE,YAAoB;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK;QAAE,OAAO,YAAY,CAAC;IAChC,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,MAAM,CAAC;IAEzD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,KAAK;YACd,QAAQ,EAAE,EAAE;YACZ,YAAY,EAAE,EAAE;YAChB,YAAY,EAAE;gBACZ,cAAc,EAAE,qBAAqB;gBACrC,GAAG,qBAAqB;aACzB;SACF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;IACvC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;IAClG,CAAC;IAED,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,QAAQ,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACzF,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,qBAAqB,CAAC;IAE/E,MAAM,YAAY,GAAwB;QACxC,cAAc;QACd,aAAa,EAAE,WAAW,CAAC,wBAAwB,EAAE,qBAAqB,CAAC,aAAa,CAAC;QACzF,SAAS,EAAE,WAAW,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,SAAS,CAAC;QAC7E,UAAU,EAAE,WAAW,CAAC,qBAAqB,EAAE,qBAAqB,CAAC,UAAU,CAAC;QAChF,qBAAqB,EAAE,WAAW,CAChC,iCAAiC,EACjC,qBAAqB,CAAC,qBAAqB,CAC5C;QACD,SAAS,EAAE;YACT,GAAG,EAAE,WAAW,CAAC,iBAAiB,EAAE,qBAAqB,CAAC,SAAS,CAAC,GAAG,CAAC;YACxE,GAAG,EAAE,WAAW,CAAC,iBAAiB,EAAE,qBAAqB,CAAC,SAAS,CAAC,GAAG,CAAC;SACzE;QACD,UAAU,EAAE,WAAW,CAAC,kBAAkB,EAAE,qBAAqB,CAAC,UAAU,CAAC;QAC7E,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;KACpC,CAAC;IAEF,OAAO;QACL,OAAO;QACP,QAAQ;QACR,YAAY;QACZ,YAAY;KACb,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAyB;IACjE,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO;IAE5B,4BAA4B;IAC5B,IAAI,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC;QAC1E,MAAM,IAAI,KAAK,CACb,wCAAwC,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,wBAAwB,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,GAAG,CACtI,CAAC;IACJ,CAAC;IAED,sCAAsC;IACtC,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC,CAAC;IAC/F,IAAI,MAAM,CAAC,YAAY,CAAC,UAAU,GAAG,YAAY,EAAE,CAAC;QAClD,OAAO,CAAC,IAAI,CACV,4BAA4B,MAAM,CAAC,YAAY,CAAC,UAAU,kCAAkC,YAAY,8BAA8B,YAAY,GAAG,CACtJ,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/src/worker/port-allocator.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Port Allocator
+ *
+ * Manages allocation and release of ports for Chrome CDP endpoints.
+ * Tracks which ports are in use and provides the next available port.
+ */
+import type { PortRange } from './types.js';
+/**
+ * Configuration for PortAllocator
+ */
+export interface PortAllocatorConfig {
+    /** Minimum port number (inclusive) */
+    min: number;
+    /** Maximum port number (inclusive) */
+    max: number;
+}
+/**
+ * Manages port allocation for Chrome CDP endpoints.
+ *
+ * @example
+ * ```typescript
+ * const allocator = new PortAllocator({ min: 9300, max: 9399 });
+ *
+ * const port1 = allocator.allocate();  // 9300
+ * const port2 = allocator.allocate();  // 9301
+ *
+ * allocator.release(port1);            // Return 9300 to pool
+ * const port3 = allocator.allocate();  // 9300 (reused)
+ * ```
+ */
+export declare class PortAllocator {
+    private readonly min;
+    private readonly max;
+    private readonly allocatedPorts;
+    constructor(config: PortAllocatorConfig);
+    /**
+     * Get the port range configuration
+     */
+    get portRange(): PortRange;
+    /**
+     * Get the number of currently allocated ports
+     */
+    get allocatedCount(): number;
+    /**
+     * Get the total capacity (max possible allocations)
+     */
+    get capacity(): number;
+    /**
+     * Allocate the next available port.
+     *
+     * @returns The allocated port number
+     * @throws WorkerError with PORT_EXHAUSTED if no ports are available
+     */
+    allocate(): number;
+    /**
+     * Release a previously allocated port back to the pool.
+     *
+     * @param port - The port number to release
+     * @returns true if the port was released, false if it wasn't allocated
+     */
+    release(port: number): boolean;
+    /**
+     * Check if a specific port is currently allocated.
+     *
+     * @param port - The port number to check
+     * @returns true if the port is allocated
+     */
+    isAllocated(port: number): boolean;
+    /**
+     * Check if a port is available for use by attempting to bind to it.
+     * This verifies that no other process is using the port.
+     *
+     * @param port - The port number to check
+     * @returns Promise that resolves to true if the port is available
+     */
+    isPortAvailable(port: number): Promise<boolean>;
+    /**
+     * Allocate a port that is verified to be available on the system.
+     * This is slower than allocate() but ensures the port can actually be used.
+     *
+     * @returns Promise that resolves to the allocated port number
+     * @throws WorkerError with PORT_EXHAUSTED if no available ports are found
+     */
+    allocateVerified(): Promise<number>;
+    /**
+     * Get all currently allocated ports.
+     *
+     * @returns Array of allocated port numbers
+     */
+    getAllocatedPorts(): number[];
+    /**
+     * Reset the allocator, releasing all ports.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=port-allocator.d.ts.map

package/dist/src/worker/port-allocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-allocator.d.ts","sourceRoot":"","sources":["../../../src/worker/port-allocator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;gBAExC,MAAM,EAAE,mBAAmB;IAWvC;;OAEG;IACH,IAAI,SAAS,IAAI,SAAS,CAEzB;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;OAKG;IACH,QAAQ,IAAI,MAAM;IAclB;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC;;;;;;OAMG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBrD;;;;;;OAMG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAqBzC;;;;OAIG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAI7B;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}