# 機能設計書 90-base64

## 概要

本ドキュメントは、Nim標準ライブラリのbase64モジュールに関する機能設計書である。Base64エンコード/デコード機能を提供する。

### 本機能の処理概要

base64モジュールは、RFC 4648で定義されたBase64エンコーディングを実装する。バイナリデータをASCII文字列に変換し、テキストベースのプロトコルでバイナリデータを安全に転送できるようにする。

**業務上の目的・背景**：Email、HTTP、JSON、XMLなどテキストベースのプロトコルでバイナリデータを扱う必要がある場面で広く使用される。3バイトのバイナリデータを4文字のASCII文字列に変換することで、どのような環境でも安全にデータを転送できる。

**機能の利用シーン**：Emailの添付ファイル（MIME）、HTTP認証ヘッダ（Basic認証）、Data URI、JWT、WebSocket、API通信など。

**主要な処理内容**：
1. バイナリ/文字列のBase64エンコード（encode関数）
2. Base64文字列のデコード（decode関数）
3. MIME形式エンコード（encodeMime関数、行分割対応）
4. URL-safe Base64対応（safeパラメータ）

**関連システム・外部連携**：md5、sha1等のハッシュ関数と併用される。

**権限による制御**：特になし。

## 関連画面

該当なし

## 機能種別

エンコード/デコード変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| s | openArray[T] | Yes | エンコード対象データ（byte/char） | - |
| s | string | Yes | デコード対象のBase64文字列 | 有効なBase64文字列 |
| safe | bool | No | URL-safe Base64を使用するか | デフォルトfalse |
| lineLen | Positive | No | MIME形式での1行の長さ | デフォルト75 |
| newLine | string | No | MIME形式での改行文字 | デフォルト"\r\n" |

### 入力データソース

任意のバイナリ/文字列データ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| encoded | string | Base64エンコードされた文字列 |
| decoded | string | デコードされたバイナリデータ |

### 出力先

戻り値

## 処理フロー

### 処理シーケンス

```
1. エンコード処理
   └─ encode(s, safe)
      ├─ 3バイトずつ読み込み
      ├─ 24ビットを6ビット×4に分割
      ├─ 各6ビット値をアルファベット表で変換
      ├─ パディング処理（=）
      └─ safe=trueなら+→-, /→_に置換

2. MIME形式エンコード
   └─ encodeMime(s, lineLen, newLine, safe)
      ├─ encode(s, safe)でエンコード
      └─ lineLenごとに改行を挿入

3. デコード処理
   └─ decode(s)
      ├─ 先頭の空白をスキップ
      ├─ 末尾の=やスペースを除去
      ├─ 4文字ずつ読み込み
      ├─ デコードテーブルで6ビット値に変換
      ├─ 4×6ビット→3バイトに結合
      └─ 結果文字列を返却
```

### フローチャート

```mermaid
flowchart TD
    A[入力データ] --> B{操作}
    B -->|encode| C[3バイトずつ処理]
    B -->|decode| D[4文字ずつ処理]

    C --> E[24ビット→6ビット×4]
    E --> F[アルファベット変換]
    F --> G{パディング必要?}
    G -->|Yes| H[=追加]
    G -->|No| I[safe処理]
    H --> I
    I --> J{safe?}
    J -->|Yes| K[+→- /→_]
    J -->|No| L[結果返却]
    K --> L

    D --> M[デコードテーブル参照]
    M --> N[6ビット×4→24ビット]
    N --> O[3バイトに分割]
    O --> P[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-90-01 | 標準Base64 | A-Z, a-z, 0-9, +, / を使用 | safe=false |
| BR-90-02 | URL-safe Base64 | A-Z, a-z, 0-9, -, _ を使用 | safe=true |
| BR-90-03 | パディング | 3の倍数でない場合は=でパディング | エンコード時 |
| BR-90-04 | 空白スキップ | デコード時は先頭空白と末尾の=を除去 | デコード時 |

### 計算ロジック

**エンコードサイズ計算**:
- 出力サイズ = ceil(入力サイズ / 3) * 4 + 余裕

**Base64アルファベット**:
- 標準: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
- URL-safe: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ValueError | 不正な文字 | デコード時に無効な文字を検出 | 入力データを確認 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- O(n) where n = 入力データサイズ
- エンコード: 入力の約1.33倍の出力
- デコードテーブルはコンパイル時に生成

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

- Base64は暗号化ではない（単なるエンコーディング）
- 機密データの保護にはBase64+暗号化を併用すべき
- URL-safeモードはURLに含める場合に使用

## 備考

- Unstable APIとマークされている
- MIME形式は email/HTTP での使用を想定

---

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

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

### 推奨読解順序

#### Step 1: 定数とテーブルを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | base64.nim | `lib/pure/base64.nim` | cbBaseテンプレート（62-67行目） |
| 1-2 | base64.nim | `lib/pure/base64.nim` | cb64/cb64safe定数（69-71行目） |
| 1-3 | base64.nim | `lib/pure/base64.nim` | invalidChar定数（73-74行目） |

**読解のコツ**:
- cbBaseは64文字のアルファベット配列を生成するテンプレート
- cb64は標準アルファベット（+, /）
- cb64safeはURL-safeアルファベット（-, _）

#### Step 2: エンコード処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | base64.nim | `lib/pure/base64.nim` | encodeSize計算（76行目） |
| 2-2 | base64.nim | `lib/pure/base64.nim` | encodeInternalテンプレート（78-130行目） |
| 2-3 | base64.nim | `lib/pure/base64.nim` | encode関数（138-155行目） |
| 2-4 | base64.nim | `lib/pure/base64.nim` | encodeMime関数（162-198行目） |

**主要処理フロー**:
- **78-130行目**: 3バイト→4文字の変換ループ
- **106-113行目**: メインループ（完全な3バイトブロック）
- **115-128行目**: パディング処理（1バイトまたは2バイト残り）

#### Step 3: デコード処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | base64.nim | `lib/pure/base64.nim` | initDecodeTable関数（200-211行目） |
| 3-2 | base64.nim | `lib/pure/base64.nim` | decodeTable定数（213-214行目） |
| 3-3 | base64.nim | `lib/pure/base64.nim` | decode関数（216-277行目） |

**主要処理フロー**:
- **200-211行目**: コンパイル時にデコードテーブルを生成
- **231-237行目**: 不正な文字のエラー処理
- **251-264行目**: 4文字→3バイトの変換ループ
- **265-276行目**: 末尾2-3文字の処理

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

```
アプリケーションコード
    │
    ├─ encode(s, safe)
    │      └─ encodeInternal(s, cb64/cb64safe)
    │            ├─ 3バイトずつループ
    │            │      └─ 24ビット→6ビット×4変換
    │            └─ パディング処理
    │
    ├─ encodeMime(s, lineLen, newLine, safe)
    │      ├─ encode(s, safe)
    │      └─ lineLen毎に改行挿入
    │
    └─ decode(s)
           ├─ 先頭空白/末尾=除去
           ├─ 4文字ずつループ
           │      └─ decodeTable参照
           │      └─ 6ビット×4→3バイト変換
           └─ 末尾2-3文字処理
```

### データフロー図

```
[エンコード]

入力: [0x48, 0x65, 0x6c]  "Hel"
       │
       ▼
  24ビット結合: 0x48656c
       │
       ▼
  6ビット分割: [18, 6, 21, 44]
       │
       ▼
  アルファベット変換: "SGVs"

入力: [0x6c, 0x6f]  "lo" (2バイト)
       │
       ▼
  16ビット→18ビット: 0x6c6f00
       │
       ▼
  分割: [27, 6, 60]
       │
       ▼
  変換+パディング: "bG8="


[デコード]

入力: "SGVs"
       │
       ▼
  デコードテーブル: [18, 6, 21, 44]
       │
       ▼
  24ビット結合: 0x48656c
       │
       ▼
  8ビット分割: [0x48, 0x65, 0x6c]
       │
       ▼
  出力: "Hel"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| base64.nim | `lib/pure/base64.nim` | メインソース | Base64エンコード/デコード実装 |
| md5.nim | `lib/pure/md5.nim` | 関連 | ハッシュ値のBase64エンコードで併用 |
| sha1.nim | `lib/std/sha1.nim` | 関連 | ハッシュ値のBase64エンコードで併用 |
