コントラクト

コントラクト

型付きコントラクトを通じてサービスを呼び出し。スキーマ検証と非同期実行サポート付きでリモートAPI、ワークフロー、関数を呼び出し。

ロード

local contract = require("contract")

バインディングを開く

IDで直接バインディングを開く：

local greeter, err = contract.open("app.services:greeter")
if err then
    return nil, err
end

local result, err = greeter:say_hello("Alice")

スコープコンテキストまたはクエリパラメータ付き：

-- スコープテーブル付き
local svc, err = contract.open("app.services:user", {
    tenant_id = "acme",
    region = "us-east"
})

-- クエリパラメータ付き（自動変換: "true"→bool, numbers→int/float）
local api, err = contract.open("app.services:api?debug=true&timeout=5000")

-- 呼び出しオプション付き（第3引数）
local inst, err = contract.open("app.services:flaky", nil, {
    retry = { max_attempts = 5, initial_delay = 100 }
})

パラメータ	型	説明
binding_id	string	バインディングID、クエリパラメータをサポート
scope	table	コンテキスト値（オプション、クエリパラメータをオーバーライド）
options	table	呼び出しオプション（オプション）— 例: retry.max_attempts, retry.initial_delay

戻り値: Instance, error

コントラクトを取得

イントロスペクション用のコントラクト定義を取得：

local c, err = contract.get("app.services:greeter")

print(c:id())  -- "app.services:greeter"

local methods = c:methods()
for _, m in ipairs(methods) do
    print(m.name, m.description)
end

local method, err = c:method("say_hello")

メソッド定義

フィールド	型	説明
name	string	メソッド名
description	string	メソッドの説明
input_schemas	table[]	入力スキーマ定義
output_schemas	table[]	出力スキーマ定義

実装を検索

コントラクトを実装するすべてのバインディングをリスト：

local bindings, err = contract.find_implementations("app.services:greeter")

for _, binding_id in ipairs(bindings) do
    print(binding_id)
end

またはコントラクトオブジェクト経由：

local c, err = contract.get("app.services:greeter")
local bindings, err = c:implementations()

実装をチェック

インスタンスがコントラクトを実装しているかチェック：

if contract.is(instance, "app.services:greeter") then
    instance:say_hello("World")
end

メソッドの呼び出し

同期呼び出し - 完了までブロック：

local calc, err = contract.open("app.services:calculator")

local sum, err = calc:add(10, 20)
local product, err = calc:multiply(5, 6)

非同期呼び出し

非同期実行には_asyncサフィックスを追加：

local processor, err = contract.open("app.services:processor")

local future, err = processor:process_async(large_dataset)

-- 他の処理を実行...

-- 結果を待機
local ch = future:response()
local payload, ok = ch:receive()
if ok then
    local result = payload:data()
end

FutureメソッドについてはFutureを参照。

コントラクト経由で開く

コントラクトオブジェクトを通じてバインディングを開く：

local c, err = contract.get("app.services:user")

-- デフォルトバインディング
local instance, err = c:open()

-- 特定のバインディング
local instance, err = c:open("app.services:user_impl")

-- スコープ付き
local instance, err = c:open(nil, {user_id = 123})
local instance, err = c:open("app.services:user_impl", {user_id = 123})

コンテキストを追加

事前設定されたコンテキスト付きラッパーを作成：

local c, err = contract.get("app.services:user")

local wrapped = c:with_context({
    request_id = ctx.get("request_id"),
    user_id = current_user.id
})

local instance, err = wrapped:open()

呼び出しオプション

with_options でリトライおよびその他の呼び出し動作を構成します:

local c, err = contract.get("app.services:flaky")

local inst, err = c
    :with_options({ retry = { max_attempts = 5, initial_delay = 100 } })
    :open("app.services:flaky_impl")

local result, err = inst:call()

オプションは返されるインスタンスのすべてのメソッド呼び出しに適用されます。リトライ可能なエラーのみがリトライをトリガーします。リトライ不可能なエラーは即座に返されます。with_context、with_actor、with_scope とチェーン可能です。

オプション	型	説明
retry.max_attempts	int	最初を含む最大試行回数 (1 はリトライを無効化)
retry.initial_delay	int/duration	最初のリトライ前の遅延（ミリ秒または duration 文字列）

セキュリティコンテキスト

認可用のアクターとスコープを設定：

local security = require("security")
local c, err = contract.get("app.services:admin")

local secured = c:with_actor(security.actor()):with_scope(security.scope())

local admin, err = secured:open()

権限

権限	リソース	関数
contract.get	contract id	get()
contract.open	binding id	open()、Contract:open()
contract.implementations	contract id	find_implementations()、Contract:implementations()
contract.call	method name	同期および非同期メソッド呼び出し
contract.context	”context”	Contract:with_context()
contract.security	”security”	Contract:with_actor()、Contract:with_scope()

エラー

条件	種別
無効なバインディングIDフォーマット	errors.INVALID
コントラクトが見つからない	errors.NOT_FOUND
バインディングが見つからない	errors.NOT_FOUND
メソッドが見つからない	errors.NOT_FOUND
デフォルトバインディングがない	errors.NOT_FOUND
権限拒否	errors.PERMISSION_DENIED
呼び出し失敗	errors.INTERNAL