局所トレーサビリティビュー グループ: STORE

大きなキャッシュデータを外部ストレージ（ローカルファイルシステムやS3等）に保存できること。

DB直接保存とBlob保存を自動判定できること。

コンポーネント構成

graph TD
  A[core.Spot] -->|判定| B[StoragePolicyProtocol];
  A -->|保存/読込| C[BlobStorageBase];
  D[LocalStorage] --> C;
  E[S3Storage] --> C;
  A -->|メタデータ| F[TaskDBBase];

コンポーネント責務

データフロー

sequenceDiagram
  participant Spot as core.Spot
  participant Policy as StoragePolicy
  participant DB as TaskDB
  participant Blob as BlobStorage

  Spot->>Policy: should_save_as_blob(data)
  alt Policy: True (Blob保存)
    Spot->>Blob: save(key, data)
    Blob-->>Spot: location (path/URI)
    Spot->>DB: insert(metadata, storage_type=FILE, blob_key=location)
  else Policy: False (Inline保存)
    Spot->>DB: insert(metadata, storage_type=DIRECT_BLOB, result_data=data)
  end

技術選定

非機能要件方針

• 安全性: LocalStorage では is_relative_to によるパストラバーサル防止を徹底

• 信頼性: 保存時は fsync を実行し、OSレベルでのデータ到達を確認

• 効率性: S3 保存時は upload_fileobj を使用し、5GB超のマルチパートアップロードに自動対応

インターフェース

class LocalStorage(BlobStorageMaintenable):
    def __init__(self, base_dir: str | Path): ...
    def save(self, key: str, data: bytes) -> str: ...
    def load(self, location: str) -> bytes: ...

振る舞い

アトミック書き込み (save)

1. 指定ディレクトリ内に tempfile.mkstemp で一時ファイルを作成
2. データを書き込み、flush() および os.fsync() でディスク到達を保証
3. os.replace で最終的なパスへリネーム（アトミックな置換）

パストラバーサル対策 (load / delete)

• 解決後の絶対パスが base_dir の配下にあることを is_relative_to で厳密にチェックし、範囲外へのアクセスを遮断する。

パラメータ詳細

エラーハンドリング

• ファイル不在: load 時にファイルがない場合 CacheCorruptedError を送出
• 権限エラー: PermissionError 発生時は、GCでの回収に委ねるため警告ログのみ出力

エッジケース

• ディスクフル: 書き込み中に容量不足になった場合、一時ファイルを削除して OSError を送出
• Windowsパス: パス区切り文字として / と \ の両方を検証対象とする

インターフェース

class S3Storage(BlobStorageMaintenable):
    def __init__(self, s3_uri: str, s3_opts: dict | None = None): ...

振る舞い

URIベースの管理

• s3://bucket/prefix/key.bin 形式のURIをロケーション識別子として使用する。

大容量対応 (save)

• boto3.upload_fileobj を使用。5GBを超えるデータに対しては、自動的にマルチパートアップロードに切り替えられ、PutObjectの制限を回避する。

高速なメタデータ取得 (get_mtime)

• head_object を使用し、データ本体をダウンロードせずに最終更新時刻（LastModified）を取得する。

パラメータ詳細

エラーハンドリング

• ライブラリ不在: boto3 がインポートできない環境でインスタンス化を試みると ImportError を送出
• ネットワークエラー: botocore.exceptions.ClientError をキャッチし、状況に応じて CacheCorruptedError に変換

エッジケース

• リージョン不一致: S3クライアントの設定とバケットのリージョンが異なる場合の動作は Boto3 のデフォルト設定に依存
• 削除の冪等性: S3 は存在しないオブジェクトの削除要求に対してエラーを返さないため、常に成功として扱う

インターフェース

class StoragePolicyProtocol(Protocol):
    def should_save_as_blob(self, data: bytes) -> bool: ...

振る舞い

判定ロジック

• ThresholdStoragePolicy: len(data) が threshold を超えた場合に True を返す。
• WarningOnlyPolicy: 常に False を返すが、閾値を超えた場合にログ出力のみ行う（互換モード）。
• AlwaysBlobPolicy: 常に True を返す。

パラメータ詳細

エラーハンドリング

• ポリシー内の判定で例外が発生した場合は、安全のため False (DB保存) とみなし、エラーをログに記録する。

エッジケース

• ゼロバイト: 空のデータに対する挙動は各ポリシーの閾値設定に依存する（通常はDB保存）。
• 閾値ちょうどのサイズ: len(data) > threshold のため、閾値と等しい場合はDB保存となる。

インターフェース

class BlobStorageBase(ABC):
    @abstractmethod
    def save(self, key: str, data: ReadableBuffer) -> str: ...
    @abstractmethod
    def load(self, location: str) -> bytes: ...
    @abstractmethod
    def delete(self, location: str) -> None: ...
    @abstractmethod
    def list_keys(self) -> Iterator[str]: ...
    @abstractmethod
    def get_mtime(self, location: str) -> float: ...

振る舞い

• save: データを永続化し、一意な識別子（パスやURI）を返す。
• load: 識別子を基にバイトデータを復元する。
• delete: 識別子を基にデータを削除する。存在しない場合は無視する（冪等）。
• list_keys: メンテナンス用に、保存されている全オブジェクトの識別子を列挙する。
• get_mtime: 最終更新時刻を POSIX タイムスタンプで返す。

パラメータ詳細

エラーハンドリング

• 実装クラスは、データの欠損やアクセス不可時に CacheCorruptedError を送出すべきである。

エッジケース

• バイナリ互換: ReadableBuffer を受け入れることで、memoryview 等を使用したゼロコピー書き込みを可能にする。

目的

LocalStorage はBlobデータのファイルシステム永続化を担い、並行書き込み時のデータ破損やパストラバーサルによるセキュリティ脆弱性が発生しうる。アトミック書き込みとセキュリティバリデーションの正確性を保証する。

検証観点

• ワークスペース初期化: base_dir が存在しない場合に自動作成され、.gitignore が配置されること
• アトミック書き込み: tempfile.mkstemp → fsync → os.replace のフローで、書き込み中のクラッシュや並行アクセスでファイルが破損しないこと
• 並行書き込み一貫性: 複数スレッドから同一キーへの同時書き込みで、最終状態が正しい完全なデータであること
• パストラバーサル防止: キーに .. や / を含む場合に ValidationError が送出され、base_dir 外へのアクセスが不可能であること。load() でも is_relative_to 検証が機能すること
• 一時ファイルクリーンアップ: clean_temp_files() が猶予期間超過の .spot_tmp ファイルを削除し、猶予期間内のファイルは保持すること
• 冪等削除: delete() が存在しないキーに対してもエラーを送出しないこと

目的

S3Storage はクラウド環境での大規模Blob保存を担い、ネットワーク障害・認証エラー・バケット不在などオンプレミスにはない障害モードが存在する。boto3 オプショナル依存のガード処理も含め、クラウドストレージ統合の信頼性を検証する。

検証観点

• 基本CRUD: S3互換ストレージへの save / load / delete / list_keys が正しく動作すること
• オプショナル依存ガード: boto3 がインストールされていない環境で import 時にわかりやすいエラーメッセージが表示されること
• エラーハンドリング: バケット不在、権限不足、ネットワークエラー時に適切な例外が送出されること
• 注記: boto3 のモック戦略（moto 等）を使用したテストの実装を推奨

目的

ストレージポリシーは「データをDB直接保存するか、Blobストレージに分離するか」を決定する戦略レイヤーである。閾値判定の誤りはDBの肥大化（性能劣化）や不要なBlob分離（オーバーヘッド増加）を招く。3種のポリシー実装がそれぞれの契約を正しく満たすことを検証する。

検証観点

• ThresholdStoragePolicy: 閾値未満のデータで False、閾値以上のデータで True を返すこと。境界値（ちょうど閾値サイズ）での挙動が明確であること
• WarningOnlyPolicy: 常に False を返しDB直接保存を選択すること。ただし閾値超過時に WARNING レベルのログが出力されること
• AlwaysBlobPolicy: データサイズに関係なく常に True を返すこと
• Spot 統合: @spot.mark(save_blob=True/False) の明示指定がポリシー判定より優先されること。save_blob=None（デフォルト）時にポリシーの should_save_as_blob() が呼ばれること

目的

BlobStorageBase は全ストレージバックエンド（LocalStorage, S3Storage, サードパーティ）が 準拠すべき抽象契約を定義する。この契約が正しく機能しないと、キャッシュデータの 保存・復元・削除・メンテナンス（GC）の全てが破綻する。 LocalStorage を具象実装として使い、インターフェース契約を網羅的に検証する。

検証観点

• save 基本動作: データを永続化し、一意な識別子（文字列）を返すこと
• ReadableBuffer 互換: bytes, bytearray, memoryview の全てを受け入れること（ゼロコピー書き込み）
• save 上書き: 同一キーに再保存するとデータが更新されること
• 空データ: 空バイト (b"") を正常に保存・復元できること
• load ラウンドトリップ: save した内容を load で完全に復元できること
• load 欠損時エラー: 存在しないロケーションへの load は CacheCorruptedError を送出すること
• delete 基本動作: 保存済みデータを削除し、以後の load がエラーになること
• delete 冪等性: 存在しないロケーションや二重削除でエラーにならないこと（冪等）
• list_keys 空: データ未保存時は空イテレータを返すこと
• list_keys 列挙: save したアイテムが list_keys に含まれること
• list_keys 削除後: delete 後は list_keys に含まれないこと
• get_mtime 正確性: POSIX タイムスタンプ（float）を返し、保存直後は現在時刻に近いこと
• get_mtime 欠損時エラー: 存在しないロケーションでエラーを送出すること

実装概要

• LocalStorage クラスが BlobStorageBase を実装。 ファイルは {base_dir}/{key}.bin 形式で保存される。

• save() は tempfile.mkstemp() → fsync() → os.replace() の アトミック書き込みパターンで実装。

設計判断

アトミック書き込みパターン

一時ファイルに書き込み → fsync でディスクに確実に反映 → os.replace で アトミックにリネーム。この3段階により、書き込み中のクラッシュや 並行アクセスでファイルが半壊状態になることを防ぐ。 一時ファイルには .spot_tmp 接尾辞を使用し、残存時のクリーンアップを容易にした。

パストラバーサル防止の二重ガード

• save() / _validate_key(): キーに .., /, \ を含む場合に ValidationError

• load() / delete(): 解決済みパスが base_dir.is_relative_to() を満たすか検証 二重のチェックにより、キー経由とロケーション経由の両方のパストラバーサルを防ぐ。

実装メモ

• 初期化時に base_dir を絶対パスに正規化し、ディレクトリと .gitignore を自動作成

• delete() は冪等。ファイル不在時もエラーを送出しない。パーミッションエラーは警告のみ

• list_keys() は rglob("*.bin") でレガシーサブディレクトリ構造にも対応

• clean_temp_files() は猶予期間（デフォルト24時間）超過の .spot_tmp ファイルのみ削除。 ファイルロック（アンチウイルス等）のエラーは安全に無視する

• prune_empty_dirs() はボトムアップで走査し、.DS_Store 等のシステムファイルのみの ディレクトリも空とみなして削除する。base_dir 自体は保持する

実装概要

S3Storage クラスが BlobStorageBase を実装。 s3://bucket/prefix/ 形式の URI を解析し、boto3 の S3 クライアントを使用。 ファイルは {prefix}/{key}.bin のキーで S3 に保存される。

設計判断

オプショナル依存のガード

boto3 は import 時にガードし、未インストール時は クラス定義は成功するがインスタンス化で明確なエラーメッセージを表示する。 beautyspot 全体が boto3 に依存しないよう、遅延インポートパターンを採用。

URI ベースのバックエンド選択

s3://bucket/prefix 形式の URI から bucket と prefix を自動解析する _parse_s3_uri() ヘルパーにより、ファクトリ関数がスキームに基づいて LocalStorage と S3Storage を透過的に切り替えられる。

実装メモ

• save() は upload_fileobj() を使用し、5GB 超のデータにも マルチパートアップロードで対応する
• ロケーションは完全な S3 URI（s3://bucket/prefix/key.bin）を返す
• list_keys() は paginator で全キーを列挙し、prefix を除いた相対キーを返す
• get_mtime() は head_object で LastModified を取得（GC の grace period 判定用）

実装概要

StoragePolicyProtocol が should_save_as_blob(data: bytes) -> bool を定義。 3つの実装を提供: - ThresholdStoragePolicy: len(data) > threshold で判定 - WarningOnlyPolicy: 常に False を返し、閾値超過時に WARNING ログを出力 - AlwaysBlobPolicy: 常に True を返す

設計判断

Strategy パターンによるポリシー分離

保存先判定ロジックを core.Spot から分離し、差し替え可能なポリシーオブジェクトに 委譲する。@mark(save_blob=True/False) の明示指定はポリシーより優先されるが、 save_blob=None（デフォルト）時にポリシーが判定を行う。

WarningOnlyPolicy をデフォルトにした理由

v2.0 との後方互換性を維持するため。v2.0 では全データが DB 直接保存だったため、 デフォルトを ThresholdStoragePolicy にすると既存ユーザーの挙動が変わる。 WARNING ログにより、ユーザーに Blob 分離の恩恵を段階的に周知する。

実装メモ

• 各ポリシーは dataclass で実装し、threshold パラメータを属性として保持
• WarningOnlyPolicy のログは warnings.warn ではなく logging.warning を使用。 ユーザーコードの警告フィルタに影響されないため

実装概要

storage.py 内の BlobStorageBase ABC が SPEC024 の中核実装。 5つの抽象メソッド（save, load, delete, list_keys, get_mtime）を定義し、 LocalStorage と S3Storage が具象実装として継承する。

加えて、ランタイム型チェックのために BlobStorageCore・Maintenable・ BlobStorageMaintenable の3つの Protocol クラスを定義し、 isinstance() での型判定を可能にしている（@runtime_checkable）。

設計判断

ABC と Protocol の併用

BlobStorageBase は ABC として抽象メソッドを強制する一方、 BlobStorageCore / Maintenable は Protocol として構造的部分型を提供する。 これにより、BlobStorageBase を継承しないサードパーティ実装でも isinstance(obj, BlobStorageCore) で利用可能になる柔軟性を確保した。

3層の Protocol 分割

• BlobStorageCore: 実行時に必要な最小限（save/load/delete）
• Maintenable: メンテナンス（GC）に必要な拡張（list_keys/get_mtime）
• BlobStorageMaintenable: 両方を兼備する完全版

これにより、save/load/delete のみを実装した軽量バックエンドも受け入れ可能。

ReadableBuffer 型エイリアス

bytes | bytearray | memoryview を ReadableBuffer として定義。 memoryview を受け入れることでゼロコピー書き込みが可能になり、 大きなデータを保存する際のメモリ効率を改善している。

実装メモ

• BlobStorageBase 自体はロジックを持たず、インターフェース定義のみ
• 各 @abstractmethod にはdocstringで契約を明記（冪等性、エラー時の挙動など）
• delete は冪等であるべきことを docstring で規定
• list_keys は delete と同じフォーマットの識別子を yield すべきことを規定