iii

iii - クロスランゲージバックエンドエンジン

SDK 0.3.0-alpha の破壊的変更（2026-02-18 に確認済み）：registerTrigger フィールドは trigger_type です（type ではありません）。HTTP トリガーでは trigger_type: "api" を使用します（"http" ではありません）。type: "http" を使用すると、すべてのルートでエラーを返さずに 404 が発生します。これは、motia から直接 iii-sdk を使用する形に書き換えた tac-4-go で確認されました。

SDK に関する注意：iii.dev のドキュメントでは Bridge クラスを含む @iii-dev/sdk が参照されていますが、このパッケージは npm に存在しません（2026-02-17 時点で 404）。必ず iii-sdk（スコープなし）をインストールしてください。ドキュメントに記載された SDK では異なる規約（ドット区切り、trigger_type、function_path）が使われています。翻訳ガイドについては references/cross-language.md を参照してください。

---

基本概念

iii には、次の 2 つの基本プリミティブがあります。

1. 登録 - エンジンから関数を呼び出せるようにします
2. 呼び出し - 言語やプロセスを問わず、登録済みの関数を呼び出します

サービスは WebSocket 経由で iii エンジンに接続します。エンジンは、ルーティング、再試行、可観測性、状態、ストリーム、cron、および HTTP API の公開を処理します。

---

クイックスタート

1. エンジンをインストールする

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh
iii --version

または、Docker 経由で実行します。

docker pull iiidev/iii:latest
docker run -p 3111:3111 -p 49134:49134 \
  -v ./iii-config.yaml:/app/config.yaml:ro \
  iiidev/iii:latest

2. エンジン設定を作成する（iii-config.yaml）

modules:
  - class: modules::api::RestApiModule
    config:
      port: 3111
      host: 127.0.0.1
      default_timeout: 30000
      concurrency_request_limit: 1024
      cors:
        allowed_origins: ["*"]
        allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]

  - class: modules::state::StateModule
    config:
      adapter:
        class: modules::state::adapters::KvStore
        config:
          store_method: file_based
          file_path: ./data/state_store.db

  - class: modules::shell::ExecModule
    config:
      exec:
        - bun run --enable-source-maps worker.js

StreamModule、OtelModule、QueueModule、PubSubModule、CronModule、KvServer、LoggingModule、BridgeClientModule を含むモジュール設定の詳細については、references/engine-modules.md を参照してください。

3. エンジンを起動する

iii -c iii-config.yaml

4. TypeScript サービスを作成する

mkdir my-service && cd my-service
npm init -y
npm install iii-sdk

package.json で "type": "module" を設定します。

// src/worker.ts
import { init, getContext } from "iii-sdk";

const { registerFunction, registerTrigger, call, callVoid } = init(
  process.env.III_BRIDGE_URL ?? "ws://localhost:49134"
);

// Register a function callable by any connected service
const health = registerFunction({ id: "my-service::health" }, async () => {
  const { logger } = getContext();
  logger.info("Health check OK");
  return { status: 200, body: { healthy: true, timestamp: Date.now() } };
});

// Expose as HTTP endpoint via the engine's REST API module
registerTrigger({
  trigger_type: "api",
  function_id: health.id,
  config: { api_path: "health", http_method: "GET" },
});

console.log("Service started - listening for calls");

次のコマンドで実行します：npx tsx src/worker.ts

テスト：curl http://localhost:3111/health

---

重要なルール

必ず行うこと

• 関数 ID には service-name::function-name の規約を使用します（例："client::health"、"data-service::transform"）
• package.json で "type": "module" を設定します（SDK は ESM を使用します）
• エンジンアドレスには process.env.III_BRIDGE_URL ?? "ws://localhost:49134" を使用します
• サービスを起動する前に iii エンジンを起動します
• 関数ハンドラー内でのログ記録には getContext() を使用します（構造化された OTEL ロギングが提供されます）
• 複数のリモート関数を並列で呼び出す場合は Promise.allSettled() を使用します（部分的な失敗を適切に処理できます）
• サービスに接続する前に、ポート 3111 の GET /health を使用してエンジンの健全性を確認します
• KV Server の関数パラメーターには scope ではなく index を使用します。scope は State モジュール専用です

絶対に行わないこと

• 環境変数のフォールバックなしで ws://localhost:49134 をハードコードしないでください
• 関数 ID に process.env を使用しないでください（静的な文字列である必要があります）
• すべてのサービスが利用可能だと想定しないでください。サービスが見つからない場合も適切に処理してください
• 6 フィールドの cron 式を使用しないでください。iii は 7 フィールド（秒を含む）に対応しています："*/30 * * * * * *"
• iii-sdk 0.3.0-alpha：registerTrigger では type ではなく trigger_type を使用します。HTTP トリガーでは "http" ではなく "api" を使用します。キュートリガーでは "queue"、cron トリガーでは "cron" を使用します
• iii-sdk 0.2.0：trigger_type ではなく type を使用します。HTTP トリガーでは "http" を使用します
• 基本的な状態操作で iii-sdk/state や iii-sdk/stream からインポートしないでください。代わりに sdk.call("state::set", ...) を使用します。これらは 0.3.0 で削除されました
• npm install @iii-dev/sdk を実行しないでください。このスコープ付きパッケージは npm に存在しません（404）。代わりに iii-sdk を使用してください
• エンジンの関数パスでドット区切りを使用しないでください。::（コロン 2 つ）を使用します。"kv_server::get" を使用し、"kv_server.get" は使用しないでください

---

SDK のエントリーポイント

インポート	用途
iii-sdk	コア：init、getContext、withContext、Logger（および型）。init() は registerFunction、registerTrigger、call、callVoid、shutdown メソッドを備えた ISdk を返します
iii-sdk/state	高度な用途：直接使用する IState インターフェース（get/set/delete/list/update）
iii-sdk/stream	高度な用途：グループを備えた直接使用する IStream インターフェース
iii-sdk/telemetry	OpenTelemetry：initOtel、withSpan、getTracer、getMeter

多くの場合、コア SDK を使用し、状態の操作には call("state::set", ...) / call("state::get", ...) を使用してください。

---

関数の登録

const fn = registerFunction(
  {
    id: "service::action",           // Required: unique function ID
    description: "What it does",     // Optional: for discovery
    request_format: { /* schema */ },  // Optional: input schema
    response_format: { /* schema */ }, // Optional: output schema
    metadata: { version: "1.0" },    // Optional: custom metadata
  },
  async (payload) => {
    const { logger } = getContext();
    logger.info("Processing", { payload });
    return { result: "done" };       // Return value sent back to caller
  }
);

// fn.id = "service::action"
// fn.unregister() - removes the function

---

関数の呼び出し

// Awaitable call (returns result)
const result = await call<InputType, OutputType>("other-service::action", { data: "hello" });

// Fire-and-forget (no return value)
callVoid("log-service::audit", { event: "user_login" });

// Parallel calls with graceful failure
const [a, b] = await Promise.allSettled([
  call("service-a::process", payload),
  call("service-b::process", payload),
]);

組み込み関数

// State management (uses 'scope')
await call("state::set", { scope: "shared", key: "VERSION", value: 1 });
const val = await call("state::get", { scope: "shared", key: "VERSION" });
const items = await call("state::list", { scope: "shared" });

// KV Server (uses 'index' — NOT 'scope')
await call("kv_server::set", { index: "default", key: "user:123", value: { name: "Alice" } });
const user = await call("kv_server::get", { index: "default", key: "user:123" });
await call("kv_server::delete", { index: "default", key: "user:123" });
const keys = await call("kv_server::list_keys_with_prefix", { prefix: "user:" });

// Queue — enqueue a message to a topic
await call("enqueue", { topic: "user.created", data: { id: "123", email: "[email protected]" } });

// Engine introspection
const functions = await call("engine::functions::list", {});
const workers = await call("engine::workers::list", {});

// Health check (HTTP, not via SDK)
// curl http://localhost:3111/health

// Graceful shutdown (new in 0.2.0)
await sdk.shutdown();  // Closes WebSocket, cleans up resources

Note：shutdown() は 0.2.0 で追加されました。プロセスを正常に終了するときは、必ず呼び出してください。

---

トリガー

HTTP トリガー（API）

関数をエンジンの REST API（デフォルトポート 3111）の HTTP エンドポイントとして公開します。

// iii-sdk 0.3.0-alpha (current working — use this)
registerTrigger({
  trigger_type: "api",
  function_id: "service::handler",
  config: {
    api_path: "users/:id",           // Path params supported
    http_method: "POST",             // GET, POST, PUT, DELETE, OPTIONS
  },
});
// Accessible at: http://localhost:3111/users/123

Warning：iii engine 0.4.0 以降で type: "http"（0.2.0 の構文）を使用すると、すべてのルートで警告なしに 404 が返されます。0.3.0-alpha SDK では、必ず trigger_type: "api" を使用してください。

ハンドラーは ApiRequest オブジェクトを受け取ります。

registerFunction({ id: "service::handler" }, async (req: ApiRequest) => {
  const { path_params, query_params, body, headers, method } = req;
  return {
    status_code: 200,
    headers: { "Content-Type": "application/json" },
    body: { id: path_params.id, data: body },
  };
});

Cron トリガー

7 フィールドの cron 式（秒単位の精度）に対応しています。

registerTrigger({
  trigger_type: "cron",
  function_id: "service::cleanup",
  config: { expression: "*/30 * * * * * *" },  // Every 30 seconds
});
// Fields: seconds minutes hours day-of-month month day-of-week year

キュートリガー

特定のトピックにメッセージがエンキューされたときに関数を呼び出します。エンジンの設定で QueueModule が必要です。

const consumer = registerFunction(
  { id: "events::on-user-created" },
  async (data) => {
    console.log("User created", data);
    return { ok: true };
  }
);

registerTrigger({
  trigger_type: "queue",
  function_id: consumer.id,
  config: { topic: "user.created" },
});

// Enqueue from anywhere:
await call("enqueue", { topic: "user.created", data: { id: "123", email: "[email protected]" } });

ログトリガー

ログイベントが指定したレベルに一致したときに関数を呼び出します。エンジンの設定で LoggingModule が必要です。

registerFunction({ id: "monitoring::on-error" }, async (logEntry) => {
  // logEntry: { trace_id, message, level, function_name, date }
  const { logger } = getContext();
  logger.info("Error captured", logEntry);
  // Send alert, store in database, etc.
});

registerTrigger({
  trigger_type: "log",
  function_id: "monitoring::on-error",
  config: { level: "error" },  // Optional: info, warn, error, debug (omit for all)
});

---

リファレンス

必要な情報	ファイル
SDK の型定義と状態／ストリーム API の全容	references/api-reference.md
エンジンモジュールの設定スキーマ	references/engine-modules.md
言語間のサンプル、OpenTelemetry、環境変数	references/cross-language.md
Docker のデプロイとプロジェクト構成	references/docker-deployment.md

---

既知の問題

• アルファ版ソフトウェア：リリースごとに API が変更される場合があります
• ポート 49134 の競合：エンジンの WebSocket ポートは 49134 に固定されています。他の用途で使用されていないことを確認してください
• Docker のネットワーク：Linux の Docker <20.10 では、host.docker.internal に明示的な extra_hosts マッピングが必要です
• 再接続：SDK は指数バックオフ（初回 1 秒、最大 30 秒、デフォルトでは無制限に再試行）で自動再接続します
• CJS のサポート：0.2.0 では ESM と併せて CommonJS エクスポートが追加され、import と require の両方が使用できるようになりました

0.3.0-alpha の破壊的変更（2026-02-18 に動作確認済み）

これらは、[email protected] と iii engine 0.4.0 の組み合わせにおける現在の仕様です。

• registerTrigger では type が trigger_type に置き換わりました — trigger_type: "api" を使用してください（type: "http" ではありません）
• HTTP トリガーの種類名は "http" から "api" に置き換わりました
• iii-sdk/state のエクスポートは削除されました — call("state::set", ...) と call("state::get", ...) を使用してください
• iii-sdk/stream は iii-sdk/streams（複数形）に名称変更されました
• ISdk 型はメインのエントリーポイントからエクスポートされなくなりました
• SDK の移行：ドキュメントのみの @iii-dev/sdk（Bridge クラス、ドット区切り）が公式 SDK になる可能性があります。@iii-dev/sdk が利用可能になるか、npm を確認してください

確認済み：tac-4-go プロジェクトは trigger_type: "api" を使用して iii-sdk 0.3.0-alpha を直接利用しており、4 つすべての HTTP エンドポイントに加えて、キューと cron が正常に動作します。

---

トラブルシューティング

エラー	原因	対処方法
ECONNREFUSED 127.0.0.1:49134	エンジンが起動していません	iii -c iii-config.yaml で起動します
関数呼び出しがタイムアウトする（30 秒）	対象のサービスが接続されていません	サービスを起動し、engine::workers::list を確認します
Cannot find module 'iii-sdk'	SDK がインストールされていません	npm install iii-sdk
HTTP エンドポイントが 404 を返す	トリガーフィールドまたはタイプが誤っています	0.3.0-alpha では、trigger_type: "api" を使用します（type: "http" は使用しません）。api_path が URL と一致することを確認します
Cron が実行されない	式の形式が誤っています	7 フィールド形式を使用します：sec min hour dom mon dow year
状態が null を返す	スコープまたはキーが誤っています	スコープとキーの文字列が完全に一致することを確認します
trigger_type_not_found	SDK とエンジンのバージョンが一致していません	0.2.0：type を使用します。0.3.0-alpha：trigger_type を使用します
すべてのルートが 404 を返す（サイレント）	0.3.0-alpha SDK で type: "http" を使用しています	trigger_type: "api" に変更します — motia は "http" を送信しますが、iii engine 0.4.0 は "api" を要求します
KV Server がタイムアウトする	KV Server モジュールが設定にありません	iii-config.yaml に modules::kv_server::KvServer を追加します
module class not found	単数形または複数形のパスが誤っています	クラスパスで stream と streams を切り替えてみて、エンジンのバージョンを確認します
@iii-dev/sdk が npm で 404 になる	パッケージが公開されていません	iii-sdk（スコープなし）を使用します。@iii-dev/sdk はドキュメント専用です
キューメッセージが処理されない	キュートリガーがないか、トピックが誤っています	registerTrigger({ type: "queue", config: { topic } }) がエンキュー時のトピックと一致することを確認します