docs: refine operation interfaces and batching
This commit is contained in:
+81
-30
@@ -20,21 +20,24 @@ OperationがWebSocket等のendpointを通常のdomain valueとして返すこと
|
||||
|
||||
- `fetch`
|
||||
- `fetch_tree`
|
||||
- `fetch_interface`
|
||||
- `call_operation`
|
||||
|
||||
具体的なHTTP method、endpoint、content type、error mapping、認証方式、batch表現などは、このbinding仕様側で定義する。
|
||||
|
||||
## WIP IDLの取得
|
||||
## Interfaceの取得
|
||||
|
||||
Operationのinput / output schemaは[WIP IDL](wip-idl.md)のsourceとして交換する。HostはIDLのlanguage identifier、sourceまたはsourceを取得するための参照、およびcacheと同一性確認に利用できるdigestを公開する。
|
||||
Objectの公開情報はOperation定義を直接含まず、[WIP IDL](wip-idl.md) documentで定義されたInterfaceへの参照を持つ。`fetch_interface`は、その参照に対応するInterfaceのlanguage identifier、source、digestを返す。
|
||||
|
||||
HTTPS response全体をJSON envelopeにする場合、IDL sourceをJSON stringとして格納してよい。ただし、これはIDLをJSON ASTへ変換するものではない。BindingはIDL sourceを専用resourceおよびcontent typeで直接取得する方法を定義してもよい。
|
||||
|
||||
ClientはObjectのInterface参照をcacheと比較し、未知のInterfaceだけを`fetch_interface`する。HostはClientのcache状態を推測せず、`fetch`や`fetch_tree`のresponseへInterface定義を先行同梱しない。複数のInterface取得はHTTP batchingでまとめられる。
|
||||
|
||||
## Operation valueのJSON encoding
|
||||
|
||||
WIP over HTTPSでは、`call_operation`のinputとoutputをWIP IDLに従うJSON valueとしてencodeする。JSONはHTTPS binding上の値表現であり、WIP Coreの型定義形式ではない。
|
||||
WIP over HTTPSでは、`call_operation`のargumentsとresultを、選択したOperation declarationに従うJSON valueとしてencodeする。JSONはHTTPS binding上の値表現であり、WIP CoreのInterface定義形式ではない。
|
||||
|
||||
`input`は常に名前付きfieldを持つJSON objectとする。位置引数は用いず、引数を持たないOperationには空のobjectを渡す。
|
||||
`arguments`はOperationのparameter名をfield名とするJSON objectとする。位置引数は用いず、引数を持たないOperationには空のobjectを渡す。
|
||||
|
||||
概念的なrequest bodyは次の形になる。
|
||||
|
||||
@@ -42,7 +45,7 @@ WIP over HTTPSでは、`call_operation`のinputとoutputをWIP IDLに従うJSON
|
||||
{
|
||||
"target": "/items/current",
|
||||
"operation": "get_related_item",
|
||||
"input": {
|
||||
"arguments": {
|
||||
"relation": "sibling",
|
||||
"limit": 10
|
||||
}
|
||||
@@ -52,7 +55,7 @@ WIP over HTTPSでは、`call_operation`のinputとoutputをWIP IDLに従うJSON
|
||||
IDL型からJSONへのmappingはbindingで一意に定める。少なくとも次の規則を持つ。
|
||||
|
||||
- `boolean`、`string`、`number`、record、listは対応するJSON valueで表す。
|
||||
- optionalなrecord fieldはfieldの省略で表し、`null`とは区別する。
|
||||
- optionalなparameterまたはrecord fieldはfieldの省略で表し、`null`とは区別する。
|
||||
- unit形式のenumはstring、payloadを持つunionは明示的なdiscriminatorを持つobjectで表す。
|
||||
- `bytes`はbase64でencodeしたstringとして表す。
|
||||
- 通常のJSON numberで表す`integer`は相互運用可能な安全範囲に制限する。それを超える整数型を設ける場合はdecimal string等のlosslessな表現を定義する。
|
||||
@@ -60,42 +63,90 @@ IDL型からJSONへのmappingはbindingで一意に定める。少なくとも
|
||||
|
||||
ClientはWIP IDLに従ってvalueをdecodeし、IDL上で`entry`と宣言された位置にある文字列だけをエントリとして認識する。通常の`string`や任意JSON値に含まれるpathらしい文字列を、エントリとして推測してはならない。
|
||||
|
||||
## Entry取得のbatching
|
||||
## HTTP batching
|
||||
|
||||
Operation Resultに複数のentry pathが含まれる場合、Clientはそれらを抽出して重複を除去し、必要なpathを取得できる。
|
||||
WIP over HTTPSは、複数の独立したCore取得requestを一つのHTTP requestへまとめるbatch形式を提供する。Batchingは通信上のpackagingであり、Core Protocolへ新しい操作や意味論を追加しない。
|
||||
|
||||
Core Protocol上では各`fetch`を独立した観測として扱う。WIP over HTTPSは、複数の`fetch`を一つのHTTP requestへまとめ、個別に実行した場合と同じ結果を返すbatch表現を定義してよい。Batchingは通信上の最適化であり、Core Protocolへ別の意味を追加しない。
|
||||
Clientは、Known SpaceとInterface cacheをもとに必要なrequestだけを選択してbatchを構成する。HostはClientの既知状態を推測して、要求されていないentry公開情報やInterface定義をresponseへ追加しない。
|
||||
|
||||
## Invoke responseへの同梱
|
||||
|
||||
Hostは追加のround tripを避けるため、Operation Resultに含まれるentry pathの公開情報を、invoke responseの`included` sidecarへ同梱してよい。
|
||||
Batch endpointは概念的に`POST {wip-endpoint}/batch`とし、bodyに一意な`id`を持つsubrequestの配列を格納する。
|
||||
|
||||
```json
|
||||
{
|
||||
"output": {
|
||||
"items": [
|
||||
"/items/123",
|
||||
"/items/456"
|
||||
]
|
||||
},
|
||||
"included": {
|
||||
"/items/123": {
|
||||
"type": "item",
|
||||
"description": "First item",
|
||||
"operations": []
|
||||
"requests": [
|
||||
{
|
||||
"id": "entry-123",
|
||||
"method": "fetch",
|
||||
"arguments": {
|
||||
"entry": "/items/123"
|
||||
}
|
||||
},
|
||||
"/items/456": {
|
||||
"type": "item",
|
||||
"description": "Second item",
|
||||
"operations": []
|
||||
{
|
||||
"id": "entry-456",
|
||||
"method": "fetch",
|
||||
"arguments": {
|
||||
"entry": "/items/456"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "item-interface",
|
||||
"method": "fetch_interface",
|
||||
"arguments": {
|
||||
"interface": "sha256:item-interface"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`included`のkeyはOperation Resultに現れるcanonical entry path、valueは同じpathに対する通常の`fetch`結果と同じ観測とする。`included`はOperationのtyped outputには含まれず、Operationのoutput schemaを変更しない。
|
||||
Hostは各subrequestを、単独で受け取った場合と同じ規則で処理する。Responseは同じ`id`で対応付けたsubresponseの配列を返す。
|
||||
|
||||
Clientは`included`をfetch済みの観測として利用しても、無視して改めて取得してもよい。Clientが同梱を要求する方法、Hostが自動的に同梱できる条件、response sizeの上限はbindingの詳細として定める。
|
||||
```json
|
||||
{
|
||||
"responses": [
|
||||
{
|
||||
"id": "entry-123",
|
||||
"result": {
|
||||
"name": "123",
|
||||
"description": "First item",
|
||||
"interface": "sha256:item-interface"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "entry-456",
|
||||
"error": {
|
||||
"code": "not_found",
|
||||
"message": "Entry not found"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "item-interface",
|
||||
"result": {
|
||||
"interface": "sha256:item-interface",
|
||||
"language": "wip-idl/1",
|
||||
"digest": "sha256:item-interface",
|
||||
"source": "..."
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Batchには次の規則を適用する。
|
||||
|
||||
- Request内の`id`は一意なstringとする。
|
||||
- Responseの順序に意味を持たせず、`id`でcorrelateする。
|
||||
- 各subrequestは独立して成功または失敗し、一つの失敗によって他のresultを破棄しない。
|
||||
- Batch全体はtransactionではなく、atomicity、共通snapshot、実行順序を保証しない。
|
||||
- Hostはsubrequestを直列または並列に実行してよい。
|
||||
- Subrequest間で、先行requestのresultを後続requestのargumentsとして参照できない。
|
||||
- 各`result`は対応するCore操作を単独で呼んだ場合と同じvalueとする。
|
||||
- 各`error`は通常のProtocol errorと同じschemaを使用する。
|
||||
- HostはClientが要求していないsubresponseを追加してはならない。
|
||||
|
||||
初期のbatch形式に格納できるのは`fetch`、`fetch_tree`、`fetch_interface`とし、`call_operation`は含めない。将来、WIP IDLのEffect annotationを採用する場合に、副作用を持たないと明示されたOperationをbatch対象へ加えるかを改めて検討する。
|
||||
|
||||
Batch件数、request / response byte size、timeoutの上限、およびbatch envelope自体が不正な場合のHTTP statusはbindingの詳細として定める。
|
||||
|
||||
## 非目標
|
||||
|
||||
|
||||
Reference in New Issue
Block a user