wrpc-interfaces
World wrpc-interfaces
- Imports:
- interface
wasmcloud:messaging/types@0.2.0
- interface
wasmcloud:messaging/consumer@0.2.0
- interface
wrpc:keyvalue/store@0.2.0-draft
- interface
wrpc:keyvalue/atomics@0.2.0-draft
- interface
wrpc:keyvalue/batch@0.2.0-draft
- interface
wasi:io/error@0.2.0
- interface
wasi:io/poll@0.2.0
- interface
wasi:io/streams@0.2.0
- interface
wasi:blobstore/types@0.2.0-draft
- interface
wrpc:blobstore/types@0.1.0
- interface
wrpc:blobstore/blobstore@0.1.0
- interface
- Exports:
- interface
wasmcloud:messaging/handler@0.2.0
- interface
Import interface wasmcloud:messaging/types@0.2.0
Types common to message broker interactions
Types
record broker-message
A message sent to or received from a broker
Record Fields
Import interface wasmcloud:messaging/consumer@0.2.0
Types
type broker-message
----
Functions
request: func
Perform a request operation on a subject
Params
Return values
- result<
broker-message
,string
>
publish: func
Publish a message to a subject without awaiting a response
Params
msg
:broker-message
Return values
Import interface wrpc:keyvalue/store@0.2.0-draft
A keyvalue interface that provides eventually consistent key-value operations.
Each of these operations acts on a single key-value pair.
The value in the key-value pair is defined as a u8
byte array and the intention is that it is
the common denominator for all data types defined by different key-value stores to handle data,
ensuring compatibility between different key-value stores. Note: the clients will be expecting
serialization/deserialization overhead to be handled by the key-value store. The value could be
a serialized object from JSON, HTML or vendor-specific data types like AWS S3 objects.
Data consistency in a key value store refers to the guarantee that once a write operation completes, all subsequent read operations will return the value that was written.
Any implementation of this interface must have enough consistency to guarantee "reading your writes." In particular, this means that the client should never get a value that is older than the one it wrote, but it MAY get a newer value if one was written around the same time. These guarantees only apply to the same client (which will likely be provided by the host or an external capability of some kind). In this context a "client" is referring to the caller or guest that is consuming this interface. Once a write request is committed by a specific client, all subsequent read requests by the same client will reflect that write or any subsequent writes. Another client running in a different context may or may not immediately see the result due to the replication lag. As an example of all of this, if a value at a given key is A, and the client writes B, then immediately reads, it should get B. If something else writes C in quick succession, then the client may get C. However, a client running in a separate context may still see A or B
Types
variant error
The set of errors which may be raised by functions in this package
Variant Cases
-
The host does not recognize the store identifier requested.
-
The requesting component does not have access to the specified store (which may or may not exist).
-
Some implementation-specific error has occurred (e.g. I/O)
record key-response
A response to a list-keys
operation.
Record Fields
-
The list of keys returned by the query.
-
The continuation token to use to fetch the next page of keys. If this is `null`, then there are no more keys to fetch.
Functions
get: func
A bucket is a collection of key-value pairs. Each key-value pair is stored as a entry in the bucket, and the bucket itself acts as a collection of all these entries.
It is worth noting that the exact terminology for bucket in key-value stores can very depending on the specific implementation. For example:
- Amazon DynamoDB calls a collection of key-value pairs a table
- Redis has hashes, sets, and sorted sets as different types of collections
- Cassandra calls a collection of key-value pairs a column family
- MongoDB calls a collection of key-value pairs a collection
- Riak calls a collection of key-value pairs a bucket
- Memcached calls a collection of key-value pairs a slab
- Azure Cosmos DB calls a collection of key-value pairs a container
In this interface, we use the term bucket
to refer to a collection of key-value pairs
Get the value associated with the specified key
The value is returned as an option. If the key-value pair exists in the
store, it returns Ok(value)
. If the key does not exist in the
store, it returns Ok(none)
.
If any other error occurs, it returns an Err(error)
.
Params
Return values
- result<option<list<
u8
>>,error
>
set: func
Set the value associated with the key in the store. If the key already exists in the store, it overwrites the value.
If the key does not exist in the store, it creates a new key-value pair.
If any other error occurs, it returns an Err(error)
.
Params
Return values
- result<_,
error
>
delete: func
Delete the key-value pair associated with the key in the store.
If the key does not exist in the store, it does nothing.
If any other error occurs, it returns an Err(error)
.
Params
Return values
- result<_,
error
>
exists: func
Check if the key exists in the store.
If the key exists in the store, it returns Ok(true)
. If the key does
not exist in the store, it returns Ok(false)
.
If any other error occurs, it returns an Err(error)
.
Params
Return values
- result<
bool
,error
>
list-keys: func
Get all the keys in the store with an optional cursor (for use in pagination). It
returns a list of keys. Please note that for most KeyValue implementations, this is a
can be a very expensive operation and so it should be used judiciously. Implementations
can return any number of keys in a single response, but they should never attempt to
send more data than is reasonable (i.e. on a small edge device, this may only be a few
KB, while on a large machine this could be several MB). Any response should also return
a cursor that can be used to fetch the next page of keys. See the key-response
record
for more information.
Note that the keys are not guaranteed to be returned in any particular order.
If the store is empty, it returns an empty list.
MAY show an out-of-date list of keys if there are concurrent writes to the store.
If any error occurs, it returns an Err(error)
.
Params
Return values
- result<
key-response
,error
>
Import interface wrpc:keyvalue/atomics@0.2.0-draft
A keyvalue interface that provides atomic operations.
Atomic operations are single, indivisible operations. When a fault causes an atomic operation to fail, it will appear to the invoker of the atomic operation that the action either completed successfully or did nothing at all.
Please note that this interface is bare functions that take a reference to a bucket. This is to
get around the current lack of a way to "extend" a resource with additional methods inside of
wit. Future version of the interface will instead extend these methods on the base bucket
resource.
Types
type error
----
Functions
increment: func
Atomically increment the value associated with the key in the store by the given delta. It returns the new value.
If the key does not exist in the store, it creates a new key-value pair with the value set to the given delta.
If any other error occurs, it returns an Err(error)
.
Params
Return values
- result<
u64
,error
>
Import interface wrpc:keyvalue/batch@0.2.0-draft
A keyvalue interface that provides batch operations.
A batch operation is an operation that operates on multiple keys at once.
Batch operations are useful for reducing network round-trip time. For example, if you want to get the values associated with 100 keys, you can either do 100 get operations or you can do 1 batch get operation. The batch operation is faster because it only needs to make 1 network call instead of 100.
A batch operation does not guarantee atomicity, meaning that if the batch operation fails, some of the keys may have been modified and some may not.
This interface does has the same consistency guarantees as the store
interface, meaning that
you should be able to "read your writes."
Please note that this interface is bare functions that take a reference to a bucket. This is to
get around the current lack of a way to "extend" a resource with additional methods inside of
wit. Future version of the interface will instead extend these methods on the base bucket
resource.
Types
type error
----
Functions
get-many: func
Get the key-value pairs associated with the keys in the store. It returns a list of key-value pairs.
If any of the keys do not exist in the store, it returns a none
value for that pair in the
list.
MAY show an out-of-date value if there are concurrent writes to the store.
If any other error occurs, it returns an Err(error)
.
Params
Return values
- result<list<option<(
string
, list<u8
>)>>,error
>
set-many: func
Set the values associated with the keys in the store. If the key already exists in the store, it overwrites the value.
Note that the key-value pairs are not guaranteed to be set in the order they are provided.
If any of the keys do not exist in the store, it creates a new key-value pair.
If any other error occurs, it returns an Err(error)
. When an error occurs, it does not
rollback the key-value pairs that were already set. Thus, this batch operation does not
guarantee atomicity, implying that some key-value pairs could be set while others might
fail.
Other concurrent operations may also be able to see the partial results.
Params
Return values
- result<_,
error
>
delete-many: func
Delete the key-value pairs associated with the keys in the store.
Note that the key-value pairs are not guaranteed to be deleted in the order they are provided.
If any of the keys do not exist in the store, it skips the key.
If any other error occurs, it returns an Err(error)
. When an error occurs, it does not
rollback the key-value pairs that were already deleted. Thus, this batch operation does not
guarantee atomicity, implying that some key-value pairs could be deleted while others might
fail.
Other concurrent operations may also be able to see the partial results.
Params
Return values
- result<_,
error
>
Import interface wasi:io/error@0.2.0
Types
resource error
A resource which represents some error information.
The only method provided by this resource is to-debug-string
,
which provides some human-readable information about the error.
In the wasi:io
package, this resource is returned through the
wasi:io/streams/stream-error
type.
To provide more specific error information, other interfaces may
provide functions to further "downcast" this error into more specific
error information. For example, error
s returned in streams derived
from filesystem types to be described using the filesystem's own
error-code type, using the function
wasi:filesystem/types/filesystem-error-code
, which takes a parameter
borrow<error>
and returns
option<wasi:filesystem/types/error-code>
.
The set of functions which can "downcast" an error
into a more
concrete type is open.
Functions
[method]error.to-debug-string: func
Returns a string that is suitable to assist humans in debugging this error.
WARNING: The returned string should not be consumed mechanically! It may change across platforms, hosts, or other implementation details. Parsing this string is a major platform-compatibility hazard.
Params
self
: borrow<error
>
Return values
Import interface wasi:io/poll@0.2.0
A poll API intended to let users wait for I/O events on multiple handles at once.
Types
resource pollable
pollable
represents a single I/O event which may be ready, or not.
Functions
[method]pollable.ready: func
Return the readiness of a pollable. This function never blocks.
Returns true
when the pollable is ready, and false
otherwise.
Params
self
: borrow<pollable
>
Return values
[method]pollable.block: func
block
returns immediately if the pollable is ready, and otherwise
blocks until ready.
This function is equivalent to calling poll.poll
on a list
containing only this pollable.
Params
self
: borrow<pollable
>
poll: func
Poll for completion on a set of pollables.
This function takes a list of pollables, which identify I/O sources of interest, and waits until one or more of the events is ready for I/O.
The result list<u32>
contains one or more indices of handles in the
argument list that is ready for I/O.
If the list contains more elements than can be indexed with a u32
value, this function traps.
A timeout can be implemented by adding a pollable from the wasi-clocks API to the list.
This function does not return a result
; polling in itself does not
do any I/O so it doesn't fail. If any of the I/O sources identified by
the pollables has an error, it is indicated by marking the source as
being reaedy for I/O.
Params
in
: list<borrow<pollable
>>
Return values
Import interface wasi:io/streams@0.2.0
WASI I/O is an I/O abstraction API which is currently focused on providing stream types.
In the future, the component model is expected to add built-in stream types; when it does, they are expected to subsume this API.
Types
type error
#### `type pollable` [`pollable`](#pollable)
An error for input-stream and output-stream operations.
Variant Cases
-
last-operation-failed
: own<error
>The last operation (a write or flush) failed before completion.
More information is available in the
error
payload. -
The stream is closed: no more input will be accepted by the stream. A closed output-stream will return this error on all future operations.
resource input-stream
An input bytestream.
input-stream
s are non-blocking to the extent practical on underlying
platforms. I/O operations always return promptly; if fewer bytes are
promptly available than requested, they return the number of bytes promptly
available, which could even be zero. To wait for data to be available,
use the subscribe
function to obtain a pollable
which can be polled
for using wasi:io/poll
.
resource output-stream
An output bytestream.
output-stream
s are non-blocking to the extent practical on
underlying platforms. Except where specified otherwise, I/O operations also
always return promptly, after the number of bytes that can be written
promptly, which could even be zero. To wait for the stream to be ready to
accept data, the subscribe
function to obtain a pollable
which can be
polled for using wasi:io/poll
.
Functions
[method]input-stream.read: func
Perform a non-blocking read from the stream.
When the source of a read
is binary data, the bytes from the source
are returned verbatim. When the source of a read
is known to the
implementation to be text, bytes containing the UTF-8 encoding of the
text are returned.
This function returns a list of bytes containing the read data,
when successful. The returned list will contain up to len
bytes;
it may return fewer than requested, but not more. The list is
empty when no bytes are available for reading at this time. The
pollable given by subscribe
will be ready when more bytes are
available.
This function fails with a stream-error
when the operation
encounters an error, giving last-operation-failed
, or when the
stream is closed, giving closed
.
When the caller gives a len
of 0, it represents a request to
read 0 bytes. If the stream is still open, this call should
succeed and return an empty list, or otherwise fail with closed
.
The len
parameter is a u64
, which could represent a list of u8 which
is not possible to allocate in wasm32, or not desirable to allocate as
as a return value by the callee. The callee may return a list of bytes
less than len
in size while more bytes are available for reading.
Params
self
: borrow<input-stream
>len
:u64
Return values
- result<list<
u8
>,stream-error
>
[method]input-stream.blocking-read: func
Read bytes from a stream, after blocking until at least one byte can
be read. Except for blocking, behavior is identical to read
.
Params
self
: borrow<input-stream
>len
:u64
Return values
- result<list<
u8
>,stream-error
>
[method]input-stream.skip: func
Skip bytes from a stream. Returns number of bytes skipped.
Behaves identical to read
, except instead of returning a list
of bytes, returns the number of bytes consumed from the stream.
Params
self
: borrow<input-stream
>len
:u64
Return values
- result<
u64
,stream-error
>
[method]input-stream.blocking-skip: func
Skip bytes from a stream, after blocking until at least one byte
can be skipped. Except for blocking behavior, identical to skip
.
Params
self
: borrow<input-stream
>len
:u64
Return values
- result<
u64
,stream-error
>
[method]input-stream.subscribe: func
Create a pollable
which will resolve once either the specified stream
has bytes available to read or the other end of the stream has been
closed.
The created pollable
is a child resource of the input-stream
.
Implementations may trap if the input-stream
is dropped before
all derived pollable
s created with this function are dropped.
Params
self
: borrow<input-stream
>
Return values
- own<
pollable
>
[method]output-stream.check-write: func
Check readiness for writing. This function never blocks.
Returns the number of bytes permitted for the next call to write
,
or an error. Calling write
with more bytes than this function has
permitted will trap.
When this function returns 0 bytes, the subscribe
pollable will
become ready when this function will report at least 1 byte, or an
error.
Params
self
: borrow<output-stream
>
Return values
- result<
u64
,stream-error
>
[method]output-stream.write: func
Perform a write. This function never blocks.
When the destination of a write
is binary data, the bytes from
contents
are written verbatim. When the destination of a write
is
known to the implementation to be text, the bytes of contents
are
transcoded from UTF-8 into the encoding of the destination and then
written.
Precondition: check-write gave permit of Ok(n) and contents has a length of less than or equal to n. Otherwise, this function will trap.
returns Err(closed) without writing if the stream has closed since the last call to check-write provided a permit.
Params
self
: borrow<output-stream
>contents
: list<u8
>
Return values
- result<_,
stream-error
>
[method]output-stream.blocking-write-and-flush: func
Perform a write of up to 4096 bytes, and then flush the stream. Block until all of these operations are complete, or an error occurs.
This is a convenience wrapper around the use of check-write
,
subscribe
, write
, and flush
, and is implemented with the
following pseudo-code:
let pollable = this.subscribe();
while !contents.is_empty() {
// Wait for the stream to become writable
pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, contents.len());
let (chunk, rest) = contents.split_at(len);
this.write(chunk ); // eliding error handling
contents = rest;
}
this.flush();
// Wait for completion of `flush`
pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write(); // eliding error handling
Params
self
: borrow<output-stream
>contents
: list<u8
>
Return values
- result<_,
stream-error
>
[method]output-stream.flush: func
Request to flush buffered output. This function never blocks.
This tells the output-stream that the caller intends any buffered
output to be flushed. the output which is expected to be flushed
is all that has been passed to write
prior to this call.
Upon calling this function, the output-stream
will not accept any
writes (check-write
will return ok(0)
) until the flush has
completed. The subscribe
pollable will become ready when the
flush has completed and the stream can accept more writes.
Params
self
: borrow<output-stream
>
Return values
- result<_,
stream-error
>
[method]output-stream.blocking-flush: func
Request to flush buffered output, and block until flush completes and stream is ready for writing again.
Params
self
: borrow<output-stream
>
Return values
- result<_,
stream-error
>
[method]output-stream.subscribe: func
Create a pollable
which will resolve once the output-stream
is ready for more writing, or an error has occured. When this
pollable is ready, check-write
will return ok(n)
with n>0, or an
error.
If the stream is closed, this pollable is always ready immediately.
The created pollable
is a child resource of the output-stream
.
Implementations may trap if the output-stream
is dropped before
all derived pollable
s created with this function are dropped.
Params
self
: borrow<output-stream
>
Return values
- own<
pollable
>
[method]output-stream.write-zeroes: func
Write zeroes to a stream.
This should be used precisely like write
with the exact same
preconditions (must use check-write first), but instead of
passing a list of bytes, you simply pass the number of zero-bytes
that should be written.
Params
self
: borrow<output-stream
>len
:u64
Return values
- result<_,
stream-error
>
[method]output-stream.blocking-write-zeroes-and-flush: func
Perform a write of up to 4096 zeroes, and then flush the stream. Block until all of these operations are complete, or an error occurs.
This is a convenience wrapper around the use of check-write
,
subscribe
, write-zeroes
, and flush
, and is implemented with
the following pseudo-code:
let pollable = this.subscribe();
while num_zeroes != 0 {
// Wait for the stream to become writable
pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, num_zeroes);
this.write-zeroes(len); // eliding error handling
num_zeroes -= len;
}
this.flush();
// Wait for completion of `flush`
pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write(); // eliding error handling
Params
self
: borrow<output-stream
>len
:u64
Return values
- result<_,
stream-error
>
[method]output-stream.splice: func
Read from one stream and write to another.
The behavior of splice is equivelant to:
- calling
check-write
on theoutput-stream
- calling
read
on theinput-stream
with the smaller of thecheck-write
permitted length and thelen
provided tosplice
- calling
write
on theoutput-stream
with that read data.
Any error reported by the call to check-write
, read
, or
write
ends the splice and reports that error.
This function returns the number of bytes transferred; it may be less
than len
.
Params
self
: borrow<output-stream
>src
: borrow<input-stream
>len
:u64
Return values
- result<
u64
,stream-error
>
[method]output-stream.blocking-splice: func
Read from one stream and write to another, with blocking.
This is similar to splice
, except that it blocks until the
output-stream
is ready for writing, and the input-stream
is ready for reading, before performing the splice
.
Params
self
: borrow<output-stream
>src
: borrow<input-stream
>len
:u64
Return values
- result<
u64
,stream-error
>
Import interface wasi:blobstore/types@0.2.0-draft
Types used by blobstore
Types
type input-stream
#### `type output-stream` [`output-stream`](#output_stream)
#### `type container-name` `string`
name of a container, a collection of objects. The container name may be any valid UTF-8 string.
type object-name
string
name of an object within a container The object name may be any valid UTF-8 string.
type timestamp
u64
TODO: define timestamp to include seconds since Unix epoch and nanoseconds https://github.com/WebAssembly/wasi-blob-store/issues/7
type object-size
u64
size of an object, in bytes
type error
string
#### `record container-metadata`
information about a container
Record Fields
-
name
:container-name
the container's name
-
created-at
:timestamp
date and time container was created
record object-metadata
information about an object
Record Fields
-
name
:object-name
the object's name
-
container
:container-name
the object's parent container
-
created-at
:timestamp
date and time the object was created
-
size
:object-size
size of the object, in bytes
record object-id
identifier for an object that includes its container name
Record Fields
container
:container-name
object
:object-name
resource outgoing-value
A data is the data stored in a data blob. The value can be of any type
that can be represented in a byte array. It provides a way to write the value
to the output-stream defined in the wasi-io
interface.
Soon: switch to resource value { ... }
resource incoming-value
A incoming-value is a wrapper around a value. It provides a way to read the value
from the input-stream defined in the wasi-io
interface.
The incoming-value provides two ways to consume the value:
incoming-value-consume-sync
consumes the value synchronously and returns the value as a list of bytes.incoming-value-consume-async
consumes the value asynchronously and returns the value as an input-stream. Soon: switch toresource incoming-value { ... }
type incoming-value-async-body
#### `type incoming-value-sync-body` [`incoming-value-sync-body`](#incoming_value_sync_body)
----
Functions
[static]outgoing-value.new-outgoing-value: func
Return values
- own<
outgoing-value
>
[method]outgoing-value.outgoing-value-write-body: func
Returns a stream for writing the value contents.
The returned output-stream
is a child resource: it must be dropped
before the parent outgoing-value
resource is dropped (or finished),
otherwise the outgoing-value
drop or finish
will trap.
Returns success on the first call: the output-stream
resource for
this outgoing-value
may be retrieved at most once. Subsequent calls
will return error.
Params
self
: borrow<outgoing-value
>
Return values
- result<own<
output-stream
>>
[static]outgoing-value.finish: func
Finalize an outgoing value. This must be
called to signal that the outgoing value is complete. If the outgoing-value
is dropped without calling outgoing-value.finalize
, the implementation
should treat the value as corrupted.
Params
this
: own<outgoing-value
>
Return values
- result<_,
error
>
[static]incoming-value.incoming-value-consume-sync: func
Params
this
: own<incoming-value
>
Return values
- result<
incoming-value-sync-body
,error
>
[static]incoming-value.incoming-value-consume-async: func
Params
this
: own<incoming-value
>
Return values
- result<own<
incoming-value-async-body
>,error
>
[method]incoming-value.size: func
Params
self
: borrow<incoming-value
>
Return values
Import interface wrpc:blobstore/types@0.1.0
Types
type wasi-container-metadata
#### `type wasi-container-name` [`container-name`](#container_name)
#### `type wasi-object-id` [`object-id`](#object_id)
#### `type wasi-object-metadata` [`object-metadata`](#object_metadata)
#### `type timestamp` [`timestamp`](#timestamp)
#### `type object-size` [`object-size`](#object_size)
#### `record container-metadata`
information about a container
Record Fields
created-at
:timestamp
date and time container was created
type container-name
#### `type object-id` [`wasi-object-id`](#wasi_object_id)
information about an object
Record Fields
-
created-at
:timestamp
date and time the object was created
-
size
:object-size
size of the object, in bytes
Import interface wrpc:blobstore/blobstore@0.1.0
Types
type container-name
#### `type container-metadata` [`container-metadata`](#container_metadata)
#### `type object-metadata` [`object-metadata`](#object_metadata)
#### `type object-id` [`object-id`](#object_id)
----
Functions
clear-container: func
Params
Return values
container-exists: func
Params
Return values
create-container: func
Params
Return values
delete-container: func
Params
Return values
get-container-info: func
Params
Return values
- result<
container-metadata
,string
>
list-container-objects: func
Params
Return values
copy-object: func
Params
Return values
delete-object: func
Params
id
:object-id
Return values
delete-objects: func
Params
Return values
get-container-data: func
Params
id
:object-id
start
:u64
end
:u64
Return values
get-object-info: func
Params
id
:object-id
Return values
- result<
object-metadata
,string
>
has-object: func
Params
id
:object-id
Return values
move-object: func
Params
Return values
write-container-data: func
Params
id
:object-id
data
: stream<u8
>
Return values
Export interface wasmcloud:messaging/handler@0.2.0
Types
type broker-message
----
Functions
handle-message: func
Callback handled to invoke a function when a message is received from a subscription
Params
msg
:broker-message