@reftrixmcp/mcp-server 0.1.7

package/dist/services/worker-stall-recovery.service.d.ts.map

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

package/dist/services/worker-stall-recovery.service.js

@@ -0,0 +1,335 @@
+"use strict";
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PERIODIC_CHECK_INTERVAL_MS = void 0;
+exports.isOrphanedActiveJob = isOrphanedActiveJob;
+exports.categorizeOrphanedJob = categorizeOrphanedJob;
+exports.recoverOrphanedJobs = recoverOrphanedJobs;
+exports.handleStalledJob = handleStalledJob;
+exports.createPeriodicStallCheck = createPeriodicStallCheck;
+/**
+ * Worker Stall Recovery Service
+ *
+ * BullMQジョブのstall検出不能問題に対する回復メカニズム。
+ *
+ * 問題の背景:
+ * - ワーカーがNarrative/Embedding処理中（progress 90%）に再起動されると、
+ *   ジョブがBullMQ上でactive状態のまま孤立する
+ * - lockDuration=2400000ms (40分) 経過後もstall detectionが機能しない場合がある
+ * - ジョブが永久にactive状態で残り、新しいワーカーが取得しない
+ *
+ * 解決策:
+ * 1. ワーカー起動時にorphaned active jobsを検出
+ * 2. BullMQ stalled イベント発火時に即座にカスタム回復を実行
+ * 3. 定期的なstallチェック（10分間隔）で取りこぼしを回復
+ * 4. カテゴリ分類（DB保存済み/処理中断/未開始）に基づく回復アクション
+ * 5. DB保存済みジョブはcompleted/failedに遷移させる
+ *
+ * @module services/worker-stall-recovery
+ */
+const logger_1 = require("../utils/logger");
+const orphaned_job_utils_1 = require("./orphaned-job-utils");
+/** デフォルトの定期チェック間隔: 10分 */
+exports.DEFAULT_PERIODIC_CHECK_INTERVAL_MS = 600_000;
+// ============================================================================
+// Functions
+// ============================================================================
+/**
+ * ジョブがorphaned active jobかどうかを判定する
+ *
+ * 共通ユーティリティ isOrphanedByLockExpiry に委譲する。
+ * BullMQ Jobの詳細情報（state, lockDurationMs）を使用した判定。
+ *
+ * @param jobInfo - ジョブ情報
+ * @returns orphanedであればtrue
+ */
+function isOrphanedActiveJob(jobInfo) {
+    return (0, orphaned_job_utils_1.isOrphanedByLockExpiry)(jobInfo.state, jobInfo.processedOn, jobInfo.lockDurationMs);
+}
+/**
+ * Orphaned jobのカテゴリを分類する
+ *
+ * categorizeByProgress に委譲する。OrphanedJobInfo 構造体を受け取る
+ * 高レベルラッパー。recoverOrphanedJobs から使用される。
+ *
+ * カテゴリに基づいて回復アクションを決定する:
+ * - db_saved_but_stuck: completedに遷移（DB保存済みデータが利用可能）
+ * - processing_interrupted: failedに遷移して再実行可能にする
+ * - never_started: waitingに戻して再処理
+ *
+ * @param jobInfo - ジョブ情報
+ * @returns カテゴリ
+ */
+function categorizeOrphanedJob(jobInfo) {
+    return (0, orphaned_job_utils_1.categorizeByProgress)(jobInfo.progress, jobInfo.processedOn);
+}
+/**
+ * Orphaned active jobsを検出して回復する
+ *
+ * ワーカー起動時に呼び出され、前回のワーカー停止で孤立したジョブを処理する。
+ * BullMQ Queue APIを使用してactive状態のジョブを走査し、
+ * lockDurationを超過しているものを回復する。
+ *
+ * @param getActiveJobs - active状態のジョブを取得する関数（DI）
+ * @param moveToFailed - ジョブをfailedに移動する関数（DI）
+ * @param moveToCompleted - ジョブをcompletedに移動する関数（DI）
+ * @param lockDurationMs - ワーカーのlockDuration設定（ms）
+ * @returns 回復結果
+ */
+async function recoverOrphanedJobs(getActiveJobs, moveToFailed, moveToCompleted, lockDurationMs) {
+    const result = {
+        success: true,
+        recoveredCount: 0,
+        failedCount: 0,
+        details: [],
+    };
+    try {
+        const activeJobs = await getActiveJobs();
+        logger_1.logger.info("[StallRecovery] Checking for orphaned active jobs", {
+            activeJobCount: activeJobs.length,
+            lockDurationMs,
+        });
+        for (const jobInfo of activeJobs) {
+            if (!isOrphanedActiveJob(jobInfo)) {
+                continue;
+            }
+            const category = categorizeOrphanedJob(jobInfo);
+            logger_1.logger.warn("[StallRecovery] Orphaned job detected", {
+                jobId: jobInfo.jobId,
+                category,
+                progress: jobInfo.progress,
+                processedOn: jobInfo.processedOn,
+                url: jobInfo.data.url,
+                webPageId: jobInfo.data.webPageId,
+            });
+            try {
+                switch (category) {
+                    case "db_saved_but_stuck": {
+                        // DB保存済み: completedに遷移
+                        await moveToCompleted(jobInfo.jobId);
+                        result.details.push({
+                            jobId: jobInfo.jobId,
+                            category,
+                            action: "completed",
+                        });
+                        result.recoveredCount++;
+                        break;
+                    }
+                    case "processing_interrupted": {
+                        // 処理中断: failedに遷移（再実行可能）
+                        await moveToFailed(jobInfo.jobId, `Worker restarted during processing (progress: ${jobInfo.progress}%). Job was orphaned and recovered by stall recovery.`);
+                        result.details.push({
+                            jobId: jobInfo.jobId,
+                            category,
+                            action: "moved_to_failed",
+                        });
+                        result.recoveredCount++;
+                        break;
+                    }
+                    case "never_started": {
+                        // 未開始: failedに遷移（ユーザーが再試行を判断）
+                        await moveToFailed(jobInfo.jobId, "Worker restarted before processing started. Job was orphaned and recovered by stall recovery.");
+                        result.details.push({
+                            jobId: jobInfo.jobId,
+                            category,
+                            action: "moved_to_failed",
+                        });
+                        result.recoveredCount++;
+                        break;
+                    }
+                }
+            }
+            catch (recoveryError) {
+                const errorMessage = recoveryError instanceof Error ? recoveryError.message : String(recoveryError);
+                logger_1.logger.error("[StallRecovery] Failed to recover orphaned job", {
+                    jobId: jobInfo.jobId,
+                    category,
+                    error: errorMessage,
+                });
+                result.details.push({
+                    jobId: jobInfo.jobId,
+                    category,
+                    action: "skipped",
+                    error: errorMessage,
+                });
+                result.failedCount++;
+            }
+        }
+        if (result.recoveredCount > 0 || result.failedCount > 0) {
+            logger_1.logger.info("[StallRecovery] Recovery complete", {
+                recoveredCount: result.recoveredCount,
+                failedCount: result.failedCount,
+            });
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger_1.logger.error("[StallRecovery] Recovery process failed", {
+            error: errorMessage,
+        });
+        result.success = false;
+    }
+    return result;
+}
+// ============================================================================
+// Single Stalled Job Handler (BullMQ stalled event 用)
+// ============================================================================
+/**
+ * BullMQ stalled イベントで発火する単一ジョブ回復ハンドラー
+ *
+ * BullMQ Worker.on('stalled', jobId) から呼ばれ、stalledジョブを
+ * progressに基づいて completed または failed に遷移させる。
+ *
+ * BullMQ の stalled イベントは、ジョブのロックが既に失効した状態で発火する。
+ * この時点でジョブは再び waiting に戻されるか、maxStalledCount 超過で
+ * failed に移動される。本ハンドラーは BullMQ の内部処理「後」に追加の
+ * 回復アクション（DB保存済みジョブの完了遷移等）を行う。
+ *
+ * @param jobId - stalled となったジョブのID
+ * @param accessor - ジョブ操作のDI
+ * @returns 回復結果
+ */
+async function handleStalledJob(jobId, accessor) {
+    logger_1.logger.warn("[StallRecovery] Handling stalled job event", { jobId });
+    try {
+        const job = await accessor.getJob(jobId);
+        if (!job) {
+            logger_1.logger.warn("[StallRecovery] Stalled job not found (already removed or completed)", {
+                jobId,
+            });
+            return {
+                success: true,
+                jobId,
+                category: null,
+                action: "not_found",
+            };
+        }
+        const state = await job.getState();
+        const progress = typeof job.progress === "number" ? job.progress : 0;
+        logger_1.logger.info("[StallRecovery] Stalled job state", {
+            jobId,
+            state,
+            progress,
+            processedOn: job.processedOn,
+            url: job.data.url,
+            webPageId: job.data.webPageId,
+        });
+        // BullMQ may have already moved the job to failed (maxStalledCount exceeded)
+        // or back to waiting (stall retry). Only act on active/waiting jobs.
+        if (state === "completed") {
+            return {
+                success: true,
+                jobId,
+                category: null,
+                action: "skipped",
+            };
+        }
+        // Determine category based on progress
+        const category = (0, orphaned_job_utils_1.categorizeByProgress)(progress, job.processedOn);
+        if (category === "db_saved_but_stuck") {
+            // DB保存済み: completedに遷移
+            // token '0' は orphaned (lock-expired) ジョブの遷移に使用する慣例
+            logger_1.logger.info("[StallRecovery] Moving DB-saved stalled job to completed", {
+                jobId,
+                progress,
+                webPageId: job.data.webPageId,
+            });
+            await job.moveToCompleted({
+                webPageId: job.data.webPageId,
+                success: true,
+                partialSuccess: true,
+                completedPhases: [],
+                failedPhases: [],
+                processingTimeMs: 0,
+                completedAt: new Date().toISOString(),
+            }, "0", false);
+            return {
+                success: true,
+                jobId,
+                category,
+                action: "completed",
+            };
+        }
+        // For processing_interrupted and never_started:
+        // BullMQ's built-in stall handler already moves to failed after maxStalledCount.
+        // If the job is still active/waiting, force it to failed for visibility.
+        if (state === "active" || state === "waiting") {
+            const reason = category === "processing_interrupted"
+                ? `worker_restart_during_processing (progress: ${progress}%)`
+                : "worker_restart_before_processing";
+            logger_1.logger.info("[StallRecovery] Moving stalled job to failed", {
+                jobId,
+                category,
+                progress,
+                reason,
+            });
+            await job.moveToFailed(new Error(`Stall recovery: ${reason}`), "0", false);
+            return {
+                success: true,
+                jobId,
+                category,
+                action: "moved_to_failed",
+            };
+        }
+        // Job is already in failed/delayed state — no action needed
+        return {
+            success: true,
+            jobId,
+            category,
+            action: "skipped",
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger_1.logger.error("[StallRecovery] Failed to handle stalled job", {
+            jobId,
+            error: errorMessage,
+        });
+        return {
+            success: false,
+            jobId,
+            category: null,
+            action: "skipped",
+            error: errorMessage,
+        };
+    }
+}
+// ============================================================================
+// Periodic Stall Check
+// ============================================================================
+/**
+ * 定期的なstallチェックを開始する
+ *
+ * BullMQの内蔵stall検出に依存せず、独立した間隔でorphaned jobsを検出・回復する。
+ * CPU-bound処理（ONNX推論）がイベントループをブロックし、BullMQのstalledInterval
+ * タイマーが発火しない場合のセーフティネット。
+ *
+ * @param getActiveJobs - active状態のジョブを取得する関数（DI）
+ * @param moveToFailed - ジョブをfailedに移動する関数（DI）
+ * @param moveToCompleted - ジョブをcompletedに移動する関数（DI）
+ * @param config - 定期チェック設定
+ * @returns タイマーを停止するcleanup関数
+ */
+function createPeriodicStallCheck(getActiveJobs, moveToFailed, moveToCompleted, config) {
+    const intervalMs = config.intervalMs ?? exports.DEFAULT_PERIODIC_CHECK_INTERVAL_MS;
+    logger_1.logger.info("[StallRecovery] Starting periodic stall check", {
+        intervalMs,
+        lockDurationMs: config.lockDurationMs,
+    });
+    const timerId = setInterval(() => {
+        recoverOrphanedJobs(getActiveJobs, moveToFailed, moveToCompleted, config.lockDurationMs).catch((error) => {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger_1.logger.error("[StallRecovery] Periodic stall check failed", { error: errorMessage });
+        });
+    }, intervalMs);
+    // unref() so the timer doesn't prevent process exit
+    timerId.unref();
+    return {
+        stop: () => {
+            clearInterval(timerId);
+            logger_1.logger.info("[StallRecovery] Periodic stall check stopped");
+        },
+    };
+}
+//# sourceMappingURL=worker-stall-recovery.service.js.map

package/dist/services/worker-stall-recovery.service.js.map

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

package/dist/services/worker-supervisor.service.d.ts

@@ -0,0 +1,145 @@
+/**
+ * WorkerSupervisor Service
+ *
+ * page.analyzeワーカープロセスのライフサイクルを自動管理するサービス。
+ * OOM問題（16GBヒープ上限で2-3サイト後にクラッシュ）をプロセス再起動で解決する。
+ *
+ * 機能:
+ * - child_process.fork でワーカーを子プロセスとして起動
+ * - N件のジョブ完了後にワーカーを再起動（メモリリーク蓄積を防止）
+ * - クラッシュ時の自動再起動（exit code/signal 両対応）
+ * - graceful shutdown（SIGTERM → タイムアウト → SIGKILL エスカレーション）
+ * - maxRestartAttempts による連続クラッシュ時の停止
+ *
+ * @module services/worker-supervisor
+ */
+import { type ChildProcess } from "node:child_process";
+/**
+ * WorkerSupervisorの設定オプション
+ */
+export interface WorkerSupervisorOptions {
+    /** ワーカースクリプトのパス（fork対象） */
+    workerScript: string;
+    /** fork時のオプション引数 */
+    workerArgs?: string[];
+    /** fork時の環境変数（process.env にマージ） */
+    workerEnv?: Record<string, string>;
+    /** N件完了後にワーカーを再起動する（OOM回避） */
+    maxJobsBeforeRestart: number;
+    /** クラッシュ時の最大再起動試行回数 */
+    maxRestartAttempts: number;
+    /** graceful shutdown のタイムアウト（ms）。超過でSIGKILL送信 */
+    shutdownTimeoutMs: number;
+    /** 再起動間の最小間隔（ms）。連続クラッシュのスロットリング */
+    restartDelayMs?: number;
+}
+/**
+ * WorkerSupervisorの状態
+ */
+export type WorkerState = "idle" | "running" | "restarting" | "stopped" | "crashed";
+/**
+ * ワーカーからスーパーバイザーへのIPCメッセージ型
+ *
+ * P1-D: job-completed — BullMQ Worker.on('completed') で送信。
+ *       maxJobsBeforeRestart カウンタの駆動に使用。
+ */
+export interface WorkerMessage {
+    type: "job-completed";
+    jobId?: string;
+}
+/**
+ * ワーカープロセスの監視・再起動を行うスーパーバイザー
+ *
+ * child_process.fork で子プロセスとしてワーカーを起動し、
+ * OOMクラッシュや計画的なメモリリフレッシュのためにプロセスを自動再起動する。
+ */
+export declare class WorkerSupervisor {
+    private readonly config;
+    private worker;
+    private state;
+    private completedJobCount;
+    private restartCount;
+    private isShuttingDown;
+    private pendingRestart;
+    constructor(options: WorkerSupervisorOptions);
+    /**
+     * ワーカーが起動していなければ起動する
+     *
+     * 冪等操作: 既にrunning状態なら何もしない。
+     * crashed/idle 状態なら新しいワーカーを fork する。
+     */
+    ensureWorkerRunning(): void;
+    /**
+     * 現在のワーカー状態を取得
+     */
+    getState(): WorkerState;
+    /**
+     * 完了ジョブカウントを取得
+     */
+    getCompletedJobCount(): number;
+    /**
+     * 再起動回数を取得
+     */
+    getRestartCount(): number;
+    /**
+     * ジョブ完了を通知
+     *
+     * 内部カウンタをインクリメントし、maxJobsBeforeRestart に達したら
+     * ワーカーを graceful restart する。
+     */
+    notifyJobCompleted(): void;
+    /**
+     * graceful shutdown
+     *
+     * 3段階のシャットダウンプロトコル:
+     * 1. IPCメッセージ 'shutdown' を送信 → BullMQ Worker.close() を先行実行させる
+     * 2. SIGTERM を送信 → プロセスレベルの graceful shutdown
+     * 3. shutdownTimeoutMs 超過時 → SIGKILL エスカレーション
+     *
+     * IPCメッセージ送信により、BullMQ Workerがclose()を完了してからプロセスが
+     * 終了する機会を確保する。これにより、処理中のジョブがorphanedになるリスクを軽減する。
+     *
+     * ワーカー未起動時はエラーなしで即座に完了する。
+     */
+    shutdown(): Promise<void>;
+    /**
+     * ワーカーの ChildProcess を取得（テスト/モニタリング用）
+     */
+    getWorkerProcess(): ChildProcess | null;
+    /**
+     * ワーカーを fork で起動する
+     */
+    private spawnWorker;
+    /**
+     * ワーカーの exit イベントを処理する
+     *
+     * shutdown 中でなければ自動再起動を試みる。
+     * maxRestartAttempts を超過した場合は crashed 状態に遷移する。
+     */
+    private handleWorkerExit;
+    /**
+     * 計画的再起動を開始する
+     *
+     * P1-E: shutdown() と同じ3-Phase Shutdown Protocol を適用。
+     * 直接SIGTERMを送信するのではなく、IPC shutdown → 猶予 → SIGTERM → タイムアウト → SIGKILL
+     * の順序でワーカーを停止し、BullMQ Worker.close() によるロック解放を保証する。
+     * exit ハンドラーで pendingRestart フラグを検出して再起動をスケジュールする。
+     */
+    private initiateRestart;
+    /**
+     * 遅延後にワーカーを再起動する
+     */
+    private scheduleRestart;
+}
+/**
+ * デフォルト設定で WorkerSupervisor シングルトンを取得する
+ *
+ * page.analyze ハンドラーから呼び出される。
+ * 設定は環境変数から読み取る。
+ */
+export declare function getWorkerSupervisor(): WorkerSupervisor;
+/**
+ * シングルトンインスタンスをリセットする（テスト用）
+ */
+export declare function resetWorkerSupervisor(): void;
+//# sourceMappingURL=worker-supervisor.service.d.ts.map

package/dist/services/worker-supervisor.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-supervisor.service.d.ts","sourceRoot":"","sources":["../../src/services/worker-supervisor.service.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAQ,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA8G7D;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,8BAA8B;IAC9B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uBAAuB;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA2BD;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CACqC;IAC5D,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAAS;gBAEnB,OAAO,EAAE,uBAAuB;IAO5C;;;;;OAKG;IACH,mBAAmB,IAAI,IAAI;IA8B3B;;OAEG;IACH,QAAQ,IAAI,WAAW;IAIvB;;OAEG;IACH,oBAAoB,IAAI,MAAM;IAI9B;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;OAKG;IACH,kBAAkB,IAAI,IAAI;IAgB1B;;;;;;;;;;;;OAYG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAkF/B;;OAEG;IACH,gBAAgB,IAAI,YAAY,GAAG,IAAI;IAQvC;;OAEG;IACH,OAAO,CAAC,WAAW;IAqFnB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IA6CxB;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAwEvB;;OAEG;IACH,OAAO,CAAC,eAAe;CAcxB;AAQD;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAqDtD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}