Hare/wip-reference
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add Astro reference site and organize book contents
Reference site / build (push) Canceled after 0s
Details

Browse Source
This commit is contained in:
Hare
2026-10-09 23:40:37 +09:00
parent 6086f3c5ef
commit 01c9498e6d
39 changed files with 7772 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
contents/3-protocol.md
+741
View File
@@ -0,0 +1,741 @@
# 3. Protocol
WIP Protocolは、ClientとHostの間で交換するlogical data modelと、Core interactionのrequest / responseを定義する。
この章のstructはRust風の記法を使用するが、Rust固有のmemory layoutやserialization libraryを要求しない。TypeScriptを含む他言語でも同じ型、必須性、validation semanticsを実装できなければならない。
HTTP endpoint、JSON fieldへのencoding、status codeはTransport Bindingの責務とし、共通要件を[5. Transport Bindings](5-transports.md)、標準bindingを[5.1. WIP over HTTP](5.1-wip-over-http.md)で扱う。
## Protocol dataの分類
WIPがfirst-classなprotocol dataとして定義し、Clientが取得およびcacheするものは次の二つである。
- `Object`
- `InterfaceDescriptor`
Operationのargumentsとresultには、Interface Descriptorで宣言された`Value`を使用する。Application dataは独立したWIP resourceではなく、Operation callの入力または出力として交換される。
```text
Protocol data
|-- Object
`-- InterfaceDescriptor
Operation value
|-- arguments
`-- result
```
Path、Object参照、Interface参照、validator、error等の意味は、それらが現れるfieldまたはenvelopeによって決まる。Protocol上のnamed scalarとしては定義しない。
## 記法
この章では次の記法を使用する。
```rust
struct T { ... } // 名前付きfieldを持つrecord
enum T { ... } // 閉じたcaseの集合
Option<T> // 省略可能なfield
Vec<T> // 順序付きlist
BTreeMap<String, T> // string keyを持つlogical map
```
`Option<T>`はfieldの省略を表し、`null`を表さない。Transport Bindingは、省略されたfieldをwire valueへ出力してはならない。
`BTreeMap`はstring-keyed mapをRust風に示すための記法であり、keyのiteration orderをProtocol semanticsには含めない。
## Protocol primitives
Protocol structは、次のprimitiveおよびcompositeだけで表す。
```text
unit
boolean
integer
number
string
bytes
list
record
```
Path、Interface参照、Object identity、validator、Operation名等を独立したProtocol scalarにはしない。同じprimitiveを使用するfieldでも意味は交換可能ではなく、各fieldの定義とvalidation ruleに従って解釈する。
Rust SDKは利便性や安全性のために`Path`等のnewtypeを公開してよく、TypeScript SDKはbrand等を利用してよい。それらは言語別SDKのAPIであり、Protocol structの一部ではない。
## Path
Pathとして宣言されたfieldのvalueは、同じWorldspace内のObjectを取得するためのcanonical absolute pathでなければならない。
- Root pathは`/`とする。
- 非root pathは、rootから対象Objectまでの各`name`を`/`で連結して構成する。
- 空segmentを含めない。
- `.`または`..`であるsegmentを含めない。
- Root以外は末尾に`/`を持たない。
- Pathに含まれる各segmentはUnicode stringとして扱い、Unicode normalizationを行わない。
- Segmentの比較はUnicode code point sequenceの完全一致で行う。
- Navigationに使用できるが、恒久的なObject identityとして使用しない。
Nameに`/`を許可しないため、Protocolはpath segment escapeを定義しない。Transport BindingによるURL encodingはWIP Pathの構成とは別に扱う。
## Interface Reference
Interface参照は、scopeとlocal nameからなるrecordとして表す。新しいfirst-class resourceやnamed scalarではなく、Objectやinteractionが使用する参照のstructである。
```rust
struct InterfaceReference {
scope: String,
name: String,
}
```
- `scope`はClient-facing Worldspaceのrootに基づくcanonical absolute path。上記Pathの規則を適用し、relative path、`.` / `..`、空scopeを認めない。Root scopeは`/`とする。
- `name`はそのscope内のInterfaceを識別する空でないUnicode string。`.`、`::`、`#`等を含んでもfield内の文字として扱い、pathやOperation名へ分解しない。
- 同じWorldspace context内で`scope`と`name`のUnicode code point sequenceがそれぞれ完全一致する場合だけ、同じ参照とする。Normalization、case変換、URL decodeは行わない。
- `Object.interfaces`の重複判定、membership、request / responseの参照一致、Interface cacheのkeyにはこの組を使う。Object member順や短縮表記の引用・escapeの違いは参照の同一性へ影響しない。
- Interface Descriptorはscopeやnameを自身のfieldとして持たない。同じ構造のDescriptorであることから参照の同一性を推測しない。
`Object.interfaces`の各要素、`FetchInterfaceRequest.interface`、`FetchInterfaceResponse.interface`、`InterfaceTarget.reference`はすべてこのstructを使用する。Opaque stringや`scope::name`という連結stringを代替として受理しない。Operation名は`CallOperationRequest.operation`に独立して保持する。
人間・AI向けの短縮表記は[4.2. Text View](4.2-text-view.md#参照表記)に従う。Scope省略形を入力として受けるadapterも、明示されたcontextから絶対scopeを確定してからProtocol requestを構築する。
不正な参照shape、relative scope、空name等はCore request validationで`InvalidRequest`とする。Responseに不正な参照がある場合はClient-localな`InvalidResponse`とする。Validな参照に対応するInterfaceが主体へ公開されているか、対象Objectで使えるかはinteractionごとに検証する。
## Documentation
Interface、Operation、type、field、parameter、caseに付与するdocumentationを次のlogical structで表す。
```rust
struct Documentation {
summary: String,
details: Option<String>,
}
```
`summary`は一覧やInterface signatureへ短く表示する説明、`details`は明示的に展開したときに使用する説明である。
DocumentationはHostが提供するplain text dataであり、Clientのsystem instructionとして信頼しない。Transport BindingおよびClientはresource limitを適用できる。Markup、localization、構造化exampleは現在のProtocolに含めない。
## Object
`Object`は、一つのpathで現在公開されているprotocol-level projectionを表す。
```rust
struct Object {
name: String,
description: Option<String>,
interfaces: Vec<InterfaceReference>,
r#ref: Option<String>,
validator: Option<Vec<u8>>,
}
```
### `name`
親Objectの下でObjectを識別するpath segment。Root Objectの`name`は空文字列とし、非root Objectの`name`は空であってはならない。Nameに`/`を含めてはならず、Name全体が`.`または`..`であってはならない。
NameはUnicode stringとして扱い、Unicode normalizationを行わない。同じ親のchildrenは、Unicode code point sequenceの完全一致で互いに異なる`name`を持たなければならない。
### `description`
Objectが何を表すかを説明する短い公開情報。Objectの本文やApplication data全体を格納するfieldではない。
### `interfaces`
Objectで利用できるOperationを定義するInterface Descriptorへの参照を、Hostの立項順で保持するordered set。
- 集合は空でもよい。
- 同じInterface参照を重複して含めてはならない。Clientは重複を含むObject responseをHostから返されたProtocol failureではなく`InvalidResponse`として扱う。
- Membershipはset semanticsを持ち、列挙順はOperation解決、validation、authorizationへ影響しない。
- Clientは列挙順をInterfaceおよびOperationのUI表示順として使用してよい。
- Operation callは集合から一つのInterface参照を明示する。
異なるInterfaceでは同じOperation名を宣言できる。Protocolでは構造化参照とOperation名を別fieldとして扱い、表示用の短縮表記は[4.2. Text View](4.2-text-view.md#参照表記)に従う。
Hostはvalidatorを発行することで、同じInterface参照のDescriptorを時間とともに変更できる。Validatorを発行しない参照のDescriptorは、その参照が有効な間は変更しない。Clientは`fetch_interface`でDescriptorとvalidatorを一つの観測として取得する。
### `ref`
同じ主体に公開された一つのWorldspace内で、複数の観測またはエントリが同じObjectを表すことを示すoptionalなopaque string。
- 同じ有効な`ref`は同じObjectを表す。
- Hostは同じ有効な`ref`を異なるObjectへ付与してはならない。
- 異なるまたは欠落した`ref`からObjectが異なるとは判断しない。
- 異なるWorldspace間で`ref`を比較しない。
- Session、再接続、Host restart、Worldspace再構築をまたぐ永続性を要求しない。
- Navigationには使用せず、`ref`からObjectを取得するinteractionは提供しない。
Backendに適切なUIDがある場合、Hostはそれを直接または変換して使用できるが、Protocolはbackend UIDの存在または公開を要求しない。
### `validator`
HostがそのObjectの現在状態へ付与するoptionalなopaque bytes。Clientは内容を解釈せず、観測に基づくOperationを条件付きで実行するときに、pathとともに`target.validator`へコピーする。
Hostはvalidatorの生成方法を自由に選べる。Generation、content hash、database revision等を使用してよい。ValidatorはObject identityとHostが保護する現在状態の両方へ結び付け、target pathが別Objectを指す場合は、内容が同じでも一致させてはならない。Content hashを使用する場合はObject identityをhashへ含めるか、Hostがidentityを別途検証する。
Hostは、どの状態変化によってObject validatorを無効にするかについて、そのObjectに対して一貫した方針を適用する。Object validatorはpathに固有ではなく、同じ`ref`を持つObjectの現在状態に付与する。
Object validatorはAIやユーザーへ公開するApplication dataではない。Client runtimeがObject observationとともに保持するprotocol metadataである。
ここでいうObjectの「現在状態」は、Hostがvalidatorによってobservation consistencyを保護する対象を指す。WIP Objectはprotocol-level projectionであり、Application stateを格納する共通containerではない。WIPは状態遷移modelを定義せず、OperationをObject stateに対するread / writeとして分類しない。
### 同じ`ref`を持つObjectの整合性
同じWorldspace内で同じ`ref`を持つObjectは、一つの共有された現在状態を表す。
- 同じ`ref`と同じvalidator valueを持つObjectは、validatorが存在する場合、`name`、`description`、`interfaces`を含む全fieldが一致しなければならない。
- 同じ`ref`と異なるvalidatorを持つObjectは、同一Objectの異なる状態として扱う。
- HostはObjectが配置されたpathを理由に、同じ`ref`へ異なる`name`、`description`、`interfaces`を同時に公開してはならない。
- Clientは最後に成功した観測を、その`ref`を持つObjectの現在状態として扱う。
同じObjectを複数のpathへ配置する場合、各配置は同じObjectの`name`を使用する。異なる親を経由することでpathが異なる。
`Object`はchildrenとpathを直接持たない。これらはObject identityに固有とは限らず、Objectを観測したentryのcontextに属するため、request pathと`ObjectObservation`で表す。
Objectの意味とApplication dataとの境界は[2. Core Model](2-core-model.md)と[2.1. Object tree / Schema](2.1-object-tree-schema.md)で扱う。
## Interface Descriptor
`InterfaceDescriptor`は、実装コード上のInterface Declarationから生成されるmachine-readable metadataである。
```rust
struct InterfaceDescriptor {
format: String,
documentation: Option<Documentation>,
types: Vec<TypeDeclaration>,
operations: Vec<OperationDeclaration>,
}
```
Interface実装者がこのstructのJSON encodingを手書きすることは想定しない。Rust macro、TypeScript definition API、code generator等が生成し、Hostが公開する。
`types`と`operations`のdeclaration順は表示時に保持してよいが、名前解決とvalidationの結果には影響しない。
### Type declaration
```rust
struct TypeDeclaration {
name: String,
documentation: Option<Documentation>,
definition: TypeExpr,
}
```
一つのDescriptor内でType名は一意でなければならない。
### Type expression
```rust
enum TypeExpr {
Unit,
Boolean,
Integer,
Number,
String,
Bytes,
Json,
Entry,
Named {
name: String,
},
Record {
fields: Vec<FieldDeclaration>,
},
List {
items: Box<TypeExpr>,
},
Enum {
cases: Vec<EnumCase>,
},
Union {
cases: Vec<UnionCase>,
},
}
```
`Named`は同じInterface Descriptor内の`TypeDeclaration`を参照する。External type importとrecursive type referenceは定義しない。Descriptorの意味検証では、存在しないTypeへの参照と参照cycleを拒否する。
### Record
```rust
struct FieldDeclaration {
name: String,
required: bool,
documentation: Option<Documentation>,
r#type: TypeExpr,
}
```
一つのRecord内でfield名は一意でなければならない。`required = false`はfieldの省略を許可するが、`null`を許可する意味ではない。
Record valueに未宣言fieldが存在する場合はvalidation failureとする。
### Enum
```rust
struct EnumCase {
name: String,
documentation: Option<Documentation>,
}
```
Enum caseはpayloadを持たない。一つのEnum内でcase名は一意でなければならない。
### Union
```rust
struct UnionCase {
name: String,
documentation: Option<Documentation>,
payload: Option<TypeExpr>,
}
```
Union caseは、caseごとに0個または1個のpayloadを持つ。一つのUnion内でcase名は一意でなければならない。
### Operation declaration
```rust
struct OperationDeclaration {
name: String,
documentation: Option<Documentation>,
parameters: Vec<ParameterDeclaration>,
returns: ReturnDeclaration,
}
struct ParameterDeclaration {
name: String,
required: bool,
documentation: Option<Documentation>,
r#type: TypeExpr,
}
struct ReturnDeclaration {
documentation: Option<Documentation>,
r#type: TypeExpr,
}
```
一つのDescriptor内でOperation名は一意でなければならない。一つのOperation内でparameter名は一意でなければならない。
Interface Descriptorの生成と意味論は[2.2. Operation and Interface](2.2-operation-and-interface.md)、人間とAIへのInterface signatureは[4.2. Text View](4.2-text-view.md)で扱う。
## Value
Operation argumentsとresultは、schema上の意味を持たない次のlogical valueで表す。
```rust
enum Value {
Unit,
Boolean(bool),
Integer(i64),
Number(f64),
String(String),
Bytes(Vec<u8>),
Record(BTreeMap<String, Value>),
List(Vec<Value>),
}
```
`Value`はHostとClientが交換するprimitiveおよびcompositeだけを表す。Path、enum case、union case等のsemantic variantを持たない。既知のInterfaceに対するgenerated bindingは、言語固有DTOと`Value`のcodecを提供できる。
### Primitive semantics
| Value | 意味 | 制約 |
| --- | --- | --- |
| `Unit` | 値を持たない | Optional fieldの省略とは異なる |
| `Boolean` | 真偽値 | — |
| `Integer` | 符号付き整数 | `-9007199254740991`から`9007199254740991`まで |
| `Number` | IEEE 754 binary64 | NaN、正負Infinityを禁止する |
| `String` | Unicode string | — |
| `Bytes` | 任意のoctet列 | Transport Bindingがencodingを定める |
| `Record` | String keyを持つvalueの集合 | Key順に意味を持たない |
| `List` | 順序付きvalue | — |
`integer`の範囲はRustとTypeScript間でlosslessに相互運用できる範囲へ制限する。
`number`を受信したruntimeは、有限値であることを検証する。
### Descriptorによる解釈
Interface Descriptorの`TypeExpr`は、rawな`Value`に意味と追加validationを与える。
| TypeExpr | 対応するValue | 追加の解釈 |
| --- | --- | --- |
| `Unit` | `Value::Unit` | 値を持たないresult等 |
| `Boolean` | `Value::Boolean` | — |
| `Integer` | `Value::Integer` | 相互運用範囲を検証する |
| `Number` | `Value::Number` | 有限値を検証する |
| `String` | `Value::String` | 通常の文字列として扱う |
| `Bytes` | `Value::Bytes` | Octet列として扱う |
| `Json` | JSON data modelで表現可能なValue | 内部構造をWIP schemaとして解釈しない |
| `Entry` | `Value::String` | Canonical absolute Worldspace pathとして検証する |
| `Record` | `Value::Record` | Field declarationに従って検証する |
| `List` | `Value::List` | 各要素をitems typeに従って検証する |
| `Enum` | `Value::String` | 宣言されたcase名として検証する |
| `Union` | `Value::Record` | Discriminatorとpayloadをcase declarationに従って検証する |
`Json`が受け付けるのはJSONのnull、boolean、number、string、array、objectに対応するValueだけであり、`Bytes`は含まない。JSON内の整数と数値にも`Value::Integer`と`Value::Number`と同じ範囲および有限性の制約を適用する。
`Entry`と`String`は同じprimitiveで交換する。ClientはDescriptor上で`Entry`と宣言された位置だけをWorldspace pathとして扱い、通常のStringを内容からEntryへ変換しない。
EnumもString、UnionもRecordとして交換する。SDKまたはruntimeは、Descriptorによるvalidation後の内部表現としてtyped enum、union、Path等を構築してよい。それらはProtocolの送受信形式ではない。
### Value validation
Valueは、Operation declarationのTypeExprと照合して検証する。
- `Named`を参照先Typeへ解決する。
- Required fieldまたはparameterの欠落を拒否する。
- 未宣言のRecord fieldを拒否する。
- Optional fieldの省略と`Unit`を区別する。
- EnumおよびUnionの未知caseを拒否する。
- Union discriminator、payloadの有無、payload typeをcase declarationに照合する。
- `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件数、`observe`のdepth等が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ではない。
## `observe`
一つのpathで現在公開されているObjectと、そのObjectから指定depthまでのindexable childrenを一つの観測として取得する。
```rust
struct ObserveRequest {
path: String,
depth: u32,
}
struct ObjectObservation {
object: Object,
children: Option<Vec<ObjectObservation>>,
}
type ObserveResponse = ObjectObservation;
```
起点Objectをdepth `0`とする。`depth = 0`は対象Objectだけを観測する通常の形であり、root nodeの`children`を省略する。
- Root nodeのObjectはrequest pathが指すObjectである。Root pathが`/`の場合はObjectの`name`が空文字列でなければならず、非root pathでは最後のsegmentとObjectの`name`が一致しなければならない。
- Request pathのObjectがその主体へ公開されていない場合は`NotFound`を返す。
- 各childのpathは、parent pathへchild Objectの`name`を追加して導出する。
- 同じparent nodeのchildrenは、互いに異なる`name`を持つ。
- Nodeのdepthがrequestの`depth`より小さい場合、`children`は必須であり、その主体へ公開された直接のindexable childrenをすべて含む。Childが存在しない場合は空listとする。
- Nodeのdepthがrequestの`depth`と等しい場合、`children`を省略する。省略された`children`からemptyを推測してはならない。
- Requested depthより深いnodeをresponseへ含めない。
- その主体へ公開されていないObjectはresponseへ含めず、存在や省略を示すmarkerも返さない。
Success responseはrequested depthまで完全である。Node数によるpartial success、`limit`、`truncated`は定義しない。Hostが完全なresponseをresource budget内で構築できない場合は`ResourceLimitExceeded`を返す。
各nodeのObjectがvalidatorを持つ場合、Clientはrequest pathとchildrenの`name`から導出したpathに対応付けてcacheし、条件付きOperationの`target`を構築できる。
HostとClientは各nodeの配置pathに対して[Interface scopeの祖先制約](2.1-object-tree-schema.md#interface-scope)を検証する。Self-scopeを含み、root Objectではscope `/`を使用できる。制約に違反する参照を含むObject responseは`InvalidResponse`であり、そのObjectを操作へ使用しない。
## `fetch_interface`
Interface参照に対応する現在のInterface Descriptorを取得する。
### Interface参照とvalidator
`Object.interfaces`の各要素、`FetchInterfaceRequest.interface`、`FetchInterfaceResponse.interface`、`InterfaceTarget.reference`は`InterfaceReference`である。同じWorldspace context内の同じ有効な`(scope, name)`は同じInterfaceを表すが、Hostはvalidatorを使用してDescriptorを時間とともに変更できる。
`FetchInterfaceResponse.validator`は、HostがそのInterface Descriptorの現在状態へ付与するoptionalなopaque bytesである。Clientは内容を解釈せず、観測したDescriptorに基づいてOperationを実行するときに、Interface参照とともに`InterfaceTarget`へコピーする。
同じ有効期間内のInterface参照とvalidatorには次の規則を適用する。有効期間とscope Objectの紐付きは次節に従う。
- 同じInterface参照と同じvalidator valueを持つ観測は、validatorが存在する場合、同じInterface Descriptorを表す。
- 同じInterface参照と異なるvalidatorを持つ観測は、同じInterfaceの異なる状態を表す。
- Validatorを返さないInterface参照は、その参照が有効である間、異なるDescriptorへ変更してはならない。
- 同じInterface参照のDescriptorを変更可能にするHostはvalidatorを返し、Descriptorの変更時に以前と異なるvalidatorを発行しなければならない。
- Validator valueはInterface参照と組み合わせて比較する。異なるInterface参照で同じopaque bytesを使用してもよい。
- Validatorから状態の順序、新旧、Descriptor内容を推測してはならない。
HostはInterface validatorの生成方法を自由に選べる。Generation、content hash、database revision等を使用してよい。Clientは生成方法を解釈せず、Interface参照とvalidator valueの組をOperation executionのpreconditionとして使用する。
Interface validatorはAIやユーザーへ公開するApplication dataではない。Client runtimeがInterface Descriptor observationとともに保持するprotocol metadataである。
### Scope Objectの紐付き
Interface scopeはそのpathのObjectに紐づく。Scope Objectがそのpathから消えれば、そのObjectに紐づくInterface参照の有効期間は終了し、未公開のInterfaceへの`fetch_interface`は`InterfaceNotFound`となる。削除されたObject自身と消えた配下への`observe` / `call_operation`は`NotFound`となる。同じpathへ別Objectが公開された場合は現在の公開状態で解決する。
`FetchInterfaceResponse.scope_ref`は、scope Objectが同じ主体へ公開する`Object.ref`である。Hostはその`ref`があれば同じstringを返し、なければfieldを省略する。別のscope専用identityやvalidatorを生成するfieldではない。Scope Objectとの紐付き、Descriptor、Interface validatorは一つの整合した観測として取得し、別々の時点の値を組み合わせない。Clientにscope Objectやその祖先の追加取得を必須にしない。
Clientは`scope_ref`をInterface observationとともに保持し、その観測を使うcallの`InterfaceTarget.scope_ref`へ存在する値をコピーする。Hostは指定された`scope_ref`を、現在のscope Objectの`ref`とUnicode code point sequenceの完全一致で比較する。一致しない場合、または現在のObjectが`ref`を持たない場合、その紐付きは確認できず`InterfaceMismatch`とする。異なる`ref`から別Objectだと断定するものではなく、指定された同一性条件を満たせないことを表す。Clientの事前確認だけで済ませず、Hostがcallの他のpreconditionと一貫して確認する。
`scope_ref`は参照の識別子に含めない。Interfaceの識別とmembershipは引き続き`(scope, name)`であり、通常の表示も変更しない。Scope Objectの状態validatorはこの確認に使わず、通常の状態更新でscopeの紐付きを無効にしない。Descriptorの変更検出には独立したInterface validatorを使う。
`scope_ref`が省略されたcallにはscope Objectのidentity preconditionを適用しない。Scope Objectの`ref`はoptionalであり、`ref`なしで同じpathのObjectが差し替わったことをClientが追跡できないのは仕様上許容される。Hostは`ref`がないことやidentityを追跡できないことだけを理由に拒否せず、現在の公開状態と残るpreconditionに従う。Hostにref生成、Clientに疑似refやscope validatorの生成を要求しない。
Scopeの削除・移動・差し替えによる有効期間終了を確認したClientは、旧Interface observationを新しいcallへ再利用せず、必要なら現在の参照を再取得する。同じpathへ再公開された参照の観測と、終了した有効期間のcacheは区別する。`scope_ref`の相違や欠落により以前の紐付きを確認できなくなった場合も、旧観測をそのまま付け替えない。異なる有効期間のDescriptorを、同じvalidatorであることだけから同一とみなさない。
`ref`も削除の観測もない場合、有効期間の切り替わりを検出できるとは限らない。Clientは得られた情報で通常のvalidationを行うが、検出不能な差し替えを防ぐ保証はない。この許容は、存続中の同じInterfaceのDescriptor整合性を弱めない。Scopeが別pathへ移動すれば別参照として扱い、Clientは移動を追跡しない。実行開始済みcallが固定した観測と結果検証用Descriptorの保持は、有効期間終了後も維持する。
### Requestとresponse
```rust
struct FetchInterfaceRequest {
interface: InterfaceReference,
}
struct FetchInterfaceResponse {
interface: InterfaceReference,
scope_ref: Option<String>,
descriptor: InterfaceDescriptor,
validator: Option<Vec<u8>>,
}
```
Clientは次を検証する。
- Responseの`interface`がrequestと一致する。
- Descriptorが構造検証および意味検証に成功する。
- Descriptorの`format`がClientの対応するversionである。
- 同じ有効期間のInterface参照と同じvalidator valueを持つ既存cache entryがある場合、validatorが存在する観測ではDescriptorがそのentryと一致する。Scopeの紐付きが確認できなくなった旧cacheとの比較は、前節の規則に従う。
ResponseまたはDescriptorがProtocol contractに違反する場合、ClientはHostが返したProtocol failureではなく`InvalidResponse`として扱う。Descriptorが構造的にはvalidだが、その`format`をClientが実装していない場合は`UnsupportedDescriptorFormat`として扱い、`InvalidResponse`と混在させない。
Clientはvalidatorが存在するInterface observationを、同じ有効期間内の`(interface, validator)`の組でcacheし、`scope_ref`も観測metadataとして保持する。Interface参照ごとに最後に成功した観測を現在のcache entryとしてよいが、実行中のOperationが参照する観測はresponseのvalidationが完了するまで保持する。次の規則は同じ有効期間の観測に適用し、終了・紐付きの不一致を確認した旧cacheは新しいcallに使わない。
- 同じInterface参照でvalidatorが異なる場合は、同じInterfaceの新しい状態としてlatest observationを更新する。
- Validatorが存在しないInterface参照はimmutableなDescriptorとして、Interface参照だけをcache keyに使用できる。
- 同じ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`を省略する。
Hostは、主体へ公開したObjectの`interfaces`に含まれる各参照について、現在のDescriptorをその主体の`fetch_interface`で取得可能にしなければならない。現在公開されていないInterface参照には`InterfaceNotFound`を返し、Descriptor取得の認可失敗として`PermissionDenied`は使用しない。
`fetch_interface`は完全な`(scope, name)`を受け取るため、Clientに祖先Objectを順に取得するlookupを要求しない。Hostはscope Objectと、そのObjectに紐づくInterfaceの現在の公開状態を解決し、近い祖先の同名Interfaceへのfallbackは行わない。Requestに対象Objectのpathはなく、特定Objectで利用できるかの祖先制約（self-scopeを含む）は`observe`と`call_operation`で検証する。Scope外のObjectで使えないことと、Interface単独の取得可否は同一視しない。
## `call_operation`
指定pathにあるObjectへOperationを実行する。
```rust
struct Target {
path: String,
validator: Option<Vec<u8>>,
}
struct InterfaceTarget {
reference: InterfaceReference,
scope_ref: Option<String>,
validator: Option<Vec<u8>>,
}
struct CallOperationRequest {
target: Target,
interface: InterfaceTarget,
operation: String,
arguments: BTreeMap<String, Value>,
}
struct CallOperationResponse {
result: Value,
validator: Option<Vec<u8>>,
}
```
`target.path`はOperationを実行するObjectのpathである。`target.validator`は、Clientが観測したObjectのvalidatorを条件として指定する。Validatorを持たないObjectまたは無条件実行では省略する。
`interface.reference`は、ClientがObjectの`interfaces`から選択し、そのOperation schemaを取得するために使用したInterface参照である。`interface.validator`は、その参照への`fetch_interface`で観測したvalidatorである。`fetch_interface` responseにvalidatorが存在する場合は必ず指定し、validatorが存在しないimmutableなInterface参照では省略する。
`interface.scope_ref`は、そのDescriptor observationで得たscope Objectのoptionalな`ref`である。観測に存在する場合はコピーし、存在しない場合は省略する。Scope Objectを別途観測して得た新しい`ref`だけを古いDescriptorへ付け替えてはならない。紐付きが確認できなくなった場合はInterface observationを取得し直す。
`arguments`はOperation parameterに対応する名前付きrecordである。引数がない場合は空のmapを送る。
Hostは、現在その主体へ公開しているObjectとInterfaceに基づいてOperationを解決する。複数のfailure条件が同時に成立する場合は、次の順で最初のcodeだけを返す。
1. `target.path`のObjectが公開されていない場合は`NotFound`。
2. 指定された`target.validator`が現在のObject validatorと一致しない場合は`ValidatorMismatch`。
3. `interface.reference`が、現在そのObjectで公開されている`Object.interfaces`に`(scope, name)`の完全一致で含まれない、対象pathへのInterface scopeの祖先制約（self-scopeを含む）に違反する、または指定された`interface.scope_ref`が現在のscope Objectの`ref`と一致しない場合は`InterfaceMismatch`。指定があるのに現在の`ref`がない場合も一致しない。`scope_ref`の省略だけではこのfailureにしない。
4. 現在のInterfaceがvalidatorを持つにもかかわらず`interface.validator`が省略されている場合は`InterfaceValidatorRequired`。
5. 指定された`interface.validator`が現在のInterface validatorと一致しない場合は`InterfaceValidatorMismatch`。現在のInterfaceがvalidatorを持たない場合にvalidatorが指定されたときも一致しないものとする。
6. `operation`が現在のInterface Descriptorに宣言されていない場合は`OperationNotFound`。
7. HostがObject validatorを要求するOperationに`target.validator`が指定されていない場合は`ValidatorRequired`。
8. `arguments`が現在のOperation declarationに適合しない場合は`InvalidArguments`。
9. 宣言されたOperationの存在を公開しつつ、その主体による実行を認めない場合は`PermissionDenied`。
指定されたObject validatorまたはInterface validatorの不一致は、現在のDescriptorに基づくOperation lookupとarguments validationより先に判定する。これによりClientは、古いObjectまたはschemaに基づくrequestを`OperationNotFound`や`InvalidArguments`として扱わず、対応する観測を更新できる。
Hostは一つのlinearization pointで、現在のObject identityと状態、Object validator、Objectが公開するInterface参照、scope Objectとの紐付きと指定された`scope_ref`、Interface validator、Interface Descriptor、Operation implementation、実行対象を解決し、各preconditionを確認して、そのcallが使用する観測を固定する。ObjectまたはInterfaceが後から変化しても、callの途中で別のscope Object、Descriptor、Operation implementation、実行対象へ解決し直してはならない。
Argumentsとresultのvalidationは、固定したInterface Descriptorの同じOperation declarationを使用する。Authorizationも固定したObject、Interface、主体のcontextに対して評価する。
Hostが`target.validator`をbackendへのcommit条件として使用する場合、validatorの比較とcommitをatomicに行う。Responseの`validator`は、Operation完了後にHostがそのObjectについて発行する現在のvalidatorである。Operationが何を行ったか、またはApplication dataを変更したかをvalidatorの有無や値から推測しない。Object validatorを提供しない場合は省略する。
Validatorの比較はopaque bytesの完全一致で行う。Clientはvalidatorの生成方法または内容に基づいて分岐してはならない。
HostはOperationをInterfaceから除外して存在を非公開にすることも、Interfaceへ含めたうえで実行時に`PermissionDenied`として拒否することもできる。
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`を返す。
## Worldspace composition
Clientが扱う絶対pathとInterface scopeは、常に接続先Hostが公開するClient-facing Worldspaceのrootに基づく。Proxyや合成によってUpstream Worldspaceの公開位置が変わる場合、Hostが公開先とUpstreamの座標を対応付ける。Upstreamのrootやmount構成をClientに追跡・補完させない。
Upstreamのrootを`/github`へ配置する例:
| 項目 | Upstream | 公開先 |
| --- | --- | --- |
| Root | `/` | `/github` |
| Object path | `/my-rep/issues` | `/github/my-rep/issues` |
| Interface参照 | `{ scope: "/", name: "issue.read" }` | `{ scope: "/github", name: "issue.read" }` |
| Repository scope | `/my-rep` | `/github/my-rep` |
| `entry` | `/my-rep/issues/123` | `/github/my-rep/issues/123` |
別のUpstreamを`/gitlab`へ配置した場合、その`{ scope: "/", name: "issue.read" }`は`{ scope: "/gitlab", name: "issue.read" }`となる。同じlocal nameでもscopeによって区別される。さらに全体を`/services`へ配置するHostは、`/github`を`/services/github`へ変換する。Worldspaceの配置を変えないHTTP proxyはscopeを変更する必要がない。HTTP endpointのpath prefixとWorldspace pathを混同しない。
### 座標の変換
合成Hostは次の対応を一貫させる。
- `observe`のrequest pathをUpstreamへ変換する。ResponseのObjectの`name`とchildrenは公開先pathの規則を満たすようにする。特にUpstream rootの空の`name`を、非rootのmount先へそのまま公開しない。
- `Object.interfaces`の各構造化参照のscopeを公開先へ変換し、公開先での祖先制約と名前の一意性を保つ。
- `fetch_interface`を適切なUpstreamと構造化参照へ対応付ける。Responseの`interface`はClientが要求した公開先の参照にする。
- `call_operation`のtarget pathとInterface参照をUpstreamへ対応付ける。Local name単独で転送先を選ばない。
- `scope_ref`は公開先scope Objectの`ref`と一致させる。Upstreamのscope Objectが持つ`ref`との対応をHostが保持し、公開先で指定されたpreconditionを検証してからUpstreamへ対応付ける。Opaqueな`ref`へpath prefixを機械的に加えたり、指定された条件を転送時に落としたりしない。公開先scope Objectが`ref`を持たない形態も許可する。
- Descriptorで`entry`と宣言されたargumentsをUpstreamへ、resultを公開先へ変換する。Named type、record、list、unionの内部にある`entry`も同じ規則で扱う。
通常の`string`、opaqueな`json`、documentation内のpathらしい文字列を推測して書き換えない。Application固有の別の座標系はApplication adapterの責務とする。
公開subtree外のscopeや`entry`に対応付けがない場合、Upstream pathをそのまま公開したり、scopeを削除・rootへ付け替えたりしてはならない。部分合成の対応付け方針と詳細な拒否条件は未確定だが、失敗時も既存のProtocol failure契約を守る。特にUpstreamでeffectがcommit済みのOperationのresultを変換できない場合、未実行を保証するerrorへ置き換えない。Validなsuccessを返せず、未実行またはrollbackを保証できない場合は`OperationOutcomeUnknown`として扱う。
### 同一性と観測整合性
- 公開先の同じ有効な`(scope, name)`とvalidatorを、異なるDescriptorへ対応付けない。Validatorのない参照のDescriptorは、その参照が有効な間immutableとする。
- 異なるUpstreamのObjectへ同じ有効な公開`ref`を割り当てない。
- Routingやmountの変更後に、古いObject validatorで別の対象へOperationを実行できないようにする。
- Upstream validatorをそのまま使用するか、Host側で対応付け・wrapするかは、これらの保証を満たす範囲でHostが決める。
- Scopeが変わればProtocol上は別のInterface参照である。Clientに移動前後の同一性を推測させない。
同じUpstream Objectを複数のscope配下へ配置すると、公開するInterface集合が配置ごとに変わり得る。異なる公開representationへ同じ`ref`とvalidatorを無条件に引き継げない。共通祖先scopeでの共有やprojectionごとのidentity割当等の選択は[未解決事項](draft/unresolved-issues.md)に残す。Renameやmount変更では新しいscopeを別参照として扱い、同じpathでのscope Objectの差し替えには上述のoptionalな`scope_ref`の確認を適用する。Clientによる移動追跡は要求しない。これらは既存のvalidator・実行中callの一貫性を弱めない。
## Protocol responseとfailure
Core interactionは、成功responseまたはProtocol failureを返す。
```rust
enum ProtocolResult<T> {
Success(T),
Failure(ProtocolError),
}
struct ProtocolError {
code: ProtocolErrorCode,
message: String,
}
enum ProtocolErrorCode {
InvalidRequest,
NotFound,
InterfaceNotFound,
InterfaceMismatch,
OperationNotFound,
InvalidArguments,
ValidatorRequired,
ValidatorMismatch,
InterfaceValidatorRequired,
InterfaceValidatorMismatch,
PermissionDenied,
ResourceLimitExceeded,
Internal,
OperationOutcomeUnknown,
}
```
`message`は人間向けのboundedな診断であり、Clientが分岐に使用する安定した値ではない。Clientは`code`を使用する。Hostは秘密情報、非公開Object、backend path、credential、内部stack traceをmessageへ含めない。
各interactionが返してよいcodeは次に限定する。
| Code | `observe` | `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として扱い、必要に応じて親を再観測する。
- `InterfaceNotFound`では、ClientはそのInterface observationを使用せず、参照元Objectを再観測できる。
- `ValidatorRequired`または`ValidatorMismatch`では、Clientは対象Objectを再観測する。
- `InterfaceMismatch`では、Clientは対象Objectを再観測し、現在公開されているInterface参照の集合を取得する。Scopeの紐付きが変わった可能性もあるため、使用したInterface observationを新しいcallへ再利用せず、必要なら`fetch_interface`で再取得する。
- `InterfaceValidatorRequired`または`InterfaceValidatorMismatch`では、Clientは同じInterface参照を`fetch_interface`で再観測し、現在のDescriptorに基づいてOperationを再構築する。
同じOperationを再試行するなら、先に新しい観測を取得しなければならない。
- `InvalidRequest`または`InvalidArguments`では、Clientは同じrequestを変更せずに再送しない。
- `ResourceLimitExceeded`では、Clientはlogical request shapeやobservation depth等を削減できるが、`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に存在しないものとして扱い、`observe`と`call_operation`へ`NotFound`を返す。Objectの存在を秘匿する目的で`PermissionDenied`を返してはならない。
`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等へ対応付ける。Authentication、route、media type、framing、response不達等のTransport failureをProtocol errorへ変換しない。
## Resource limit
HostとClientは、untrusted inputによるresource exhaustionを避けるため、少なくとも次へ上限を設ける。
- Pathとして解釈するstring、validator、name、description、documentationの長さ。
- Interface Descriptor内のdeclaration、documentation、field等の総量。
- ObjectごとのInterface参照数。
- Type declaration、Operation、parameter、field、caseの数。
- TypeExprとValueのnesting depth。
- Record field数とList要素数。
- `observe`のdepthとresponse node数。
- Protocol error messageの長さ。
各実装はこれらにboundedな上限を設定する。Request fieldだけで判定できる上限違反は、interaction固有のtarget resolutionまたはOperation dispatchより前に`ResourceLimitExceeded`として拒否する。Hostが取得responseを構築する途中でresponse node数やlogical collection size等の上限超過を検出した場合も、success responseの代わりに`ResourceLimitExceeded`を返してよい。
`call_operation`では、dispatch後にresultのlogical size、validation、backend budget等の問題を検出しても、effectがcommitされていないと保証できる場合だけ`ResourceLimitExceeded`または`Internal`を返す。未実行またはrollbackを保証できない場合は`OperationOutcomeUnknown`とする。Transport implementationまたはdeploymentのmessage-size上限、response不達等はProtocol failureへ変換せず、Transport failureとして扱う。
## Transport Bindingの要件
Transport Bindingは、この章のlogical structについて次を定義する。
- Requestとresponseのframing。
- Protocol primitiveのconcrete encoding。
- Object、Descriptor、Valueのencoding。
- Optional fieldの省略。
- Protocol failureのmapping。
- Object validator、Interface validator、Operation preconditionのmapping。
Transport固有のmessage size、timeout、concurrency、security、connection policyはTransport実装とdeploymentの責務であり、BindingがWIP Protocolとして値またはnegotiationを定義する必要はない。複数のinteractionを並行実行またはmultiplexする場合も、それぞれは独立したrequestとresponseを持つ。
Transport Bindingは、logical typeの区別またはvalidation semanticsを失ってはならない。