# 機能設計書 8-Action Dispatch

## 概要

本ドキュメントは、Ruby on RailsフレームワークにおけるAction Dispatchの機能設計を記述する。Action Dispatchは、リクエストルーティングとミドルウェア管理を担当し、受信リクエストを適切なコントローラへ振り分けるコンポーネントである。

### 本機能の処理概要

Action Dispatchは、HTTPリクエストの解析、ルーティング、ミドルウェアスタック管理、セッション・Cookie管理、およびセキュリティ機能を提供するモジュールである。

**業務上の目的・背景**：Webアプリケーションでは、URLパターンに基づいて適切なコントローラ・アクションにリクエストを振り分ける必要がある。Action Dispatchは、DSLベースのルーティング定義と高速なパターンマッチングを提供し、RESTfulなURL設計を容易にする。また、ミドルウェアスタックにより、リクエスト/レスポンスの前処理・後処理を柔軟に構成できる。

**機能の利用シーン**：
- URLパターンからコントローラ・アクションへのルーティング
- ミドルウェアによるリクエスト/レスポンス処理
- セッション・Cookie管理
- リクエスト/レスポンスオブジェクトの提供
- SSL強制、CSRF保護等のセキュリティ機能
- 開発時のデバッグ情報表示

**主要な処理内容**：
1. Journeyルーターによるパターンマッチング
2. RoutesでのDSLベースルーティング定義
3. ミドルウェアスタック管理
4. Request/Responseオブジェクトの提供
5. セッションストア（Cookie、Cache、MemCache等）
6. Cookie管理（署名付き、暗号化）
7. セキュリティミドルウェア（SSL、CSRF、HostAuthorization等）
8. デバッグミドルウェア（DebugExceptions、DebugLocks）

**関連システム・外部連携**：
- Rack: Webサーバーインターフェース
- Journey: ルーティングエンジン（内部）
- Redis/Memcached: セッションストア

**権限による制御**：HostAuthorizationによる許可ホストの制限、SSLによる暗号化通信の強制が可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | アプリケーションプロパティ画面 | 補助機能 | ローカルリクエスト検証（require_local!） |
| 3 | ルーティング一覧画面 | 主機能 | RoutesInspectorによるルーティング一覧の生成 |
| 8 | 例外診断画面 | 主機能 | DebugExceptionsミドルウェアによる例外キャプチャ・処理 |
| 9 | ルーティングエラー画面 | 補助機能 | 定義済みルート一覧の表示処理 |
| 16 | ルーティングFSM可視化画面 | 補助機能 | NFAシミュレーション機能の提供 |

## 機能種別

ルーティング / ミドルウェア管理 / リクエスト処理

## 入力仕様

### 入力パラメータ

#### routes.rb DSL

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| path | String | Yes | URLパス | 有効なURLパターン |
| controller | String | No | コントローラ名 | - |
| action | String | No | アクション名 | - |
| constraints | Hash/Proc | No | ルート制約 | - |
| defaults | Hash | No | デフォルト値 | - |

#### Request

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| env | Hash | Yes | Rack環境変数 | 有効なRack env |

### 入力データソース

- HTTPリクエスト（Rackから）
- config/routes.rb
- ミドルウェア設定

## 出力仕様

### 出力データ

#### ルーティング結果

| 項目名 | 型 | 説明 |
|--------|-----|------|
| controller | String | マッチしたコントローラ名 |
| action | String | マッチしたアクション名 |
| params | Hash | URLパラメータ |

#### Response

| 項目名 | 型 | 説明 |
|--------|-----|------|
| status | Integer | HTTPステータスコード |
| headers | Hash | レスポンスヘッダ |
| body | Array | レスポンスボディ |

### 出力先

- コントローラ（ルーティング結果）
- Rackサーバー（レスポンス）

## 処理フロー

### 処理シーケンス（ルーティング）

```
1. HTTPリクエスト受信
   └─ Rackサーバーからenvを受け取る
2. ミドルウェアスタック（往路）
   └─ 各ミドルウェアがリクエストを処理
3. ルーターによるパターンマッチング
   └─ Journeyエンジンでルート検索
4. コントローラ・アクション特定
   └─ マッチしたルートからディスパッチ情報を抽出
5. コントローラ呼び出し
   └─ Action Controllerへディスパッチ
6. ミドルウェアスタック（復路）
   └─ レスポンスの後処理
7. レスポンス返却
   └─ Rackサーバーへ
```

### フローチャート

```mermaid
flowchart TD
    A[HTTPリクエスト] --> B[Rack env]
    B --> C[ミドルウェアスタック]
    C --> D[ActionDispatch::Routing::RouteSet]
    D --> E{パターンマッチ}
    E -->|成功| F[controller/action 抽出]
    E -->|失敗| G[RoutingError]
    F --> H[Action Controller]
    H --> I[レスポンス生成]
    I --> J[ミドルウェアスタック復路]
    J --> K[HTTPレスポンス]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ルート優先順位 | 先に定義されたルートが優先 | ルーティング時 |
| BR-002 | RESTfulルート | resourcesは7つの標準アクションを生成 | resources定義時 |
| BR-003 | ミドルウェア順序 | 定義順にリクエスト処理、逆順にレスポンス処理 | リクエスト処理時 |
| BR-004 | SSL強制 | force_ssl有効時はHTTPSにリダイレクト | リクエスト受信時 |
| BR-005 | ホスト制限 | HostAuthorizationで許可ホストのみアクセス可 | リクエスト受信時 |

### 計算ロジック

**ルートパターンマッチング（Journey）**：
```ruby
# 有限状態マシン（FSM）によるパターンマッチング
# /users/:id -> /users/123 でマッチし、params[:id] = "123"
```

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

Action Dispatch自体は直接データベース操作を行わない。ただし、セッションストア（CacheStore等）はキャッシュを介してデータを保存する場合がある。

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | Action Dispatch自体はDB操作を行わない |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 404 | ActionController::RoutingError | ルートが見つからない | routes.rbを確認 |
| - | ActionDispatch::MissingController | コントローラクラスが見つからない | コントローラファイルを確認 |
| 403 | ActionDispatch::HostAuthorization::DefaultResponseApp | 許可されていないホスト | hosts設定を確認 |

### リトライ仕様

リクエスト処理でのリトライは行われない。

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

Action Dispatchはトランザクション管理を直接行わない。

## パフォーマンス要件

- ルーティングはFSMで最適化された高速パターンマッチング
- ミドルウェアスタックのオーバーヘッドは最小限

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

- SSL/TLS強制（ForceSSL/AssumeSSL）
- HostAuthorizationによるホスト制限
- Content Security Policyの設定
- Permissions Policyの設定
- セッション・Cookieの署名・暗号化

## 備考

Action Dispatchは `actionpack` gem の一部として提供される。セッション・Cookie・セキュリティ機能を含む。

---

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

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

### 推奨読解順序

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

Action Dispatchのモジュール構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | action_dispatch.rb | `actionpack/lib/action_dispatch.rb` | モジュール定義とautoload一覧 |

**読解のコツ**: `eager_autoload` と `autoload_under` でグループ化されたモジュール群を把握する。

**主要処理フロー**:
- **47-66行目**: eager_autoloadブロック
- **68-88行目**: autoload_under "middleware" でミドルウェア群の定義
- **95-104行目**: Http名前空間の定義
- **106-125行目**: Session名前空間の定義

#### Step 2: Request/Responseを理解する

リクエスト・レスポンスオブジェクトを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | request.rb | `actionpack/lib/action_dispatch/http/request.rb` | Requestクラスの実装 |
| 2-2 | response.rb | `actionpack/lib/action_dispatch/http/response.rb` | Responseクラスの実装 |

#### Step 3: ルーティングを理解する

ルーティングシステムを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | routing.rb | `actionpack/lib/action_dispatch/routing.rb` | ルーティングモジュール |
| 3-2 | route_set.rb | `actionpack/lib/action_dispatch/routing/route_set.rb` | RouteSetクラス |

#### Step 4: Journeyを理解する

ルーティングエンジンの内部を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | journey.rb | `actionpack/lib/action_dispatch/journey.rb` | Journeyモジュール |
| 4-2 | router.rb | `actionpack/lib/action_dispatch/journey/router.rb` | Routerクラス |

#### Step 5: ミドルウェアを理解する

主要なミドルウェアを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | debug_exceptions.rb | `actionpack/lib/action_dispatch/middleware/debug_exceptions.rb` | デバッグ例外表示 |
| 5-2 | ssl.rb | `actionpack/lib/action_dispatch/middleware/ssl.rb` | SSL強制 |
| 5-3 | host_authorization.rb | `actionpack/lib/action_dispatch/middleware/host_authorization.rb` | ホスト制限 |

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

```
ActionDispatch
    │
    ├─ Routing
    │      ├─ RouteSet
    │      │      └─ draw ブロック
    │      └─ Mapper (DSL)
    │             ├─ get/post/patch/put/delete
    │             ├─ resources
    │             └─ namespace/scope
    │
    ├─ Journey (ルーティングエンジン)
    │      ├─ Router
    │      ├─ Routes
    │      └─ GTG (Graph Transition Graph)
    │
    ├─ Http
    │      ├─ Request
    │      ├─ Response
    │      ├─ Headers
    │      └─ Parameters
    │
    ├─ Middleware
    │      ├─ SSL
    │      ├─ HostAuthorization
    │      ├─ DebugExceptions
    │      ├─ Cookies
    │      └─ Session
    │
    └─ Session
           ├─ CookieStore
           ├─ CacheStore
           └─ MemCacheStore
```

### データフロー図

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

HTTPリクエスト ───▶ Rack env ───▶ ActionDispatch::Request
       │                              │
       ▼                              ▼
PATH_INFO ───▶ Journey Router ───▶ controller/action
       │                              │
       ▼                              ▼
パラメータ ───▶ ActionDispatch::Http::Parameters ───▶ params
       │
       ▼
レスポンス ◀─── ActionDispatch::Response ◀─── コントローラ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| action_dispatch.rb | `actionpack/lib/action_dispatch.rb` | ソース | モジュールエントリーポイント |
| request.rb | `actionpack/lib/action_dispatch/http/request.rb` | ソース | Requestクラス |
| response.rb | `actionpack/lib/action_dispatch/http/response.rb` | ソース | Responseクラス |
| routing.rb | `actionpack/lib/action_dispatch/routing.rb` | ソース | ルーティングモジュール |
| route_set.rb | `actionpack/lib/action_dispatch/routing/route_set.rb` | ソース | RouteSetクラス |
| mapper.rb | `actionpack/lib/action_dispatch/routing/mapper.rb` | ソース | ルーティングDSL |
| journey.rb | `actionpack/lib/action_dispatch/journey.rb` | ソース | Journeyエンジン |
| ssl.rb | `actionpack/lib/action_dispatch/middleware/ssl.rb` | ソース | SSLミドルウェア |
| cookies.rb | `actionpack/lib/action_dispatch/middleware/cookies.rb` | ソース | Cookieミドルウェア |
| debug_exceptions.rb | `actionpack/lib/action_dispatch/middleware/debug_exceptions.rb` | ソース | デバッグ例外表示 |
| content_security_policy.rb | `actionpack/lib/action_dispatch/http/content_security_policy.rb` | ソース | CSP設定 |
