# WIP over HTTPS

WIP over HTTPSは、**WIP Core ProtocolをHTTPS上へ対応付ける標準Transport Binding**である。

## 目的

Core Protocolの意味論を変えずに、既存のWebインフラを利用してClientとHostを接続する。

## 方針

標準bindingとしてHTTPSを採用することを第一候補とする。

HTTPSを利用することで、TLS、認証、Proxy、Gateway、Observability、Caching、Streamingなど既存の仕組みを再利用できる。

必要に応じてHTTP/2、HTTP/3、SSE、WebSocket等を利用してよい。ただし、これらは通信上の最適化または補助機構であり、WIP Core Protocolの意味論を変更しない。

## Binding対象

少なくとも、Core Protocolの以下の操作をHTTP request / responseへ対応付ける。

- `fetch`
- `fetch_tree`
- `call_operation`

具体的なHTTP method、endpoint、content type、error mapping、認証方式、streaming表現などは、この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依存のモデルへ変えることも目的としない。