docs: define HTTPS and error semantics
This commit is contained in:
+1
-1
@@ -106,7 +106,7 @@ Objectは、同じ主体に公開された一つのWorldspace内でObjectの同
|
||||
4. 同じObjectへ条件付きで操作する場合、Clientは`path`とObjectの`validator`をtargetとしてHostへ渡す。
|
||||
5. Hostは現在のvalidatorとの一致確認とOperation実行をatomicに行う。
|
||||
|
||||
ValidatorはClientとHostの間で扱い、AIやユーザーに直接管理させない。Transport Bindingは、同じlogical semanticsを保つ形でHTTP ETag等へ対応付けてよい。
|
||||
ValidatorはClientとHostの間で扱い、AIやユーザーに直接管理させない。Transport Bindingはvalidatorを対応するProtocol fieldとして保持し、HTTP ETag等のrepresentation metadataで置き換えない。
|
||||
|
||||
Validatorが一致しない場合、Clientは現在のObjectに対してOperationを自動的に再試行してはならない。Hostは`validator_mismatch`を返し、Clientは再観測を要求する。
|
||||
|
||||
|
||||
+8
-3
@@ -129,7 +129,7 @@ Object validator、Interface membership、Interface validator、Descriptor、Ope
|
||||
|
||||
Argumentsに未知のfieldがある場合、必須parameterがない場合、またはvalueが宣言型に一致しない場合、HostはOperationを実行せず`invalid_arguments`を返す。
|
||||
|
||||
ClientはHostから受け取ったresultをreturn typeに従って検証する。Hostが宣言と異なるresultを返した場合は`invalid_result`として扱い、そのvalueをApplicationへ渡さない。
|
||||
ClientはHostから受け取ったsuccess responseのresultをreturn typeに従って検証する。Hostが宣言と異なるresultを返した場合はHostが返したProtocol failureではなく`InvalidResponse`として扱い、そのvalueをApplicationへ渡さない。Host Runtimeがinvalidなimplementation resultを送信前に検出した場合は、effectがcommitされていないと保証できるときだけ`Internal`を返し、保証できない場合は`OperationOutcomeUnknown`を返す。
|
||||
|
||||
## Application data
|
||||
|
||||
@@ -166,7 +166,7 @@ Operationがpathを返したこと自体から、実行対象との間に親子
|
||||
|
||||
## Protocol failureとdomain failure
|
||||
|
||||
Protocol failureは、WIPのrequest、対象、Interface、validation、validatorによる条件付き実行に関する失敗である。
|
||||
Protocol failureは、WIPのrequest、対象、Interface、validation、validatorによる条件付き実行、Host executionに関する失敗である。
|
||||
|
||||
- `invalid_request`
|
||||
- `not_found`
|
||||
@@ -176,11 +176,16 @@ Protocol failureは、WIPのrequest、対象、Interface、validation、validato
|
||||
- `interface_validator_mismatch`
|
||||
- `operation_not_found`
|
||||
- `invalid_arguments`
|
||||
- `invalid_result`
|
||||
- `validator_required`
|
||||
- `validator_mismatch`
|
||||
- `permission_denied`
|
||||
- `resource_limit_exceeded`
|
||||
- `internal`
|
||||
- `operation_outcome_unknown`
|
||||
|
||||
`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固有の照会手段を利用する。
|
||||
|
||||
Domain failureは、型として正しいOperationをApplicationが実行した結果として生じる失敗である。
|
||||
|
||||
|
||||
+58
-11
@@ -121,7 +121,7 @@ Objectが何を表すかを説明する短い公開情報。Objectの本文やAp
|
||||
Objectで利用できるOperationを定義するInterface Descriptorへの参照を、Hostの立項順で保持するordered set。
|
||||
|
||||
- 集合は空でもよい。
|
||||
- 同じInterface参照を重複して含めてはならない。Clientは重複を含むObject responseを`InvalidResult`として扱う。
|
||||
- 同じInterface参照を重複して含めてはならない。Clientは重複を含むObject responseをHostから返されたProtocol failureではなく`InvalidResponse`として扱う。
|
||||
- Membershipはset semanticsを持ち、列挙順はOperation解決、validation、authorizationへ影響しない。
|
||||
- Clientは列挙順をInterfaceおよびOperationのUI表示順として使用してよい。
|
||||
- Operation callは集合から一つのInterface参照を明示する。
|
||||
@@ -373,6 +373,16 @@ Valueは、Operation declarationのTypeExprと照合して検証する。
|
||||
- `Entry`として宣言されたStringがcanonical pathであることを検証する。
|
||||
- Integerの相互運用範囲とNumberの有限性を検証する。
|
||||
|
||||
## Core request validation
|
||||
|
||||
Transport Bindingがframing、media type、authentication等を受理した後、Hostはinteraction固有のObject / Interface解決より前にlogical requestを検証する。
|
||||
|
||||
1. Request structとして解釈できない、required fieldがない、未知fieldがある、Path等のfield semanticsに違反する場合は`InvalidRequest`。
|
||||
2. Field長、nesting、collection件数、`fetch_tree`のdepth / limit等がHostのboundedな上限を超える場合は`ResourceLimitExceeded`。
|
||||
3. 検証済みrequestについて、各interaction固有のtarget resolutionとpreconditionを評価する。
|
||||
|
||||
`InvalidArguments`は`call_operation` request自体がvalidであり、固定したOperation declarationに対して`arguments`が適合しない場合だけに使用する。Transport route、authentication、media type、framing等のfailureはCore interactionのProtocol failureではない。
|
||||
|
||||
## `fetch`
|
||||
|
||||
一つのpathで現在公開されているObjectを取得する。
|
||||
@@ -385,7 +395,7 @@ struct FetchRequest {
|
||||
type FetchResponse = Object;
|
||||
```
|
||||
|
||||
Requestの`path`はresponseに重複して含めない。Root path `/`ではObjectの`name`が空文字列でなければならず、非root pathでは最後のsegmentとObjectの`name`が一致しなければならない。Clientは一致しないresponseを`InvalidResult`として扱う。
|
||||
Requestの`path`はresponseに重複して含めない。Root path `/`ではObjectの`name`が空文字列でなければならず、非root pathでは最後のsegmentとObjectの`name`が一致しなければならない。Clientは一致しないresponseを`InvalidResponse`として扱う。
|
||||
|
||||
指定pathのObjectがその主体のClient-facing Worldspaceへ公開されていない場合、Host内部での存在理由にかかわらず`NotFound`を返す。`fetch`はObject取得の認可失敗として`PermissionDenied`を返さない。Objectを返すこと自体が、そのpathとObjectの公開情報を主体へ認識させるためである。
|
||||
|
||||
@@ -427,7 +437,7 @@ struct FetchTreeResponse {
|
||||
|
||||
各nodeのObjectがvalidatorを持つため、Clientはrequest pathとObjectの`name`から各pathを導出し、Treeから発見したObjectを再度`fetch`せずに条件付きOperationのtargetを構築できる。
|
||||
|
||||
`limit`は1以上とする。Hostはdepthとlimitへ実装上の上限を設定し、超過したrequestには`ResourceLimitExceeded`を返す。
|
||||
`limit`は1以上とし、`0`は`InvalidRequest`とする。Hostはdepthとlimitへ実装上の上限を設定し、有効範囲内だが上限を超えたrequestには`ResourceLimitExceeded`を返す。
|
||||
|
||||
## `fetch_interface`
|
||||
|
||||
@@ -473,11 +483,13 @@ Clientは次を検証する。
|
||||
- Descriptorの`format`がClientの対応するversionである。
|
||||
- 同じInterface参照と同じvalidator valueを持つ既存cache entryがある場合、validatorが存在する観測ではDescriptorがそのentryと一致する。
|
||||
|
||||
ResponseまたはDescriptorがProtocol contractに違反する場合、ClientはHostが返したProtocol failureではなく`InvalidResponse`として扱う。Descriptorが構造的にはvalidだが、その`format`をClientが実装していない場合は`UnsupportedDescriptorFormat`として扱い、`InvalidResponse`と混在させない。
|
||||
|
||||
Clientはvalidatorが存在するInterface observationを、`(interface, validator)`の組でcacheする。Interface参照ごとに最後に成功した観測を現在のcache entryとしてよいが、実行中のOperationが参照する観測はresponseのvalidationが完了するまで保持する。
|
||||
|
||||
- 同じInterface参照でvalidatorが異なる場合は、同じInterfaceの新しい状態としてlatest observationを更新する。
|
||||
- Validatorが存在しないInterface参照はimmutableなDescriptorとして、Interface参照だけをcache keyに使用できる。
|
||||
- 同じInterface参照と同じvalidator valueで異なるDescriptorを受け取った場合は`InvalidResult`として扱い、そのDescriptorをOperationへ使用しない。
|
||||
- 同じInterface参照と同じvalidator valueで異なるDescriptorを受け取った場合は`InvalidResponse`として扱い、そのDescriptorをOperationへ使用しない。
|
||||
- 新しい観測を得ても、異なるvalidatorを使用して実行中のrequestに必要なDescriptorをresponse validation前に破棄しない。
|
||||
|
||||
`fetch_interface`は現在のDescriptorを観測するinteractionであり、requestにvalidatorを含めない。Responseにvalidatorが存在する場合、Clientは後続の`call_operation`で、そのDescriptorに基づくOperation実行の必須preconditionとして使用する。Responseにvalidatorが存在しない場合、そのInterface参照のDescriptorはimmutableであり、`call_operation`の`interface.validator`を省略する。
|
||||
@@ -542,7 +554,9 @@ Validatorの比較はopaque bytesの完全一致で行う。Clientはvalidator
|
||||
|
||||
HostはOperationをInterfaceから除外して存在を非公開にすることも、Interfaceへ含めたうえで実行時に`PermissionDenied`として拒否することもできる。
|
||||
|
||||
Clientはresultを、requestの`interface`が指定し、Hostがpreconditionを確認して固定したOperation return typeに従って検証する。Validationに失敗したvalueをApplicationへ渡さない。
|
||||
Clientはresultを、requestの`interface`が指定し、Hostがpreconditionを確認して固定したOperation return typeに従って検証する。Validationに失敗したsuccess responseはHostから返されたProtocol failureではなく`InvalidResponse`として扱い、そのvalueをApplicationへ渡さない。
|
||||
|
||||
Host Runtimeがimplementation resultのencodeまたはvalidation failureを送信前に検出し、Operationのeffectがcommitされていないと保証できる場合は`Internal`を返す。Operationが未実行またはrollback済みであることを保証できず、validなsuccess responseも返せない場合は`OperationOutcomeUnknown`を返す。
|
||||
|
||||
## Protocol responseとfailure
|
||||
|
||||
@@ -566,7 +580,6 @@ enum ProtocolErrorCode {
|
||||
InterfaceMismatch,
|
||||
OperationNotFound,
|
||||
InvalidArguments,
|
||||
InvalidResult,
|
||||
ValidatorRequired,
|
||||
ValidatorMismatch,
|
||||
InterfaceValidatorRequired,
|
||||
@@ -574,24 +587,56 @@ enum ProtocolErrorCode {
|
||||
PermissionDenied,
|
||||
ResourceLimitExceeded,
|
||||
Internal,
|
||||
OperationOutcomeUnknown,
|
||||
}
|
||||
```
|
||||
|
||||
`message`は人間向けのboundedな診断であり、Clientが分岐に使用する安定した値ではない。Clientは`code`を使用する。
|
||||
`message`は人間向けのboundedな診断であり、Clientが分岐に使用する安定した値ではない。Clientは`code`を使用する。Hostは秘密情報、非公開Object、backend path、credential、内部stack traceをmessageへ含めない。
|
||||
|
||||
Validator関連errorの回復対象は次のとおりである。
|
||||
各interactionが返してよいcodeは次に限定する。
|
||||
|
||||
| Code | `fetch` | `fetch_tree` | `fetch_interface` | `call_operation` |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `InvalidRequest` | ✓ | ✓ | ✓ | ✓ |
|
||||
| `ResourceLimitExceeded` | ✓ | ✓ | ✓ | ✓ |
|
||||
| `NotFound` | ✓ | ✓ | — | ✓ |
|
||||
| `InterfaceNotFound` | — | — | ✓ | — |
|
||||
| `InterfaceMismatch` | — | — | — | ✓ |
|
||||
| `InterfaceValidatorRequired` | — | — | — | ✓ |
|
||||
| `InterfaceValidatorMismatch` | — | — | — | ✓ |
|
||||
| `OperationNotFound` | — | — | — | ✓ |
|
||||
| `ValidatorRequired` | — | — | — | ✓ |
|
||||
| `ValidatorMismatch` | — | — | — | ✓ |
|
||||
| `InvalidArguments` | — | — | — | ✓ |
|
||||
| `PermissionDenied` | — | — | — | ✓ |
|
||||
| `Internal` | ✓ | ✓ | ✓ | ✓ |
|
||||
| `OperationOutcomeUnknown` | — | — | — | ✓ |
|
||||
|
||||
Hostがinteractionに許可されていないcodeを返した場合、Clientはそのerror responseを`InvalidResponse`として扱う。
|
||||
|
||||
Validatorおよび観測関連errorの回復対象は次のとおりである。
|
||||
|
||||
- `NotFound`では、Clientは対象Entryをstaleとして扱い、必要に応じて親Treeを再観測する。
|
||||
- `InterfaceNotFound`では、ClientはそのInterface observationを使用せず、参照元Objectを再観測できる。
|
||||
- `ValidatorRequired`または`ValidatorMismatch`では、Clientは対象Objectを再観測してから、ユーザーまたはApplicationの判断なしにOperationを自動再実行してはならない。
|
||||
- `InterfaceMismatch`では、Clientは対象Objectを再観測し、現在公開されているInterface参照の集合を取得する。
|
||||
- `InterfaceValidatorRequired`または`InterfaceValidatorMismatch`では、Clientは同じInterface参照を`fetch_interface`で再観測してから、現在のDescriptorに基づいてOperationを再構築する。ユーザーまたはApplicationの判断なしにOperationを自動再実行してはならない。
|
||||
- `InvalidRequest`または`InvalidArguments`では、Clientは同じrequestを変更せずに再送しない。
|
||||
- `ResourceLimitExceeded`では、Clientはrequest size、depth、limit等を削減できるが、`call_operation`を自動再実行しない。
|
||||
|
||||
`call_operation`が`OperationOutcomeUnknown`以外のProtocol failureを返した場合、HostはOperationのeffectがcommitされていないことを保証する。`OperationOutcomeUnknown`は、HostがOperationの未実行またはrollbackを保証できず、validなsuccess responseも返せないことを示す。Clientは対象Objectをstaleとして扱い、Operationを自動再実行せず、再観測またはdomain固有の照会手段を利用者へ提示する。
|
||||
|
||||
`Internal`はHost内部のfailureであり、`call_operation`ではeffectがcommitされていないと保証できる場合だけ返す。Clientは`Internal`を理由にOperationを自動再実行しない。Transport timeoutやconnection lossでresponse自体を受け取れない場合もOperation outcomeは不明になり得るが、それはProtocol failureではなくTransport failureとして扱う。
|
||||
|
||||
Objectを主体へ公開しない場合、HostはそのObjectをClient-facing Worldspaceに存在しないものとして扱い、`fetch`、`fetch_tree`、`call_operation`へ`NotFound`を返す。Objectの存在を秘匿する目的で`PermissionDenied`を返してはならない。
|
||||
|
||||
`PermissionDenied`は、現在公開されているInterfaceに宣言されたOperationについて、その存在を公開しつつ実行を認めない場合に使用する。Operation自体をInterfaceから除外している場合は`OperationNotFound`を返す。
|
||||
`PermissionDenied`は、現在公開されているInterfaceに宣言されたOperationについて、その存在を公開しつつ実行を認めない場合に使用する。Operation自体をInterfaceから除外している場合は`OperationNotFound`を返す。Operation argumentが参照するdomain resourceの不存在やbusiness rule failureを、対象Objectの`NotFound`へ変換しない。
|
||||
|
||||
`InvalidResponse`と`UnsupportedDescriptorFormat`はClient-localなclassificationであり、`ProtocolErrorCode`ではない。前者はsuccess responseまたはerror responseがProtocol contractに違反した場合、後者はvalidなDescriptor formatをClientが実装していない場合に使用する。
|
||||
|
||||
Protocol failureとdomain failureを混在させない。現在のProtocolでは、Domain failureをApplicationのOperation resultに含まれるUnion caseとして明示する。専用のfailure envelopeは定義しない。
|
||||
|
||||
Transport BindingはProtocol Resultをstatus code、response envelope、stream termination等へ対応付ける。
|
||||
Transport BindingはProtocol Resultをstatus code、response envelope、stream termination等へ対応付ける。Authentication、route、media type、framing、response不達等のTransport failureをProtocol errorへ変換しない。
|
||||
|
||||
## Resource limit
|
||||
|
||||
@@ -606,7 +651,9 @@ HostとClientは、untrusted inputによるresource exhaustionを避けるため
|
||||
- `fetch_tree`のdepthとlimit。
|
||||
- Protocol error messageの長さ。
|
||||
|
||||
各実装はこれらにboundedな上限を設定する。上限を超えたrequestまたはresponseは`ResourceLimitExceeded`として扱い、現在のProtocolではlimit negotiationを定義しない。
|
||||
各実装はこれらにboundedな上限を設定する。上限を超えたrequestは、interaction固有のtarget resolutionまたはOperation dispatchより前に`ResourceLimitExceeded`として拒否する。Hostがread-only responseを構築する途中で上限超過を検出した場合も、success responseの代わりに`ResourceLimitExceeded`を返してよい。
|
||||
|
||||
`call_operation`では、dispatch後にresult size、encoding、backend budget等の問題を検出しても、effectがcommitされていないと保証できる場合だけ`ResourceLimitExceeded`または`Internal`を返す。未実行またはrollbackを保証できない場合は`OperationOutcomeUnknown`とする。Client側のresponse byte limit超過やresponse不達はProtocol failureへ変換せず、Transport failureとして扱う。現在のProtocolではlimit negotiationを定義しない。
|
||||
|
||||
## Batch
|
||||
|
||||
|
||||
+20
-3
@@ -53,9 +53,9 @@ struct CachedEntry {
|
||||
- Entry Treeはpathと親子関係を保持し、Object storeはObjectの現在状態を保持する。
|
||||
- 同じObjectを複数のEntryが参照しても、Object stateをEntryごとに複製しない。
|
||||
|
||||
Objectの`interfaces`はmembershipをsetとして扱い、同じ参照の重複を`invalid_result`として拒否する。ClientはHostの立項順をCachedObjectへ保持し、InterfaceやOperationの表示順に使用してよい。
|
||||
Objectの`interfaces`はmembershipをsetとして扱い、同じ参照の重複を`InvalidResponse`として拒否する。ClientはHostの立項順をCachedObjectへ保持し、InterfaceやOperationの表示順に使用してよい。
|
||||
|
||||
同じ`ref`と同じvalidator valueを持つObjectを再観測したとき、validatorが存在するにもかかわらずObject representationが異なる場合、Clientはresponseを`invalid_result`として扱う。同じ`ref`でvalidatorが異なる場合、またはvalidatorが存在しない場合は、同一Objectの新しい観測として最後に成功した観測でCachedObjectを更新する。
|
||||
同じ`ref`と同じvalidator valueを持つObjectを再観測したとき、validatorが存在するにもかかわらずObject representationが異なる場合、Clientはresponseを`InvalidResponse`として扱う。同じ`ref`でvalidatorが異なる場合、またはvalidatorが存在しない場合は、同一Objectの新しい観測として最後に成功した観測でCachedObjectを更新する。
|
||||
|
||||
このnormalizeはClientのcache実装であり、Objectと別のWIP resourceまたはProtocol上のEntry resourceを導入するものではない。
|
||||
|
||||
@@ -122,7 +122,7 @@ Backend UIDが適している場合、Hostはそれを直接または変換し
|
||||
|
||||
Clientは、エントリを観測した後にOperationを実行するまでの間に、そのエントリが別Objectを指すようになっていないことを検証する責務を持つ。
|
||||
|
||||
Objectが`validator`を持つ場合、Clientは観測したpathとvalidatorを対応付ける。条件付きOperationでは両者をtargetとしてHostへ渡し、validatorの比較と実行をHost上でatomicに行わせる。ValidatorはAIやユーザーに直接管理させない。HTTPS Bindingは、semanticsが適合する場合にHTTP ETag等へ対応付けてよい。
|
||||
Objectが`validator`を持つ場合、Clientは観測したpathとvalidatorを対応付ける。条件付きOperationでは両者をtargetとしてHostへ渡し、validatorの比較と実行をHost上でatomicに行わせる。ValidatorはAIやユーザーに直接管理させず、Transport BindingでもProtocol struct上のfieldとして保持する。HTTP ETag等のrepresentation metadataをWIP validatorの代用として解釈しない。
|
||||
|
||||
ClientはOperationに選択したInterface参照と、`fetch_interface`で観測したoptionalなInterface validatorもrequestへ含める。MutableなInterfaceがvalidatorを返す場合は必須preconditionとして使用し、`InterfaceValidatorMismatch`ではInterfaceだけを再観測する。`InterfaceMismatch`ではObjectを再観測し、現在のInterface集合を取得する。いずれの場合もOperationを自動再試行しない。
|
||||
|
||||
@@ -130,6 +130,23 @@ Operation responseが新しいObject validatorを返した場合、Clientは対
|
||||
|
||||
対象が変化していた場合、Clientは新しいObjectに対してOperationを自動再試行せず、対象が変化したことを上位インターフェースへ通知して再観測を要求する。
|
||||
|
||||
## Failure handling
|
||||
|
||||
ClientはHostが返すProtocol errorの`code`で回復actionを決定し、人間向け`message`やTransport statusからcodeを推測しない。各interactionで許可されていないcode、schemaに違反するsuccess / error response、同じvalidatorに矛盾するrepresentationは`InvalidResponse`として拒否する。Validだが未対応のInterface Descriptor formatは`UnsupportedDescriptorFormat`として区別する。
|
||||
|
||||
- `NotFound`では対象Entryをstaleとして扱い、必要に応じて親Treeを再観測する。
|
||||
- `InterfaceNotFound`では参照元Objectを再観測できる。
|
||||
- `InterfaceMismatch`では対象Objectを再観測する。
|
||||
- `InterfaceValidatorRequired`または`InterfaceValidatorMismatch`では対象Interfaceを再観測する。
|
||||
- `ValidatorRequired`または`ValidatorMismatch`では対象Objectを再観測する。
|
||||
- `InvalidRequest`または`InvalidArguments`では同じrequestを変更せずに再送しない。
|
||||
- `ResourceLimitExceeded`ではrequest size、depth、limit等を削減できるが、Operationを自動再実行しない。
|
||||
- `PermissionDenied`では公開済みOperationが実行拒否されたことを示し、Object自体が閲覧禁止で存在するとは推測しない。
|
||||
|
||||
`OperationOutcomeUnknown`では、Operationが未実行またはrollback済みであることが保証されない。ClientはOperationを自動再実行せず、対象Objectをstaleとして再観測するか、domain固有の照会手段を提示する。`Internal`、Transport timeout、connection lossの場合も、Effect annotationがない現在のProtocolではOperationを自動再実行しない。Response不達はProtocol errorへ変換せず、Transport failureとOperation outcomeが不明な状態をClient内部で保持する。
|
||||
|
||||
HTTP authentication failureとWorldspace endpoint全体のaccess denialはTransport layerのfailureであり、WIPの`PermissionDenied`へ変換しない。
|
||||
|
||||
## 想定実装
|
||||
|
||||
Clientは用途に応じて複数の上位インターフェースを提供できる。
|
||||
|
||||
@@ -231,7 +231,9 @@ Host APIは、backend transaction、lock、revision付きconditional update、fi
|
||||
- Child enumeration、backend lookup、descriptor生成、Value変換へboundedなresource limitを適用できる。
|
||||
- `fetch_tree`の`depth`と`limit`をProvider側の無制限列挙へ変換しない。
|
||||
- Client disconnect、timeout、Host shutdown等に応じてbackend処理へcancellationを伝播できる。
|
||||
- Side effectを持つOperationでは、cancellationやtimeoutを未実行またはrollback済みの証明として扱わず、実行結果が不明なcallをHost Runtimeが自動retryしない。
|
||||
- `call_operation`をdispatchする前にresource limitへ達した場合は`ResourceLimitExceeded`として拒否し、Operationを実行しない。
|
||||
- Dispatch後のcancellation、timeout、implementation failure、result encoding failureについて、Operationが未実行またはrollback済みであると保証できる場合だけ`Internal`または`ResourceLimitExceeded`を返す。保証できない場合は`OperationOutcomeUnknown`を返す。
|
||||
- Side effectを持つOperationでは、cancellationやtimeoutを未実行またはrollback済みの証明として扱わず、Host RuntimeもClientも実行結果が不明なcallを自動retryしない。
|
||||
- Partial backend failureをProtocol上の成功Treeへ黙って変換しない。
|
||||
|
||||
### RustとTypeScriptで同じsemanticsを表現できること
|
||||
|
||||
@@ -428,15 +428,16 @@ Operation argumentとして`Entry` pathを受け取った場合も、pathの所
|
||||
|
||||
## Error model
|
||||
|
||||
Rust methodのerror表現は、次の三種類を区別できなければならない。
|
||||
Rust methodのerror表現は、次の四種類を区別できなければならない。
|
||||
|
||||
- Protocol validationまたはdispatch failure。
|
||||
- Host / backend implementation failure。
|
||||
- Effectがcommitされていないと保証できるHost / backend implementation failure。
|
||||
- Operationの未実行またはrollbackを保証できない`OperationOutcomeUnknown`。
|
||||
- Interfaceがreturn typeとして宣言したdomain failure。
|
||||
|
||||
現在のProtocolでは、domain failureはOperation resultのUnion caseとして表す。Rustの`Result<T, E>`をdomain Union、Host error、または両方のどれへ対応付けるかは未決定である。
|
||||
|
||||
MacroがRust panicをdomain failureへ自動変換してはならない。Panic isolationと`Internal`へのmappingはHost Runtimeの実装要件として別途決定する。
|
||||
MacroがRust panic、result encode failure、宣言型に違反するimplementation resultをdomain failureへ自動変換してはならない。Host Runtimeは、effectがcommitされていないと保証できる場合だけ`Internal`へmappingし、保証できない場合は`OperationOutcomeUnknown`へmappingする。Clientへ送信済みか不明なtransport切断も自動retryしない。
|
||||
|
||||
## 要件
|
||||
|
||||
@@ -461,7 +462,8 @@ Rust API modelは少なくとも次を満たす。
|
||||
- Object validatorを現在のObject identityと保護対象状態へ結び付け、別Objectに同じprovider-local revisionがあっても一致させない。
|
||||
- Object validator比較、identity confirmation、Interface membershipとvalidator比較、DescriptorとOperation実装の固定、authorization、Operation実行を同じatomic boundaryで行う。
|
||||
- Object validatorを要求するOperationへの省略を`ValidatorRequired`として拒否できる。
|
||||
- Provider、Host Runtime、macro-generated codeのerrorをProtocolErrorへ安全に対応付けられる。
|
||||
- Provider、Host Runtime、macro-generated codeのerrorを、effect未commitを保証できる`Internal`と、保証できない`OperationOutcomeUnknown`へ安全に対応付けられる。
|
||||
- InvalidなObject、Descriptor、Operation resultをsuccess responseとして送信せず、Host-side validation failureをdomain failureへ変換しない。
|
||||
- Rust SDK固有の型やlifetimeをProtocol semanticsとして要求しない。
|
||||
|
||||
## 非目標
|
||||
|
||||
@@ -590,15 +590,16 @@ Operation argumentとして`Entry` pathを受け取った場合も、pathの所
|
||||
|
||||
## Error model
|
||||
|
||||
TypeScript methodのerror表現は、次の三種類を区別できなければならない。
|
||||
TypeScript methodのerror表現は、次の四種類を区別できなければならない。
|
||||
|
||||
- Protocol validationまたはdispatch failure。
|
||||
- Host / backend implementation failure。
|
||||
- Effectがcommitされていないと保証できるHost / backend implementation failure。
|
||||
- Operationの未実行またはrollbackを保証できない`OperationOutcomeUnknown`。
|
||||
- Interfaceがreturn typeとして宣言したdomain failure。
|
||||
|
||||
現在のProtocolでは、domain failureはOperation resultのUnion caseとして表す。Thrown value、rejected Promise、explicit result objectをHost errorまたはdomain resultへどう対応付けるかは未決定である。
|
||||
現在のProtocolでは、domain failureはOperation resultのUnion caseとして表す。Thrown value、rejected Promise、explicit result objectをdomain resultまたはHost errorへどう対応付けるかは、Interface authoring APIで明示しなければならない。
|
||||
|
||||
Arbitrary thrown valueをdomain failureへ自動変換してはならない。`Error`以外のthrow、Promise rejection、panicに相当するfatal conditionのisolationと`Internal`へのmappingはHost Runtimeの実装要件として別途決定する。
|
||||
Arbitrary thrown value、Promise rejection、result encode failure、宣言型に違反するimplementation resultをdomain failureへ自動変換してはならない。Host Runtimeは、effectがcommitされていないと保証できる場合だけ`Internal`へmappingし、保証できない場合は`OperationOutcomeUnknown`へmappingする。Abortやtransport切断を未実行の証明として扱わず、自動retryしない。
|
||||
|
||||
## Custom transpilerを必須にしない
|
||||
|
||||
@@ -659,7 +660,8 @@ TypeScript API modelは少なくとも次を満たす。
|
||||
- Object validatorを現在のObject identityと保護対象状態へ結び付け、別Objectに同じprovider-local revisionがあっても一致させない。
|
||||
- Object validator比較、identity confirmation、Interface membershipとvalidator比較、DescriptorとInterface-specific implementation bindingの固定、authorization、Operation実行を同じatomic boundaryで行う。
|
||||
- Object validatorを要求するOperationへの省略を`ValidatorRequired`として拒否できる。
|
||||
- Provider、Host Runtime、runtime definition codeのerrorをProtocolErrorへ安全に対応付けられる。
|
||||
- Provider、Host Runtime、runtime definition codeのerrorを、effect未commitを保証できる`Internal`と、保証できない`OperationOutcomeUnknown`へ安全に対応付けられる。
|
||||
- InvalidなObject、Descriptor、Operation resultをsuccess responseとして送信せず、Host-side validation failureをdomain failureへ変換しない。
|
||||
- Custom transpiler、decorator、特定bundlerをHost実装の必須要件にしない。
|
||||
- TypeScript SDK固有の型をProtocol semanticsとして要求しない。
|
||||
|
||||
|
||||
@@ -41,7 +41,5 @@
|
||||
対象: [WIP over HTTPS](wip-over-https.md)
|
||||
|
||||
- Protocol primitive、Object、Interface Descriptor、ValueのJSON encoding。
|
||||
- Protocol failureのHTTP statusとerror body。
|
||||
- Batch件数、request / response byte size、timeoutの上限。
|
||||
- Batch envelope自体が不正な場合のHTTP statusとerror body。
|
||||
- Batch件数、request / response byte size、timeoutの具体的な上限。
|
||||
- Effect annotationを採用した場合に、副作用のない`call_operation`をbatch対象へ加えるか。
|
||||
|
||||
+103
-26
@@ -23,13 +23,71 @@ OperationがWebSocket等のendpointを通常のApplication dataとして返す
|
||||
- `fetch_interface`
|
||||
- `call_operation`
|
||||
|
||||
具体的なHTTP method、endpoint、content type、error mapping、認証方式、validator mapping、batch表現は、このbinding仕様側で定義する。
|
||||
HTTP method、endpoint、content type、success / error response、Protocol errorのHTTP status、validator mapping、authenticationの位置付けは以下で定義する。Batch表現の残る詳細も、このbinding仕様側で定義する。
|
||||
|
||||
## Endpointとroute
|
||||
|
||||
WIP endpointは、一つのWorldspace access surfaceを指すabsolute HTTPS URLである。Endpoint URLのpath prefixはdeploymentが任意に選択できる。Clientはorigin直下や`/wip`等の既定prefixを仮定しない。
|
||||
|
||||
Endpoint URLはqueryとfragmentを持たず、pathが`/`で終わるcanonical formとする。利用者から末尾`/`のないURLを受け付ける実装は、routeを解決する前に`/`を追加してcanonical formへ変換する。
|
||||
|
||||
各routeはendpoint URLをbase URLとして、次のrelative pathをRFC 3986に従って解決する。すべてのinteractionは`POST`を使用する。
|
||||
|
||||
| Interaction | HTTP method | Relative path |
|
||||
| --- | --- | --- |
|
||||
| `fetch` | `POST` | `v1/fetch` |
|
||||
| `fetch_tree` | `POST` | `v1/fetch_tree` |
|
||||
| `fetch_interface` | `POST` | `v1/fetch_interface` |
|
||||
| `call_operation` | `POST` | `v1/call_operation` |
|
||||
| batch | `POST` | `v1/batch` |
|
||||
|
||||
`v1`はWIP over HTTPS Bindingのmajor versionである。Interactionごとに独立したrouteを設定したり、固定suffixを別名へ置き換えたりしない。
|
||||
|
||||
例えば、次のendpointを指定した場合、
|
||||
|
||||
```text
|
||||
https://gateway.example/tenants/acme/proxies/filesystem/wip/
|
||||
```
|
||||
|
||||
`fetch` routeは次になる。
|
||||
|
||||
```text
|
||||
https://gateway.example/tenants/acme/proxies/filesystem/wip/v1/fetch
|
||||
```
|
||||
|
||||
Endpointのpath prefixはHTTP deployment上のroutingであり、Worldspace内のpathではない。Worldspace pathは常に各WIP requestのlogical fieldとして渡す。Hostまたはreverse proxyは異なるbase pathに複数のWorldspaceやproxy surfaceをmountできるが、一つのendpointに属するinteractionはすべて同じbase URL配下へ公開する。
|
||||
|
||||
Clientは異なるcanonical endpoint間でKnown Space、Object observation、Interface cacheを混在させない。同じendpointであっても認証またはsecurity contextによって異なるWorldspaceが見える場合、それらの観測状態を共有しない。
|
||||
|
||||
## HTTP message
|
||||
|
||||
Requestおよびbodyを持つresponseは`Content-Type: application/json`を使用し、JSON textをUTF-8でencodeする。Clientは`Accept: application/json`を送信する。
|
||||
|
||||
WIP routeで受信したbodyがmalformed JSONである、logical request structへdecodeできない、required fieldがない、未知fieldがある、またはfield semanticsに違反する場合、Hostは`400 Bad Request`と`invalid_request` envelopeを返す。Unsupported media typeは`415 Unsupported Media Type`、受理できない`Accept`は`406 Not Acceptable`とし、これらTransport BindingのfailureをProtocol errorへ変換しない。
|
||||
|
||||
単独interactionが成功した場合、Hostは`200 OK`を返し、response bodyへ対応するProtocol responseを直接encodeする。単独interactionのsuccess bodyを`result`等の追加envelopeで包まない。
|
||||
|
||||
Protocol failureの場合、Hostは非2xx statusを返し、response bodyへ後述するProtocol error envelopeをencodeする。HTTP statusは成功と失敗の大分類および既存HTTP infrastructureのための補助情報であり、Protocol failureの機械可読な意味を決定しない。ClientはHTTP status、reason phrase、または人間向けmessageからProtocol error codeや回復actionを推測しない。
|
||||
|
||||
非2xx responseが有効なProtocol error envelopeを含まない場合、Clientは特定のProtocol errorへ変換せず、HTTPまたはTransport Bindingのfailureとして扱う。これにより、reverse proxyやgatewayが生成したresponseをHost由来の`NotFound`、`PermissionDenied`等と誤認しない。
|
||||
|
||||
Clientに再観測、WIP request修正、Operationの権限要求、resource削減等の具体的なactionを求めるProtocol failureは、HTTP statusだけで表さず、対応する`ProtocolErrorCode`としてProtocolに定義する。
|
||||
|
||||
## Authentication
|
||||
|
||||
WIP over HTTPSは特定のauthentication schemeを要求せず、HTTP authentication、mTLS、gateway、reverse proxy等の既存infrastructureを使用できる。AuthenticationはWIP interactionを実行する主体とsecurity contextを確立するTransport / deployment concernであり、WIP Protocolの`ProtocolErrorCode`を追加して表現しない。
|
||||
|
||||
Credentialが欠落または無効でWIP interactionを開始できない場合、HTTP layerは`401 Unauthorized`と、使用するschemeに応じた`WWW-Authenticate`を返してよい。HTTP layerは、特定のWIP endpointが表すWorldspace access surface全体へのaccessを認めない場合に、そのendpointへのrequestを`403 Forbidden`等で拒否してよい。ClientはこれらをProtocol failureへ変換せず、Transport authentication / authorization failureとして扱う。
|
||||
|
||||
HTTP layerによるWorldspace全体のaccess controlを通過してWIP interactionを開始した後は、個別Objectへのaccess拒否を「Objectは存在するが閲覧禁止」という状態として公開しない。その主体へ公開しないObjectはClient-facing Worldspaceに存在しないものとして扱い、`fetch`、`fetch_tree`、`call_operation`では`NotFound`を返す。個別Objectの存在を示唆する`PermissionDenied`や、Protocol error envelopeを持たない`403 Forbidden`へ置き換えない。
|
||||
|
||||
Authentication後に確立された主体に対するInterface / Operation visibilityとOperation authorizationもWIP Protocol semanticsに従う。現在公開されていないInterfaceには`InterfaceNotFound`、現在のInterfaceに宣言されていないOperationには`OperationNotFound`を返す。`PermissionDenied`は、現在公開されているOperationの存在を示したうえで、その主体による実行だけを拒否する場合に使用する。
|
||||
|
||||
## JSON encodingの基本規則
|
||||
|
||||
ProtocolのrecordはJSON object、listはJSON array、optional fieldの省略はJSON fieldの省略としてencodeする。
|
||||
|
||||
Protocol structの`String`はJSON string、`Vec<u8>`はbindingが定めるopaque encodingへ対応付ける。Path、Interface参照、Object identity、名前等の意味はJSON typeではなくfieldの位置によって決まる。
|
||||
Protocol structの`String`はJSON string、`Vec<u8>`はRFC 4648 Section 4のbase64 stringへ対応付ける。Path、Interface参照、Object identity、名前等の意味はJSON typeではなくfieldの位置によって決まる。
|
||||
|
||||
| Field | JSON encoding | 解釈 |
|
||||
| --- | --- | --- |
|
||||
@@ -39,9 +97,9 @@ Protocol structの`String`はJSON string、`Vec<u8>`はbindingが定めるopaque
|
||||
| `interface`、`InterfaceTarget.reference` | string | 一つのInterfaceへのopaqueな参照 |
|
||||
| `format` | string | Descriptor format identifier |
|
||||
| `ref` | string | opaqueなObject identity |
|
||||
| `validator` | base64 stringまたはHTTP metadata | opaqueな条件付き操作用value |
|
||||
| `validator` | RFC 4648 Section 4のbase64 string | opaqueな条件付き操作用value |
|
||||
|
||||
Validatorをresponse bodyのbase64 stringとして運ぶか、HTTP ETag等へ対応付けるかは、このbindingがresponse形態ごとに定める。どちらの場合もClient runtimeは値をopaqueに扱い、AIやユーザーへ直接管理させない。
|
||||
すべてのWIP validatorは、対応するProtocol struct上のfieldとしてJSON bodyへencodeする。HTTP headerへ移したことを理由にbody fieldを省略してはならない。Client runtimeはvalidatorをopaqueに扱い、AIやユーザーへ直接管理させない。
|
||||
|
||||
未知のJSON fieldを許可する箇所はProtocol側で明示する。Object、Interface Descriptor、request / response、Protocol errorの未宣言fieldは既定で拒否する。
|
||||
|
||||
@@ -244,30 +302,17 @@ Payloadを持たないUnionは`value`を省略する。
|
||||
|
||||
ClientはInterface Descriptorに従ってvalueをdecodeし、`entry`と宣言された位置にあるstringだけをエントリとして認識する。通常の`string`やopaqueな`json`に含まれるpathらしいstringをエントリとして推測してはならない。
|
||||
|
||||
## ValidatorとHTTP conditional request
|
||||
## Validatorのencoding
|
||||
|
||||
WIP Protocolのlogical fieldには、ObjectおよびOperation responseのObject `validator`、Operation requestの`target.validator`、`FetchInterfaceResponse.validator`、Operation requestの`interface.validator`がある。Object validatorとInterface validatorは別のpreconditionであり、同じHTTP headerへ曖昧に畳み込まない。
|
||||
WIP Protocolのlogical fieldには、ObjectおよびOperation responseのObject `validator`、Operation requestの`target.validator`、`FetchInterfaceResponse.validator`、Operation requestの`interface.validator`がある。Object validatorとInterface validatorは別のpreconditionであり、それぞれ対応するJSON body fieldへRFC 4648 Section 4のbase64 stringとしてencodeする。
|
||||
|
||||
単独のHTTP request / responseで、WIP validatorがHTTPのstrong validator semanticsを満たす場合、HTTPS Bindingは次へ対応付けてよい。
|
||||
単独request / responseとbatch subrequest / subresponseは同じvalidator表現を使用する。HostはWIP validatorを`ETag`、`If-Match`、その他のHTTP headerだけにencodeしてbody fieldを省略してはならず、ClientはそれらのheaderをWIP validatorとして解釈しない。
|
||||
|
||||
```text
|
||||
Object.validatorまたはCallOperationResponse.validator -> ETag
|
||||
CallOperationRequest.target.validator -> If-Match
|
||||
FetchInterfaceResponse.validator -> ETag on fetch_interface response
|
||||
CallOperationRequest.interface.validator -> request body or dedicated header
|
||||
validator_mismatch -> 412 Precondition Failed
|
||||
validator_required -> 428 Precondition Required
|
||||
interface_validator_mismatch -> 412 Precondition Failed
|
||||
interface_validator_required -> 428 Precondition Required
|
||||
```
|
||||
|
||||
HTTP headerへmappingした場合も、Client adapterは値を対応するProtocol上のObject、Operation response、またはInterface observationへ復元する。Object validatorとInterface validatorの両方がある`call_operation`では、標準`If-Match`だけで二つを表したと推測してはならない。Validatorが対象HTTP response representationの変更を反映しない場合、strong ETagとして使用してはならず、body fieldまたは意味を区別できる専用headerで運ぶ。
|
||||
|
||||
Batchではsubresponseごとにvalidatorが存在し得るため、各Object、Operation response、または`fetch_interface` responseのbody fieldとしてencodeする。
|
||||
Host、gateway、またはHTTP cacheは通常のHTTP representation metadataとして`ETag`等を追加してよいが、その値はWIP validatorとは独立しており、WIPのObject identity、Interface observation、またはOperation preconditionを置き換えない。
|
||||
|
||||
## Protocol error
|
||||
|
||||
Protocol failureをJSON response bodyへ含める場合、概念的に次の形を使用する。
|
||||
Protocol failureは、非2xx HTTP responseのJSON bodyへ次のenvelopeでencodeする。
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -278,9 +323,36 @@ Protocol failureをJSON response bodyへ含める場合、概念的に次の形
|
||||
}
|
||||
```
|
||||
|
||||
`code`はProtocolが定義する安定した識別子、`message`は人間向けのboundedな診断である。Clientは`message`の内容で分岐しない。
|
||||
`code`はProtocolが定義する`ProtocolErrorCode`をsnake_caseへ変換した安定した識別子、`message`は人間向けのboundedな診断である。Clientは`message`の内容で分岐しない。Clientがfailureの種類と回復actionを決定するときは`code`を使用し、HTTP statusだけから`NotFound`、`InterfaceMismatch`、validator failure等を推測しない。
|
||||
|
||||
Protocol error codeとHTTP statusのmapping、およびvalidation errorのstructured detailは未確定である。`not_found`、`interface_mismatch`、`operation_not_found`、`permission_denied`の使い分けと、Object / Interfaceそれぞれのvalidator failureの区別はProtocol semanticsに従い、HTTP statusへのmappingによって変更しない。
|
||||
単独interactionのProtocol error codeを次のHTTP statusへ対応付ける。
|
||||
|
||||
| Protocol error code | HTTP status |
|
||||
| --- | --- |
|
||||
| `invalid_request` | `400 Bad Request` |
|
||||
| `not_found` | `404 Not Found` |
|
||||
| `interface_not_found` | `404 Not Found` |
|
||||
| `interface_mismatch` | `409 Conflict` |
|
||||
| `operation_not_found` | `404 Not Found` |
|
||||
| `invalid_arguments` | `422 Unprocessable Content` |
|
||||
| `validator_required` | `428 Precondition Required` |
|
||||
| `validator_mismatch` | `412 Precondition Failed` |
|
||||
| `interface_validator_required` | `428 Precondition Required` |
|
||||
| `interface_validator_mismatch` | `412 Precondition Failed` |
|
||||
| `permission_denied` | `403 Forbidden` |
|
||||
| `resource_limit_exceeded` | `413 Content Too Large`または`422 Unprocessable Content` |
|
||||
| `internal` | `500 Internal Server Error` |
|
||||
| `operation_outcome_unknown` | `500 Internal Server Error` |
|
||||
|
||||
`resource_limit_exceeded`がrequestまたはresponse representationのbyte size超過を表す場合は`413 Content Too Large`、depth、limit、nesting、collection件数等のlogical limit超過を表す場合は`422 Unprocessable Content`を使用する。Rate limitまたはconcurrency limitによる`429 Too Many Requests`はTransport / deployment concernであり、Core interactionの`resource_limit_exceeded`へ自動変換しない。
|
||||
|
||||
HTTP statusはProtocol error codeを置き換えない。複数のcodeが同じstatusを使用し、同じcodeがresource limitの種類に応じて異なるstatusを使用できる。Hostは上記mappingに従わなければならないが、Clientが非2xx responseからvalidなProtocol error envelopeを取得できた場合、statusがmappingと一致しなくても回復actionは`code`に従い、statusから別のcodeを推測しない。Clientはstatus mismatchをTransport Binding違反として診断してよい。2xx responseのerror envelope、または非2xx responseのsuccess bodyは`InvalidResponse`として扱う。
|
||||
|
||||
`operation_outcome_unknown`はretryを促す`503 Service Unavailable`へmappingしない。Clientは`500`であってもcodeに従い、Operationを自動再実行せず対象をstaleとして扱う。`internal`についてもEffect annotationがない現在のProtocolではOperationを自動再実行しない。
|
||||
|
||||
`InvalidResponse`と`UnsupportedDescriptorFormat`はClient-localなclassificationであり、Hostがerror envelopeで返してはならない。非2xx responseが有効なProtocol error envelopeを含まない場合も、Clientは特定のProtocol errorへ変換せずTransport Binding failureとして扱う。
|
||||
|
||||
Clientに特定の回復actionを求める条件をHTTP statusだけで新設しない。その条件がTransport Binding固有のfailureではなくWIP interactionとして回復可能である場合、対応する`ProtocolErrorCode`をProtocolへ追加してからbindingする。
|
||||
|
||||
Domain failureをProtocol errorへ変換しない。Domain failureはOperation resultのApplication dataとしてencodeする。
|
||||
|
||||
@@ -290,7 +362,7 @@ WIP over HTTPSは、複数の独立したCore取得requestを一つのHTTP reque
|
||||
|
||||
ClientはKnown SpaceとInterface cacheをもとに必要なrequestだけを選択してbatchを構成する。HostはClientの既知状態を推測して、要求されていないObjectやInterface Descriptorをresponseへ追加しない。
|
||||
|
||||
Batch endpointは概念的に`POST {wip-endpoint}/batch`とし、bodyに一意な`id`を持つsubrequestの配列を格納する。
|
||||
Batchは上記の`POST v1/batch` routeを使用し、bodyに一意な`id`を持つsubrequestの配列を格納する。
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -358,10 +430,15 @@ Batchには次の規則を適用する。
|
||||
- 各`result`は対応するProtocol interactionを単独で呼んだ場合と同じvalueとする。
|
||||
- 各`error`は通常のProtocol errorと同じschemaを使用する。
|
||||
- HostはClientが要求していないsubresponseを追加してはならない。
|
||||
- 各subresponseは`result`または`error`の一方だけを持つ。
|
||||
|
||||
初期のbatch形式に格納できるのは`fetch`、`fetch_tree`、`fetch_interface`とし、`call_operation`は含めない。将来Effect annotationを採用する場合に、副作用を持たないと明示されたOperationをbatch対象へ加えるかを改めて検討する。
|
||||
|
||||
Batch件数、request / response byte size、timeoutの上限、およびbatch envelope自体が不正な場合のHTTP statusはbindingの詳細として定める。
|
||||
Batch envelopeがvalidである場合、Hostは一部または全部のsubrequestがProtocol failureでも`200 OK`を返す。各subresponseの`error`は対応するinteractionで許可されたProtocol errorの`code`と`message`を直接含み、itemごとのHTTP statusは持たない。
|
||||
|
||||
`requests`の欠落、duplicate `id`、未知の`method`、subrequest envelope自体のfield違反等によりbatch全体をsubrequest列として解釈できない場合、Hostは`400 Bad Request`とtop-levelの`invalid_request` error envelopeを返す。既知の`method`を持つsubrequestの`arguments`が対応するlogical requestとして不正な場合は、batch全体を拒否せず、その`id`のsubresponseへ`invalid_request`を返す。Batch requestのbyte size超過には`413 Content Too Large`、件数等のlogical limit超過には`422 Unprocessable Content`を使用し、いずれもtop-levelの`resource_limit_exceeded` error envelopeを返す。
|
||||
|
||||
Batch件数、request / response byte size、timeoutの具体的な上限はbindingの運用profileまたはHost configurationでboundedに定める。
|
||||
|
||||
## 非目標
|
||||
|
||||
|
||||
Reference in New Issue
Block a user