iii-functions-and-triggers

Functions & Triggers

比較対象：サーバーレス関数ランタイム、Lambda、Cloud Functions

主な概念

タスクに適している場合は、以下の概念を使用してください。すべてのワーカーに必要なわけではありません。

• Function は、一意の ID で登録される非同期ハンドラーです
• Trigger は、イベントソースを関数にバインドします。種類には、http、queue、cron、state、stream、subscribe があります
• 関数は、言語やワーカーの場所にかかわらず、trigger() を介して他の関数を呼び出します
• エンジンは、シリアル化、ルーティング、配信を自動的に処理します
• HTTP で呼び出される関数は、外部エンドポイントを呼び出し可能な関数 ID としてラップします
• 関数は、ドキュメント化と検出のためにリクエスト／レスポンス形式を宣言できます。Rust（schemars::JsonSchema 経由）と Python（型ヒント／Pydantic 経由）では型から自動生成され、Node.js では手動で指定できます

アーキテクチャ

registerWorker() はワーカーをエンジンに接続し、registerFunction はハンドラーを定義し、registerTrigger はイベントソースをそれらのハンドラーにバインドします。エンジンは受信したイベントを適切な関数にルーティングします。関数は、trigger() を介してワーカーや言語をまたいで他の関数を呼び出せます。

使用するプリミティブ

プリミティブ	目的
registerWorker(url, options?)	ワーカーをエンジンに接続する
registerFunction({ id }, handler)	関数ハンドラーを定義する
registerTrigger({ type, function_id, config })	イベントソースを関数にバインドする
trigger({ function_id, payload })	関数を同期的に呼び出す
trigger({ ..., action: TriggerAction.Void() })	結果を待たずに呼び出す
trigger({ ..., action: TriggerAction.Enqueue({ queue }) })	キューを介して永続的に非同期で呼び出す

リファレンス実装

• TypeScript: ../references/functions-and-triggers.js
• Python: ../references/functions-and-triggers.py
• Rust: ../references/functions-and-triggers.rs

各リファレンスでは、それぞれの言語で同じパターン（関数の登録、トリガーのバインド、関数間の呼び出し）を示しています。

一般的なパターン

このパターンを使用するコードには、該当する場合、一般に以下が含まれます。

• registerWorker('ws://localhost:49134', { workerName: 'my-worker' }) — エンジンに接続する
• registerFunction({ id: 'namespace::name' }, async (input) => { ... }) — ハンドラーを登録する
• registerTrigger({ type: 'http', function_id, config: { api_path, http_method } }) — HTTP トリガー
• registerTrigger({ type: 'queue', function_id, config: { topic } }) — キュートリガー
• registerTrigger({ type: 'cron', function_id, config: { expression } }) — cron トリガー
• registerTrigger({ type: 'state', function_id, config: { scope, key } }) — 状態変更トリガー
• registerTrigger({ type: 'stream', function_id, config: { stream } }) — ストリームトリガー
• registerTrigger({ type: 'subscribe', function_id, config: { topic } }) — pubsub サブスクライバー
• 言語をまたいだ呼び出し：TypeScript の関数から、ID を指定して Python または Rust の関数をトリガーできます

リクエスト／レスポンス形式（自動登録）

関数は、ドキュメント化と検出のために入出力スキーマを宣言できます。

• Rust：ハンドラーの入力／出力型に schemars::JsonSchema を導出します。RegisterFunction::new() は型から JSON Schema（Draft 7）を自動生成します
• Python：ハンドラーのパラメーターと戻り値の型に型ヒント（Pydantic モデルまたはプリミティブ型）を使用します。register_function() は JSON Schema（Draft 2020-12）を自動抽出します
• Node.js：登録メッセージで request_format／response_format を手動で渡します（例：Zod の toJSONSchema() を使用）

このパターンの適用

タスクに該当する場合は、以下のように適用してください。

• プレースホルダーのハンドラーロジックを実際のビジネスロジック（API 呼び出し、DB クエリ、LLM 呼び出し）に置き換えます
• 関連する関数をグループ化するため、関数 ID には namespace::name の規則を使用します
• HTTP エンドポイントでは、トリガー設定で api_path と http_method を設定します
• 永続的な非同期処理には、同期トリガーの代わりに TriggerAction.Enqueue({ queue }) を使用します
• ファイア・アンド・フォーゲットの副作用には、TriggerAction.Void() を使用します
• 異なる言語で動作する複数のワーカーが、相互に ID を指定して関数を呼び出すように登録できます

パターンの適用範囲

• HTTP エンドポイントの詳細（リクエスト／レスポンス形式、パスパラメーター）については、iii-http-endpoints を優先してください。
• キュー処理の詳細（再試行、並行処理、FIFO）については、iii-queue-processing を優先してください。
• cron スケジュールの詳細（式、タイムゾーン）については、iii-cron-scheduling を優先してください。
• 呼び出しモード（同期、void、enqueue）については、iii-trigger-actions を優先してください。
• 主な課題が関数の登録、トリガーのバインド、または言語をまたいだ呼び出しである場合は、iii-functions-and-triggers を使用してください。

使用する場合

• タスクの主な内容が iii エンジンの iii-functions-and-triggers に関する場合は、このスキルを使用してください。
• リクエストでこのパターン、または同等の実装を直接求められた場合に使用します。

境界

• 無関係なタスクに対する汎用的な代替手段として、このスキルを使用しないでください。
• より具体的な iii スキルが適している場合は、このスキルを適用してはいけません。
• このスキルの例を適用する前に、必ず環境と安全性の制約を確認してください。