ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

シャドウモジュールとカナリア昇格

Tip

このドキュメントを読むべきタイミング:カナリアリリース——新バージョンの並行トライアル実行、動作比較、昇格・ロールバックが必要なとき。不要であればスキップしても、他の機能の利用には影響しません。

読み終えるとわかること:シャドウモジュールの5つの分離ゲート、動作 diff のアライメント方法、 promote による昇格と失敗時のロールバック手順、そしてフレームワークでは防げない誠実な限界。

このドキュメントでは扱わないこと:通常モジュールのホットリロードとオーナーのクリーンアップに関する汎用メカニズム (オーナー(owner)システム を参照)。

シャドウ = 同一モジュールの新バージョンであり、独立した owner(例:roll_shadow)として本番の旧バージョンと 共存しながらトライアル実行します:実際のイベントのコピーを受け取り、そのアウトバウンドは本当に送信されるのではなく 傍受して記録されます——shadow_diff で2つのバージョンの動作を比較し、無害であることを確認したら promote で ワンクリック昇格、dismiss でいつでも破棄できます。モジュールコードは一切変更不要、全工程がランタイム API 駆動: load / unload / reload と同種の運用アクションであり、Dashboard / カスタム管理モジュールから直接 呼び出せ、書くべき設定項目は一切ありません。

{!--< tips >!--}

  1. 起動:await sdk.module.shadow_start("roll", source="path/to/v2") ——新バージョンのコードは独立した owner(デフォルトはパス名)として旧バージョンと共存
  2. シャドウは実際のディスパッチと依存グラフには参加しません:同名コマンドはシャドウのカタログに入り、ルートは登録のみでマウントせず、 ライフサイクルブロードキャストはサイレント、module.call と依存解決は引き続き v1 を指します
  3. 昇格は常に人間が確認します:await sdk.module.promote_shadow("roll")、失敗時は 自動ロールバックで旧インスタンスがサービスを継続;dismiss_shadow でいつでも破棄 {!--< /tips >!--}

クイックスタート

# v2 コード:通常のモジュールの書き方、シャドウを一切意識しない(任意のディレクトリ、例:downloads/roll_v2/)
# 本番ボット内で(Dashboard / 管理モジュールから呼び出し)、1行でカナリアを起動:
await sdk.module.shadow_start("roll", source="downloads/roll_v2")
# → シャドウは独立した owner "roll_v2" として v1 と共存し、アウトバウンドは傍受・記録される

# トライアル実行中に動作を比較:
report = sdk.module.shadow_diff("roll")
# {"shadow_owner": "roll_v2", "count": 3, "aligned": [...]}
  • v1 の実際の送信:受信箱(transcript)からの bot タイムライン
  • v2 の送信意図:シャドウ台帳(アウトバウンドゲートが記録した「送りたかったもの」)
  • 両者は trace_id で整列されます——同じメッセージについて、2つのバージョンがそれぞれなぜ発火した/しなかった、 何を送りたかった/実際に送ったのかが一目瞭然

問題ないことを確認したら昇格:

await sdk.module.promote_shadow("roll")   # 昇格、失敗時は自動的に v1 へロールバック
await sdk.module.dismiss_shadow("roll")   # または:シャドウを破棄

5つの分離ゲート

ゲート メカニズム
イベントコピー シャドウハンドラーはイベントの独立したコピーを受け取る(shadow マーク付き)——シャドウによる改変 / 引き取り / 伝播停止はコピーにのみ作用し、元のイベントチェーンには影響しない
アウトバウンドゲート シャドウの Send DSL と Api 呼び出しはすべて傍受して記録(成功形状のフェイクレスポンスを返却)、実際には送信しない——シャドウが重複して返信することはない
ストレージオーバーレイ シャドウの KV 書き込みはメモリ上のオーバーレイに入り、実DBへの永続化は破棄;読み取りはまずオーバーレイを確認し、ミスなら実DBへ透過(カナリアは実際のデータに対して実行);削除はトゥームストーンとして記録
ルートブロック シャドウの HTTP/WS/SSE ルートは登録のみでマウントしない;同名コマンドはシャドウのコマンドカタログに入り、プラットフォームイベントメソッドの注入は禁止
ライフサイクルサイレント シャドウは自身のライフサイクルイベントをブロードキャストせず、エコシステムの依存グラフに参加しない(module.call と依存解決は引き続き v1 を指し、未完成品が依存されるのを回避)

設定の継承:シャドウはデフォルトで元モジュールの設定セクションを継承します(そうでないとカナリアの結果が歪みます)。昇格後は設定がそのまま有効になります。

誠実な限界(防げないもの)

  • フレームワーク経由の送信 / API / KV ストレージ / 統一 HTTP クライアントはすべて傍受可能; モジュールがフレームワークを迂回して生の aiohttp を起動したり、スレッドを立てて外部システムへ書き込むことは——フレームワークでは防げません
  • ORM の読み書きはオーバーレイのセマンティクス外です(行単位の overlay は SQL レイヤーではクリーンに実装できない)—— シャドウ期間中は ORM 書き込み分離への依存を避けることを推奨
  • シャドウソースはローカルパス:新バージョンのコードはパスからインポートされ、独立した owner としてロード;同一 PyPI パッケージは 同一インタプリタ内では sys.modules の単一キー制限を受け、新旧2バージョンの共存は不可能
  • リーク監査器(sdk.module.audit)はシャドウリソースの帰属を可視化;フレームワークを迂回した副作用も、 少なくとも無音のままにはなりません

昇格とロールバック

promote の流れ:現在のバージョンをスナップショット(カスケード依存を含む)→ 完全にアンロード → シャドウが実名で登録・ロード → いずれかのステップで失敗した場合は自動的にロールバックし、旧インスタンスがサービスを継続(ベストエフォートのセマンティクス:on_unload で実行された副作用は取り消せず、ロールバック後の旧インスタンスは終了処理済みの状態となる)。昇格に成功したシャドウのリソースは回収され、バインドは解除される。元モジュールの設定セクションはその場で有効になる。

永続化に関する注意:promote はランタイムでの切り替えです——再起動後も v2 で実行されるため、新しいバージョンを永続的にインストールする必要があります(新バージョンの pip install -U 実行 / プラグインファイルの置き換え)。ランタイムの切り替えはパッケージ管理を代行してはくれません。Dashboard の「昇格して永続化」は、昇格の成功後にバックグラウンドで pip を実行し、アップロード時にディスクへ書き込まれた whl 原本をインストールすることで、このステップを自動化します。通常の promote ではディスクへの書き込みは行われません。

3つのハード境界

境界 説明
pip 排他 シャドウ期間は展開のみでインストールしない:whl の原本を shadows/<module>/ に保存するのは昇格後の永続化のためだけであり、シャドウ実行中は pip インストールを行わず、インストール済みパッケージの上書きによる本番環境の挙動ドリフトを回避します
promote はディスクに書き込まず promote_shadow は実行時の切り替えのみを行い、パッケージマネージャーには書き込みません。再起動後は v1 にロールバックされます(設定では依然として旧バージョンを指しています)。再起動後も v2 を維持したい場合は「昇格して永続化」または手動の pip install を使用してください
サードパーティ依存関係 = プロセスにインストール済みのバージョン シャドウが import するサードパーティライブラリは現在のプロセスにインストール済みのバージョンを使用します。whl が宣言する新規依存関係は自動インストールされず、依存関係が不足している場合はシャドウのロードに失敗します(エラーはそのままスローされます)

whl の取り込み、list_shadows および「昇格して永続化」(shadow_ingest_whl / shadow_promote_persist / shadow_persist_status)には ErisPulse 2.12+ が必要です。 旧バージョンの SDK では自動的に基本シャドウ(展開して起動するのみで、永続化なし)に縮退し、Dashboard の機能検出により自動的に切り替わります。

運用向けクエリインターフェース:sdk.module.list_shadows() は現在のすべてのバインディング {元モジュール名: シャドウ owner 名} を返し、Dashboard / スクリプトでの集約表示に使用できます。

whl の取り込みと「昇格して永続化」の実装は SDK に帰属します:展開 / ディスクへの保存 / pip オーケストレーションは SDK のバージョン進化に伴って変化し、Dashboard は単なる呼び出しエントリに過ぎません。

関連ドキュメント