ライフサイクル管理

ErisPulse は、システムの各コンポーネントの実行状態を監視し、監査、統計、カスタムロジックなどの拡張機能を実現するための統一されたフック/ライフサイクルシステムを提供します。

システムは以下の3つのトリガ方法をサポートしています：

• await lifecycle.emit("event", data) — 精簡版、任意のデータを渡す（to="Owner" で指定送信）
• lifecycle.emit_sync("event", data) — 同期版（非非同期コンテキストで使用）
• await lifecycle.submit_event("event", ...) — 旧版との互換性、標準イベント形式を自動構築

イベント処理メカニズム

ハンドラの登録

from ErisPulse import sdk

# デコレータ方式
@sdk.lifecycle.on("module.load")
async def on_module_load(data):
    print(f"モジュールのロード: {data}")

# プログラム的登録
sdk.lifecycle.register("module.load", on_module_load, priority=10)

# 登録解除
sdk.lifecycle.unregister("module.load", on_module_load)

# 所有者毎に一括解除（モジュール/アダプターのアンロード時にフレームワークが自動的に呼び出す）
removed = sdk.lifecycle.unregister_by_owner("MyModule")
print(f"クリーンアップしたライフサイクルフック: {removed}")

優先度

ハンドラは priority パラメータをサポートし、数値が大きいほど先に実行されます（モジュールローダーと同様）：

@sdk.lifecycle.on("adapter.event.receive", priority=10)  # 最初に実行
async def first_handler(data):
    pass

@sdk.lifecycle.on("adapter.event.receive", priority=0)  # 後に実行
async def second_handler(data):
    pass

点構造イベント

具体的なイベントをトリガーすると、その親イベントもトリガーされます：

• module.load をトリガーすると、module もトリガーされます
• adapter.event.receive をトリガーすると、adapter.event と adapter もトリガーされます

ワイルドカード

* を登録すると、すべてのイベントをキャッチできます：

@sdk.lifecycle.on("*")
async def on_anything(data):
    print(f"イベントを受信: {data}")

定向送信（emit to=）

emit() に to パラメータを指定すると、定向送信モードになります：イベントは、その所有者（owner）として登録されたハンドラにのみ配信されます（モジュールは on_load 内で登録されたフックは自動的に自身の所有者になります）。他のモジュールやワイルドカード * ハンドラは感知しません。

# 送信元：イベントは Chat モジュールが登録したハンドラにのみ送信
await sdk.lifecycle.emit("message_received", {"text": "hi"}, to="Chat")

# 受信元（Chat モジュール内）：同名のハンドラを登録し、owner は登録時に自動的に記録されます
@sdk.lifecycle.on("message_received")
async def on_message_received(data): ...

@sdk.lifecycle.on("message")   # 点式の親プレフィックスも同様に有効（owner でフィルタリング）
async def on_any(data): ...

• 目標の owner に登録されたハンドラがない場合 → イベントは消費されません（has_handlers() で事前に検出できます）
• data が dict の場合、自動的に _trace_id を含みます（既存の値は上書きされません）
• emit_sync / submit_event でも to= パラメータをサポートします
• モジュール間通信の3層モデル（RPC / 定向 / ブロードキャスト）は モジュール間通信 を参照してください

1回限りの登録（once）

2.7.0 から、lifecycle.once() で登録されたハンドラは1回実行後に自動的に登録解除されます。これは「初回準備完了」のような1回限りのフックに適しています：

@sdk.lifecycle.once("core.init.complete")
async def on_first_ready(data):
    print("初回準備完了、以降はトリガーされません")

• on() と同じ優先度パラメータの意味（priority 数値が大きいほど先に実行）
• 自動的に登録解除、手動の unregister は不要
• 同期/非同期ハンドラの両方をサポート

監視者クエリ（has_handlers）

ホットパスの短絡処理では、has_handlers() を使って事前に監視者がいるかどうかを判断し、不要なイベントのループとタスクのスケジューリングを避けることができます：

if sdk.lifecycle.has_handlers("message.sending"):
    await sdk.lifecycle.emit("message.sending", send_ctx)

• 正確なイベント名、ワイルドカード *、親イベントの3種類のマッチングをカバー
• 監視者がいない場合、False を返し、emit を安全にスキップできます

フックブレークポイント一覧

プラットフォームからフレームワークにメッセージが届き、処理が完了するまでの典型的なライフサイクルイベントの時系列：

sequenceDiagram
    participant P as プラットフォーム
    participant A as アダプタ
    participant F as フレームワークコア
    participant M as モジュールハンドラ

    P->>A: ネイティブイベント到着
    A->>F: adapter.event.receive（初期段階）
    F->>F: event.pre_process（ハンドラ実行前）
    F->>M: ハンドラに分散（コマンド/メッセージ/通知など）
    M->>M: command.matched / command.executed
    M->>F: event.reply()
    F->>F: message.sending（送信前）
    F->>A: SendDSL 送信
    A->>P: プラットフォームに送信
    A->>F: message.sent（送信完了）
    F->>F: adapter.event.dispatched（分散完了）

フレームワークには、ユーザーが @sdk.lifecycle.on() を使って任意のブレークポイントにカスタムロジックを実装できる、以下のフックが用意されています。

コア初期化

例：起動進行表示

@sdk.lifecycle.on("core.init.stage")
def show_stage(data):
    print(f"[起動] 階段に移行: {data['stage']}")

設定変更

例：設定監査

@sdk.lifecycle.on("config.set")
def audit_config(data):
    print(f"[監査] {data['key']}: {data['old_value']} -> {data['new_value']}")

モジュールライフサイクル

アダプタライフサイクル

イベント受信と処理

例：イベント統計

event_counter = {}

@sdk.lifecycle.on("adapter.event.receive")
def count_events(data):
    platform = data["platform"]
    event_counter[platform] = event_counter.get(platform, 0) + 1

@sdk.lifecycle.on("adapter.event.dispatched")
def log_unhandled(data):
    if data["onebot_handlers_count"] == 0:
        print(f"[未処理] {data['platform']}/{data['event_type']}")

メッセージ送信

例：メッセージ送信監査

@sdk.lifecycle.on("message.sending")
def log_sending(data):
    print(f"[送信] -> {data['platform']}/{data['detail_type']}/{data['target_id']} via {data['method']}")

コマンドシステム

例：コマンド統計

@sdk.lifecycle.on("command.matched")
def count_commands(data):
    print(f"[コマンド] /{data['command']} from {data['user_id']}@{data['platform']}")

HTTPルーティング

例：リクエストログ

@sdk.lifecycle.on("server.response")
def log_http(data):
    print(f"[HTTP] {data['method']} {data['path']} -> {data['status_code']}")

WebSocket

例：WebSocket接続監視

@sdk.lifecycle.on("server.websocket.connect")
def on_ws_connect(data):
    print(f"[WS] 接続: {data['path']} from {data['client_ip']}")

@sdk.lifecycle.on("server.websocket.disconnect")
def on_ws_disconnect(data):
    print(f"[WS] 切断: {data['path']} ({data['reason']})")

ストレージ接続状態

ストレージバックエンドの接続プールの確立、障害、回復（すべてバックグラウンドで発行され、ストレージ操作をブロックしない）：

例：ストレージ障害アラート

@sdk.lifecycle.on("storage.unreachable")
def alert_storage_down(data):
    print(f"[アラート] ストレージバックエンド {data['backend']} が利用不可: {data['error']}、{data['cooldown']}秒後に自動再接続")

@sdk.lifecycle.on("storage.recovered")
def notify_storage_back(data):
    print(f"[回復] ストレージバックエンド {data['backend']} が再利用可能になりました")

HTTPクライアント

sdk.client のリクエストと接続イベント（すべてバックグラウンドで発行）：

国際化

標準イベント定義

STANDARD_EVENTS = {
    "core": ["init.start", "init.stage", "init.complete", "uninit.complete"],
    "module": ["load", "init", "unload", "register", "reload"],
    "adapter": [
        "load", "start", "status.change", "stop", "stopped",
        "event.receive", "event.dispatched",
        "bot.online", "bot.offline",
    ],
    "server": [
        "start", "stop",
        "request", "response",
        "websocket.connect", "websocket.disconnect",
    ],
    "event": ["pre_process"],
    "message": ["sending", "sent"],
    "command": ["matched", "executed"],
    "config": ["set", "updated"],
    "storage": ["ready", "unreachable", "recovered"],
    "client": ["request.success", "request.failed", "ws.connect"],
    "i18n": ["language.changed"],
}

完全なAPIリファレンス

登録と解除

トリガー

ユーティリティ

モジュールでの使用例

from ErisPulse.Core.Bases import BaseModule
from ErisPulse import sdk

class Main(BaseModule):
    async def on_load(self, event):
        # 簡単なメッセージ統計を実装
        self.msg_count = 0
        
        @sdk.lifecycle.on("adapter.event.receive")
        async def count(data):
            if data["event_type"] == "message":
                self.msg_count += 1
        
        # すべてのコマンドを監視
        @sdk.lifecycle.on("command.matched")
        async def log_cmd(data):
            sdk.logger.info(f"コマンド実行: /{data['command']} by {data['user_id']}")
        
        # 設定変更の監査
        @sdk.lifecycle.on("config.set")
        def audit(data):
            sdk.logger.info(f"設定変更: {data['key']} = {data['new_value']}")

バックグラウンドタスクの所有者と自動キャンセル

モジュールが作成した asyncio バックグラウンドタスクは、on_unload でキャンセルしない場合、self の参照を保持し、モジュールインスタンスが回収されず（ホットリロード後に古いインスタンスが残る）。フレームワークは以下のバックアップメカニズムを提供します：

• **self.spawn(coro)**（モジュール内で推奨）：タスクはモジュール名に自動的に所有者として割り当てられ、モジュールのアンロード時にフレームワークが on_unload 後に未終了のタスクをバックアップでキャンセルし、警告を記録します
• **spawn_background(coro)**（ErisPulse.runtime）：現在の owner_scope コンテキストを自動的にキャプチャします；cancel_owner_tasks(owner) で所有者に属するタスクをキャンセル、cancel_all_background_tasks() は sdk.uninit() のバックアップ用
• アダプター：プラットフォーム名の下のバックグラウンドタスクも同様にバックアップでキャンセル

async def on_load(self, event):
    # 推奨：バックグラウンドタスクは self.spawn() を使用し、アンロード時にフレームワークがバックアップで自動キャンセル
    self.spawn(self._poll())

async def on_unload(self, event):
    # 精密制御の場面では、手動でキャンセルし、終了処理を待つことを推奨
    if self._poll_task:
        self._poll_task.cancel()
        await asyncio.gather(self._poll_task, return_exceptions=True)

async def _poll(self):
    while True:
        await asyncio.sleep(60)
        ...

注意事項

1. ハンドラは同期または非同期：システムは自動的に識別し、適切に呼び出します
2. データの渡し方：emit() モードでは、ハンドラが None 以外の値を返すと、次のハンドラに渡される data を変更します
3. イベント名の命名規則：点構造のイベント名を使用することを推奨し、親イベントの監視が容易になります
4. エラーの隔離：1つのハンドラのエラーは他のハンドラの実行に影響しません
5. 同期トリガーの制限：emit_sync() では、非同期ハンドラは fire-and-forget でスケジュールされ、返り値は戻りません
6. ライフサイクルのクリーンアップ：sdk.uninit() を呼び出すと、すべての登録されたハンドラとタイマーがクリーンアップされます
7. ロードの優先性：フレームワークの初期化段階でイベントを監視したい場合は、高優先度を設定し、遅延ロードを無効にすることを推奨します

関連ドキュメント

• モジュール開発ガイド - モジュールのライフサイクルメソッドを理解する
• ベストプラクティス - ライフサイクルイベントの使用に関する推奨事項