# 非機能要件定義書

## 概要

本ドキュメントは、mruby（軽量Ruby実装、バージョン3.4.0）の非機能要件を、ソースコード・設定ファイル・ドキュメントから逆引きして定義したものである。mrubyは組み込みシステム向けの軽量Ruby処理系であり、マイクロコントローラからデスクトップ・サーバまで幅広い環境への適合を設計思想としている。本書では、性能、可用性、セキュリティ、拡張性、保守性、運用・監視の各観点から要件を整理する。

## 性能要件

### メモリ管理・ガベージコレクション

mrubyの性能特性は、主にガベージコレクション（GC）とメモリ管理の設定に依存する。以下のパラメータがビルド時に設定可能である。

| 項目 | デフォルト値 | 設定マクロ | 備考 |
| --- | --- | --- | --- |
| ヒープページサイズ（オブジェクト数/ページ） | 1024 | `MRB_HEAP_PAGE_SIZE` | Constrainedプロファイルでは256、Main/Highプロファイルでは4096 |
| GCインターバル比率 | 200 | `DEFAULT_GC_INTERVAL_RATIO` | gc_interval_ratio_set APIで実行時調整可能 |
| GCステップ比率 | 200 | `DEFAULT_GC_STEP_RATIO` | gc_step_ratio_set APIで実行時調整可能 |
| GCステップサイズ | 1024 | `GC_STEP_SIZE` | インクリメンタルGCの1ステップあたりの処理量 |
| Major GC増加比率 | 120 | `MAJOR_GC_INC_RATIO` | 世代別GCにおけるメジャーGC閾値の増加率 |
| Major GC上限 | 10000 | `MAJOR_GC_TOOMANY` | この値を超えるとメジャーGCが強制発動 |
| GCアリーナサイズ | 100 | `MRB_GC_ARENA_SIZE` | 固定サイズアリーナ使用時のデフォルト値 |
| グレースタックサイズ | 1024 | `MRB_GRAY_STACK_SIZE` | マーク用グレーオブジェクトスタック |
| 世代別GC | デフォルト有効 | `MRB_GC_TURN_OFF_GENERATIONAL` | 定義するとオフ |

### メソッドキャッシュ

| 項目 | デフォルト値 | 設定マクロ | 備考 |
| --- | --- | --- | --- |
| メソッドキャッシュサイズ | 256（2^8） | `MRB_METHOD_CACHE_SIZE` | 2のべき乗で指定。Mainプロファイル:1024、Highプロファイル:4096 |
| メソッドキャッシュ無効化 | 無効（キャッシュ有効） | `MRB_NO_METHOD_CACHE` | Constrainedプロファイルでは無効化 |

### スタック設定

| 項目 | デフォルト値 | 設定マクロ | 備考 |
| --- | --- | --- | --- |
| 初期スタックサイズ | 128スロット | `STACK_INIT_SIZE` | VM実行スタック |
| コールインフォ初期サイズ | 32エントリ | `CALLINFO_INIT_SIZE` | 呼び出し情報スタック |
| スタック成長量 | 128 | `MRB_STACK_GROWTH` | 線形成長時の最小増分 |
| 最大スタックサイズ | 0x40000 - MRB_STACK_GROWTH（約262,016スロット、約60,000再帰呼び出し相当） | `MRB_STACK_MAX` | 超過時にSystemStackError |
| 最大再帰呼び出し深度 | 512（ASAN使用時は128） | `MRB_CALL_LEVEL_MAX` | 超過時にSystemStackError |

### メモリプール設定

| 項目 | デフォルト値 | 設定マクロ | 備考 |
| --- | --- | --- | --- |
| プールページサイズ | 16,000バイト | `POOL_PAGE_SIZE` | コンパイラ等の内部用メモリプール |
| プールアライメント | 4バイト（32bit）/ 8バイト（64bit） | `POOL_ALIGNMENT` | アーキテクチャに応じて自動選択 |

### データ構造制限

| 項目 | デフォルト値 | 設定マクロ | 備考 |
| --- | --- | --- | --- |
| 文字列最大長 | 1,048,576バイト（1MB）（Linux/macOS/FreeBSD/OpenBSDでは無制限） | `MRB_STR_LENGTH_MAX` | 0でチェック無効化 |
| 配列最大長 | 131,072エントリ（2^17） | `MRB_ARY_LENGTH_MAX` | 0でチェック無効化 |
| mrb_funcall最大引数数 | 16 | `MRB_FUNCALL_ARGC_MAX` | C APIからの関数呼び出し引数上限 |
| ハッシュテーブルデフォルトサイズ | 32 | `KHASH_DEFAULT_SIZE` | Constrainedプロファイルでは16 |
| シンボルテーブル線形探索閾値 | 256 | `MRB_SYMBOL_LINEAR_THRESHOLD` | 超過時にハッシュテーブルに切り替え |

### チューニングプロファイル

mrubyは用途に応じた4つのプロファイルを提供する。

| プロファイル | マクロ | メソッドキャッシュ | ヒープページサイズ | 対象環境 |
| --- | --- | --- | --- | --- |
| Constrained Baseline | `MRB_CONSTRAINED_BASELINE_PROFILE` | 無効 | 256 | マイクロコントローラ |
| Baseline（デフォルト） | `MRB_BASELINE_PROFILE` | 256 | 1024 | 汎用 |
| Main | `MRB_MAIN_PROFILE` | 1024 | 4096 | デスクトップ/ワークステーション |
| High | `MRB_HIGH_PROFILE` | 4096 | 4096 | サーバ（長寿命VM） |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| CIビルド＋テスト実行時間 | 10分以内 | GitHub Actions CI設定の `timeout-minutes: 10` |
| ファズテスト実行時間 | 600秒（10分） | OSS-Fuzz CIの `fuzz-seconds: 600` |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| メモリ不足時の挙動 | NoMemoryError例外の送出 | 事前割り当て済みエラーオブジェクトによりOOM状態でも例外処理が可能。mrb_realloc_simple()でメモリ確保失敗時にフルGCを実行し、再試行する |
| スタックオーバーフロー時の挙動 | SystemStackError例外の送出 | 事前割り当て済みエラーオブジェクトで検出・通知 |
| GCアリーナオーバーフロー時の挙動 | アリーナ自動拡張（動的モード）またはRuntimeError（固定モード） | 固定アリーナ使用時は事前割り当て済みのarena_errで通知 |
| malloc(3)がNULL返却した場合 | グレースフルエラー処理 | SECURITY.mdにて、NULL返却は正常なエラーハンドリングと定義 |
| リソース枯渇管理 | ホストアプリケーションの責務 | 無限ループ、過大メモリ割り当て等はmruby側のスコープ外。ホスト側でサンドボックス・リソース制限を実装する設計 |
| 状態終了処理 | mrb_state_atexit()による登録 | 最大5つ（固定スタック時）のクリーンアップ関数を登録可能 |

## セキュリティ要件

### セキュリティポリシー

mrubyのセキュリティモデルは、ホストアプリケーションへの組み込みを前提として設計されている。サンドボックスとリソース管理はホスト側の責務である。

| 脅威カテゴリ | 優先度 | 対応 |
| --- | --- | --- |
| リモートコード実行（RCE） | 高 | セキュリティ脆弱性として報告対象。matz@ruby.or.jpへの報告 |
| 有効なRubyコードによるVMクラッシュ | 低（バグ報告推奨） | DoS限定の影響。issueトラッカーでのバグ報告を推奨 |
| リソース枯渇 | 対象外 | ホストアプリケーションの責務 |
| 不正バイトコードによるクラッシュ | 対象外 | バイトコードはセキュリティ境界でない。信頼されたソースのみ実行 |
| C API誤用によるクラッシュ | 対象外 | C APIは信頼されたインターフェース |
| 理論的未定義動作 | 対象外 | 実用的セキュリティ影響がある場合のみ対処 |

### 静的解析・セキュリティテスト

| 項目 | 対応内容 | 根拠 |
| --- | --- | --- |
| CodeQL解析 | GitHub Actions上でmaster/PRに対して自動実行 | `.github/workflows/codeql-analysis.yml` |
| ファズテスト（OSS-Fuzz） | Google OSS-Fuzz統合。PRごとにファジングビルド・実行（600秒） | `.github/workflows/oss-fuzz.yml`, `oss-fuzz/` |
| AddressSanitizer/UBSan | clang-asanビルド設定で検証可能 | `build_config/clang-asan.rb` |
| 依存関係自動更新 | Dependabotによるbundler/GitHub Actionsの日次チェック | `.github/dependabot.yml` |
| スーパーリンター | GitHub Super-Linterによるコード品質チェック | `.github/workflows/super-linter.yml` |
| Pre-commitフック | コミット前の自動品質チェック | `.github/workflows/pre-commit.yml`, `Makefile` |

### メモリ安全性

| 項目 | 対応内容 | 根拠 |
| --- | --- | --- |
| 整数オーバーフロー防止 | mrb_calloc()でnelem * lenのオーバーフローチェック | `src/gc.c` |
| 文字列長チェック | str_check_length()による負数・上限チェック | `src/string.c` |
| Write Barrier | GCの整合性維持のためのmrb_field_write_barrier / mrb_write_barrier | `src/gc.c` |
| 事前割当エラーオブジェクト | NoMemoryError, SystemStackError, arena overflow errorを起動時に事前割当 | `src/error.c` |

## 拡張性要件

### モジュラーアーキテクチャ（mrbgems）

mrubyはmrbgemsパッケージマネージャによるモジュラー拡張を提供する。

| 項目 | 内容 |
| --- | --- |
| 拡張方式 | mrbgems（C拡張/Ruby拡張/混合拡張） |
| gembox機構 | default, full-core, stdlib, metaprog等のプリセットグループ |
| 標準同梱gem数 | 約70個（コンパイラ、数学、IO、ソケット、タスク等） |
| gem除外 | `MRB_NO_GEMS`マクロでgem完全無効化可能 |

### ビルド時構成の柔軟性

| 項目 | 内容 |
| --- | --- |
| アーキテクチャ対応 | 32bit/64bit自動検出。`MRB_32BIT`/`MRB_64BIT`で手動指定可能 |
| 整数型選択 | 32bit整数（`MRB_INT32`）/ 64bit整数（`MRB_INT64`） |
| 浮動小数点選択 | 64bit double（デフォルト）/ 32bit float（`MRB_USE_FLOAT32`）/ 無効化（`MRB_NO_FLOAT`） |
| 値表現方式 | Word Boxing（デフォルト）/ NaN Boxing / No Boxing |
| stdio依存除去 | `MRB_NO_STDIO`でstdio関数の使用を排除 |
| メモリアロケータ差替え | `mrb_basic_alloc_func()`のオーバーライド、またはmalloc/realloc/freeの差替え |
| 文字列エンコーディング | `MRB_UTF8_STRING`でUTF-8サポート有効化 |

### クロスコンパイル対応

| プラットフォーム | 設定ファイル |
| --- | --- |
| Arduino Due | `build_config/ArduinoDue.rb` |
| Intel Edison / Galileo | `build_config/IntelEdison.rb`, `build_config/IntelGalileo.rb` |
| Android (ARM64/ARMv7) | `build_config/android_arm64_v8a.rb`, `build_config/android_armeabi_v7a_neon_hard.rb` |
| Emscripten (WebAssembly) | `build_config/emscripten.rb` |
| Nintendo Switch/Wii | `build_config/nintendo_switch.rb`, `build_config/nintendo_wii.rb` |
| PlayStation Portable | `build_config/playstationportable.rb` |
| Game Boy Advance | `build_config/gameboyadvance.rb` |
| Cosmopolitan (ポータブル) | `build_config/cosmopolitan.rb` |
| RISC-V (Luckfox Pico, Milk-V Duo) | `build_config/luckfox_pico.rb`, `build_config/milkv_duo.rb` |
| MS-DOS (DJGPP) | `build_config/i586-pc-msdosdjgpp.rb` |
| MinGW (Windows) | `build_config/cross-mingw.rb` |
| SerenityOS | `build_config/serenity.rb` |

### アマルガメーション（単一ファイルビルド）

| 項目 | 内容 |
| --- | --- |
| 機能 | 全ソースを単一の`mruby.c`と`mruby.h`に結合（SQLite類似） |
| ビルドコマンド | `rake amalgam` |
| 出力先 | `build/host/amalgam/` |
| 用途 | 他プロジェクトへの簡易組み込み |

## 保守性要件

### コード品質管理

| 項目 | 内容 | 根拠 |
| --- | --- | --- |
| リンター | GitHub Super-Linter, RuboCop, markdownlint, yamllint, shellcheck, ls-lint | `.github/workflows/super-linter.yml`, `.github/linters/` |
| Pre-commitフック | pre-commit利用による自動チェック | `Makefile`, `.pre-commit-config.yaml` |
| テストフレームワーク | mrbtest（C言語テスト）+ Rubyテスト + bintest | `build_config/default.rb`の`enable_test`, `enable_bintest` |
| CI/CDパイプライン | GitHub Actions（Linux/macOS/Windows）+ AppVeyor（Visual Studio） | `.github/workflows/build.yml`, `appveyor.yml` |
| CIマトリクス | GCC/Clang on Ubuntu 22.04/24.04, Clang on macOS 14/15, MinGW on Windows 2022/2025, MSVC | `.github/workflows/build.yml` |
| 並列テスト | `rake -m test:run:serial`による効率的テスト実行 | CI設定各所 |
| コードカバレッジ | カバレッジ計測ワークフローあり | `.github/workflows/coverage.yml` |

### デバッグ支援

| 項目 | 内容 | 根拠 |
| --- | --- | --- |
| デバッグビルド | `enable_debug`でアサーション有効化 | `build_config/host-debug.rb` |
| デバッグフック | `MRB_USE_DEBUG_HOOK`で命令フェッチフック・デバッグOPフック有効化 | `include/mruby.h`, `doc/guides/mrbconf.md` |
| デバッガ | mrdbコマンド（mruby-bin-debuggerジェム） | `mrbgems/mruby-bin-debugger` |
| GCストレスモード | `MRB_GC_STRESS`で全オブジェクト割当時にフルGC実行（メモリバグ検出） | `src/gc.c`, `doc/guides/mrbconf.md` |
| GCデバッグ | `GC_DEBUG`マクロでGC内部デバッグ出力 | `src/gc.c` |
| VMデバッグ | `VM_DEBUG`マクロでVM内部デバッグ出力 | `src/vm.c` |
| バイトコードデコーダフック | `MRB_BYTECODE_DECODE_OPTION`でバイトコード変換フック | `include/mruby.h` |

### ドキュメント

| 項目 | 内容 |
| --- | --- |
| APIドキュメント | YARD（Ruby API）+ Doxygen/Graphviz（C API） |
| ガイドドキュメント | `doc/guides/`配下に13件のMarkdownドキュメント |
| 制限事項 | `doc/limitations.md`にCRubyとの差異を明文化 |
| ビルド方法 | `doc/guides/compile.md`に詳細記載 |

## 運用・監視要件

### ビルド・テスト運用

| 項目 | 内容 | 根拠 |
| --- | --- | --- |
| CI自動テスト | push/PR時に自動ビルド・テスト実行 | `.github/workflows/build.yml` |
| CI最大並列数 | 8 | `.github/workflows/build.yml`の`max-parallel: 8` |
| CIタイムアウト | 10分（通常ビルド）、15分（Cosmopolitan） | `.github/workflows/build.yml` |
| Docker対応テスト | docker-composeでビルド＋テスト実行可能 | `docker-compose.yml`, `Dockerfile` |
| マルチプラットフォームCI | Linux（Ubuntu 22.04/24.04）、macOS（14/15）、Windows（2022/2025）、AppVeyor（Visual Studio 2015-2022） | `.github/workflows/build.yml`, `appveyor.yml` |

### GC実行時モニタリング

| 項目 | 内容 | 根拠 |
| --- | --- | --- |
| ライブオブジェクト数 | `mrb_gc.live`フィールドで追跡 | `include/mruby/gc.h` |
| GC閾値 | `mrb_gc.threshold`でGC起動閾値を管理 | `include/mruby/gc.h` |
| GC状態 | ROOT/MARK/SWEEPの3状態で遷移管理 | `include/mruby/gc.h` |
| GC無効化フラグ | `mrb_gc.disabled`でGCの一時無効化が可能 | `include/mruby/gc.h` |
| メモリ不足検出 | `mrb_gc.out_of_memory`フラグ | `include/mruby/gc.h` |
| オブジェクト空間走査 | `mrb_objspace_each_objects()`でヒープ上の全オブジェクトを列挙可能 | `include/mruby/gc.h` |
| GC比率調整API | `gc_interval_ratio_set`, `gc_step_ratio_set`で実行時調整 | `src/gc.c` |

### リリース管理

| 項目 | 内容 | 根拠 |
| --- | --- | --- |
| バージョニング | セマンティックバージョニング（3.4.0） | `include/mruby/version.h` |
| リリースワークフロー | GitHub Actionsリリースワークフロー | `.github/workflows/release.yml` |
| 依存関係管理 | Dependabotによる日次自動チェック（bundler, GitHub Actions） | `.github/dependabot.yml` |
| ライセンス | MITライセンス | `LICENSE` |

## 備考

- mrubyはライブラリ/組み込みエンジンとしての性格が強いため、一般的なWebアプリケーションにおけるレスポンスタイム、稼働率、RTO/RPO等の可用性指標はmruby自体には直接適用されない。これらはmrubyを組み込むホストアプリケーション側の責務となる。
- リソース制限（CPU時間上限、メモリ使用量上限、実行タイムアウト等）はmrubyの設計上、ホストアプリケーション側で実装すべきものとして明示されている（SECURITY.md）。
- レートリミット、リトライ設定といったネットワーク関連の非機能要件は、mrubyコアには含まれない。ソケット関連機能はmrbgems（`hal-posix-socket`, `mruby-socket`）としてオプション提供される。
- ロギング機構はmrubyコアには含まれない。`MRB_NO_STDIO`定義時はstdio出力も無効化される。ホスト側でのロギング統合が前提の設計である。
- ベンチマークスイートが`benchmark/`ディレクトリに用意されており、フィボナッチ、マンデルブロ集合、VMディスパッチ等の性能計測が可能である。
