# インフラ設計書

## 概要

本ドキュメントは、mruby プロジェクトの開発・ビルド・テスト・リリースに関するインフラ構成を記載する。mruby は軽量 Ruby 実装であり、組み込みシステム向けの言語処理系である。本プロジェクトは Web サービスとしてのデプロイインフラではなく、OSS 開発プロジェクトとしての CI/CD パイプライン、ビルド環境、コード品質管理を中心としたインフラ構成を持つ。

## システム構成

### 全体構成

mruby プロジェクトのインフラは以下の3層で構成される。

1. **ローカル開発環境**: Docker コンテナによるビルド・テスト環境を提供
2. **CI/CD パイプライン**: GitHub Actions を中心とした自動ビルド・テスト・リリース基盤
3. **補助 CI サービス**: Travis CI、AppVeyor による追加プラットフォーム向けテスト

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| GitHub Actions Runner (ubuntu-24.04) | Linux ビルド・テスト (GCC/Clang) | GitHub ホスト型 | マトリクス実行（最大8並列） |
| GitHub Actions Runner (ubuntu-22.04) | Linux ビルド・テスト (GCC/Clang) | GitHub ホスト型 | マトリクス実行 |
| GitHub Actions Runner (macos-15) | macOS ビルド・テスト (Clang) | GitHub ホスト型 | マトリクス実行 |
| GitHub Actions Runner (macos-14) | macOS ビルド・テスト (Clang) | GitHub ホスト型 | マトリクス実行 |
| GitHub Actions Runner (windows-2025) | Windows ビルド・テスト (MinGW GCC) | GitHub ホスト型 | マトリクス実行 |
| GitHub Actions Runner (windows-2022) | Windows ビルド・テスト (MinGW GCC / MSVC) | GitHub ホスト型 | マトリクス実行 |
| Travis CI Runner | Linux / macOS ビルド・テスト | Travis CI ホスト型 | 2（linux, osx） |
| AppVeyor Runner | Windows ビルド・テスト (Visual Studio 2015-2022) | AppVeyor ホスト型 | 7（VS バージョンごと） |

### ネットワーク構成

本プロジェクトは SaaS ベースの CI/CD サービスを利用しており、独自のネットワークインフラは持たない。

- **GitHub**: ソースコード管理、Issue 管理、Pull Request レビュー、リリース管理
- **GitHub Actions**: CI/CD パイプラインの実行基盤（GitHub ネットワーク内で完結）
- **Travis CI**: 補助 CI サービス（外部ネットワーク経由で GitHub と連携）
- **AppVeyor**: Windows 向け補助 CI サービス（外部ネットワーク経由で GitHub と連携）
- **RubyGems.org**: Gem 依存関係の取得元
- **Google OSS-Fuzz**: ファジングテスト基盤（外部ネットワーク経由で GitHub と連携）

## コンテナ構成

### Docker イメージ

| 項目 | 内容 |
| --- | --- |
| ベースイメージ | `ruby:3.2.2-bullseye` |
| 追加パッケージ | `python3-pip`, `shellcheck` |
| Ruby 依存管理 | Bundler (`bundle install`) |
| Python ツール | pre-commit |
| 作業ディレクトリ | `/app` |

### docker-compose 構成

| サービス名 | 用途 | 環境変数 |
| --- | --- | --- |
| test | ビルド・テスト実行 | `MRUBY_CONFIG=ci/gcc-clang`, `CC=gcc`, `CXX=g++`, `LD=gcc`, `SKIP=check-executables-have-shebangs` |

**docker-compose バージョン**: 3.8

**実行コマンド**: `sh -c 'rake deep_clean && rake -m test:run:serial'`

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Ruby | 3.2.2 | ビルドシステムの実行環境（Rake） |
| Rake | 13.3.1 | ビルドタスク管理 |
| Bundler | 2.4.10 | Ruby Gem 依存管理 |
| Docker | - | ローカルビルド・テスト環境のコンテナ化 |
| Docker Compose | 3.8 (spec version) | マルチコンテナ管理 |
| pre-commit (prek) | >= 3.2.0 | コード品質チェックの自動化 |
| GCC | - | C コンパイラ（Linux / Windows MinGW） |
| Clang | 18 (Coverage 用) | C コンパイラ（Linux / macOS） |
| MSVC | 2015-2022 | C コンパイラ（Windows） |
| YARD | 0.9.38 | Ruby API ドキュメント生成 |
| yard-coderay | 0.1.0 | YARD のシンタックスハイライト |
| yard-mruby | 0.3.0 | mruby 固有の YARD 拡張 |
| cosmocc | 20260104 | Cosmopolitan ビルド用ツールチェーン |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| GitHub | ソースコード管理、Issue/PR 管理、リリース管理 | HTTPS / Git プロトコル |
| GitHub Actions | CI/CD パイプライン | GitHub イベントトリガー（push, pull_request, tag） |
| Travis CI | 補助 CI（Linux / macOS） | GitHub Webhook |
| AppVeyor | 補助 CI（Windows / Visual Studio） | GitHub Webhook |
| Google OSS-Fuzz | ファジングテスト | GitHub Actions 連携 |
| GitHub CodeQL | セキュリティ静的解析 | GitHub Actions 連携 |
| GitHub Dependabot | 依存関係の自動更新 | GitHub ネイティブ連携 |
| RubyGems.org | Gem パッケージの取得 | HTTPS |
| softprops/action-gh-release | GitHub Release の自動作成 | GitHub Actions 連携 |
| Super-Linter | 複合 Linter（Dockerfile hadolint 等） | GitHub Actions 連携 |

## CI/CD パイプライン設計

### GitHub Actions ワークフロー一覧

| ワークフロー名 | トリガー | 目的 | タイムアウト |
| --- | --- | --- | --- |
| Build & Test | push, pull_request | マルチプラットフォームビルド・テスト | 10-15 分 |
| Coverage | push | コードカバレッジ計測・レポート生成 | - |
| Release Builds | tag push (`*.*.*`) | リリースパッケージの作成・公開 | 10 分 |
| CodeQL Analysis | push/PR to master | セキュリティ静的解析 | - |
| CIFuzz (OSS-Fuzz) | pull_request | ファジングテスト（600秒） | - |
| Super-Linter | pull_request | コード品質チェック | - |
| ls-lint | pull_request | ファイル名規則チェック | - |
| pre-commit | pull_request | pre-commit フック実行 | - |
| Pull Request Labeler | pull_request_target | PR の自動ラベル付け | - |

### Build & Test マトリクス

| OS | コンパイラ | 備考 |
| --- | --- | --- |
| ubuntu-24.04 | GCC | - |
| ubuntu-24.04 | Clang | - |
| ubuntu-22.04 | GCC | - |
| ubuntu-22.04 | Clang | - |
| macos-15 | Clang | - |
| macos-14 | Clang | - |
| windows-2025 | MinGW GCC | - |
| windows-2022 | MinGW GCC | - |
| windows-2022 | MSVC | 別ジョブ（Windows-VC） |
| ubuntu-24.04 | cosmocc | Cosmopolitan ビルド |

### リリースプロセス

1. タグ (`*.*.*`) の push をトリガーに `release.yml` が起動
2. `mruby/mruby` リポジトリのみで実行（`github.repository == 'mruby/mruby'`）
3. `git archive` でソースコードパッケージを3形式で生成:
   - `.zip`
   - `.tar.gz`
   - `.tar.xz`
4. SHA256 チェックサムファイルを生成
5. `softprops/action-gh-release` でドラフトリリースを作成
6. `-rc` を含むタグはプレリリースとして扱う

### Dependabot 設定

| パッケージエコシステム | ディレクトリ | 更新間隔 | クールダウン |
| --- | --- | --- | --- |
| bundler | `/` | daily | 7 日 |
| github-actions | `/` | daily | 7 日 |

## コード品質管理

### pre-commit フック構成

| フック | ツール | 目的 |
| --- | --- | --- |
| gitleaks | gitleaks v8.30.0 | ハードコードされたシークレットの検出 |
| oxipng | oxipng v10.0.0 | PNG ファイルのロスレス圧縮（manual ステージ） |
| check-added-large-files | pre-commit-hooks v6.0.0 | 大きなファイルのコミット防止 |
| check-case-conflict | pre-commit-hooks | ファイル名の大文字小文字衝突検出 |
| check-executables-have-shebangs | pre-commit-hooks | 実行可能ファイルの shebang 確認 |
| detect-aws-credentials | pre-commit-hooks | AWS 認証情報の検出 |
| detect-private-key | pre-commit-hooks | 秘密鍵の検出 |
| forbid-tabs | Lucas-C/pre-commit-hooks v1.5.5 | タブ文字の禁止（Makefile 除外） |
| actionlint | rhysd/actionlint v1.7.9 | GitHub Actions ワークフローの lint |
| codespell | codespell v2.4.1 | スペルチェック |
| markdownlint | markdownlint-cli v0.46.0 | Markdown スタイルチェック |
| rubocop | rubocop v1.81.7 | Ruby コードスタイルチェック |
| shellcheck | shellcheck v0.11.0.1 | シェルスクリプト静的解析 |
| yamllint | yamllint v1.37.1 | YAML ファイルの lint |

## スケーリング設計

本プロジェクトは OSS 開発プロジェクトであり、CI/CD パイプラインのスケーリングは利用する SaaS サービスに依存する。

- **GitHub Actions**: 最大8並列のマトリクスビルド（`max-parallel: 8`）で構成
- **Travis CI / AppVeyor**: 各サービスの無料枠・プラン内で運用
- **ローカルビルド**: Docker Compose を利用した単一コンテナ実行

## 可用性設計

OSS 開発プロジェクトとして、CI/CD サービスの可用性は各 SaaS プロバイダーの SLA に依存する。

- **GitHub Actions**: GitHub の SLA に準拠
- **Travis CI / AppVeyor**: 各サービスの SLA に準拠
- **CI の冗長性**: 同一テストを複数の CI サービス（GitHub Actions, Travis CI, AppVeyor）で実行することで、単一 CI サービスの障害時でもテスト結果を確認可能
- **ビルドマトリクスの `fail-fast: false` 設定**: 一部のビルドが失敗しても他のビルドを継続実行

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| ソースコード | GitHub リポジトリ（分散 Git） | リアルタイム（push ごと） | 無期限 |
| リリースパッケージ | GitHub Releases | タグ push 時 | 無期限 |
| カバレッジレポート | GitHub Actions Artifacts | push 時 | 3 日間 |
| ファジングクラッシュレポート | GitHub Actions Artifacts | 失敗時のみ | デフォルト（90 日） |

## 監視設計

本プロジェクトでは以下の監視・通知機構を利用する。

- **GitHub Actions ステータスチェック**: PR へのビルド結果の自動フィードバック
- **GitHub CodeQL**: セキュリティ脆弱性の自動検出とアラート
- **GitHub Dependabot**: 依存関係の脆弱性検出と自動更新 PR 作成
- **OSS-Fuzz**: ファジングテストによるクラッシュバグの検出
- **Super-Linter / pre-commit**: コード品質の継続的監視

## ビルドシステム設計

### ビルドツールチェーン

mruby は Rake をビルドシステムとして使用し、以下のビルドタスクを提供する。

| タスク | コマンド | 説明 |
| --- | --- | --- |
| all | `rake` / `make` | 全ターゲットのビルドとローカルインストール |
| test | `rake test` / `make test` | ビルドと全テストの実行 |
| clean | `rake clean` / `make clean` | ビルド成果物のクリーンアップ |
| deep_clean | `rake deep_clean` | 全ビルド成果物と mrbgems の完全クリーンアップ |
| check | `rake check` / `make check` | pre-commit フックの全ファイル実行 |
| composetest | `rake composetest` / `make composetest` | Docker Compose によるビルド・テスト |
| composecheck | `rake composecheck` / `make composecheck` | Docker Compose による pre-commit 実行 |
| doc | `rake doc` | ドキュメント生成（YARD + Doxygen） |
| amalgam | `rake amalgam` | 単一ファイルビルド（mruby.c / mruby.h） |

### クロスコンパイル対応プラットフォーム

`build_config/` ディレクトリに以下のプラットフォーム向けビルド設定が用意されている。

| ビルド設定 | ターゲットプラットフォーム |
| --- | --- |
| default.rb | ホスト環境 |
| host-debug.rb | ホスト環境（デバッグ） |
| host-shared.rb | ホスト環境（共有ライブラリ） |
| android_arm64_v8a.rb | Android ARM64 |
| android_armeabi_v7a_neon_hard.rb | Android ARMv7 |
| cosmopolitan.rb | Cosmopolitan Libc（ポータブルバイナリ） |
| emscripten.rb | WebAssembly (Emscripten) |
| cross-mingw.rb | Windows (MinGW クロスコンパイル) |
| ArduinoDue.rb | Arduino Due |
| IntelEdison.rb | Intel Edison |
| IntelGalileo.rb | Intel Galileo |
| RX630.rb | Renesas RX630 |
| nintendo_switch.rb | Nintendo Switch |
| nintendo_wii.rb | Nintendo Wii |
| gameboyadvance.rb | Game Boy Advance |
| playstationportable.rb | PlayStation Portable |
| dreamcast_shelf.rb | Dreamcast |
| milkv_duo.rb | Milk-V Duo |
| luckfox_pico.rb | LuckFox Pico |
| serenity.rb | SerenityOS |

## 備考

- mruby は Web サービスやクラウドアプリケーションではなく、組み込み向け軽量 Ruby 言語処理系の OSS プロジェクトである。そのため、本インフラ設計書では従来の Web サービス向けインフラ（ロードバランサ、DB サーバー、CDN 等）ではなく、CI/CD パイプライン、ビルド環境、コード品質管理を中心に記載した。
- Terraform、CloudFormation、Kubernetes 等の IaC / コンテナオーケストレーション設定は本プロジェクトには存在しない。
- Docker / Docker Compose はプロダクション環境向けではなく、ローカル開発環境でのビルド・テスト用途に限定される。
- 環境変数 `MRUBY_CONFIG` によりビルド設定を切り替える仕組みとなっており、CI 環境では `ci/gcc-clang` や `ci/msvc` が使用される。
