# インフラ設計書

## 概要

本ドキュメントは、clojure-lspプロジェクトのインフラストラクチャ構成を記載した設計書です。clojure-lspはClojure/ClojureScript向けのLanguage Serverであり、GitHub Actionsを活用したCI/CDパイプラインを通じて、複数プラットフォーム向けのネイティブバイナリを自動ビルド・配布しています。

## システム構成

### 全体構成

clojure-lspはオープンソースのデスクトップ開発ツールであり、サーバーレスアーキテクチャを採用しています。本番環境のサーバーは存在せず、以下の外部サービスを活用してソフトウェア配布を行っています：

- **ソースコード管理**: GitHub（github.com/clojure-lsp/clojure-lsp）
- **CI/CD**: GitHub Actions
- **パッケージ配布**: GitHub Releases、Clojars（Maven Repository）
- **ドキュメントホスティング**: GitHub Pages（clojure-lsp.io）
- **Nixパッケージキャッシュ**: Cachix

### サーバー構成

本プロジェクトはデスクトップアプリケーションのため、従来のサーバー構成は存在しません。代わりに、ビルド・配布に使用されるCI/CDランナーの構成を以下に示します。

| ランナー種別 | 役割 | スペック | 用途 |
| --- | --- | --- | --- |
| ubuntu-22.04 | メインビルドランナー | GitHub Actions標準 | Linux AMD64ビルド、リリース、テスト |
| ubuntu-24.04-arm | ARMビルドランナー | GitHub Actions標準 | Linux AArch64ビルド |
| macos-15-intel | macOS Intel ビルドランナー | GitHub Actions標準 | macOS AMD64ビルド |
| macos-14 | macOS Apple Silicon ビルドランナー | GitHub Actions標準 | macOS AArch64ビルド |
| windows-latest | Windows ビルドランナー | GitHub Actions標準 | Windows AMD64ビルド |

### ネットワーク構成

本プロジェクトは外部サービスを活用したサーバーレス構成のため、プロジェクト固有のネットワーク構成は存在しません。すべての通信はパブリックインターネット経由でHTTPS通信を使用します。

主要なネットワーク通信:
- **GitHub → Clojars**: アーティファクトのデプロイ
- **GitHub Actions → GitHub Releases**: バイナリのアップロード
- **GitHub Actions → Cachix**: Nixパッケージのキャッシュ
- **GitHub Actions → Slack**: Nightly ビルド通知

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| GraalVM | 21（graalvm distribution） | ネイティブイメージのビルド |
| GraalVM (Windows) | 22.2.0 / Java 11 | Windowsネイティブイメージのビルド |
| JDK | 11, 15, 17, 19 | JVMテスト実行、JARビルド |
| Clojure CLI | 1.12.0.1495 | Clojureプロジェクトビルド |
| Babashka | 0.9.161 | ビルドスクリプト実行 |
| Leiningen | 2.9.1 | 統合テスト用 |
| Boot | 2.8.3 | 統合テスト用 |
| UPX | 最新 | バイナリ圧縮 |
| MSVC | 最新 | Windowsネイティブビルド |
| Docker | GitHub Actions標準 | ドキュメント生成 |
| MkDocs | docker.pkg.github.com/clojure-lsp/docs-image/docs-image | 静的サイト生成 |
| Nix | nixos-unstable | 再現可能なビルド |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| GitHub Actions | CI/CDパイプライン | GitHub統合 |
| GitHub Releases | バイナリ配布 | REST API (gh CLI) |
| GitHub Pages | ドキュメントホスティング | GitHub統合 |
| Clojars | Mavenアーティファクト配布 | HTTPS (Maven deploy) |
| Cachix | Nixパッケージキャッシュ | HTTPS |
| Slack (Clojurians) | Nightlyビルド通知 | Webhook |

## スケーリング設計

### CI/CD スケーリング

本プロジェクトはGitHub Actionsを使用したサーバーレスCI/CDを採用しており、以下のスケーリング特性を持ちます：

- **並列ビルド**: リリースワークフローでは最大7つのプラットフォーム向けビルドを並列実行
- **マトリクスビルド**: 複数のJDKバージョン（11, 15, 17, 19）と複数のOS（Ubuntu, macOS, Windows）でのテスト並列実行
- **自動スケーリング**: GitHub Actionsランナーは需要に応じて自動的にスケール

### リソース割り当て

| ビルドタイプ | メモリ設定 | 備考 |
| --- | --- | --- |
| ネイティブイメージビルド (Linux/macOS) | -J-Xmx6g | GraalVM native-image用 |
| ネイティブイメージビルド (Windows) | -J-Xmx7g | Windows Pagefile設定：8GB-16GB |

## 可用性設計

### 配布チャネルの冗長性

本プロジェクトは複数の配布チャネルを提供することで可用性を確保しています：

| 配布形式 | 提供先 | 対象ユーザー |
| --- | --- | --- |
| ネイティブバイナリ（zip） | GitHub Releases | エンドユーザー |
| JARファイル（standalone） | GitHub Releases, Clojars | JVMユーザー、CI環境 |
| JARファイル（server） | GitHub Releases, Clojars | ライブラリ利用者 |
| JARファイル（lib） | Clojars | 開発者 |
| Nixパッケージ | Cachix, nixpkgs | Nixユーザー |

### Nightlyビルド

開発版は `clojure-lsp/clojure-lsp-dev-builds` リポジトリに自動的にリリースされ、最新の開発状態を常に提供します。

### 継続的インテグレーション

- **lint**: ソースコード品質チェック
- **unit-test**: 複数JDKバージョン・複数OSでのユニットテスト
- **jvm-integration-test**: JVM統合テスト
- **graalvm-build**: ネイティブイメージビルドテスト
- **graalvm-integration-test**: ネイティブイメージ統合テスト
- **nix-flake-test**: Nixビルドテスト

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| ソースコード | Git（分散型VCS） | コミット毎 | 無期限 |
| リリースアーティファクト | GitHub Releases | リリース毎 | 無期限 |
| Nightlyビルド | GitHub Releases (dev-builds) | 日次 | 無期限 |
| Clojarsアーティファクト | Clojars | リリース毎 | 無期限 |
| Nixキャッシュ | Cachix | ビルド毎 | Cachixポリシーに準拠 |

## 監視設計

### GitHub Actions監視

- **ビルドステータス**: GitHub Actionsダッシュボード、README.mdバッジ
- **テスト結果**: GitHub Actions実行ログ
- **ビルド通知**: Slack Webhook（Nightlyビルド完了時）

### 品質メトリクス

| メトリクス | 収集方法 | 表示場所 |
| --- | --- | --- |
| ビルドステータス | GitHub Actions | READMEバッジ |
| ダウンロード数 | GitHub API | READMEバッジ |
| Clojarsダウンロード | Clojars API | READMEバッジ |
| ドキュメント | cljdoc | cljdocバッジ |

## ビルドアーティファクト一覧

### ネイティブバイナリ

| アーティファクト名 | プラットフォーム | 備考 |
| --- | --- | --- |
| clojure-lsp-native-linux-amd64.zip | Linux x86_64 | UPX圧縮 |
| clojure-lsp-native-static-linux-amd64.zip | Linux x86_64 (static) | musl libc使用 |
| clojure-lsp-native-linux-aarch64.zip | Linux ARM64 | - |
| clojure-lsp-native-macos-amd64.zip | macOS x86_64 | - |
| clojure-lsp-native-macos-aarch64.zip | macOS ARM64 (Apple Silicon) | - |
| clojure-lsp-native-windows-amd64.zip | Windows x86_64 | UPX圧縮 |

### JARファイル

| アーティファクト名 | 用途 |
| --- | --- |
| clojure-lsp.jar | ライブラリJAR |
| clojure-lsp-server.jar | サーバーJAR |
| clojure-lsp-standalone.jar | スタンドアロンJAR（全依存関係含む） |
| clojure-lsp（Unix）/ clojure-lsp.bat（Windows） | JVM埋め込みバイナリ |

## 備考

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

- **シークレット管理**: GitHub Secrets（CLOJURE_LSP_BOT_TOKEN、CACHIX_AUTH_TOKEN、CLOJURIANS_SLACK_WEBHOOK）
- **SHA256チェックサム**: 全アーティファクトにSHA256チェックサムファイルを提供
- **署名**: 未対応（将来的な検討事項）

### 将来の拡張計画

- Alpine Linux向けの完全静的バイナリ（musl libc使用）のサポート強化
- Apple Silicon向けの最適化
- ARM64 Windows対応（需要次第）
