wip-reference/2.2-operation.md

2.2. Operation

2.2.1 目的

Operationは、Objectが外部へ公開する意味的な操作を表す。WIPではドメインデータをpropertiesとして常時露出するのではなく、読み取り・検索・更新を含む行為をOperationとして公開する。

2.2.2 基本形

Operationは少なくとも次の情報を持つ。

• name — Operationを識別する名前。
• description — 何を行う操作かを説明する短い自然言語。
• input — 呼び出し時に受け取る入力の型。
• output — 呼び出し結果の型。
• guard — 必要に応じて公開される実行条件・precondition。

Operation名や型だけに意味を担わせず、descriptionをinterface metadataの一部として扱う。長文documentationを埋め込むことは想定しない。

2.2.3 入出力型

Operationのinput / outputは、Wire Protocol上で機械的に検証・解釈できる構造化された型として定義する。

ただしWIPは任意のドメインデータをObjectのpropertiesとしてモデル化するものではない。ここでの型はOperation境界の値を記述するためのものである。

具体的な型システム、primitive type、record / list / optional / union、ObjectやLinkを結果として返す場合の表現はこのページで定める。

2.2.4 可視性

Hostは、主体の権限やrole / capabilityに基づいて、その主体へ公開するOperation集合を決定してよい。

Operationの可視性は、頻繁に変化する実行可否やdomain stateを表すものではなく、その主体に対してどのinterfaceを公開するかというprojectionとして扱う。

例えばread-only主体には読み取り系Operationのみを公開し、maintainerやadminには追加の更新・管理Operationを公開できる。

WIPはOperationのavailable / disabledのような揮発的状態をinterface metadataとして同期することを前提としない。現在の実行可否やpreconditionは、必要に応じてdomain固有のOperationで観測し、最終的なauthorizationや実行条件はcall_operation時にHostが検証する。

2.2.5 Guard

Guardを設ける場合は、現在時点のavailabilityを同期する仕組みではなく、Operationに一般的に課されるpreconditionやconstraintを説明するsemantic metadataとして扱う。

Guardの具体的schemaは未解決事項として管理する。

2.2.6 Operation Result

Operationの結果には通常の値だけでなく、新しいObject / エントリやLinkの発見が含まれ得る。

ClientがそれらをKnown Spaceへ統合できるよう、発見されたWorldspace要素は構造化された結果として表現する。