distributed-systems

分散システムのパターン

信頼性の高い分散システムを構築するための包括的なパターンです。各カテゴリーには個別のルールファイルがあり、rules/ から必要に応じて読み込まれます。

クイックリファレンス

カテゴリー	ルール	影響度	使用する場面
分散ロック	1	CRITICAL	フェンシングトークン、所有者の検証。Redis/Redlock および Postgres アドバイザリロックについては、上流ドキュメントを参照
レジリエンス	3	CRITICAL	サーキットブレーカー、バックオフ付き再試行、バルクヘッド分離
冪等性	1	HIGH	冪等性キー。重複排除とデータベースを利用したストレージについては、上流ドキュメントを参照
レート制限	2	HIGH	トークンバケット、スライディングウィンドウ。SlowAPI の統合については、上流ドキュメントを参照
エッジコンピューティング	2	HIGH	エッジワーカー、V8 アイソレート、CDN キャッシュ、ジオルーティング
イベント駆動	2	HIGH	イベントソーシング、CQRS、トランザクショナルアウトボックス、サーガ

合計：6 カテゴリーにわたる 11 個のルール。 削除されたトピックについては、上流のカバー範囲にある一次情報を参照してください。ork 固有の知見は references/ork-delta.md にあります。

クイックスタート

# Redis distributed lock with Lua scripts
async with RedisLock(redis_client, "payment:order-123"):
    await process_payment(order_id)

# Circuit breaker for external APIs
@circuit_breaker(failure_threshold=5, recovery_timeout=30)
@retry(max_attempts=3, base_delay=1.0)
async def call_external_api():
    ...

# Idempotent API endpoint
@router.post("/payments")
async def create_payment(
    data: PaymentCreate,
    idempotency_key: str = Header(..., alias="Idempotency-Key"),
):
    return await idempotent_execute(db, idempotency_key, "/payments", process)

# Token bucket rate limiting
limiter = TokenBucketLimiter(redis_client, capacity=100, refill_rate=10)
if await limiter.is_allowed(f"user:{user_id}"):
    await handle_request()

分散ロック

複数のサービスインスタンス間で、リソースへの排他的アクセスを調整します。

ルール	ファイル	主なパターン
フェンシングトークン	rules/locks-fencing-tokens.md	所有者の検証、TTL、ハートビートによる延長

Redis のシングルノードロック、Redlock のクォーラム、PostgreSQL のアドバイザリロックは一次情報で文書化されています。上流のカバー範囲を参照してください。

レジリエンス

本番環境向けの、分散システムにおける高いフォールトトレランスです。

ルール	ファイル	主なパターン
サーキットブレーカー	rules/resilience-circuit-breaker.md	CLOSED／OPEN／HALF_OPEN 状態、スライディングウィンドウ
再試行とバックオフ	rules/resilience-retry-backoff.md	指数バックオフ、ジッター、エラー分類
バルクヘッド分離	rules/resilience-bulkhead.md	セマフォの階層、拒否ポリシー、キューの深さ

冪等性

意図しない副作用を伴わずに、操作を安全に再試行できるようにします。

ルール	ファイル	主なパターン
冪等性キー	rules/idempotency-keys.md	決定論的ハッシュ、Stripe 形式のヘッダー

イベントコンシューマーの重複排除とデータベースを利用した冪等性ストレージには、Stripe のパターンを使用します。上流のカバー範囲を参照してください。

レート制限

Redis を使用した分散レート制限で API を保護します。

ルール	ファイル	主なパターン
トークンバケット	rules/ratelimit-token-bucket.md	Redis Lua スクリプト、バースト容量、補充レート
スライディングウィンドウ	rules/ratelimit-sliding-window.md	ソート済みセット、正確なカウント、境界での急増なし

SlowAPI と Redis の接続設定、および段階的な制限は一次情報で文書化されています。上流のカバー範囲を参照してください。

エッジコンピューティング

Cloudflare Workers、Vercel Edge、Deno Deploy 向けのエッジランタイムパターンです。

ルール	ファイル	主なパターン
エッジワーカー	rules/edge-workers.md	V8 アイソレートの制約、Web API、ジオルーティング、エッジでの認証
エッジキャッシュ	rules/edge-caching.md	エッジでのキャッシュアサイド、CDN ヘッダー、KV ストレージ、stale-while-revalidate

イベント駆動

イベントソーシング、CQRS、サーガのオーケストレーション、信頼性の高いメッセージングのパターンです。

ルール	ファイル	主なパターン
イベントソーシング	rules/event-sourcing.md	イベントソーシングによる集約、CQRS の読み取りモデル、楽観的並行性制御
イベントメッセージング	rules/event-messaging.md	トランザクショナルアウトボックス、サーガの補償、冪等なコンシューマー

上流ドキュメントの対象範囲（再記載しないでください）

これらのトピックは、一次情報源で管理されているため、2026-07-31 にこのスキルから削除されました（wrap-plus-delta による整理）。一次情報源を参照してください。ここにチュートリアルを再追加しないでください。これらのトピックに関する Ork 固有の知見は、references/ork-delta.md にあります。

トピック	一次情報源
Redis の単一ノードロック、Redlock アルゴリズム、クォーラム	https://redis.io/docs/latest/develop/use/patterns/distributed-locks/
PostgreSQL のアドバイザリロック（セッションレベルおよびトランザクションレベル）	https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS
サーキットブレーカーパターン、しきい値、セットアップおよびロールアウトのガイド	https://learn.microsoft.com/azure/architecture/patterns/circuit-breaker
バルクヘッドパターンの詳細（スレッドプール、セマフォ、階層）	https://learn.microsoft.com/azure/architecture/patterns/bulkhead
リトライ戦略、指数バックオフ、ジッター、リトライ予算	https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/ and https://tenacity.readthedocs.io
HTTP および LLM プロバイダーのエラー分類（リトライ可能かどうか）	https://docs.claude.com/en/api/errors and https://platform.openai.com/docs/guides/error-codes
冪等性キー、リクエストの重複排除、データベースを利用した冪等性	https://docs.stripe.com/api/idempotent_requests
トークンバケットアルゴリズムおよび Redis のレート制限パターン	https://redis.io/glossary/rate-limiting/
FastAPI の分散レート制限（SlowAPI ミドルウェア、階層）	https://slowapi.readthedocs.io/
LLM のフォールバックチェーン、プロバイダーのフェイルオーバー、コスト追跡	https://vercel.com/docs/ai-gateway; モデル ID と料金については https://docs.claude.com/en/docs/about-claude/pricing

主要な決定事項

決定事項	推奨
ロックのバックエンド	高速性を重視するなら Redis、すでに使用しているなら PostgreSQL、高可用性を求めるなら Redlock
ロックの TTL	想定される操作時間の 2～3 倍
サーキットブレーカーの復旧	スライディングウィンドウを使用した半開状態でのプローブ
リトライアルゴリズム	指数バックオフ＋フルジッター
バルクヘッドによる分離	セマフォベースの階層（Critical／Standard／Optional）
冪等性の保存先	Redis（高速性）＋ DB（耐久性）、TTL は 24～72 時間
レート制限アルゴリズム	ほとんどの API にはトークンバケット、厳密なクォータにはスライディングウィンドウ
レート制限の保存先	Redis（分散対応、アトミックな Lua スクリプト）

使用しない場合

イベントソーシング／Saga／CQRS 用の独立したスキルは存在しません。これらは分散システム内のルールです。ただし、ほとんどのプロジェクトでは不要です。

パターン	面接	ハッカソン	MVP	成長期	エンタープライズ	よりシンプルな代替手段
イベントソーシング	過剰	過剰	過剰	過剰	正当な理由がある場合	ステータス列を持つ追記専用テーブル
Saga オーケストレーション	過剰	過剰	過剰	選択的	適切	手動ロールバックを伴う逐次サービス呼び出し
サーキットブレーカー	過剰	過剰	境界的	適切	必須	タイムアウト付きの try／except
分散ロック	過剰	過剰	境界的	適切	必須	データベースの行レベルロック（SELECT FOR UPDATE）
CQRS	過剰	過剰	過剰	過剰	正当な理由がある場合	読み取り／書き込みに単一のモデルを使用
トランザクショナルアウトボックス	過剰	過剰	過剰	選択的	適切	コミット後に直接パブリッシュ
レート制限	過剰	過剰	シンプルなもののみ	適切	必須	Nginx のレート制限またはクラウド WAF

経験則： サーバープロセスが 1 つだけなら、分散システムのパターンは不要です。プロセス内の代替手段を使用してください。実際に複数のインスタンスが必要になった場合にのみ、分散化を導入してください。

アンチパターン（禁止）

# LOCKS: Never forget TTL (causes deadlocks)
await redis.set(f"lock:{name}", "1")  # WRONG - no expiry!

# LOCKS: Never release without owner check
await redis.delete(f"lock:{name}")  # WRONG - might release others' lock

# RESILIENCE: Never retry non-retryable errors
@retry(max_attempts=5, retryable_exceptions={Exception})  # Retries 401!

# RESILIENCE: Never put retry outside circuit breaker
@retry  # Would retry when circuit is open!
@circuit_breaker
async def call(): ...

# IDEMPOTENCY: Never use non-deterministic keys
key = str(uuid.uuid4())  # Different every time!

# IDEMPOTENCY: Never cache error responses
if response.status_code >= 400:
    await cache_response(key, response)  # Errors should retry!

# RATE LIMITING: Never use in-memory counters in distributed systems
request_counts = {}  # Lost on restart, not shared across instances

詳細ドキュメント

リソース	説明
scripts/	テンプレート：ロックの実装、サーキットブレーカー、レートリミッター
references/ork-delta.md	wrap-plus-delta による整理後も残された、Ork 固有の知見とプロジェクト内の決定事項

関連スキル

• caching - Redis のキャッシュパターン、フォールバックとしてのキャッシュ
• background-jobs - ジョブの重複排除、リトライを伴う非同期処理
• observability-monitoring - サーキットブレーカーの状態変化に関するメトリクスとアラート
• error-handling-rfc9457 - レジリエンス障害に対する構造化されたエラーレスポンス
• auth-patterns - API キー管理、認証の統合