threadforge 0.1.1 → 0.2.1

package/dist/core/Supervisor.d.ts

@@ -0,0 +1,198 @@
+import { type Worker } from "node:cluster";
+import { EventEmitter } from "node:events";
+import { type Server as HttpServer } from "node:http";
+import { ServiceRegistry } from "../registry/ServiceRegistry.js";
+import type { ScaleRecommendation } from "../scaling/ScaleAdvisor.js";
+import { ScaleAdvisor } from "../scaling/ScaleAdvisor.js";
+import { AlertSink } from "./AlertSink.js";
+import type { Channel, NormalizedConfig, NormalizedService, ProcessGroup } from "./config.js";
+import { type RegistryMode as RegistryModeValue, type ServiceType as ServiceTypeValue } from "./config-enums.js";
+import { DirectMessageBus } from "./DirectMessageBus.js";
+import { ThreadAllocator } from "./ThreadAllocator.js";
+interface WorkerMapEntry {
+    groupName: string;
+    services: string[];
+    workerId: number;
+}
+interface RestartHistory {
+    count: number;
+    firstRestart: number;
+    lastRestart: number;
+}
+interface MetricsSnapshot {
+    expected: Set<number>;
+    chunks: string[];
+    timer: ReturnType<typeof setTimeout>;
+    finish: () => void;
+}
+interface PortTarget {
+    port: number;
+    purpose: string;
+}
+interface ParsedAddress {
+    host: string;
+    port: number;
+}
+interface EndpointEntry {
+    host: string;
+    port?: number;
+    remote: boolean;
+    uds?: string | null;
+    group?: string;
+}
+export interface StatusGroup {
+    group: string;
+    services: {
+        name: string;
+        type: ServiceTypeValue;
+        port: number | null;
+    }[];
+    workers: number;
+    pids: number[];
+}
+interface StatusResult {
+    supervisorPid: number;
+    uptime: number;
+    totalCpus: number;
+    nodeId: string;
+    host: string;
+    registryMode: RegistryModeValue;
+    processGroups: StatusGroup[];
+    channels: Channel[];
+    totalProcesses: number;
+    totalServices: number;
+    remoteServices: number;
+    portsUsed: (number | null)[];
+    messageBus: Record<string, unknown>;
+    topology: Record<string, unknown[]>;
+    scalingRecommendations: ScaleRecommendation[];
+    hostMode?: boolean;
+    domain?: string | null;
+    projects?: Record<string, unknown>;
+    platformMode?: boolean;
+}
+interface SupervisorOptions {
+    cpus?: number;
+    reserved?: number;
+    registryMode?: RegistryModeValue;
+    host?: string;
+    httpBasePort?: number;
+    evaluationIntervalMs?: number;
+}
+interface ForgeWorkerMessage {
+    type: string;
+    requestId?: string;
+    error?: string;
+    message?: string;
+    port?: number;
+    metrics?: string;
+    [key: string]: unknown;
+}
+interface ForgePlugin {
+    name?: string;
+    validate?: () => Promise<void>;
+    env?: () => Record<string, string>;
+}
+/**
+ * Supervisor v2
+ *
+ * Key differences from v1:
+ *
+ *  - Understands service types (edge/internal/background)
+ *  - Only edge services get HTTP servers
+ *  - Colocated services share a process (same event loop)
+ *  - Channels are dependency-based, not full mesh
+ *  - Thread allocation is per process group, not per service
+ */
+export declare class Supervisor extends EventEmitter {
+    config: NormalizedConfig;
+    services: Record<string, NormalizedService>;
+    groups: Record<string, ProcessGroup>;
+    channels: Channel[];
+    options: SupervisorOptions;
+    allocator: ThreadAllocator;
+    messageBus: DirectMessageBus;
+    registry: ServiceRegistry;
+    scaleAdvisor: ScaleAdvisor;
+    alertSink: AlertSink;
+    plugins: ForgePlugin[];
+    _pluginEnv: Record<string, string>;
+    _failedPlugins: Set<string>;
+    workerMap: Map<number, WorkerMapEntry>;
+    groupWorkers: Map<string, number[]>;
+    allocation: Map<string, number>;
+    _metricsServer: HttpServer | null;
+    _shuttingDown: boolean;
+    _restartHistory: Map<string, RestartHistory>;
+    _scalingDown: Set<number>;
+    _pendingRestarts: Map<string, ReturnType<typeof setTimeout>>;
+    _killTimers: Map<number, ReturnType<typeof setTimeout>>;
+    _restartWarningTimes: Map<string, number>;
+    _endpointTempFile: string | null;
+    _sitesTempFile: string | null;
+    _metricsRequestSeq: number;
+    _pendingMetricsSnapshots: Map<string, MetricsSnapshot>;
+    _groupReadyWorkers: Map<string, Set<number>>;
+    _groupReadyLogged: Set<string>;
+    _nextWorkerIndex: Record<string, number>;
+    _heartbeatInterval: ReturnType<typeof setInterval> | null;
+    _lastHeartbeat: Map<number, number>;
+    _workersReady: Map<number, boolean>;
+    _workerRestartCount: number;
+    _workerErrorGuards: WeakSet<object>;
+    _cachedEndpointJson: string | undefined;
+    _pidFilePath: string | null;
+    constructor(config: NormalizedConfig, options?: SupervisorOptions);
+    start(): Promise<void>;
+    /**
+     * Allocate threads per process group.
+     *
+     * Each group gets threads based on the highest weight of its member
+     * services. Colocated services share their group's allocation.
+     */
+    _allocateGroups(): void;
+    /**
+     * Fork a worker for a process group.
+     *
+     * The worker will load ALL services in the group within a single
+     * process. Colocated services communicate via direct function calls.
+     */
+    _forkGroupWorker(groupName: string, group: ProcessGroup, workerIndex: number): Worker;
+    _attachWorkerErrorGuard(worker: Worker, groupName: string, serviceNames: string[], workerIndex: number): void;
+    _sendWorkerMessage(worker: Worker, message: Record<string, unknown>, label?: string): boolean;
+    _handleWorkerMessage(worker: Worker, msg: ForgeWorkerMessage): void;
+    _mergePrometheusExpositions(expositions: string[]): string;
+    _collectMetricsSnapshot(timeoutMs?: number): Promise<string>;
+    _handleWorkerExit(worker: Worker, code: number, signal: string): void;
+    _startupPortsToCheck(): PortTarget[];
+    _isPortAvailable(port: number, host?: string): Promise<boolean>;
+    _assertStartupPortsAvailable(): Promise<void>;
+    scale(groupName: string, newCount: number): Promise<void>;
+    /**
+     * H-5: Start heartbeat monitor — checks worker health every 30s.
+     * Warns after 60s of silence, kills after 90s.
+     */
+    _startHeartbeatMonitor(): void;
+    _stopHeartbeatMonitor(): void;
+    shutdown(): Promise<void>;
+    _startMetricsServer(): Promise<void>;
+    _status(): StatusResult;
+    /**
+     * Build endpoint map for workers.
+     *
+     * Maps each service to { host, port, remote } or an array of endpoints
+     * for multi-instance services. Remote services get their address parsed
+     * into host/port. Local services get host: '127.0.0.1'.
+     */
+    _buildEndpointMap(): Record<string, EndpointEntry>;
+    /**
+     * Parse a service address string into host/port.
+     * Supports: "http://host:port", "host:port", and other URL schemes
+     */
+    _parseAddress(address: string | undefined, serviceName: string): ParsedAddress | null;
+    _printAllocation(): void;
+    _printTopology(): void;
+    _banner(): string;
+}
+export {};
+//# sourceMappingURL=Supervisor.d.ts.map

package/dist/core/Supervisor.d.ts.map

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