docs: rewrite reference and clarify interface abstraction
This commit is contained in:
@@ -2,52 +2,56 @@
|
||||
|
||||
## Interface
|
||||
|
||||
ObjectはOperation定義を直接持たず、0個以上のInterface参照をordered setとして持つ。各InterfaceはObjectが公開する一つのcapability namespaceである。
|
||||
Objectは、Operation定義を直接持つ代わりに、0個以上のInterface参照をordered setとして持つ。各Interfaceは、Objectが公開する一つのcapability namespaceであり、利用できるOperationと各Operationのparameter、return type、documentationを定義する。
|
||||
|
||||
Interfaceは、Objectで利用できるOperationと、各Operationのparameter、return type、documentationを定義する。複数のObjectが同じInterfaceを共有できるため、Operation定義をObjectごとに重複して送る必要はない。
|
||||
複数のObjectで同じInterfaceを共有できるため、ObjectごとにOperation定義を重複して送る必要はない。ObjectのInterface集合にはset semanticsを適用し、同じ参照を重複して含めない。列挙順はOperation解決には影響しないが、Hostの立項順としてUI表示に使用できる。
|
||||
|
||||
ObjectのInterface集合はset semanticsを持ち、同じ参照を重複して含めない。列挙順はOperation解決には影響しないが、Hostの立項順としてUI表示に使用できる。Operation callは集合から一つのInterfaceを明示して、そのDescriptor内のOperationを実行する。
|
||||
Operation callでは、この集合から一つのInterfaceを明示し、そのDescriptor内のOperationを実行する。
|
||||
|
||||
Interface実装者は、RustのtraitやTypeScriptのdefinition API等を使って実装コード上でInterfaceを宣言する。Libraryはその宣言から、typed handler、runtime validation、およびmachine-readableなInterface Descriptorを生成する。
|
||||
Interface実装者は、RustのtraitやTypeScriptのdefinition API等を使い、実装コード上でInterfaceを宣言する。Libraryはこの宣言から、typed handler、runtime validation、machine-readableなInterface Descriptorを生成する。
|
||||
|
||||
Interface Descriptorは人間が手書きするschema fileではない。Hostが`fetch_interface`で公開し、Clientが参照単位でcacheするprotocol dataである。
|
||||
したがって、Interface Descriptorは人間が手書きするschema fileではない。Hostが`fetch_interface`で公開し、Clientが参照単位でcacheするprotocol dataである。
|
||||
|
||||
## Interfaceの識別とscope
|
||||
|
||||
Interface参照は、Worldspace上の絶対pathである`scope`と、そのscope内のlocal nameである`name`を別fieldとして持つ構造化データである。同じClient-facing Worldspace内の同じ有効な`(scope, name)`は同じInterfaceを表す。
|
||||
Interface参照は、`scope`と`name`を別fieldとして持つ構造化データである。`scope`はWorldspace上の絶対path、`name`はそのscope内のlocal nameを表す。同じClient-facing Worldspace内では、同じ有効な`(scope, name)`が同じInterfaceを表す。
|
||||
|
||||
```text
|
||||
{ scope: "/github", name: "issue.read" }
|
||||
{ scope: "/gitlab", name: "issue.read" }
|
||||
```
|
||||
|
||||
この二つは同じlocal nameを持つが、異なるInterface参照である。Local nameの`.`等に階層やOperationとの区切りの意味を持たせない。同じscope内の異なるInterfaceへ同じnameを割り当てない。複数Providerを同じscopeへ登録する場合も、Hostが名前の衝突を検出・解消する。
|
||||
この二つの参照はlocal nameが同じでも、scopeが異なるため別のInterface参照となる。Local nameの`.`等には、階層やOperationとの区切りの意味を持たせない。同じscope内の異なるInterfaceに同じnameを割り当てない。複数Providerを同じscopeへ登録する場合にも、Hostが名前の衝突を検出・解消する。
|
||||
|
||||
ScopeはClientに対してHostが公開するWorldspaceのrootを基準とする。Backendのpath、filesystem root、HTTP endpointのprefixではなく、相対pathは認めない。異なるWorldspace間で同じ`(scope, name)`を同一Interfaceとして扱わない。
|
||||
Scopeの基準は、HostがClientへ公開するWorldspaceのrootである。Backendのpath、filesystem root、HTTP endpointのprefixを基準にはせず、相対pathも認めない。異なるWorldspaceにある同じ`(scope, name)`を、同一Interfaceとして扱わない。
|
||||
|
||||
Objectが利用できるscopeは、そのObjectの配置pathとの[祖先関係](2.1-object-tree-schema.md#interface-scope)に従う。この制約はInterfaceの自動継承ではない。Objectは使用するInterfaceを明示的に公開し、scopeだけを根拠にOperationを追加したり、実行を認可したりしない。
|
||||
Objectが利用できるscopeは、そのObjectの配置pathとの[祖先関係](2.1-object-tree-schema.md#interface-scope)に従う。ただし、祖先関係だけでInterfaceを自動継承するわけではない。使用するInterfaceはObjectで明示的に公開し、scopeだけを根拠にOperationを追加したり、実行を認可したりしない。
|
||||
|
||||
構造とvalidationは[3. Protocol](3-protocol.md#interface-reference)、`/github::issue.read#read`等の人間・AI向け短縮表記は[4.2. Text View](4.2-text-view.md#参照表記)で定義する。Interface参照とOperation名を連結した表示文字列をProtocolの参照fieldへ格納しない。
|
||||
Protocolの参照fieldへは、Interface参照とOperation名を連結した表示文字列を格納しない。構造とvalidationは[3. Protocol](3-protocol.md#interface-reference)に従う。`/github::issue.read#read`等の人間・AI向け短縮表記は[4.2. Text View](4.2-text-view.md#参照表記)で定義する。
|
||||
|
||||
Hostによるproxy・Worldspace合成では、Hostがscopeを公開先の配置へ変換する。Path、typed `entry`、identity、validatorとの一貫性は[Worldspace composition](3-protocol.md#worldspace-composition)に従う。
|
||||
HostがproxyやWorldspace合成を行う場合は、scopeを公開先の配置へ変換する。その際のpath、typed `entry`、identity、validatorとの一貫性は[Worldspace composition](3-protocol.md#worldspace-composition)に従う。
|
||||
|
||||
## Scope Objectと有効期間
|
||||
|
||||
Scopeは、そのpathにあるObject（scope Object）に紐づく。Object自身のpathをscopeにするself-scopeを許可し、root Objectもscope `/`を利用できる。Scope Object自身がそのscopeの全Interfaceを`interfaces`へ公開する必要はない。
|
||||
Scopeは、そのpathにあるObject（scope Object）に紐づく。Object自身のpathをscopeにするself-scopeも許可し、root Objectはscope `/`を利用できる。Scope Object自身の`interfaces`に、そのscopeの全Interfaceを公開する必要はない。
|
||||
|
||||
Interfaceの識別は`(scope, name)`のままであり、scope Objectの`ref`はその識別子の第三成分ではない。`ref`がある場合は観測したObjectとの紐付きを確認するために用いる。Objectの状態を確認するvalidatorや、Descriptorの版を確認するInterface validatorとは役割が異なる。Scope Objectの通常の状態更新だけを理由に、scopeの紐付きを無効にしない。
|
||||
Scope Objectの`ref`がある場合は、観測したObjectとの紐付きを確認するために用いる。Interfaceの識別子はあくまで`(scope, name)`であり、`ref`を第三成分にはしない。
|
||||
|
||||
Scope Objectがそのpathから削除・移動・差し替えられると、旧Objectに紐づくInterface参照の有効期間は終了する。同じpathへ新しいObjectとInterfaceを公開することは許可するが、旧Objectの登録を暗黙に引き継がない。移動先では新しいscopeによる別の参照となり、同じ`ref`を観測してもClientにInterface参照の移動追跡やcacheの付け替えを要求しない。
|
||||
この`ref`は、Objectの状態を確認するvalidatorとも、Descriptorの版を確認するInterface validatorとも役割が異なる。Scope Objectの通常の状態更新だけを理由に、scopeの紐付きを無効にしない。
|
||||
|
||||
Scope Objectの`ref`はoptionalである。`ref`のないObjectが同じpathで差し替えられても、そのidentityを追跡できないことは仕様上許容される。これを不正なHostとしたり、差し替えの検出を必須にしたりしない。ただし、現在のObjectへのInterface membership、scopeの適合、指定されたvalidator、authorizationは引き続き検証する。存続中の同じInterfaceについて、`ref`がないことを理由にDescriptorのimmutable / validator規則を弱めない。
|
||||
一方、scope Objectがそのpathから削除・移動・差し替えられると、旧Objectに紐づくInterface参照の有効期間は終了する。同じpathへ新しいObjectとInterfaceを公開することは許可するが、旧Objectの登録を暗黙には引き継がない。移動先では新しいscopeによる別の参照となる。同じ`ref`を観測しても、ClientにInterface参照の移動追跡やcacheの付け替えを要求しない。
|
||||
|
||||
Clientはscope Objectがそのpathから消えたことを確認した場合、そのscopeのInterface cacheを破棄できる。Client-localなcache evictionやindexable edgeの消失だけをObject削除の証拠にしない。実行中callは固定済みの観測を使用し、結果検証が終わるまで必要なDescriptorを保持する。削除通知やClientによる常時監視は要求しない。
|
||||
Scope Objectの`ref`はoptionalである。`ref`のないObjectが同じpathで差し替えられた場合、そのidentityを追跡できないことは仕様上許容される。そのHostを不正とみなしたり、差し替えの検出を必須にしたりしない。
|
||||
|
||||
ただし、`ref`の有無にかかわらず、現在のObjectへのInterface membership、scopeの適合、指定されたvalidator、authorizationは検証する。存続中の同じInterfaceでは、`ref`がないことを理由にDescriptorのimmutable / validator規則を弱めない。
|
||||
|
||||
Clientは、scope Objectがそのpathから消えたと確認した場合、そのscopeのInterface cacheを破棄できる。Client-localなcache evictionやindexable edgeの消失だけを、Object削除の証拠にはしない。実行中callでは固定済みの観測を使い、結果検証が終わるまで必要なDescriptorを保持する。削除通知やClientによる常時監視は要求しない。
|
||||
|
||||
具体的な紐付きの観測とcall preconditionは[Protocol](3-protocol.md#scope-objectの紐付き)に従う。
|
||||
|
||||
## Interface Descriptor
|
||||
|
||||
一つのInterface Descriptorは一つのInterfaceを定義し、少なくとも次を保持する。
|
||||
一つのInterface Descriptorは一つのInterfaceを定義し、少なくとも次の情報を保持する。
|
||||
|
||||
- Format version
|
||||
- Interface documentation
|
||||
@@ -56,15 +60,15 @@ Clientはscope Objectがそのpathから消えたことを確認した場合、
|
||||
- Operationごとのparameterとreturn type
|
||||
- Type、field、parameter、case等のdocumentation
|
||||
|
||||
Descriptorのlogical structは[3. Protocol](3-protocol.md)で定義する。Code-firstな生成は本章、人間とAIへのInterface signatureは[4.2. Text View](4.2-text-view.md)で扱う。
|
||||
Descriptorのlogical structは[3. Protocol](3-protocol.md)で定義する。実装コードの宣言から生成するcode-firstの形をとり、人間とAIへのInterface signatureは[4.2. Text View](4.2-text-view.md)に従う。
|
||||
|
||||
Clientは取得したDescriptorを構造検証および意味検証してからcacheする。Named typeの参照解決、Operation callのvalidation、表示生成には検証済みのInterfaceだけを使用する。
|
||||
Clientは、取得したDescriptorの構造と意味を検証してからcacheする。Named typeの参照解決、Operation callのvalidation、表示生成に使うのは、検証済みのInterfaceだけである。
|
||||
|
||||
## Operation declaration
|
||||
|
||||
Operationは、名前付きparameter、return type、documentationを持つ。
|
||||
Operationには、名前付きparameter、return type、documentationを宣言する。
|
||||
|
||||
人間とAIへ提示する場合は、Interface DescriptorからIDL風のInterface signatureを生成できる。以下はOperation部分の表示例である。
|
||||
人間とAIへ提示するときは、Interface DescriptorからIDL風のInterface signatureを生成できる。Operation部分は、例えば次のように表示する。
|
||||
|
||||
```text
|
||||
/// "Returns items related to this Object."
|
||||
@@ -77,61 +81,61 @@ operation get_related_items(
|
||||
};
|
||||
```
|
||||
|
||||
Interface signatureはInterfaceの交換形式や入力言語ではなく、検証済みDescriptorから生成する表示である。Object signatureとInterface signatureの表記は[4.2. Text View](4.2-text-view.md)で定義する。
|
||||
このInterface signatureは、検証済みDescriptorから生成する表示であり、Interfaceの交換形式や入力言語ではない。Object signatureとInterface signatureの表記は[4.2. Text View](4.2-text-view.md)で定義する。
|
||||
|
||||
Parameterは常に名前付きとし、位置引数は用いない。引数を持たないOperationは空のparameter listとして表し、`call_operation`には空のrecordを渡す。
|
||||
Parameterは常に名前付きとし、位置引数は用いない。引数を持たないOperationは空のparameter listで表し、`call_operation`には空のrecordを渡す。
|
||||
|
||||
```wip
|
||||
operation refresh() -> unit;
|
||||
```
|
||||
|
||||
Return typeにはDescriptorで定義される任意のvalue typeを使用できる。Evolution compatibilityが必要なOperationでは、fieldを追加できるrecordをreturn typeの基本とする。
|
||||
Return typeには、Descriptorで定義される任意のvalue typeを使用できる。Evolution compatibilityが必要なOperationでは、fieldを追加できるrecordをreturn typeの基本とする。
|
||||
|
||||
Operationの用途は短いdocumentationで説明する。長文documentationや大量のApplication dataをInterface Descriptorへ埋め込まない。
|
||||
Operationの用途は短いdocumentationで説明し、長文documentationや大量のApplication dataをInterface Descriptorへ埋め込まない。
|
||||
|
||||
Operation名は一つのInterface Descriptor内で一意とする。異なるInterface間では同じOperation名を使用でき、`call_operation`は構造化Interface参照とOperation名の組で解決する。表示用のqualified表記は[Text Viewの参照表記](4.2-text-view.md#参照表記)に従い、Protocolでは参照とOperation名を別fieldとして扱う。
|
||||
Operation名は、一つのInterface Descriptor内で一意とする。異なるInterface間では同じOperation名を使用できる。`call_operation`は構造化Interface参照とOperation名の組で解決し、Protocolでは両者を別fieldとして扱う。表示用のqualified表記は[Text Viewの参照表記](4.2-text-view.md#参照表記)に従う。
|
||||
|
||||
## `fetch_interface`
|
||||
|
||||
`fetch_interface(interface)`は、Interface参照に対応する現在のInterface Descriptor、optionalなscope Objectの`ref`（`scope_ref`）、optionalなInterface validatorを一つの観測として取得する。
|
||||
`fetch_interface(interface)`は、Interface参照に対応する現在のInterface Descriptorを取得する。同時に、optionalなscope Objectの`ref`（`scope_ref`）とoptionalなInterface validatorを、一つの観測として取得する。
|
||||
|
||||
```text
|
||||
fetch_interface(interface) -> Interface Descriptor, scope_ref?, validator?
|
||||
```
|
||||
|
||||
ObjectはInterface参照のordered setだけを持ち、Descriptorを先行同梱しない。ClientはInterface cacheと各参照を比較し、未知のDescriptorを取得する。Interface validator mismatch等で更新が必要になった参照は再取得する。Hostは主体へ公開したObjectの各Interface参照について、現在のDescriptorをその主体から取得可能にしなければならない。
|
||||
Objectが持つのはInterface参照のordered setだけであり、Descriptorは先行同梱しない。Clientは各参照をInterface cacheと比較して未知のDescriptorを取得し、Interface validator mismatch等で更新が必要になった参照を再取得する。Hostは、主体へ公開したObjectの各Interface参照について、現在のDescriptorをその主体から取得可能にしなければならない。
|
||||
|
||||
同じ有効期間内のInterface参照とvalidatorの組は同じDescriptorを表す。Validatorを返さないInterface参照は、その参照の有効期間中immutableでなければならない。`scope_ref`はこの観測の紐付きmetadataとして保持し、参照の識別子へ組み込まない。
|
||||
同じ有効期間内では、同じInterface参照とvalidatorの組は同じDescriptorを表す。Validatorを返さないInterface参照は、その有効期間中immutableでなければならない。`scope_ref`は、観測の紐付きmetadataとして保持し、参照の識別子へは組み込まない。
|
||||
|
||||
HostはClientのcache状態を推測して、要求されていないDescriptorをObject responseへ追加しない。複数のDescriptorが必要なClientは、それぞれの`fetch_interface`を個別に並行実行できる。
|
||||
HostはClientのcache状態を推測し、要求されていないDescriptorをObject responseへ追加しない。複数のDescriptorが必要なら、Clientはそれぞれの`fetch_interface`を個別に並行実行できる。
|
||||
|
||||
## Operationの可視性
|
||||
|
||||
Hostは、主体の権限やrole / capabilityに基づいて、その主体へ公開するInterface参照の集合を決定してよい。同じObjectでも、主体ごとに異なるInterface集合を返してよい。
|
||||
Hostは、主体の権限やrole / capabilityに基づいて、その主体へ公開するInterface参照の集合を決定してよい。同じObjectに対しても、主体ごとに異なるInterface集合を返してよい。
|
||||
|
||||
Operationを主体に認識させない場合、Hostは次のいずれかを選べる。
|
||||
Operationの存在を主体に認識させない場合には、次のいずれかを選べる。
|
||||
|
||||
- そのOperationをcapabilityとしてまとめたInterface参照をObjectの集合から除外する。
|
||||
- そのOperationを宣言しない別のInterface Descriptorを参照する。
|
||||
|
||||
ClientがObjectで公開されていないInterface参照を指定した場合は`InterfaceMismatch`、公開されているInterfaceに宣言されていないOperation名を指定した場合は`OperationNotFound`を返す。
|
||||
ClientがObjectで公開されていないInterface参照を指定すると、`InterfaceMismatch`を返す。公開されているInterfaceに宣言されていないOperation名を指定すると、`OperationNotFound`を返す。
|
||||
|
||||
Operationの存在を公開しつつ実行だけを認めない設計も可能である。この場合はOperationをいずれかのInterfaceに宣言し、`call_operation`時のauthorizationで拒否して`PermissionDenied`を返す。
|
||||
これとは別に、Operationの存在を公開し、実行だけを認めない設計も可能である。その場合は、OperationをいずれかのInterfaceに宣言したうえで、`call_operation`時のauthorizationで拒否し、`PermissionDenied`を返す。
|
||||
|
||||
したがって、Hostは主体に対して次を独立に選択できる。
|
||||
Hostは、主体に対する公開と実行の条件を次のように独立に選択できる。
|
||||
|
||||
- Object自体を公開せず、そのObjectへの`observe`とOperation callを`NotFound`にする。
|
||||
- Objectを公開するが、特定Interfaceを集合から除外する。
|
||||
- Objectを公開し、特定Operationを含まないInterfaceを使用する。
|
||||
- Object、Interface、Operationを公開するが、そのOperationの実行を`PermissionDenied`にする。
|
||||
|
||||
Interface集合と各Interface内のOperation可視性は、頻繁に変化する実行可否やdomain stateを表すものではなく、**その主体に対してどのcapabilityを公開するか**というprojectionとして扱う。
|
||||
Interface集合と各Interface内のOperation可視性は、**その主体に対してどのcapabilityを公開するか**を表すprojectionである。頻繁に変化する実行可否やdomain stateを表すものとしては扱わない。
|
||||
|
||||
WIPはOperationの`available` / `disabled`のような揮発的状態をInterface集合へ同期することを前提としない。現在状態を判断する必要がある場合は、必要に応じてdomain固有のOperationで観測する。公開されたOperationについても、最終的なauthorizationと実行条件の判定は`call_operation`時にHostが行う。
|
||||
WIPは、Operationの`available` / `disabled`のような揮発的状態をInterface集合へ同期することを前提としない。現在状態の判断が必要なら、必要に応じてdomain固有のOperationで観測する。公開されたOperationでも、最終的なauthorizationと実行条件は、`call_operation`時にHostが判定する。
|
||||
|
||||
## `call_operation`
|
||||
|
||||
`call_operation`は、指定pathにあるObjectに対して、Interfaceに宣言されたOperationを実行する。
|
||||
`call_operation`は、指定pathにあるObjectに対し、Interfaceに宣言されたOperationを実行する。
|
||||
|
||||
```text
|
||||
call_operation(target, interface, operation, arguments) -> result, validator?
|
||||
@@ -147,7 +151,7 @@ call_operation(target, interface, operation, arguments) -> result, validator?
|
||||
- `result`はOperationのreturn typeに従うvalue。
|
||||
- Responseの`validator`はOperation実行後のObject状態に対してHostが発行したoptionalな値。
|
||||
|
||||
HostはOperationを実行する前に、次を検証する。
|
||||
Hostは、Operationを実行する前に次の条件を検証する。
|
||||
|
||||
1. `target.path`が存在する。
|
||||
2. `target.validator`が指定されている場合、現在のObject validatorと一致する。
|
||||
@@ -157,26 +161,28 @@ HostはOperationを実行する前に、次を検証する。
|
||||
6. Argumentsがparameter declarationに従っている。
|
||||
7. ClientがOperationを実行できる。
|
||||
|
||||
対象Objectが現在のClient-facing Worldspaceへ公開されていない場合は`not_found`、指定Interfaceが対象Objectの現在の`interfaces`に含まれない場合や、指定された`scope_ref`の紐付きを確認できない場合は`interface_mismatch`、Operationが指定Interfaceに宣言されていない場合は`operation_not_found`、宣言されたOperationの実行が認められない場合は`permission_denied`を返す。`scope_ref`を持たない観測とcallも許可し、その省略だけでは拒否しない。
|
||||
対象Objectが現在のClient-facing Worldspaceへ公開されていなければ、`not_found`を返す。指定InterfaceがObjectの現在の`interfaces`に含まれない場合、または指定された`scope_ref`の紐付きを確認できない場合は、`interface_mismatch`を返す。指定InterfaceにOperationが宣言されていなければ`operation_not_found`、宣言されたOperationの実行が認められなければ`permission_denied`を返す。`scope_ref`を持たない観測とcallも許可し、省略したことだけを理由には拒否しない。
|
||||
|
||||
Object validator、Interface membership、scope Objectの紐付きと指定された`scope_ref`、Interface validator、Descriptor、Operation implementation、backend対象の確認と固定は、Operation実行に対して一貫したpreconditionとして扱う。Object validatorが一致しない場合は`validator_mismatch`、要求されるObject validatorがない場合は`validator_required`を返す。Mutable Interfaceのvalidatorがない場合は`interface_validator_required`、一致しない場合は`interface_validator_mismatch`を返す。いずれの場合もHostはOperationを実行しない。
|
||||
Object validator、Interface membership、scope Objectの紐付きと指定された`scope_ref`、Interface validator、Descriptor、Operation implementation、backend対象の確認と固定は、Operation実行に対して一貫したpreconditionとして扱う。
|
||||
|
||||
Argumentsに未知のfieldがある場合、必須parameterがない場合、またはvalueが宣言型に一致しない場合、HostはOperationを実行せず`invalid_arguments`を返す。
|
||||
Object validatorが一致しない場合は`validator_mismatch`を、要求されるObject validatorがない場合は`validator_required`を返す。Mutable Interfaceのvalidatorがない場合は`interface_validator_required`を、一致しない場合は`interface_validator_mismatch`を返す。いずれの場合も、HostはOperationを実行しない。
|
||||
|
||||
ClientはHostから受け取ったsuccess responseのresultをreturn typeに従って検証する。Hostが宣言と異なるresultを返した場合はHostが返したProtocol failureではなく`InvalidResponse`として扱い、そのvalueをApplicationへ渡さない。Host Runtimeがinvalidなimplementation resultを送信前に検出した場合は、effectがcommitされていないと保証できるときだけ`Internal`を返し、保証できない場合は`OperationOutcomeUnknown`を返す。
|
||||
Argumentsに未知のfieldがある場合、必須parameterがない場合、valueが宣言型に一致しない場合にも、HostはOperationを実行せず、`invalid_arguments`を返す。
|
||||
|
||||
Clientは、Hostから受け取ったsuccess responseのresultをreturn typeに従って検証する。宣言と異なるresultが返された場合は、Hostが返したProtocol failureではなく`InvalidResponse`として扱い、そのvalueをApplicationへ渡さない。
|
||||
|
||||
Host Runtimeが送信前にinvalidなimplementation resultを検出した場合は、effectがcommitされていないと保証できるときだけ`Internal`を返す。保証できない場合は`OperationOutcomeUnknown`を返す。
|
||||
|
||||
## Application data
|
||||
|
||||
Operation argumentsとresultは、Applicationが定義し、利用するdataである。
|
||||
|
||||
WIPは次を規定する。
|
||||
Operation argumentsとresultは、Applicationが定義して利用するdataである。WIPが規定する内容は次のとおりである。
|
||||
|
||||
- Descriptor上の型表現
|
||||
- Transport上のencoding
|
||||
- ClientとHostのboundary validation
|
||||
- `entry`等のWIP固有型の意味
|
||||
|
||||
WIPは次を規定しない。
|
||||
一方、次の内容はWIPでは規定しない。
|
||||
|
||||
- Dataのdomain上の意味
|
||||
- 永続化方法
|
||||
@@ -184,19 +190,19 @@ WIPは次を規定しない。
|
||||
- Business rule
|
||||
- Clientが取得したdataを利用する方法
|
||||
|
||||
Wire schema上正しいことと、domain上有効であることは別である。例えばargumentsが型に従っていても、現在のdomain stateが操作を許可しない場合、Operation implementationはdomain failureを返し得る。
|
||||
例えば、argumentsが型に従っていても、現在のdomain stateが操作を許可しない場合には、Operation implementationはdomain failureを返し得る。Wire schema上の正しさと、domain上の有効性は別の条件である。
|
||||
|
||||
## Operation Resultとエントリの発見
|
||||
|
||||
Operation Resultには、Descriptorの`entry`型として新しいエントリのpathが含まれ得る。
|
||||
Operation Resultには、Descriptorの`entry`型として、新しいエントリのpathが含まれ得る。`entry`は、同じWorldspace内のcanonical absolute pathである。
|
||||
|
||||
`entry`は同じWorldspace内のcanonical absolute pathである。Clientはreturn typeに従って`entry`型の位置を認識する。通常の`string`やopaqueな`json`に含まれるpathらしい文字列を、エントリとして推測してはならない。
|
||||
Clientは、return typeに従って`entry`型の位置を認識する。通常の`string`やopaqueな`json`に含まれるpathらしい文字列を、エントリとして推測してはならない。
|
||||
|
||||
Clientは発見したpathを参照として利用でき、Objectの公開情報が必要になったときに、必要な深さで`observe`する。発見したすべてのpathの即時取得は要求しない。Operation ResultへObject公開情報やInterface Descriptorを先行同梱しない。
|
||||
発見したpathは参照として利用できる。Clientは、Objectの公開情報が必要になったときに、必要な深さで`observe`する。すべてのpathの即時取得は要求せず、Operation ResultへObject公開情報やInterface Descriptorを先行同梱しない。
|
||||
|
||||
Operationの実行対象と、結果として発見されたエントリのTree上の位置は独立している。発見されたエントリは実行対象の子である必要はなく、親、兄弟、またはWorldspace内の任意の位置にあってよい。
|
||||
発見されたエントリは、実行対象の子である必要はない。親、兄弟、Worldspace内の任意の位置にあってよい。Operationの実行対象と、結果として発見されたエントリのTree上の位置は独立している。
|
||||
|
||||
Operationがpathを返したこと自体から、実行対象との間に親子関係や意味的関係を推論しない。親子関係はTree上の配置で表し、非内包の意味的関係はOperation名、result field名、またはApplication固有のrelation型で表現する。
|
||||
また、pathが返されたこと自体から、実行対象との親子関係や意味的関係を推論しない。親子関係はTree上の配置で表し、非内包の意味的関係はOperation名、result field名、Application固有のrelation型で表現する。
|
||||
|
||||
## Protocol failureとdomain failure
|
||||
|
||||
@@ -217,9 +223,9 @@ Protocol failureは、WIPのrequest、対象、Interface、validation、validato
|
||||
- `internal`
|
||||
- `operation_outcome_unknown`
|
||||
|
||||
`InvalidResponse`はClientが受信したsuccess responseまたはerror responseのProtocol違反を表すlocal classificationであり、Hostが返すProtocol failureではない。`UnsupportedDescriptorFormat`もClient-localであり、validだが未対応のDescriptorをProtocol違反として扱わない。
|
||||
これに対し、`InvalidResponse`は、Clientが受信したsuccess responseまたはerror responseのProtocol違反を表すlocal classificationである。Hostが返すProtocol failureには含めない。`UnsupportedDescriptorFormat`もClient-localであり、validだが未対応のDescriptorをProtocol違反としては扱わない。
|
||||
|
||||
`call_operation`が`operation_outcome_unknown`以外のProtocol failureを返した場合、HostはOperationのeffectがcommitされていないことを保証する。`operation_outcome_unknown`またはresponse不達の場合、ClientはOperationを自動再実行せず、対象を再観測するかdomain固有の照会手段を利用する。
|
||||
`call_operation`が`operation_outcome_unknown`以外のProtocol failureを返した場合、HostはOperationのeffectがcommitされていないことを保証する。`operation_outcome_unknown`またはresponse不達の場合、ClientはOperationを自動再実行しない。対象を再観測するか、domain固有の照会手段を利用する。
|
||||
|
||||
Domain failureは、型として正しいOperationをApplicationが実行した結果として生じる失敗である。
|
||||
|
||||
@@ -227,4 +233,4 @@ Domain failureは、型として正しいOperationをApplicationが実行した
|
||||
- `payment_declined`
|
||||
- `merge_conflict`
|
||||
|
||||
Domain failureをProtocol failureへ混在させない。現在のProtocolでは、Domain failureをOperation return typeのUnion caseとして宣言する。専用のfailure declarationは定義しない。
|
||||
これらのDomain failureをProtocol failureへ混在させない。現在のProtocolでは、Operation return typeのUnion caseとして宣言し、専用のfailure declarationは定義しない。
|
||||
|
||||
Reference in New Issue
Block a user