# インフラ設計書

## 概要

本ドキュメントは、serve-d（D言語向けLanguage Server Protocolサーバー）プロジェクトのインフラストラクチャ構成を記述するものである。serve-dはエディタのローカルプロセスとして動作するデスクトップアプリケーションであり、クラウド上のサーバーインフラを持たない。そのため、本設計書ではCI/CDパイプライン、ビルド・リリースインフラ、および開発者ローカルでの実行環境を中心に記載する。

## システム構成

### 全体構成

serve-dは、エディタ（VS Code、Vim、Emacs等）のクライアントプロセスから起動されるローカルプロセスとして動作する。stdin/stdoutを介したJSON-RPC通信でLSPプロトコルを実装し、エディタとの双方向通信を行う。サーバーサイドインフラは存在せず、全ての処理はエンドユーザーのローカルマシン上で完結する。

ビルド・リリースインフラとしてGitHub Actionsを利用し、マルチプラットフォーム（Linux、macOS、Windows）向けのバイナリビルドおよび配布を自動化している。

### サーバー構成

本プロジェクトはローカル実行型のアプリケーションであるため、従来型のサーバー構成は存在しない。以下にCI/CDランナー構成を記載する。

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| GitHub Actions Runner (ubuntu-22.04) | Linux向けビルド・テスト・リリース | GitHub提供ホステッドランナー | 1 |
| GitHub Actions Runner (macos-latest) | macOS向けビルド・テスト・リリース（x86_64, arm64） | GitHub提供ホステッドランナー | 1-2（アーキテクチャにより） |
| GitHub Actions Runner (windows-latest) | Windows向けビルド・テスト・リリース（x86, x86_64） | GitHub提供ホステッドランナー | 1-2（アーキテクチャにより） |

### ネットワーク構成

serve-dはローカルプロセスとして動作するため、ネットワーク通信は以下の場面でのみ発生する。

1. **LSP通信**: stdin/stdout経由のプロセス間通信（IPC）。ネットワークは使用しない。
2. **DCD（D Completion Daemon）連携**: serve-dがDCDサーバーのバイナリをダウンロードする際にHTTP/HTTPS通信が発生する。WindowsではWinHTTP API、その他OSではD言語のrequestsライブラリ（内部的にlibcurlベース）を使用する。
3. **CI/CD**: GitHub Actionsランナーからの外部パッケージリポジトリ（DUBレジストリ等）へのHTTPS通信。

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| LDC（LDC D Compiler） | latest（CI使用） | D言語ソースのコンパイル。リリースビルドおよびnightlyビルドに使用 |
| DMD（Digital Mars D Compiler） | latest（CI使用） | D言語ソースのコンパイル。ユニットテストに使用 |
| DUB | 1.40.0（dub.selections.jsonで固定） | D言語パッケージマネージャー兼ビルドツール |
| DCD（D Completion Daemon） | 0.16.2 | コード補完機能のバックエンド。serve-dが直接通信（dcd-clientスポーンなし） |
| D-Scanner | 0.16.0-beta.5 | 静的解析・リンティングツール |
| dfmt | 0.15.2 | D言語コードフォーマッター |
| libdparse | 0.25.1 | D言語パーサーライブラリ |
| 7-Zip | システム提供 | Windows向けリリースアーカイブ作成（serve-d.zip） |
| tar/xz | システム提供 | Linux/macOS向けリリースアーカイブ作成（.tar.xz, .tar.gz） |
| strip | システム提供 | Linux向けバイナリのデバッグシンボル除去 |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| GitHub Actions | CI/CD（テスト、ビルド、リリース） | GitHub APIベースのワークフロー自動実行 |
| GitHub Releases | ビルド済みバイナリの配布（stable/nightly） | HTTPS（GitHub Upload API）。リリースID: 20717582（nightlyリリース用） |
| DUB Registry | D言語パッケージの依存関係解決 | HTTPS |
| GitHub Sponsors | プロジェクトへの資金提供 | GitHub Platform |

## スケーリング設計

serve-dはエンドユーザーのローカルマシン上で1プロセスとして動作するため、従来のサーバーサイドスケーリングは適用されない。

ただし、以下のプロセス内スケーリング設計が施されている。

- **Fiber（軽量スレッド）ベースの並行処理**: `FiberManager`によりLSPリクエストを非同期的に処理する。ページサイズは4096バイト、デフォルトページ数は20。
- **マルチワークスペース対応**: 複数のDUBプロジェクトを同時に管理可能。`--require workspaces`フラグで有効化。
- **遅延読み込み（Lazy Loading）**: `manyProjects`設定により、大量プロジェクト環境での負荷を軽減。`--provide async-ask-load`フラグでプロジェクト読み込みを非同期化。
- **GCチューニング**: 30秒ごとのGC.collect、5回に1回のGC.minimizeによるメモリ管理最適化。

## 可用性設計

serve-dはエディタプロセスのチャイルドプロセスとして動作するため、可用性はエディタ側の管理に依存する。

- **プロセスクラッシュ時の復旧**: エディタ側（code-d等）がserve-dプロセスの異常終了を検知し、自動再起動する仕組みを持つ。
- **内部エラーハンドリング**: サーバー内でThrowableレベルの致命的エラーが発生した場合でも、エラーメッセージをクライアントに通知しつつ動作を継続しようとする設計（serverbase.dの`gotRequest`/`gotNotify`参照）。
- **シャットダウンプロトコル**: LSP仕様に準拠した`shutdown`/`exit`によるグレースフルシャットダウンをサポート。

CI/CDにおける可用性設計:
- **ナイトリービルド**: 毎日UTC 02:00にスケジュール実行（cron: `0 2 * * *`）。`workflow_dispatch`による手動実行も可能。
- **マトリクスビルド**: `fail-fast: false`設定により、1つのプラットフォームが失敗しても他のプラットフォームのビルドは継続。

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| ソースコード | Gitリポジトリ（GitHub） | プッシュごと | 無期限（Gitの履歴として保持） |
| ビルドバイナリ（Nightly） | GitHub Releases | 毎日（上書き） | 最新のnightlyのみ保持 |
| ビルドバイナリ（Stable） | GitHub Releases | リリースタグ作成時 | 無期限（各バージョンのリリースとして保持） |
| 依存関係バージョン | dub.selections.json | 変更時にコミット | Gitの履歴として保持 |
| CI/CDキャッシュ | GitHub Actions Cache（dub-upgrade action） | ビルドごと | GitHub Actionsのキャッシュポリシーに依存 |

## 監視設計

serve-dはローカルアプリケーションであるため、サーバー監視の仕組みは存在しない。ただし、以下の診断・ログ機能を持つ。

- **ログ出力**: 標準エラー出力（stderr）へのログ出力。`--logfile`オプションでファイルへのリダイレクトが可能。`--loglevel`オプションでログレベルを制御可能（trace, info, warning, error等）。
- **パフォーマンストレース**: `debug=PerfTraceLog`コンパイルフラグにより、`served_trace.log`へのGC統計・パフォーマンスログ出力が可能。
- **LSPトレース**: クライアント側の設定（例: VS Codeの`serve-d.trace.server: verbose`）によるRPCパケットのトレース。
- **CI/CDの監視**: GitHub Actionsのステータスバッジ（Run Unittests、Deploy Nightly）によるビルド状態の可視化。
- **`served/getInfo`リクエスト**: 実行中タスク一覧、ワークスペース状態、設定情報、モジュールインデックス等のランタイム診断情報を取得可能。

## 備考

### ビルド対象プラットフォームとアーキテクチャ

| OS | アーキテクチャ | ビルドタイプ | 配布形式 |
| --- | --- | --- | --- |
| Linux (ubuntu-22.04) | x86_64 | release / release-debug | .tar.xz, .tar.gz |
| macOS (macos-latest) | x86_64 | release / release-debug | .tar.xz, .tar.gz |
| macOS (macos-latest) | arm64 (Apple Silicon) | release | .tar.xz, .tar.gz（クロスコンパイル） |
| Windows (windows-latest) | x86_64 | release / release-debug | .zip |
| Windows (windows-latest) | x86 | release / release-debug | .zip |

- Linux向けビルドではglibc互換性のためubuntu-22.04を使用している。
- macOS向けビルドでは`MACOSX_DEPLOYMENT_TARGET=10.12`を設定し、macOS 10.12 Sierra以降との互換性を確保している。
- Windows向けビルドではSSL関連DLL（libcurl.dll, libeay32.dll, ssleay32.dll）が同梱される。
- リリースビルド時には`ci/validate_version.d`によるバージョン検証が実行される。

### CI/CDワークフロー構成

| ワークフロー | トリガー | 目的 |
| --- | --- | --- |
| `unittest.yml` (Run Unittests) | push (master) / pull_request | 全サブパッケージのユニットテスト実行 |
| `nightly.yml` (Deploy Nightly) | schedule (毎日UTC 02:00) / workflow_dispatch | ナイトリービルドの作成と配布 |
| `releases.yml` (Upload prebuild binaries) | release published | 安定版リリースバイナリの作成と配布 |

### プロジェクトのサブパッケージ構成

serve-dは以下のサブパッケージで構成されるモジュラーアーキテクチャを採用している。

| サブパッケージ | 役割 |
| --- | --- |
| `serve-d:http` | HTTP通信（ファイルダウンロード）。WinHTTP / requestsライブラリを使用 |
| `serve-d:lsp` | LSPプロトコル型定義、JSON-RPC通信基盤 |
| `serve-d:serverbase` | LSPサーバーの基本フレームワーク（stdin/stdout RPC、Fiber管理、GC管理） |
| `serve-d:dcd` | DCDクライアント（直接通信、低レイテンシ） |
| `serve-d:workspace-d` | D言語のコア機能実装（libdparse, dfmt, D-Scanner, DCD統合） |
| `serve-d:protocol` | シリアライゼーション定義 |
