# 機能設計書 156-PseudoRandom\string

## 概要

本ドキュメントは、Hack Standard Library (HSL) における `PseudoRandom\string` 関数の機能設計を記載する。この関数は擬似ランダムな文字列を生成する機能を提供する。

### 本機能の処理概要

`PseudoRandom\string` は、指定された長さの擬似ランダムな文字列を生成する関数である。**重要：現在の実装では、この関数は `SecureRandom\string` への一時的なエイリアスであり、実際には暗号学的に安全な文字列を返す。ただし、この挙動に依存すべきではなく、将来的に変更される可能性がある。**暗号用途には `SecureRandom\string` を明示的に使用すること。

**業務上の目的・背景**：API の一貫性のために、`PseudoRandom` 名前空間にも `string` 関数を提供する。ただし、現時点ではパフォーマンス最適化された擬似乱数版は実装されておらず、`SecureRandom\string` にリダイレクトされている。将来的には、暗号学的安全性が不要な場面で使用できる高速版が提供される可能性がある。

**機能の利用シーン**：
- テストデータのランダム文字列生成
- 一時的な識別子の生成（セキュリティ不要な場面）
- ファイル名のランダム化
- デバッグ用のランダムデータ生成

**主要な処理内容**：
1. `SecureRandom\string` を呼び出し（現在の実装）
2. 結果の文字列を返却

**関連システム・外部連携**：現在の実装では `SecureRandom\string` を経由して `\random_bytes` を使用する。

**権限による制御**：本機能は純粋関数として実装されており、特別な権限は必要としない。`[leak_safe]` コンテキストで実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはUIを持たないライブラリのため画面なし |

## 機能種別

計算処理（乱数生成）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $length | int | Yes | 生成する文字列の長さ | $length >= 0 でなければならない |
| $alphabet | ?string | No | 使用する文字セット。null の場合は生バイト列を返す | 指定する場合は長さ 2 以上 2^56 以下 |

### 入力データソース

現在の実装ではオペレーティングシステムの暗号学的に安全なランダムソース（`SecureRandom\string` 経由）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | 指定された長さのランダム文字列 |

### 出力先

関数の戻り値として呼び出し元に返却

## 処理フロー

### 処理シーケンス

```
1. SecureRandom\string への委譲（現在の実装）
   └─ SecureRandom\string($length, $alphabet) を呼び出し
2. 結果の返却
   └─ SecureRandom\string の結果をそのまま返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SecureRandom\string への委譲]
    B --> C[結果を返却]
    C --> D[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-156-01 | 長さ制約 | 戻り値の長さは $length と一致する | 常時 |
| BR-156-02 | 文字制約 | $alphabet が指定された場合、戻り値は $alphabet の文字のみで構成される | $alphabet != null |
| BR-156-03 | 非依存性 | この関数が暗号学的に安全であることに依存してはならない | 常時 |
| BR-156-04 | 一時的エイリアス | 現在は SecureRandom\string へのエイリアスだが、将来変更される可能性がある | 常時 |

### 計算ロジック

```
// 現在の実装（一時的なエイリアス）
return SecureRandom\string($length, $alphabet);
```

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本機能はデータベース操作を行わない |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | $length < 0 の場合 | 呼び出し側で非負の $length を指定する |
| - | InvariantException | $alphabet の長さが範囲外の場合 | 適切な長さのアルファベットを指定する |

### リトライ仕様

リトライ処理は不要。

## トランザクション仕様

本機能はトランザクションを使用しない純粋関数である。

## パフォーマンス要件

- 現在の実装では `SecureRandom\string` と同等のパフォーマンス
- 将来的にはより高速な擬似乱数版が提供される可能性がある

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

- **警告**：この関数が暗号学的に安全であることに依存してはならない
- 現在の実装は `SecureRandom\string` へのエイリアスだが、これは一時的な実装である
- 暗号用途が必要な場合は、必ず `SecureRandom\string` を明示的に使用すること
- コードコメントにも「This is a temporary alias. You should never, ever depend on this function being cryptographically secure.」と明記されている

## 備考

- 暗号用途が必要な場合は `SecureRandom\string` を使用すること
- 現在の実装は一時的なエイリアスであり、将来のバージョンで実装が変更される可能性がある
- API の一貫性のために提供されている

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

アルファベット定数を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | private.php | `src/private.php` | ALPHABET_ALPHANUMERIC 定数の定義（53-54行目） |
| 1-2 | private.php | `src/random/private.php` | ALPHABET_BASE64、ALPHABET_BASE64_URL 定数の定義（70-73行目） |

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | pseudo.php | `src/random/pseudo.php` | PseudoRandom\string 関数の実装（51-58行目） |

**主要処理フロー**:
1. **51-54行目**: 関数宣言。$length と $alphabet を引数として取る
2. **55-56行目**: コメントで一時的エイリアスであることと、暗号的安全性に依存すべきでないことを警告
3. **57行目**: `SecureRandom\string($length, $alphabet)` を呼び出して結果を返却

```hack
function string(
  int $length,
  ?string $alphabet = null,
)[leak_safe]: string {
  // This is a temporary alias. You should never, ever depend on this function
  // being cryptographically secure.
  return SecureRandom\string($length, $alphabet);
}
```

**読解のコツ**: コメントに「temporary alias」とあり、現在は `SecureRandom\string` への単純なリダイレクトであることを理解する。将来的には独自の擬似乱数実装に置き換わる可能性がある。

#### Step 3: 委譲先を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | secure.php | `src/random/secure.php` | SecureRandom\string 関数の実装（50-59行目） |
| 3-2 | private.php | `src/random/private.php` | random_string 共通実装（15-68行目） |

### プログラム呼び出し階層図

```
PseudoRandom\string($length, $alphabet)
    │
    └─ SecureRandom\string($length, $alphabet) [一時的エイリアス]
           │
           └─ _Private\random_string(lambda, $length, $alphabet)
                  │
                  ├─ invariant() [入力検証]
                  │
                  └─ \random_bytes() [暗号的ランダムソース]
```

### データフロー図

```
[入力]                         [処理]                              [出力]

$length (int) ──────▶┐
                     ├──▶ SecureRandom\string() への委譲
$alphabet (?string) ─┘
                              │
                              ▼
                     SecureRandom\string() 処理
                              │
                              ▼
                          string 返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| pseudo.php | `src/random/pseudo.php` | ソース | PseudoRandom 名前空間の公開関数を定義 |
| secure.php | `src/random/secure.php` | ソース | SecureRandom\string（委譲先）を定義 |
| private.php | `src/random/private.php` | ソース | random_string 共通実装とアルファベット定数を定義 |
| PseudoRandomTest.php | `tests/random/PseudoRandomTest.php` | テスト | PseudoRandom 関数群のユニットテスト |
| RandomTestTrait.php | `tests/random/RandomTestTrait.php` | テスト | 文字列長・文字・位置のテストを含む |
