FireCrawl 信頼性パターン

概要

FireCrawl 統合のための本番環境グレードの信頼性パターンです。

前提条件

• サーキットブレーカーパターンの理解
• opossum または同様のライブラリのインストール
• DLQ 用のキューインフラストラクチャ
• フォールバック用のキャッシングレイヤー

サーキットブレーカー

import CircuitBreaker from 'opossum';

const firecrawlBreaker = new CircuitBreaker(
  async (operation: () => Promise<any>) => operation(),
  {
    timeout: 30000,
    errorThresholdPercentage: 50,
    resetTimeout: 30000,
    volumeThreshold: 10,
  }
);

// イベント
firecrawlBreaker.on('open', () => {
  console.warn('FireCrawl circuit OPEN - requests failing fast');
  alertOps('FireCrawl circuit breaker opened');
});

firecrawlBreaker.on('halfOpen', () => {
  console.info('FireCrawl circuit HALF-OPEN - testing recovery');
});

firecrawlBreaker.on('close', () => {
  console.info('FireCrawl circuit CLOSED - normal operation');
});

// 使用方法
async function safeFireCrawlCall<T>(fn: () => Promise<T>): Promise<T> {
  return firecrawlBreaker.fire(fn);
}

べき等性キー

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// 入力から決定論的なべき等性キーを生成
function generateIdempotencyKey(
  operation: string,
  params: Record<string, any>
): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

// または、ストレージを使用してランダムキーを使用
class IdempotencyManager {
  private store: Map<string, { key: string; expiresAt: Date }> = new Map();

  getOrCreate(operationId: string): string {
    const existing = this.store.get(operationId);
    if (existing && existing.expiresAt > new Date()) {
      return existing.key;
    }

    const key = uuidv4();
    this.store.set(operationId, {
      key,
      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
    });
    return key;
  }
}

バルクヘッドパターン

import PQueue from 'p-queue';

// 異なる操作用の個別キュー
const firecrawlQueues = {
  critical: new PQueue({ concurrency: 10 }),
  normal: new PQueue({ concurrency: 5 }),
  bulk: new PQueue({ concurrency: 2 }),
};

async function prioritizedFireCrawlCall<T>(
  priority: 'critical' | 'normal' | 'bulk',
  fn: () => Promise<T>
): Promise<T> {
  return firecrawlQueues[priority].add(fn);
}

// 使用方法
await prioritizedFireCrawlCall('critical', () =>
  firecrawlClient.processPayment(order)
);

await prioritizedFireCrawlCall('bulk', () =>
  firecrawlClient.syncCatalog(products)
);

タイムアウト階層

const TIMEOUT_CONFIG = {
  connect: 5000,      // 初期接続
  request: 30000,     // 標準リクエスト
  upload: 120000,     // ファイルアップロード
  longPoll: 300000,   // Webhook ロングポーリング
};

async function timedoutFireCrawlCall<T>(
  operation: 'connect' | 'request' | 'upload' | 'longPoll',
  fn: () => Promise<T>
): Promise<T> {
  const timeout = TIMEOUT_CONFIG[operation];

  return Promise.race([
    fn(),
    new Promise<never>((_, reject) =>
      setTimeout(() => reject(new Error(`FireCrawl ${operation} timeout`)), timeout)
    ),
  ]);
}

グレースフルデグラデーション

interface FireCrawlFallback {
  enabled: boolean;
  data: any;
  staleness: 'fresh' | 'stale' | 'very_stale';
}

async function withFireCrawlFallback<T>(
  fn: () => Promise<T>,
  fallbackFn: () => Promise<T>
): Promise<{ data: T; fallback: boolean }> {
  try {
    const data = await fn();
    // 将来のフォールバック用にキャッシュを更新
    await updateFallbackCache(data);
    return { data, fallback: false };
  } catch (error) {
    console.warn('FireCrawl failed, using fallback:', error.message);
    const data = await fallbackFn();
    return { data, fallback: true };
  }
}

デッドレターキュー

interface DeadLetterEntry {
  id: string;
  operation: string;
  payload: any;
  error: string;
  attempts: number;
  lastAttempt: Date;
}

class FireCrawlDeadLetterQueue {
  private queue: DeadLetterEntry[] = [];

  add(entry: Omit<DeadLetterEntry, 'id' | 'lastAttempt'>): void {
    this.queue.push({
      ...entry,
      id: uuidv4(),
      lastAttempt: new Date(),
    });
  }

  async processOne(): Promise<boolean> {
    const entry = this.queue.shift();
    if (!entry) return false;

    try {
      await firecrawlClient[entry.operation](entry.payload);
      console.log(`DLQ: Successfully reprocessed ${entry.id}`);
      return true;
    } catch (error) {
      entry.attempts++;
      entry.lastAttempt = new Date();

      if (entry.attempts < 5) {
        this.queue.push(entry);
      } else {
        console.error(`DLQ: Giving up on ${entry.id} after 5 attempts`);
        await alertOnPermanentFailure(entry);
      }
      return false;
    }
  }
}

劣化状態を考慮したヘルスチェック

type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';

async function firecrawlHealthCheck(): Promise<{
  status: HealthStatus;
  details: Record<string, any>;
}> {
  const checks = {
    api: await checkApiConnectivity(),
    circuitBreaker: firecrawlBreaker.stats(),
    dlqSize: deadLetterQueue.size(),
  };

  const status: HealthStatus =
    !checks.api.connected ? 'unhealthy' :
    checks.circuitBreaker.state === 'open' ? 'degraded' :
    checks.dlqSize > 100 ? 'degraded' :
    'healthy';

  return { status, details: checks };
}

手順

ステップ 1: サーキットブレーカーを実装する

FireCrawl 呼び出しをサーキットブレーカーでラップします。

ステップ 2: べき等性キーを追加する

操作のための決定論的キーを生成します。

ステップ 3: バルクヘッドを設定する

異なる優先度のための個別キューを分離します。

ステップ 4: デッドレターキューを設定する

永続的な障害をグレースフルに処理します。

出力

• FireCrawl 呼び出しを保護するサーキットブレーカー
• 重複を防ぐべき等性
• バルクヘッド隔離を実装
• 失敗した操作用の DLQ

エラーハンドリング

問題	原因	解決策
サーキットが開いたままになる	しきい値が低すぎる	エラー率を調整する
重複した操作	べき等性がない	べき等性キーを追加する
キューが満杯	レートが高すぎる	並行数を増やす
DLQ が増加している	永続的な障害	根本原因を調査する

例

クイックサーキット確認

const state = firecrawlBreaker.stats().state;
console.log('FireCrawl circuit:', state);

リソース

• Circuit Breaker Pattern
• Opossum Documentation
• FireCrawl Reliability Guide

次のステップ

ポリシー強制については、firecrawl-policy-guardrails を参照してください。