# バッチ設計書 2-queue:listen

## 概要

本ドキュメントは、Laravelフレームワークのキューリスナーコマンド `queue:listen` の設計仕様を記載したものです。本バッチはキューワーカーの代替として、サブプロセス方式でジョブ処理を行う機能を提供します。

### 本バッチの処理概要

`queue:listen` コマンドは、指定されたキューをリッスンし、各ジョブをサブプロセスとして実行するバッチ処理です。`queue:work` と類似の機能を持ちますが、ジョブごとに新しいプロセスを起動するため、コード変更時の反映が容易です。

**業務上の目的・背景**：開発環境においてコード変更を即座に反映させたい場合や、ジョブ間でのメモリリークを防止したい場合に使用します。各ジョブが独立したプロセスで実行されるため、あるジョブの失敗が他のジョブに影響を与えにくい特性があります。ただし、プロセス起動のオーバーヘッドがあるため、本番環境では `queue:work` の使用が推奨されます。

**バッチの実行タイミング**：主に開発環境でシステム起動時に開始し、継続的にリスナーとして稼働します。本番環境では `queue:work` の使用が推奨されます。

**主要な処理内容**：
1. 指定されたキュー接続のリスニングを開始
2. ジョブ検出時に `queue:work --once` をサブプロセスとして起動
3. サブプロセスの出力を親プロセスに転送
4. サブプロセス完了後、次のジョブのリスニングを継続
5. メモリ使用量の監視と制限

**前後の処理との関連**：内部的に `queue:work --once` コマンドを呼び出すため、`queue:work` の機能に依存します。`queue:restart` による再起動シグナルは直接サポートしていません。

**影響範囲**：キューに登録された全てのジョブに影響を与えます。サブプロセスとして動作するため、各ジョブ実行時にPHPプロセスが新規に起動されます。

## バッチ種別

ジョブ処理（キューリスナー / サブプロセス方式）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 常時稼働（リスナー） |
| 実行時刻 | システム起動時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動起動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| キュー接続設定 | config/queue.phpにて有効なキュー接続が設定されていること |
| PHPバイナリ | php実行可能ファイルがPATHに存在すること |
| Artisanバイナリ | artisanファイルがプロジェクトルートに存在すること |

### 実行可否判定

- `--force` オプションが指定されていない場合、メンテナンスモード時の動作はサブプロセス側で判定
- 親プロセス自体は常にリスニングを継続

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| connection | string | No | config値 | キュー接続名 |
| --name | string | No | default | ワーカー名 |
| --queue | string | No | config値 | リッスン対象のキュー名 |
| --backoff | int | No | 0 | 例外発生時のリトライ待機秒数 |
| --force | bool | No | false | メンテナンスモード中も実行 |
| --memory | int | No | 128 | メモリ上限（MB） |
| --sleep | int | No | 3 | ジョブがない場合のスリープ秒数 |
| --rest | int | No | 0 | ジョブ間の休止秒数 |
| --timeout | int | No | 60 | 子プロセスのタイムアウト秒数 |
| --tries | int | No | 1 | 失敗までのリトライ回数 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| jobs テーブル | DB | データベースキュー使用時のジョブ格納先 |
| Redis キュー | Redis | Redisキュー使用時のジョブ格納先 |
| SQS キュー | AWS SQS | SQSキュー使用時のジョブ格納先 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | サブプロセスからの出力転送 |
| failed_jobs テーブル | DB | 失敗したジョブの記録（サブプロセス経由） |

### 出力ファイル仕様

該当なし（ファイル出力は行わない）

## 処理フロー

### 処理シーケンス

```
1. 初期化処理
   └─ Listenerインスタンスの生成、出力ハンドラの設定
2. キュー接続の取得
   └─ 引数またはconfig値からキュー接続とキュー名を決定
3. 処理開始メッセージ表示
   └─ "Processing jobs from the [queue_name] queue"
4. リッスンループ開始
   └─ Listener::listenメソッドで無限ループ
5. サブプロセス生成
   └─ queue:work --once コマンドをSymfony Processで起動
6. サブプロセス実行
   └─ プロセス出力を親プロセスに転送
7. 休止処理
   └─ --rest オプション指定時はスリープ
8. ループ継続
   └─ 5に戻る
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[Listener初期化]
    B --> C[出力ハンドラ設定]
    C --> D[キュー接続取得]
    D --> E[処理開始メッセージ表示]
    E --> F[リッスンループ開始]
    F --> G[サブプロセス生成]
    G --> H[queue:work --once 実行]
    H --> I[出力転送]
    I --> J{--rest指定?}
    J -->|Yes| K[スリープ]
    J -->|No| F
    K --> F
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ取得 | jobs | SELECT/DELETE | サブプロセス経由でキューからジョブを取得 |
| ジョブ削除 | jobs | DELETE | サブプロセス経由で処理完了ジョブの削除 |
| 失敗記録 | failed_jobs | INSERT | サブプロセス経由で失敗ジョブの記録 |

### テーブル別操作詳細

#### jobs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 全カラム | サブプロセス内で実行 | queue:work --once経由 |
| DELETE | - | サブプロセス内で実行 | queue:work --once経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | プロセス起動失敗 | PHPバイナリが見つからない | 環境変数PATHの確認 |
| - | タイムアウト | サブプロセスがtimeoutを超過 | timeout値の調整 |
| - | メモリ超過 | 親プロセスのメモリ使用量超過 | memory値の調整 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | --tries オプションで指定（サブプロセスに渡される） |
| リトライ間隔 | --backoff オプションで指定（サブプロセスに渡される） |
| リトライ対象エラー | サブプロセス（queue:work）の仕様に準拠 |

### 障害時対応

1. サブプロセスの異常終了は親プロセスに影響しない
2. 親プロセス異常終了時は手動再起動が必要
3. メモリリーク対策として各ジョブが独立プロセスで実行される

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | サブプロセス内で管理（queue:work準拠） |
| コミットタイミング | サブプロセス内で管理 |
| ロールバック条件 | サブプロセス内で管理 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 開発環境向け（低〜中スループット） |
| 目標処理時間 | ジョブ依存 + プロセス起動オーバーヘッド |
| メモリ使用量上限 | 128MB（--memoryで変更可能） |

## 排他制御

- 同一キューに対して複数リスナーの同時実行が可能
- 各ジョブは独立したサブプロセスで実行されるため、プロセス間の排他は不要
- データベースレベルの排他制御はqueue:work側で実施

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | Processing jobs from the [queue_name] queue |
| 進捗ログ | サブプロセス実行中 | サブプロセスからの出力転送 |
| 終了ログ | バッチ終了時 | なし（リスナーのため通常終了しない） |
| エラーログ | エラー発生時 | サブプロセスからの出力転送 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| プロセス生存 | プロセス停止時 | プロセス監視ツール |
| メモリ使用量 | --memory オプション値 | 自動終了 |

## 備考

- `--delay` オプションは非推奨、`--backoff` を使用
- 本番環境では `queue:work` の使用を推奨（パフォーマンス上の理由）
- 開発環境ではコード変更が自動反映されるため便利
- Symfony Process コンポーネントを使用してサブプロセスを管理
- `--env` オプションでサブプロセスの環境を指定可能
