# 機能設計書 12-キュー管理

## 概要

本ドキュメントは、Laravel Frameworkのキュー管理（QueueManager）機能の設計を詳細に記述したものである。非同期ジョブ処理のためのキュー接続管理と、複数のキュードライバをサポートする統合インターフェースを提供する。

### 本機能の処理概要

キュー管理機能は、アプリケーションの非同期処理基盤を提供し、時間のかかるタスクをバックグラウンドで実行することでユーザーエクスペリエンスとシステムスループットを向上させる。

**業務上の目的・背景**：Webアプリケーションにおいて、メール送信、画像処理、レポート生成などの時間のかかる処理をリクエスト・レスポンスサイクル内で完了させることは、ユーザー体験を著しく損なう。キュー管理機能は、これらの処理を非同期化することで、即時レスポンスを可能にし、システムリソースの効率的な活用を実現する。また、処理の分散化により、負荷の平準化とスケーラビリティの向上に貢献する。

**機能の利用シーン**：
- メール・通知の非同期送信
- 画像・動画のサムネイル生成
- 大量データのインポート・エクスポート
- 外部APIとの連携処理
- 定期的なデータ集計・レポート生成
- 検索インデックスの更新

**主要な処理内容**：
1. キュー接続の解決と管理（connection メソッド）
2. 複数ドライバの統合（Sync、Database、Redis、Beanstalkd、SQS）
3. キュードライバコネクタの登録（addConnector、extend メソッド）
4. キューの一時停止・再開（pause、resume、isPaused メソッド）
5. ジョブライフサイクルイベントの発行（before、after、failing 等）
6. デフォルトドライバの取得・設定

**関連システム・外部連携**：
- キャッシュシステム：キュー一時停止状態の管理
- イベントシステム：ジョブライフサイクルイベントの発行
- 外部キューサービス：Amazon SQS、Beanstalkd等

**権限による制御**：キュー管理自体は権限制御を持たないが、キューに投入されるジョブ内で個別の権限チェックを実装可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能は画面に直接関連しない |

## 機能種別

データ連携 / 非同期処理 / インフラストラクチャ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string/null | No | キュー接続名、nullでデフォルト | 設定存在チェック |
| driver | string | Yes（addConnector時） | ドライバ名 | 登録済みコネクタ存在チェック |
| resolver | Closure | Yes（addConnector時） | コネクタ解決クロージャ | callable |
| connection | string | Yes（pause/resume時） | 接続名 | - |
| queue | string | Yes（pause/resume時） | キュー名 | - |
| ttl | DateTimeInterface/DateInterval/int | No（pauseFor時） | 一時停止期間 | 正の数値 |

### 入力データソース

- 設定ファイル：`config/queue.php` からキュー接続設定を取得
- ランタイム：サービスプロバイダーからのコネクタ登録

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| connection | Queue | 解決されたキュー接続インスタンス |
| connected | bool | 指定接続が解決済みか |
| defaultDriver | string | デフォルトドライバ名 |
| isPaused | bool | キューが一時停止中か |

### 出力先

- メモリ：解決済み接続のキャッシュ（$connections）
- キャッシュストア：一時停止状態

## 処理フロー

### 処理シーケンス

```
1. 接続の要求
   └─ connection($name) 呼び出し
2. 接続名の解決
   └─ nullの場合はデフォルトドライバを使用
3. キャッシュチェック
   └─ 既に解決済みの接続があれば再利用
4. 設定の取得
   └─ queue.connections.{name} から設定読み込み
5. コネクタの取得
   └─ 設定のdriverに対応するコネクタを取得
6. 接続の生成
   └─ コネクタのconnect()で接続インスタンス生成
7. コンテナ・接続名の設定
   └─ setContainer, setConnectionName 呼び出し
8. 接続のキャッシュ
   └─ $connections 配列に保存
```

### フローチャート

```mermaid
flowchart TD
    A[connection 呼び出し] --> B{接続名指定?}
    B -->|No| C[デフォルトドライバ取得]
    B -->|Yes| D{キャッシュ済み?}
    C --> D
    D -->|Yes| E[キャッシュから返却]
    D -->|No| F[設定取得]
    F --> G{設定存在?}
    G -->|No| H[InvalidArgumentException]
    G -->|Yes| I[コネクタ取得]
    I --> J[connect 実行]
    J --> K[コンテナ設定]
    K --> L[キャッシュに保存]
    L --> M[接続を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-12-01 | 遅延解決 | 接続は実際に使用されるまで解決されない | connection呼び出し時 |
| BR-12-02 | 接続再利用 | 同一接続名の接続はキャッシュして再利用 | 2回目以降のconnection呼び出し |
| BR-12-03 | nullドライバ | 接続名がnullまたは'null'の場合はnullドライバを使用 | getConfig時 |
| BR-12-04 | 一時停止伝播 | キューを一時停止するとワーカーがジョブ取得を停止 | pause呼び出し時 |

### 計算ロジック

```php
// デフォルトドライバの取得
defaultDriver = config('queue.default')

// 接続名の解決
resolvedName = name ?? defaultDriver

// 一時停止キャッシュキー
pauseKey = "illuminate:queue:paused:{connection}:{queue}"
```

## データベース操作仕様

### 操作別データベース影響一覧

QueueManagerは直接データベースを操作しない。Databaseドライバ使用時は、解決されたDatabaseQueue接続がjobsテーブルを操作する。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | QueueManager自体はDB操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidArgumentException | 未設定の接続名を指定 | 設定ファイルに接続を追加 |
| - | InvalidArgumentException | 未登録のドライバを指定 | コネクタを登録 |

### リトライ仕様

QueueManager自体にリトライ機構はない。ジョブのリトライはWorkerクラスが担当。

## トランザクション仕様

キュー管理はトランザクションを使用しない。ジョブ投入時のトランザクション連携は各Queueドライバの責務。

## パフォーマンス要件

- 接続解決は遅延実行（Lazy Loading）
- 解決済み接続はメモリにキャッシュ
- 一時停止状態チェックはキャッシュベース

## セキュリティ考慮事項

- ジョブペイロードは暗号化可能（設定依存）
- SQS使用時はIAMロールによるアクセス制御
- Redis使用時は認証・TLS設定を推奨

## 備考

- FactoryContractとMonitorContractの両インターフェースを実装
- __callマジックメソッドでデフォルト接続にメソッドを委譲

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、キュー管理が保持するデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | QueueManager.php | `src/Illuminate/Queue/QueueManager.php` | プロパティ定義（$app, $connections, $connectors）を確認 |

**読解のコツ**: QueueManagerは3つの主要プロパティを持つ。`$app`はアプリケーションコンテナ、`$connections`は解決済み接続のキャッシュ、`$connectors`はドライバごとのコネクタファクトリである。

#### Step 2: エントリーポイントを理解する

接続解決のエントリーポイントを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | QueueManager.php | `src/Illuminate/Queue/QueueManager.php` | connectionメソッド（140-154行目）で接続解決 |
| 2-2 | QueueManager.php | `src/Illuminate/Queue/QueueManager.php` | resolveメソッド（164-181行目）で接続インスタンス生成 |

**主要処理フロー**:
1. **140-154行目**: `connection` - 接続名を解決し、キャッシュチェック後に新規解決
2. **164-181行目**: `resolve` - 設定取得、コネクタ取得、接続生成の一連の流れ
3. **191-198行目**: `getConnector` - ドライバに対応するコネクタを取得

#### Step 3: イベント管理を理解する

ジョブライフサイクルイベントの登録を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | QueueManager.php | `src/Illuminate/Queue/QueueManager.php` | before/after/failingメソッド（52-99行目）でイベント登録 |
| 3-2 | QueueManager.php | `src/Illuminate/Queue/QueueManager.php` | starting/stoppingメソッド（107-121行目）でワーカーイベント登録 |

**主要処理フロー**:
- **52-55行目**: `before` - JobProcessingイベントのリスナー登録
- **63-66行目**: `after` - JobProcessedイベントのリスナー登録
- **96-99行目**: `failing` - JobFailedイベントのリスナー登録

#### Step 4: キュー制御を理解する

キューの一時停止・再開機能を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | QueueManager.php | `src/Illuminate/Queue/QueueManager.php` | pause/pauseFor/resumeメソッド（207-253行目） |
| 4-2 | QueueManager.php | `src/Illuminate/Queue/QueueManager.php` | isPausedメソッド（262-267行目） |

**主要処理フロー**:
- **207-216行目**: `pause` - キャッシュにforeverで一時停止フラグ設定
- **226-235行目**: `pauseFor` - TTL付きで一時停止フラグ設定
- **244-253行目**: `resume` - キャッシュから一時停止フラグを削除

### プログラム呼び出し階層図

```
QueueManager::connection($name)
    │
    ├─ QueueManager::getDefaultDriver()
    │      └─ config('queue.default')
    │
    ├─ QueueManager::resolve($name)
    │      ├─ QueueManager::getConfig($name)
    │      │      └─ config("queue.connections.{$name}")
    │      │
    │      ├─ QueueManager::getConnector($driver)
    │      │      └─ $this->connectors[$driver]()
    │      │
    │      └─ Connector::connect($config)
    │             └─ new SyncQueue / DatabaseQueue / RedisQueue / etc.
    │
    └─ Queue::setContainer($app)
           └─ Queue::setConnectionName($name)
```

### データフロー図

```
[入力]                    [処理]                         [出力]

接続名             ───▶  getDefaultDriver()      ───▶  解決済み接続名
    │                        │
設定ファイル       ───▶  getConfig()             ───▶  接続設定配列
    │                        │
コネクタ登録       ───▶  getConnector()          ───▶  ConnectorInterface
    │                        │
                         connect()               ───▶  Queue接続インスタンス
                             │                          │
                         setContainer()          ───▶  コンテナ設定済みQueue
                             │
                         $connections            ───▶  キャッシュ保存
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| QueueManager.php | `src/Illuminate/Queue/QueueManager.php` | ソース | キュー管理コア実装 |
| QueueServiceProvider.php | `src/Illuminate/Queue/QueueServiceProvider.php` | ソース | サービスプロバイダー |
| Factory.php | `src/Illuminate/Contracts/Queue/Factory.php` | インターフェース | ファクトリ契約 |
| Monitor.php | `src/Illuminate/Contracts/Queue/Monitor.php` | インターフェース | モニター契約 |
| Queue.php | `src/Illuminate/Contracts/Queue/Queue.php` | インターフェース | キュー契約 |
| SyncConnector.php | `src/Illuminate/Queue/Connectors/SyncConnector.php` | ソース | Syncコネクタ |
| DatabaseConnector.php | `src/Illuminate/Queue/Connectors/DatabaseConnector.php` | ソース | Databaseコネクタ |
| RedisConnector.php | `src/Illuminate/Queue/Connectors/RedisConnector.php` | ソース | Redisコネクタ |
| SqsConnector.php | `src/Illuminate/Queue/Connectors/SqsConnector.php` | ソース | SQSコネクタ |
| BeanstalkdConnector.php | `src/Illuminate/Queue/Connectors/BeanstalkdConnector.php` | ソース | Beanstalkdコネクタ |
| Events/ | `src/Illuminate/Queue/Events/` | ソース | キューイベントクラス群 |
