WIP over HTTPS

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

目的

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

方針

初期の標準bindingはHTTPS上のrequest / responseのみを規定する。TLS、認証、Proxy、Gateway、Observability、Caching、connection reuse、multiplexing、compression等の既存機構を利用してよいが、特定のHTTP versionや実装方式を必須にしない。

OperationがWebSocket等のendpointを通常のdomain valueとして返すことは妨げない。そのendpoint上のprotocol、状態、lifecycleはWIPの規定対象外であり、ClientとHost固有実装の責務とする。

双方向socket transportをWIP bindingとして標準化する場合は、将来の独立した拡張として定義する。

Binding対象

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

fetch
fetch_tree
call_operation

具体的なHTTP method、endpoint、content type、error mapping、認証方式、batch表現などは、このbinding仕様側で定義する。

WIP IDLの取得

Operationのinput / output schemaはWIP IDLの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は次の形になる。

{
  "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へ同梱してよい。

{
  "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依存のモデルへ変えることも目的としない。

5.0 KiB Raw Blame History