# 機能設計書 43-HTTP API サーバー

## 概要

本ドキュメントは、OpenCodeにおけるHTTP APIサーバー機能の設計を記述する。HonoフレームワークベースのRESTful APIサーバーを提供し、外部クライアントからのOpenCode機能へのアクセスを可能にする。

### 本機能の処理概要

HTTP APIサーバー機能は、OpenCodeの各種機能（セッション管理、プロバイダー管理、ファイル操作、MCP連携等）をREST APIとして公開する。Bun.serveを使用した高性能なHTTPサーバーを提供し、OpenAPI 3.1仕様に準拠したAPI定義を自動生成する。

**業務上の目的・背景**：OpenCodeはCLI/TUIアプリケーションとして動作するが、Web UI、デスクトップアプリ、外部ツールからの連携が必要となる場面がある。HTTP APIサーバーにより、言語やプラットフォームを問わずOpenCodeの機能を利用でき、IDE拡張機能やカスタムクライアントの開発が可能になる。また、リモートからの操作や自動化スクリプトとの連携も実現する。

**機能の利用シーン**：
- Web UI（SolidJS）からのバックエンド連携
- デスクトップアプリ（Tauri）からのAPI呼び出し
- VS Code拡張機能からのセッション操作
- 自動化スクリプトからのバッチ処理
- 複数クライアント間でのセッション共有

**主要な処理内容**：
1. Hono アプリケーションの初期化とルーティング設定
2. CORS設定とBasic認証による保護
3. ディレクトリコンテキストの自動設定（x-opencode-directory ヘッダー）
4. 各種APIエンドポイントの提供（セッション、プロバイダー、ファイル、MCP等）
5. OpenAPI仕様の自動生成

**関連システム・外部連携**：
- Hono: 軽量Webフレームワーク
- hono-openapi: OpenAPI仕様生成
- Bun.serve: HTTPサーバー実装
- mDNS: サービスディスカバリー

**権限による制御**：Basic認証（OPENCODE_SERVER_USERNAME/OPENCODE_SERVER_PASSWORD）による保護。CORS設定でオリジン制限。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面 | API連携 | 全画面がAPI経由でバックエンドと通信 |

## 機能種別

APIサーバー / データ連携

## 入力仕様

### サーバー起動パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| port | number | No | リッスンポート（デフォルト4096） | 正の整数 |
| hostname | string | No | ホスト名（デフォルトlocalhost） | 有効なホスト名 |
| mdns | boolean | No | mDNSサービス公開有効化 | - |
| mdnsDomain | string | No | mDNSドメイン名 | 有効なドメイン名 |
| cors | string[] | No | 追加CORSホワイトリスト | URL形式 |

### リクエストヘッダー

| ヘッダー名 | 型 | 必須 | 説明 |
|-----------|-----|-----|------|
| x-opencode-directory | string | No | 操作対象ディレクトリ |
| Authorization | string | 条件付き | Basic認証（パスワード設定時必須） |

### 入力データソース

- HTTPリクエスト
- 環境変数（OPENCODE_SERVER_PASSWORD等）
- 設定ファイル（server設定）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| url | URL | サーバーURL（listen後） |
| openapi | object | OpenAPI仕様（/doc エンドポイント） |

### 出力先

- HTTPレスポンス（JSON形式）
- Server-Sent Events（イベントストリーム）
- WebSocket（PTY接続）

## 処理フロー

### 処理シーケンス

```
1. サーバー初期化
   ├─ Hono アプリケーション作成
   ├─ エラーハンドラー設定
   ├─ Basic認証ミドルウェア設定
   ├─ リクエストロギングミドルウェア設定
   └─ CORS設定

2. ルート登録
   ├─ グローバルルート（/global）
   ├─ 認証ルート（/auth）
   ├─ ディレクトリコンテキストミドルウェア
   └─ 各種APIルート（/session, /provider, /mcp 等）

3. サーバー起動（listen）
   ├─ Bun.serve でHTTPサーバー開始
   ├─ ポート4096を優先的に使用（使用中なら自動選択）
   └─ mDNS公開（設定有効時）

4. リクエスト処理
   ├─ ミドルウェアチェーン実行
   ├─ Instance.provide でディレクトリコンテキスト設定
   └─ ルートハンドラー実行
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B{OPTIONS?}
    B -->|Yes| C[CORSレスポンス]
    B -->|No| D{認証必要?}
    D -->|Yes| E{Basic認証OK?}
    E -->|No| F[401 Unauthorized]
    E -->|Yes| G[ログ出力]
    D -->|No| G
    G --> H{CORSチェック}
    H -->|NG| I[CORSエラー]
    H -->|OK| J[ディレクトリコンテキスト設定]
    J --> K[Instance.provide]
    K --> L[ルートハンドラー実行]
    L --> M{成功?}
    M -->|Yes| N[JSONレスポンス]
    M -->|No| O[エラーレスポンス]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-43-01 | ポート選択 | port=0の場合4096を優先、使用中なら0（自動）| サーバー起動時 |
| BR-43-02 | CORS許可オリジン | localhost, 127.0.0.1, tauri://, *.opencode.ai を許可 | 全リクエスト |
| BR-43-03 | Basic認証 | OPENCODE_SERVER_PASSWORD設定時のみ有効 | リクエスト時 |
| BR-43-04 | ディレクトリ解決 | x-opencode-directory > directory クエリ > cwd | コンテキスト設定時 |
| BR-43-05 | mDNS条件 | loopbackアドレス以外でのみmDNS公開 | サーバー起動時 |

### 計算ロジック

CORS許可オリジン判定：
```typescript
if (origin.startsWith("http://localhost:")) return origin
if (origin.startsWith("http://127.0.0.1:")) return origin
if (origin === "tauri://localhost") return origin
if (/^https:\/\/([a-z0-9-]+\.)*opencode\.ai$/.test(origin)) return origin
if (corsWhitelist.includes(origin)) return origin
return undefined  // 拒否
```

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

本機能は直接データベースを操作しない（各APIエンドポイントが個別に操作）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 400 | Bad Request | バリデーションエラー | 詳細メッセージを返却 |
| 401 | Unauthorized | Basic認証失敗 | 認証情報を確認 |
| 404 | Not Found | リソース不在 | NotFoundErrorをJSON形式で返却 |
| 500 | Internal Server Error | 未処理例外 | NamedError.Unknownとして返却 |

### リトライ仕様

サーバー側でのリトライは実装されていない。ポートバインド失敗時は別ポートで自動再試行。

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

HTTPリクエスト単位での処理。各リクエストは独立したInstance.provideコンテキスト内で実行。

## パフォーマンス要件

- Bun.serveによる高性能HTTP処理
- idleTimeout: 0（無制限）
- リクエストログにタイマー計測含む

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

- Basic認証によるアクセス制御（オプション）
- CORS設定による不正オリジンからのアクセス防止
- Content-Security-Policy ヘッダーの設定（プロキシ経由時）
- 環境変数での認証情報管理

## 備考

主要APIエンドポイント：
- `/session/*` - セッション管理
- `/provider/*` - プロバイダー管理
- `/mcp/*` - MCP連携
- `/pty/*` - PTY管理
- `/config/*` - 設定管理
- `/event` - SSEイベントストリーム
- `/doc` - OpenAPI仕様

---

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

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

### 推奨読解順序

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

サーバー設定の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.ts | `packages/opencode/src/config/config.ts` | Server設定スキーマ（946-958行目）を確認 |

**読解のコツ**: Zodスキーマでport, hostname, mdns, mdnsDomain, corsの設定項目が定義されている。

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

サーバー起動とアプリケーション初期化を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | server.ts | `packages/opencode/src/server/server.ts` | Server.listen関数（576-622行目）がサーバー起動 |
| 2-2 | server.ts | `packages/opencode/src/server/server.ts` | App()関数（58-559行目）がHonoアプリケーション定義 |

**主要処理フロー**:
1. **576-583行目**: listen関数のパラメータ処理
2. **585-590行目**: Bun.serve設定オブジェクト構築
3. **591-598行目**: ポート選択ロジック（4096優先）
4. **603-613行目**: mDNS公開条件判定と実行

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

認証、ログ、CORSミドルウェアを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | server.ts | `packages/opencode/src/server/server.ts` | エラーハンドラー（62-79行目）|
| 3-2 | server.ts | `packages/opencode/src/server/server.ts` | Basic認証ミドルウェア（80-88行目）|
| 3-3 | server.ts | `packages/opencode/src/server/server.ts` | リクエストログミドルウェア（89-105行目）|
| 3-4 | server.ts | `packages/opencode/src/server/server.ts` | CORS設定（106-131行目）|
| 3-5 | server.ts | `packages/opencode/src/server/server.ts` | ディレクトリコンテキスト（195-212行目）|

**主要処理フロー**:
- **80-88行目**: OPTIONSリクエストはスキップ、パスワード設定時のみBasic認証適用
- **106-131行目**: オリジン判定ロジック（localhost, tauri, *.opencode.ai）
- **195-212行目**: x-opencode-directoryヘッダーからInstance.provideを設定

#### Step 4: 各種ルートを理解する

APIエンドポイントの構成を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | server.ts | `packages/opencode/src/server/server.ts` | ルート登録（132, 227-237行目）|
| 4-2 | routes/session.ts | `packages/opencode/src/server/routes/session.ts` | セッションルート |
| 4-3 | routes/provider.ts | `packages/opencode/src/server/routes/provider.ts` | プロバイダールート |
| 4-4 | routes/mcp.ts | `packages/opencode/src/server/routes/mcp.ts` | MCPルート |

**主要処理フロー**:
- **132行目**: GlobalRoutes（認証不要）
- **227-237行目**: 各種プロジェクトスコープルート
- **543-558行目**: フォールバックプロキシ（app.opencode.ai）

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

```
Server.listen(opts)
    │
    ├─ Bun.serve({fetch: App().fetch})
    │      │
    │      └─ App() - Honoアプリケーション
    │             │
    │             ├─ onError - エラーハンドラー
    │             ├─ use(basicAuth) - Basic認証
    │             ├─ use(logging) - リクエストログ
    │             ├─ use(cors) - CORS設定
    │             ├─ route("/global", GlobalRoutes)
    │             ├─ use(directoryContext) - ディレクトリコンテキスト
    │             ├─ route("/session", SessionRoutes)
    │             ├─ route("/provider", ProviderRoutes)
    │             └─ ... その他ルート
    │
    └─ MDNS.publish(port, domain)
```

### データフロー図

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

HTTPリクエスト
       │
       ▼
ミドルウェアチェーン
├─ Basic認証
├─ ログ
├─ CORS
└─ ディレクトリコンテキスト
       │
       ▼
Instance.provide()
       │
       ▼
ルートハンドラー ───▶ JSONレスポンス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| server.ts | `packages/opencode/src/server/server.ts` | ソース | HTTPサーバーのメインモジュール |
| mdns.ts | `packages/opencode/src/server/mdns.ts` | ソース | mDNSサービス公開 |
| session.ts | `packages/opencode/src/server/routes/session.ts` | ソース | セッションAPIルート |
| provider.ts | `packages/opencode/src/server/routes/provider.ts` | ソース | プロバイダーAPIルート |
| mcp.ts | `packages/opencode/src/server/routes/mcp.ts` | ソース | MCPAPIルート |
| pty.ts | `packages/opencode/src/server/routes/pty.ts` | ソース | PTYルート |
| config.ts | `packages/opencode/src/server/routes/config.ts` | ソース | 設定APIルート |
| error.ts | `packages/opencode/src/server/error.ts` | ソース | エラー定義 |
| instance.ts | `packages/opencode/src/project/instance.ts` | ソース | ディレクトリコンテキスト管理 |
