5.9 KiB
5. Transport Bindings
WIP Transport Bindingは、3. Protocolで定義するlogical data modelとCore interactionを、具体的な通信方式とwire representationへ対応付ける。
標準bindingの定義は5.1. WIP over HTTPにある。
責務
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に従う。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を独立して検証する。