# wRPC v0.0.1 specification
wRPC is a transport-agnostic protocol designed for asynchronous transmit of WIT function calls and associated values over network.
wRPC relies on [component model value definition encoding](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Binary.md#-value-definitions) for data encoding on the wire.
wRPC makes use of *transports*, which are responsible for establishing a connection between two parties and transferring the wRPC wire protocol data between them.
As WIT interfaces and associated values are asynchronous in nature, callers and callees require ability to asynchronously, bidirectionally transfer (portions of) function parameter and result value data. For example, caller of `wasi:http/outgoing-handler.handle` function MUST be able to simultaneously send data over the passed `output-stream` and well as receive data from the returned `input-stream`. For this purpose wRPC transports must be *multiplexed*, i.e. they MUST allow for bidirectional concurrent transfer of multiple data streams.
wRPC uses a concept of "indexing" for differentiating and identifying the data streams used as part of processing of a single WIT function invocation.
An "index" represents a reflective structural path to the value,
## Transport
Primary transport used by wRPC is NATS, however this protocol can be implemented in terms of other transports as well, e.g. HTTP/2 or QUIC. Following this design decision, endpoint names are URL-safe. In URL form, `.` characters must be replaced by `/`.
wRPC protocol operates under assumption that globally-unique IDs can be generated by the caller (client). No particular type of identifier is required by wRPC by specification, but in case of NATS transport, the common NATS inbox concept is assumed to be used throughout this specification.
The default data encoding format is assumed to be `wube` defined in the appendix of this specification, implementations are free to use a different format, however, which can be specified using `Content-Type` header and/or additional out-of-band configuration mechanism.
wRPC NATS topics (or URLs) assume to be rooted at a particular (optional) prefix, this prefix is configured out-of-band from perpective of this specification.
## Invocations
wRPC follows client-server model, where peers may *serve* function (servers) and method calls invoked by the other peers (clients).
An optional concept of a "session" is used to facilitate function or method call invocations, which require asynchronous two-way data transfer.
On a high level, lifecycle of an arbitrary wRPC invocation looks the following:
1. A server subscribes on a topic `T` corresponding to WIT function or method `F` served by itself
2. A client sends a message on topic `T` carrying, optionally truncated, encoded parameters to function `F` and reply topic `R_c`
3. If the payload sent in 2. is not finite (e.g. if the parameter tuple contains async values, like streams) or is incomplete:
1. The server immediately sends a packet with no payload on topic `R_c` with a reply topic `R_s` - this initiates a "session"
2. The client sends invocation parameter data on `R_s` subtopics concurrently with the rest of the invocation flow.
4. The server begins `F` execution.
5. If `F` parameters contain server-writable async values, server sends data on `R_c` subtopics concurrently with the rest of the invocation flow.
6.
- If `F` returns:
1. Server sends a packet carrying encoded return value tuple on `R_c.results`.
2. If `F` return values contain async values, server sends data on `R_c.results` subtopics concurrently.
- If `F` traps or execution is not possible for some other reason:
1. Server sends the error on `R_c.error`
## Structured data field addressing
To facilitate structured data transfer, a reflective zero-indexed numeric (u32-sized) type path is used.
- Record fields are indexed in order of their WIT declaration
- Tuple members are indexed in order of their WIT declaration
- List elements are indexed in their list order
- Variant members elements are indexed in order of their WIT declaration
## Headers
wRPC packets may carry headers, which are defined in this section. All headers are optional unless specified otherwise.
### `Content-Type`
This header is used to override default encoding format, it's not set for packets using `wube` encoding defined in this specification.
See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
Examples:
- `application/json`
- `application/msgpack`
- `application/octet-stream`
- `text/plain`
### `Content-Range`
This header MUST be set for messages carrying partial payload.
See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range
Examples:
- `bytes 0-100/*`
- `bytes 100-200/300`
- if the encoded payload length is 100 bytes and first 10 bytes are sent, `Content-Range: bytes 0-9/100` header MUST be set.
- if the encoded payload length is unknown and second 10 bytes are sent, `Content-Range: bytes 10-19/*` header MUST be set.
### `Transfer-Encoding`
See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding
Examples:
- `chunked`
- `gzip, chunked`
## Function invocation
Topic: `[<prefix>.]?wrpc.0.0.1.<wit-namespace>:<wit-package>/<wit-interface>[@<wit-package-version>]?.[<function>|<wit-resource>.<function>]`
URL: `example.com/[<prefix>/]?wrpc/0.0.1/<wit-namespace>:<wit-package>/<wit-interface>[@<wit-package-version>]?/[<function>|<wit-resource>.<function>]`
Topic examples:
- `MBGL42DWFPGIEI63P333NCZW5BAGYJGSGLAIB6U7PPXKSXKJK74QTUZM.wrpc.0.0.1.wasi:http/outgoing-handler.handle`
- `NARNEZWUJIOUEDOHI6BDRRFST5W6SHMTQXX5CVOBJC7Z4BQ63S2DKZH6.wrpc.0.0.1.wasi:http/outgoing-handler.handle`
- `VD7C7DD6H5XSIL737EEVTHF7G6EYTMIPQLVOE2BLQDC7TEOGTUZECJYF.wrpc.0.0.1.wasi:http/outgoing-handler.handle`
- `VD7C7DD6H5XSIL737EEVTHF7G6EYTMIPQLVOE2BLQDC7TEOGTUZECJYF.wrpc.0.0.1.wasi:http/outgoing-handler@0.2.0-rc-2023-11-10.handle`
- `default.wrpc.0.0.1.wasi:http/outgoing-handler.handle`
- `default.wrpc.0.0.1.wasi:http/types/fields.constructor`
- `default.wrpc.0.0.1.wasi:http/types@0.2.0-rc-2023-11-10.fields.constructor`
- `custom.wrpc.0.0.1.wasi:http/types@0.2.0-rc-2023-11-10.fields.constructor`
URL examples:
- `example.com/wrpc/0.0.1/wasi:http/types@0.2.0-rc-2023-11-10/fields.constructor`
Messages sent on this topic represent invocations of WIT interface and static resource functions.
Messages sent on this topic MUST specify the reply inbox subject.
The request payload represents the encoded function call parameter tuple.
The caller (client) may truncate the payload and only send first N bytes of the payload, including sending no bytes at all.
## Method invocation
Topic: `<resource-topic>.wrpc.0.0.1.<method>`
URL: `<resource-url>/wrpc/0.0.1/<method>`
Messages sent on this topic represent invocations of WIT methods on previously-constructed resources managed by the remote parties (identified by `resource-topic` or `resource-url` respectively).
Messages sent on this topic MUST specify the reply inbox subject.
The request payload represents the encoded method call parameter tuple.
The caller (client) may truncate the payload and only send first N bytes of the payload, including sending no bytes at all.
## Invocation response
Once the function or method invoked finishes execution, the server responds on a topic derived from the reply inbox specified in the initial invocation.
- If function/method call returns, server uses `<reply-inbox>.results` as the response topic, on which the (possibly truncated) encoded result tuple is transmitted according to data transfer procedure defined in this specification. Client and server may still exchange data as part of the session associated with the invocation after the result tuple has been fully transmitted to the client.
- If function/method call traps, server uses `<reply-inbox>.error` as the response topic, on which the (possibly truncated) error string is transmitted according to data transfer procedure defined in this specification. The session is immediately assumed to be closed on transmit of any message on this topic, meaning that the server MUST discard all session data associated with the invocation.
## Invocation session
Once the (possibly truncated) function/method parameter tuple is received by the server, it MAY immediately start executing the function/method indicated by the topic, even if full contents of the tuple are not available yet.
In cases where the function/method parameter tuple was truncated or contained pending asynchronous values and potential execution has not resulted in a trap (yet), the server MUST communicate a reply inbox to the client in one of the two ways:
- The server MAY transmit a single packet with no payload and a reply subject set on the reply topic specified in the invocation
- If the server has already started executing the function/method and it has returned - the server MAY transmit the result tuple on invocation response topic as described in this specification and MAY set the reply inbox subject
If the invocation payload was truncated, the client sends the rest of the payload on the reply inbox negotiated in the above procedure.
## Partial data transfer
In all cases with the exception of transmit of initial invocation payload, which is defined in previous section, when encoded value is required/desired to be truncated, the truncated part of the encoding is sent on the original topic and the rest is sent on the same topic, following the first transmit. This procedure is repeated as many times as necessary until the whole data is transmitted.
## Asynchronous data transfer
If an asynchronous value is not fully-available (e.g. pending future) at time of encoding, it is encoded as "pending" (refer to encoding specification) in the structured data (e.g. parameter tuple) and sent asynchronously as it becomes available on a reply topic negotiated as part of the session with a reflective `/`-delimited structured value path suffix.
Examples:
- `_INBOX.WMZAFf1AjlpSF3r5e65nFe.dOssD7ON.0` - this could be first parameter or return value
- `_INBOX.WMZAFf1AjlpSF3r5e65nFe.dOssD7ON.0/0/1`
- `_INBOX.WMZAFf1AjlpSF3r5e65nFe.dOssD7ON.0/0`
- `_INBOX.WMZAFf1AjlpSF3r5e65nFe.dOssD7ON.0/1/0`
- `_INBOX.WMZAFf1AjlpSF3r5e65nFe.dOssD7ON.0/1/1`
- `_INBOX.WMZAFf1AjlpSF3r5e65nFe.dOssD7ON.0/1`
- `_INBOX.WMZAFf1AjlpSF3r5e65nFe.dOssD7ON.1/2/1`
## Resources
wRPC protocol implementations are encouraged to "adapt" interfaces utilising resources to interfaces using e.g. records for performance.
For example of this approach, consider existing `wasi:http/outgoing-handler.handle` function defined at https://github.com/WebAssembly/wasi-http/tree/v0.2.0-rc-2023-11-10/wit (comments omitted, type aliases resolved, relevant resource dependencies moved close):
```wit
resource pollable {
ready: func() -> bool;
block: func();
}
resource input-stream {
read: func(len: u64) -> result<list<u8>, stream-error>;
blocking-read: func(len: u64) -> result<list<u8>, stream-error>;
skip: func(len: u64) -> result<u64, stream-error>;
blocking-skip: func(len: u64) -> result<u64, stream-error>;
subscribe: func() -> pollable;
}
resource output-stream {
check-write: func() -> result<u64, stream-error>;
write: func( contents: list<u8>) -> result<_, stream-error>;
blocking-write-and-flush: func(contents: list<u8>) -> result<_, stream-error>;
flush: func() -> result<_, stream-error>;
blocking-flush: func() -> result<_, stream-error>;
subscribe: func() -> pollable;
write-zeroes: func(len: u64) -> result<_, stream-error>;
blocking-write-zeroes-and-flush: func(len: u64) -> result<_, stream-error>;
splice: func(src: borrow<input-stream>, len: u64) -> result<u64, stream-error>;
blocking-splice: func(src: borrow<input-stream>, len: u64) -> result<u64, stream-error>;
}
resource fields {
constructor();
from-list: static func(entries: list<tuple<string,list<u8>>>) -> result<fields, header-error>;
get: func(name: string) -> list<list<u8>>;
set: func(name: string, value: list<list<u8>>) -> result<_, header-error>;
delete: func(name: string) -> result<_, header-error>;
append: func(name: string, value: list<u8>) -> result<_, header-error>;
entries: func() -> list<tuple<string,list<u8>>>;
clone: func() -> fields;
}
resource incoming-response {
status: func() -> status-code;
headers: func() -> headers;
consume: func() -> result<incoming-body>;
}
resource incoming-body {
%stream: func() -> result<input-stream>;
finish: static func(this: incoming-body) -> future-trailers;
}
resource future-trailers {
subscribe: func() -> pollable;
get: func() -> option<result<option<fields>, error-code>>;
}
resource future-incoming-response {
subscribe: func() -> pollable;
get: func() -> option<result<result<incoming-response, error-code>>>;
}
resource outgoing-body {
write: func() -> result<output-stream>;
finish: static func(this: outgoing-body, trailers: option<fields>) -> result<_, error-code>;
}
resource outgoing-request {
constructor(headers: headers);
body: func() -> result<outgoing-body>;
method: func() -> method;
set-method: func(method: method) -> result;
path-with-query: func() -> option<string>;
set-path-with-query: func(path-with-query: option<string>) -> result;
scheme: func() -> option<scheme>;
set-scheme: func(scheme: option<scheme>) -> result;
authority: func() -> option<string>;
set-authority: func(authority: option<string>) -> result;
headers: func() -> fields;
}
resource request-options {
constructor();
connect-timeout-ms: func() -> option<duration>;
set-connect-timeout-ms: func(ms: option<duration>) -> result;
first-byte-timeout-ms: func() -> option<duration>;
set-first-byte-timeout-ms: func(ms: option<duration>) -> result;
between-bytes-timeout-ms: func() -> option<duration>;
set-between-bytes-timeout-ms: func(ms: option<duration>) -> result;
}
handle: func(request: outgoing-request, options: option<request-options>) -> result<future-incoming-response, error-code>;
```
An adaptation of the following interface could look like this:
```wit
record request-options {
connect-timeout: duration,
first-byte-timeout: duration,
between-bytes-timeout: duration,
}
record outgoing-request {
headers: list<tuple<string,list<u8>>>,
method: method,
path-with-query: option<string>,
scheme: option<scheme>,
authority: option<string>,
body: list<u8>,
trailers: option<list<tuple<string,list<u8>>>>,
}
record incoming-response {
status: status-code,
headers: list<tuple<string,list<u8>>>,
body: list<u8>,
trailers: option<list<tuple<string,list<u8>>>>,
}
handle: func(request: outgoing-request, options: option<request-options>) -> result<incoming-response, error-code>;
```
## WebAssembly Untyped Binary Encoding (`wube`)
`wube` encoding is a simple binary encoding optimized for:
1. simplicity
2. encoding/decoding efficiency
3. compactness
`wube` is designed to fit well with stream-based APIs and technologies, it performs no compression, however users are encouraged to rely on streaming compression/decompression technologies (like DEFLATE, defined at https://datatracker.ietf.org/doc/html/rfc1951) to transfer `wube` values over network.
Although `wube`-encoded values could potentially be speculatively decoded without access to the WIT associated with the original encoded value, it is assumed that both encoder and decoder rely on exactly the same WIT definitions when working with `wube` values, and all the type information is communicated between parties out-of-band.
`wube` represents all numeric values as little-endian
### Numeric types
All numeric values are encoded as little endian with zero padding appropriate for the numeric value byte size.
For example:
- Type: `u32`
Value: `1`
Encoding: `[0x01, 0x00, 0x00, 0x00]`
- Type: `u64`
Value: `1`
Encoding: `[0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]`
### Characters
Characters are encoded as UTF-8 32-bit unsigned number.
For example:
- Value: `a`
Encoding: `[0x61, 0x00, 0x00, 0x00]`
### Enums
Enums are encoded as their discriminant encoded as an unsigned number of bit size matching nearest byte boundary of maximum value of the descriminant (in other words, discriminants of enums containing at most 255 options are encoded as an 8-bit unsigned number).
For example:
- Type: `enum test { foo, bar, baz }`
Value: `foo`
Encoding: `[0x00]`
- Type: `enum test { foo, bar, baz }`
Value: `bar`
Encoding: `[0x01]`
### Variants
Variants are encoded as their discriminant encoded as an unsigned number of bit size matching nearest byte boundary of maximum value of the descriminant (in other words, discriminants of variants containing at most 255 options are encoded as an 8-bit unsigned number), followed by encoding of their values, if such is defined.
For example:
- Type: `enum test { foo, bar(bool), baz(option<bool>) }`
Value: `foo`
Encoding: `[0x00]`
- Type: `enum test { foo, bar(bool), baz(option<bool>) }`
Value: `bar(true)`
Encoding: `[0x01, 0x01]`
- Type: `enum test { foo, bar(bool), baz(option<bool>) }`
Value: `baz(none)`
Encoding: `[0x01, 0x00]`
- Type: `enum test { foo, bar(bool), baz(option<bool>) }`
Value: `baz(some(true))`
Encoding: `[0x01, 0x01, 0x01]`
### Booleans
Booleans are encoded as values of `enum bool { false, true }` type
- Value: `false`
Encoding: `[0x00]`
- Value: `true`
Encoding: `[0x01]`
### Options
Options are encoded as values of `variant option { none, some(value) }` type
### Results
Results are encoded as values of `variant result { error(error), ok(value) }` type
### Records
Records are encoded as concatenated encoding of their fields in definition order.
For example:
- Type: `record example { foo: bool, bar: u32 }`
Value: `{ foo: true, bar: 1}`
Encoding: `[0x01, 0x01, 0x00, 0x00, 0x00]`
### Flags
Flags are encoded as byte-aligned bit masks matching flag definition order.
For example:
- Type: `flags example { foo, bar, baz }`
Value: `{ foo, bar }`
Encoding: `[0b11000000]`
- Type: `flags example { one, two, three, four, five, six, seven, eight, nine }`
Value: `{ two, nine }`
Encoding: `[0b01000000, 0b10000000]`
- Type: `flags example { one, two, three, four, five, six, seven, eight, nine }`
Value: `{ one, two }`
Encoding: `[0b11000000, 0b00000000]`
### Tuples
Tuples are encoded as concatenating encoding of their contained elements in the order of their definition.
For example:
- Type: `tuple<bool, bool>`
Value: `(first: true, second: false)`
Encoding: `[0x01, 0x00]`
### Lists
Lists are encoded as their length encoded as 32-bit unsigned number followed by concatenated encoding of their elements in the list order.
For example:
- Type: `list<bool>`
Value: `[true, false]`
Encoding: `[0x02, 0x00, 0x00, 0x00, 0x01, 0x00]`
### Futures
Futures are transmitted as `variant future { pending, ready(value) }`
### Streams
Streams are transmitted as `future<list<value>>` as part of structured data and as `list<value>` during field transfer. `Content-Range` header (or other out-of-band mechanism) must be used to indicate the end of the stream during field transfer.
### Resources
In the general case, resources are represented as their unique URIs, e.g. a NATS inbox subject handling resource methods via wRPC, encoded as strings.
Implementations are encouraged to use alternate, optimized, representations of resource values (for example, a reference uniquely identifying the resource being owned by a particular party).
### Function parameters and return values
Function parameters and return values are encoded as tuples of their contained values.
- Type: `example: func(first: bool) -> (a: u8)`
Value: `example(true) -> 2`
Encoding: `[0x01] -> [0x02]`
## Well-known types and interfaces in wRPC 0.0.1
### `wasi:io@0.2.0-rc-2023-11-10`
`poll.pollable` values are encoded and transmitted as `future<()>` values.
`streams.input-stream` and `streams.output-stream` are encoded and transmitted as `stream<u8>` values.
### `wasi:http@0.2.0-rc-2023-12-05`
Functionality is transmitted using the following WIT contract:
```wit
package wrpc:http@0.2.0-rc-2023-12-05;
interface types {
use wasi:io/error@0.2.0-rc-2023-12-05.{error-code};
type error-code = error-code;
record request-options {
connect-timeout: duration,
first-byte-timeout: duration,
between-bytes-timeout: duration,
}
record outgoing-request {
headers: list<tuple<string,list<u8>>>,
method: method,
path-with-query: option<string>,
scheme: option<scheme>,
authority: option<string>,
body: stream<u8>,
trailers: future<list<tuple<string,list<u8>>>>,
}
record outgoing-response {
headers: list<tuple<string,list<u8>>>,
status: status-code,
body: stream<u8>,
trailers: future<list<tuple<string,list<u8>>>>,
}
record incoming-request {
method: method,
path-with-query: option<string>,
scheme: option<scheme>,
authority: option<string>,
headers: list<tuple<string,list<u8>>>,
body: stream<u8>,
trailers: future<list<tuple<string,list<u8>>>>,
}
record incoming-response {
status: status-code,
headers: list<tuple<string,list<u8>>>,
body: stream<u8>,
trailers: future<list<tuple<string,list<u8>>>>,
}
}
interface incoming-handler {
use types.{incoming-request, outgoing-response, error-code};
handle: func(request: incoming-request) -> result<outgoing-response, error-code>;
}
interface outgoing-handler {
use types.{outgoing-request, request-options, incoming-response, error-code};
handle: func(request: outgoing-request, options: option<request-options>) -> result<future<incoming-response>, error-code>;
}
```
Owned values of:
- `wasi:http/types.outgoing-request` type are transmitted as `wrpc:http/types.outgoing-request`
- `wasi:http/types.incoming-request` type are transmitted as `wrpc:http/types.incoming-request`
- `wasi:http/types.future-incoming-response` type are transmitted as `future<wrpc:http/types.incoming-response>`
- `wasi:http/types.request-options` type are transmitted as `future<wrpc:http/types.request-options>`
- `wasi:http/types.fields` type values are transmitted as `list<tuple<string,list<u8>>>`
## HTTP extensibility
Because of the flexibility of wRPC protocol, fully-specified, HTTP-to-NATS-lattice and NATS-lattice-to-HTTP bridges can be built. Potential use case for this could be a multi-tenant HTTP microservice deployed outside the lattice, which could match the tenant based on the invocation signature and perform some action, e.g. serve as bridge between two separate lattices.
### Assumptions
- wasmCloud host is the main party communicating over the NATS lattice and is the main use case we're optimizing for - i.e. native binary providers subscribing to NATS are supported, however we do not care about this use case as much as we care about the case of WASI providers relying on (mostly) standard WASI interfaces (e.g `wasi:http` or `wasi:keyvalue`) - since we already have functionality like `provider-wit-bindgen`, this would probably be the easiest point of entry for building a native binary capability provider plugging into NATS lattice directly.
- At least for MVP, we accept https://github.com/wasmCloud/wasmCloud/issues/1119 and do not focus too much on concepts like "invocation signing", especially since the feature cannot be ported to asynchronous WIT interfaces directly anyway by definition (because the payload being sent as part of invocation cannot be known by the caller in the general case). Similar functionality may be added in the future and would utilize message headers. For example, data fragments being sent could be signed or even encrypted
## Backwards Compatibility
Potentially the existing top-level invocation topic could be reused, but since we're planning to release 1.0, we should try to make changes sooner rather than later
## Alternatives Considered
Not supporting component model and/or resources and WASI cloud WIT
## Unresolved Questions
Linking has to be reworked, a separate RFC incoming (refs https://github.com/wasmCloud/wasmCloud/issues/458)
A feature similar to invocation signing could be added later, but we need to first focus on communication layer, especially considering how little we gain by actually using it
All external metadata (like trace context), really should be sent via headers.