# 非機能要件定義書

## 概要

本ドキュメントは、OpenCode（AI駆動開発ツール）の非機能要件を定義します。プロジェクトのソースコード解析に基づき、性能、可用性、セキュリティ、拡張性、保守性、運用・監視の各観点から要件を整理しています。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| Bashコマンド実行 | デフォルト2分以内 | `DEFAULT_TIMEOUT = 2 * 60 * 1000`（flag.ts経由で設定可能） |
| WebFetchリクエスト | 30秒以内（最大120秒） | `DEFAULT_TIMEOUT = 30 * 1000`, `MAX_TIMEOUT = 120 * 1000` |
| MCPサーバー接続 | 30秒以内 | `DEFAULT_TIMEOUT = 30_000`（設定で変更可能） |
| プロバイダーAPI呼び出し | 5分以内 | `timeout: 300000`（設定でfalseに無効化可能） |
| SSE heartbeat | 10秒間隔 | `setInterval(() => {...}, 10_000)` |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 同時接続数 | 制限なし | `idleTimeout: 0`設定により無制限 |
| WebFetchレスポンスサイズ | 5MB以内 | `MAX_RESPONSE_SIZE = 5 * 1024 * 1024` |
| Bashメタデータ出力 | 30,000文字以内 | `MAX_METADATA_LENGTH = 30_000` |
| ログファイル保持数 | 10ファイル | 5ファイル以下は削除せず、10ファイル超過時に古いファイルを削除 |

### コンテキストウィンドウ管理

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| コンパクションバッファ | 20,000トークン | `COMPACTION_BUFFER = 20_000` |
| プルーニング最小閾値 | 20,000トークン | `PRUNE_MINIMUM = 20_000` |
| プルーニング保護閾値 | 40,000トークン | `PRUNE_PROTECT = 40_000` |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | 明示的な定義なし | ローカルCLIツールとして動作、クラウドサービスはCloudflare Workers上で稼働 |
| 計画停止時間 | 明示的な定義なし | プロダクション環境は`protect: true`、リソース保持ポリシー`retain` |
| 障害復旧時間（RTO） | 明示的な定義なし | ステージング環境は`removal: "remove"`で自動クリーンアップ |
| 目標復旧時点（RPO） | 明示的な定義なし | SQLiteのWALモード、PASSIVE checkpointにより耐久性を確保 |

### リトライ戦略

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| 初期遅延 | 2,000ms | `RETRY_INITIAL_DELAY = 2000` |
| バックオフ係数 | 2倍 | `RETRY_BACKOFF_FACTOR = 2`（指数バックオフ） |
| ヘッダーなし時の最大遅延 | 30秒 | `RETRY_MAX_DELAY_NO_HEADERS = 30_000` |
| 最大遅延 | 約24.8日 | `RETRY_MAX_DELAY = 2_147_483_647`（32bit最大値） |

## セキュリティ要件

### 認証・認可

- **Basic認証**: サーバーは環境変数`OPENCODE_SERVER_PASSWORD`/`OPENCODE_SERVER_USERNAME`でBasic認証をサポート
- **OAuth認証**: MCPサーバーに対してOAuth 2.0フロー（PKCE対応）をサポート
- **API認証**: プロバイダー別のAPIキー管理（`auth.json`に保存、ファイル権限`0o600`）
- **WellKnown認証**: 組織向けのリモート設定認証

### CORS設定

許可されるオリジン:
- `http://localhost:*`
- `http://127.0.0.1:*`
- `tauri://localhost`
- `http://tauri.localhost`
- `https://tauri.localhost`
- `https://*.opencode.ai`
- 設定で追加されたホワイトリストドメイン

### Content Security Policy

```
default-src 'self';
script-src 'self' 'wasm-unsafe-eval';
style-src 'self' 'unsafe-inline';
img-src 'self' data: https:;
font-src 'self' data:;
media-src 'self' data:;
connect-src 'self' data:
```

### データ保護

- **ファイル権限**: 認証情報ファイルは`0o600`（所有者のみ読み書き可能）
- **機密情報管理**: SSTシークレットを使用（`sst.Secret`）
- **管理設定ディレクトリ**: プラットフォーム別の保護されたディレクトリ
  - macOS: `/Library/Application Support/opencode`
  - Windows: `C:\ProgramData\opencode`
  - Linux: `/etc/opencode`

### 入力検証

- Zod schemaによる厳格な入力バリデーション
- URLの検証（http/httpsスキームの確認）
- コマンドパース（tree-sitter-bashによる構文解析）

## 拡張性要件

### プロバイダー拡張

- **バンドルプロバイダー**: 18種類の主要AIプロバイダーを内蔵
  - Anthropic, OpenAI, Google, Azure, AWS Bedrock, GitHub Copilot等
- **カスタムプロバイダー**: npm経由での動的ロード対応
- **プロバイダー設定**: ホワイトリスト/ブラックリストによるモデル制御

### プラグインシステム

- ローカルプラグイン（`file://`プロトコル）
- npmパッケージプラグイン
- プラグインの優先度に基づく重複排除

### MCP（Model Context Protocol）

- ローカルMCPサーバー（stdio transport）
- リモートMCPサーバー（StreamableHTTP/SSE transport）
- OAuth認証対応（動的クライアント登録サポート）

### 設定の階層構造

優先度（低→高）:
1. リモート `.well-known/opencode`
2. グローバル設定 (`~/.config/opencode/`)
3. カスタム設定 (`OPENCODE_CONFIG`)
4. プロジェクト設定 (`opencode.json`)
5. `.opencode`ディレクトリ設定
6. インライン設定 (`OPENCODE_CONFIG_CONTENT`)
7. 管理設定ディレクトリ（エンタープライズ）

## 保守性要件

### コード品質

- TypeScript厳格モード使用
- Zodによる型安全なスキーマ定義
- 名前付きエラー（`NamedError`）による構造化されたエラーハンドリング

### ログ管理

- **ログレベル**: DEBUG, INFO, WARN, ERROR
- **ログ形式**: タイムスタンプ + 差分時間 + タグ + メッセージ
- **ログローテーション**: 10ファイル保持、古いファイルは自動削除
- **サービス別ロガー**: キャッシュ機構による効率的なロガーインスタンス管理

### データベース

- **SQLite**: Bunランタイム組み込み
- **Drizzle ORM**: 型安全なDB操作
- **マイグレーション**: 自動マイグレーション適用
- **PRAGMA設定**:
  - `journal_mode = WAL`
  - `synchronous = NORMAL`
  - `busy_timeout = 5000`
  - `cache_size = -64000`（64MB）
  - `foreign_keys = ON`

### 設定ファイル

- JSONC（コメント付きJSON）サポート
- 環境変数置換（`{env:VAR_NAME}`）
- ファイル参照（`{file:path}`）
- スキーマ自動追加

## 運用・監視要件

### ログ出力

- ファイルベースのログ（`Global.Path.log`）
- 開発モード: `dev.log`（固定名）
- 本番モード: タイムスタンプベースのファイル名（例: `2024-01-15T123456.log`）
- ログプッシュ対応（Cloudflare Workers: `logpush = true`）

### ヘルスチェック

- SSEハートビート（10秒間隔）による接続維持
- MCPサーバーステータス監視（connected/disabled/failed/needs_auth）
- LSPサーバーステータス監視
- フォーマッターステータス監視

### mDNSサービスディスカバリ

- ローカルネットワーク上でのサービス公開
- カスタムドメイン名設定可能（デフォルト: `opencode.local`）
- ループバックアドレス時は無効化

### 環境変数によるフラグ制御

| フラグ | 説明 |
| --- | --- |
| `OPENCODE_DISABLE_AUTOUPDATE` | 自動更新の無効化 |
| `OPENCODE_DISABLE_AUTOCOMPACT` | 自動コンパクションの無効化 |
| `OPENCODE_DISABLE_PRUNE` | プルーニングの無効化 |
| `OPENCODE_DISABLE_LSP_DOWNLOAD` | LSPダウンロードの無効化 |
| `OPENCODE_DISABLE_MODELS_FETCH` | モデル一覧取得の無効化 |
| `OPENCODE_EXPERIMENTAL_*` | 各種実験的機能のフラグ |

## 備考

### クラウドインフラストラクチャ

- **プラットフォーム**: Cloudflare（Workers, R2, Durable Objects）
- **データベース**: PlanetScale（外部）
- **決済**: Stripe
- **ビルド**: SST (Serverless Stack)

### 制限事項

- コンテキストオーバーフロー時の自動コンパクション（モデル依存）
- レートリミットはプロバイダー側の制限に依存
- ローカル実行時のリソース制限はOS依存

### 互換性

- **Node.js**: 22.x（TypeScript設定）
- **Bun**: 1.3.9（パッケージマネージャー、ランタイム）
- **対応OS**: macOS, Windows, Linux
