79 lines
5.9 KiB
Markdown
79 lines
5.9 KiB
Markdown
# 5. Transport Bindings
|
|
|
|
WIP Transport Bindingは、[3. Protocol](3-protocol.md)で定義するlogical data modelとCore interactionを、具体的な通信方式とwire representationへ対応付ける。
|
|
|
|
標準bindingの定義は[5.1. WIP over HTTP](5.1-wip-over-http.md)にある。
|
|
|
|
## 責務
|
|
|
|
Transport Bindingには、少なくとも次の定義が必要になる。
|
|
|
|
- Endpointまたはpeerの指定方法。
|
|
- Requestとresponseのframing、および一つのlogical interactionとの対応付け。
|
|
- Protocol primitive、Object、Interface Descriptor、Operation Valueのconcrete encoding。
|
|
- Required field、optional field、list、record、bytes等のwire representation。
|
|
- SuccessとProtocol failureのwire representation。
|
|
- Transport failureとProtocol failureの区別。
|
|
- ValidatorおよびOperation preconditionのmapping。
|
|
|
|
これらは通信上の表現を定めるものであり、BindingはProtocolのlogical type、validation、error、visibility、Operation executionの意味を変更してはならない。Binding固有のstatus、header、stream event等を根拠に、新しいProtocol failureや回復actionを暗黙に追加してはならない。
|
|
|
|
## Logical interactionとphysical exchange
|
|
|
|
一つのCore interactionを、一つ以上のphysical messageで実装してよい。その場合も、ClientとHostは各successまたはProtocol failureを、元のlogical requestとそのeffective Worldspace viewへ一意に対応付けられなければならない。
|
|
|
|
複数のCore interactionは、それぞれ独立したrequestとresponseを持つ。Clientは並行実行でき、Transport実装は複数のexchangeを一つのconnection上でmultiplexできる。ただし、WIPは複数のinteractionを包む共通request / response envelope、transaction、共通snapshot、request間のdata dependencyを定義しない。
|
|
|
|
## Effective Worldspace view
|
|
|
|
同じHostでも、endpoint、認証主体、tenant、capability、その他のdeployment contextに応じて、異なるClient-facing Worldspaceを公開できる。
|
|
|
|
Clientは、異なるeffective Worldspace viewのObject observation、Interface observation、validator、Known Spaceを混在させない。Connectionを再利用したりexchangeをmultiplexしたりする場合も、この分離を失ってはならない。
|
|
|
|
Viewを確立するためのauthentication方式と通信securityは、Transport実装とdeploymentが選択する。WIPはこれらを標準化しない。
|
|
|
|
## Protocol failureとTransport failure
|
|
|
|
Hostがlogical interactionを受理したうえで返す`ProtocolError`がProtocol failureである。Transport Bindingは、そのerrorを機械可読なwire representationへ対応付ける。
|
|
|
|
一方、次のfailureはProtocol failureではない。
|
|
|
|
- Endpointまたはrouteへ到達できない。
|
|
- Transport implementationまたはdeploymentがrequestを拒否する。
|
|
- Unsupportedなmedia type、framing、content coding、Transport version。
|
|
- Connection loss、timeout、response不達。
|
|
- Intermediaryが生成した、validなProtocol error representationを持たないfailure。
|
|
- Clientがresponseを受信またはdecodeできない。
|
|
|
|
ClientはTransport failureから`ProtocolErrorCode`を推測しない。Transport authentication failureを`PermissionDenied`へ、未知routeを`NotFound`へ、timeoutを`Internal`または`OperationOutcomeUnknown`へ変換しない。
|
|
|
|
`OperationOutcomeUnknown`も、Hostが返すProtocol failureの一つである。Response不達によってClientがOperation outcomeを確定できない場合はTransport failureとして扱い、Hostから同codeを受信したことにはしない。
|
|
|
|
## Dispatchとreplay
|
|
|
|
Transport Bindingは、physical exchangeを再送することで、一つのlogical `call_operation`を複数回dispatchしてはならない。
|
|
|
|
RequestがHostへdispatchされた可能性があり、responseを取得できなかった場合、Clientは`call_operation`を自動再実行しない。Connection close、timeout、local cancellationが起きても、Host上の実行やcommitが取り消された証拠にはならない。
|
|
|
|
取得interactionの再送とtimeout・retry policyは、ClientとTransport実装が決定する。取得用のpolicyを`call_operation`へ適用しない。
|
|
|
|
## Validator
|
|
|
|
Object validatorとInterface validatorは、Protocol structのlogical fieldである。Bindingはこれらをlosslessにencodeする。
|
|
|
|
Transport固有のcache validator、conditional request metadata、message identifier等は、WIP validatorとは独立している。これらのmetadataがあってもProtocol bodyのvalidatorを省略せず、ClientもTransport metadataをWIP validatorとして解釈しない。
|
|
|
|
## Transport運用との境界
|
|
|
|
通信scheme、TLS、peer authentication、proxy、gateway、HTTP cache、compression、connection管理、message size、timeout、concurrency、rate limit等は、Transport実装またはdeploymentが設定・運用する。WIPはそれらの値、negotiation、運用profileを定義しない。
|
|
|
|
これらの設定によってrequestやresponseを交換できない場合は、Transport failureとなる。HTTP status等がProtocol errorのcanonical mappingと偶然一致しても、validなProtocol error representationを受信しない限り、Protocol failureへ変換しない。
|
|
|
|
これに対し、WIPのlogical struct、observation completeness、TypeExpr / Value、Host execution等に対する`ResourceLimitExceeded`は[3. Protocol](3-protocol.md)に従う。Transport implementation自身のmessage-size、timeout、queue、connection等の上限を、同codeで包まない。
|
|
|
|
## Versioning
|
|
|
|
各Bindingは、wire互換性に影響するmajor versionの選択方法を定義する。異なるmajor version間で、route、message、fieldを推測して変換しない。
|
|
|
|
ProtocolまたはInterface Descriptorのversionは、Transport Bindingのversionとは別に扱う。Transport major versionが同じ場合も、Interface Descriptorの`format`を独立して検証する。
|