102 lines
5.0 KiB
Markdown
102 lines
5.0 KiB
Markdown
# WIP over HTTPS
|
|
|
|
WIP over HTTPSは、**WIP Core ProtocolをHTTPS上へ対応付ける標準Transport Binding**である。
|
|
|
|
## 目的
|
|
|
|
Core Protocolの意味論を変えずに、既存のWebインフラを利用してClientとHostを接続する。
|
|
|
|
## 方針
|
|
|
|
初期の標準bindingはHTTPS上のrequest / responseのみを規定する。TLS、認証、Proxy、Gateway、Observability、Caching、connection reuse、multiplexing、compression等の既存機構を利用してよいが、特定のHTTP versionや実装方式を必須にしない。
|
|
|
|
OperationがWebSocket等のendpointを通常のdomain valueとして返すことは妨げない。そのendpoint上のprotocol、状態、lifecycleはWIPの規定対象外であり、ClientとHost固有実装の責務とする。
|
|
|
|
双方向socket transportをWIP bindingとして標準化する場合は、将来の独立した拡張として定義する。
|
|
|
|
## Binding対象
|
|
|
|
少なくとも、Core Protocolの以下の操作をHTTP request / responseへ対応付ける。
|
|
|
|
- `fetch`
|
|
- `fetch_tree`
|
|
- `call_operation`
|
|
|
|
具体的なHTTP method、endpoint、content type、error mapping、認証方式、batch表現などは、このbinding仕様側で定義する。
|
|
|
|
## WIP IDLの取得
|
|
|
|
Operationのinput / output schemaは[WIP IDL](wip-idl.md)のsourceとして交換する。HostはIDLのlanguage identifier、sourceまたはsourceを取得するための参照、およびcacheと同一性確認に利用できるdigestを公開する。
|
|
|
|
HTTPS response全体をJSON envelopeにする場合、IDL sourceをJSON stringとして格納してよい。ただし、これはIDLをJSON ASTへ変換するものではない。BindingはIDL sourceを専用resourceおよびcontent typeで直接取得する方法を定義してもよい。
|
|
|
|
## Operation valueのJSON encoding
|
|
|
|
WIP over HTTPSでは、`call_operation`のinputとoutputをWIP IDLに従うJSON valueとしてencodeする。JSONはHTTPS binding上の値表現であり、WIP Coreの型定義形式ではない。
|
|
|
|
`input`は常に名前付きfieldを持つJSON objectとする。位置引数は用いず、引数を持たないOperationには空のobjectを渡す。
|
|
|
|
概念的なrequest bodyは次の形になる。
|
|
|
|
```json
|
|
{
|
|
"target": "/items/current",
|
|
"operation": "get_related_item",
|
|
"input": {
|
|
"relation": "sibling",
|
|
"limit": 10
|
|
}
|
|
}
|
|
```
|
|
|
|
IDL型からJSONへのmappingはbindingで一意に定める。少なくとも次の規則を持つ。
|
|
|
|
- `boolean`、`string`、`number`、record、listは対応するJSON valueで表す。
|
|
- optionalなrecord fieldはfieldの省略で表し、`null`とは区別する。
|
|
- unit形式のenumはstring、payloadを持つunionは明示的なdiscriminatorを持つobjectで表す。
|
|
- `bytes`はbase64でencodeしたstringとして表す。
|
|
- 通常のJSON numberで表す`integer`は相互運用可能な安全範囲に制限する。それを超える整数型を設ける場合はdecimal string等のlosslessな表現を定義する。
|
|
- WIP IDLの`entry`は、同じWorldspace内のcanonical absolute pathをJSON stringとして表す。
|
|
|
|
ClientはWIP IDLに従ってvalueをdecodeし、IDL上で`entry`と宣言された位置にある文字列だけをエントリとして認識する。通常の`string`や任意JSON値に含まれるpathらしい文字列を、エントリとして推測してはならない。
|
|
|
|
## Entry取得のbatching
|
|
|
|
Operation Resultに複数のentry pathが含まれる場合、Clientはそれらを抽出して重複を除去し、必要なpathを取得できる。
|
|
|
|
Core Protocol上では各`fetch`を独立した観測として扱う。WIP over HTTPSは、複数の`fetch`を一つのHTTP requestへまとめ、個別に実行した場合と同じ結果を返すbatch表現を定義してよい。Batchingは通信上の最適化であり、Core Protocolへ別の意味を追加しない。
|
|
|
|
## Invoke responseへの同梱
|
|
|
|
Hostは追加のround tripを避けるため、Operation Resultに含まれるentry pathの公開情報を、invoke responseの`included` sidecarへ同梱してよい。
|
|
|
|
```json
|
|
{
|
|
"output": {
|
|
"items": [
|
|
"/items/123",
|
|
"/items/456"
|
|
]
|
|
},
|
|
"included": {
|
|
"/items/123": {
|
|
"type": "item",
|
|
"description": "First item",
|
|
"operations": []
|
|
},
|
|
"/items/456": {
|
|
"type": "item",
|
|
"description": "Second item",
|
|
"operations": []
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
`included`のkeyはOperation Resultに現れるcanonical entry path、valueは同じpathに対する通常の`fetch`結果と同じ観測とする。`included`はOperationのtyped outputには含まれず、Operationのoutput schemaを変更しない。
|
|
|
|
Clientは`included`をfetch済みの観測として利用しても、無視して改めて取得してもよい。Clientが同梱を要求する方法、Hostが自動的に同梱できる条件、response sizeの上限はbindingの詳細として定める。
|
|
|
|
## 非目標
|
|
|
|
WIP over HTTPSはHost内部のAPIやデータソース接続方式を規定しない。また、WIP Core ProtocolそのものをHTTP依存のモデルへ変えることも目的としない。 |