Types used by blobstore
Types
use resource input-stream
An input bytestream.
input-streams 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.
read: func(len: u64) -> result<list<u8>, stream-error>since 0.2.0Perform a non-blocking read from the stream.
When the source of a
readis binary data, the bytes from the source are returned verbatim. When the source of areadis 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
lenbytes; 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 bysubscribewill be ready when more bytes are available.This function fails with a
stream-errorwhen the operation encounters an error, givinglast-operation-failed, or when the stream is closed, givingclosed.When the caller gives a
lenof 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 withclosed.The
lenparameter is au64, 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 thanlenin size while more bytes are available for reading.blocking-read: func(len: u64) -> result<list<u8>, stream-error>since 0.2.0Read bytes from a stream, after blocking until at least one byte can be read. Except for blocking, behavior is identical to
read.skip: func(len: u64) -> result<u64, stream-error>since 0.2.0Skip 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.blocking-skip: func(len: u64) -> result<u64, stream-error>since 0.2.0Skip bytes from a stream, after blocking until at least one byte can be skipped. Except for blocking behavior, identical to
skip.subscribe: func() -> pollablesince 0.2.0Create a
pollablewhich will resolve once either the specified stream has bytes available to read or the other end of the stream has been closed. The createdpollableis a child resource of theinput-stream. Implementations may trap if theinput-streamis dropped before all derivedpollables created with this function are dropped.
use resource output-stream
An output bytestream.
output-streams 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.
Dropping an output-stream while there's still an active write in
progress may result in the data being lost. Before dropping the stream,
be sure to fully flush your writes.
check-write: func() -> result<u64, stream-error>since 0.2.0Check readiness for writing. This function never blocks.
Returns the number of bytes permitted for the next call to
write, or an error. Callingwritewith more bytes than this function has permitted will trap.When this function returns 0 bytes, the
subscribepollable will become ready when this function will report at least 1 byte, or an error.write: func(contents: list<u8>) -> result<_, stream-error>since 0.2.0Perform a write. This function never blocks.
When the destination of a
writeis binary data, the bytes fromcontentsare written verbatim. When the destination of awriteis known to the implementation to be text, the bytes ofcontentsare 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.
blocking-write-and-flush: func( contents: list<u8>, ) -> result<_, stream-error>since 0.2.0Perform 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, andflush, 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 handlingflush: func() -> result<_, stream-error>since 0.2.0Request 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
writeprior to this call.Upon calling this function, the
output-streamwill not accept any writes (check-writewill returnok(0)) until the flush has completed. Thesubscribepollable will become ready when the flush has completed and the stream can accept more writes.blocking-flush: func() -> result<_, stream-error>since 0.2.0Request to flush buffered output, and block until flush completes and stream is ready for writing again.
subscribe: func() -> pollableCreate a
pollablewhich will resolve once the output-stream is ready for more writing, or an error has occurred. When this pollable is ready,check-writewill returnok(n)with n>0, or an error.If the stream is closed, this pollable is always ready immediately.
The created
pollableis a child resource of theoutput-stream. Implementations may trap if theoutput-streamis dropped before all derivedpollables created with this function are dropped.write-zeroes: func(len: u64) -> result<_, stream-error>since 0.2.0Write zeroes to a stream.
This should be used precisely like
writewith 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.blocking-write-zeroes-and-flush: func( len: u64, ) -> result<_, stream-error>since 0.2.0Perform 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, andflush, 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 handlingsplice: func( src: borrow<input-stream>, len: u64, ) -> result<u64, stream-error>since 0.2.0Read from one stream and write to another.
The behavior of splice is equivalent to:
- calling
check-writeon theoutput-stream - calling
readon theinput-streamwith the smaller of thecheck-writepermitted length and thelenprovided tosplice - calling
writeon theoutput-streamwith that read data.
Any error reported by the call to
check-write,read, orwriteends the splice and reports that error.This function returns the number of bytes transferred; it may be less than
len.- calling
blocking-splice: func( src: borrow<input-stream>, len: u64, ) -> result<u64, stream-error>since 0.2.0Read from one stream and write to another, with blocking.
This is similar to
splice, except that it blocks until theoutput-streamis ready for writing, and theinput-streamis ready for reading, before performing thesplice.
type container-name
name of a container, a collection of objects. The container name may be any valid UTF-8 string.
string
type object-name
name of an object within a container The object name may be any valid UTF-8 string.
string
type timestamp
TODO: define timestamp to include seconds since Unix epoch and nanoseconds https://github.com/WebAssembly/wasi-blob-store/issues/7
u64
type object-size
size of an object, in bytes
u64
type error
string
record container-metadata
information about a container
name:container-namethe container's name
created-at:timestampdate and time container was created
record object-metadata
information about an object
name:object-namethe object's name
container:container-namethe object's parent container
created-at:timestampdate and time the object was created
size:object-sizesize of the object, in bytes
record object-id
identifier for an object that includes its container name
container:container-nameobject: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 { ... }
new-outgoing-value: static func() -> outgoing-valueoutgoing-value-write-body: func() -> result<output-stream>Returns a stream for writing the value contents.
The returned
output-streamis a child resource: it must be dropped before the parentoutgoing-valueresource is dropped (or finished), otherwise theoutgoing-valuedrop orfinishwill trap.Returns success on the first call: the
output-streamresource for thisoutgoing-valuemay be retrieved at most once. Subsequent calls will return error.finish: static func(this: outgoing-value) -> result<_, error>Finalize an outgoing value. This must be called to signal that the outgoing value is complete. If the
outgoing-valueis dropped without callingoutgoing-value.finalize, the implementation should treat the value as corrupted.
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-syncconsumes the value synchronously and returns the value as a list of bytes.incoming-value-consume-asyncconsumes the value asynchronously and returns the value as an input-stream. Soon: switch toresource incoming-value { ... }
incoming-value-consume-sync: static func( this: incoming-value, ) -> result<incoming-value-sync-body, error>incoming-value-consume-async: static func( this: incoming-value, ) -> result<incoming-value-async-body, error>size: func() -> u64
type incoming-value-async-body
type incoming-value-sync-body
list<u8>
WIT
/// Types used by blobstore
interface types {
use wasi:io/streams@0.2.1.{input-stream, output-stream};
/// name of a container, a collection of objects.
/// The container name may be any valid UTF-8 string.
type container-name = string;
/// name of an object within a container
/// The object name may be any valid UTF-8 string.
type object-name = string;
/// TODO: define timestamp to include seconds since
/// Unix epoch and nanoseconds
/// https://github.com/WebAssembly/wasi-blob-store/issues/7
type timestamp = u64;
/// size of an object, in bytes
type object-size = u64;
type error = string;
/// information about a container
record container-metadata {
/// the container's name
name: container-name,
/// date and time container was created
created-at: timestamp,
}
/// information about an object
record object-metadata {
/// the object's name
name: object-name,
/// the object's parent container
container: container-name,
/// date and time the object was created
created-at: timestamp,
/// size of the object, in bytes
size: object-size,
}
/// identifier for an object that includes its container name
record object-id {
container: container-name,
object: object-name,
}
/// 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 outgoing-value {
new-outgoing-value: static func() -> outgoing-value;
/// 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.
outgoing-value-write-body: func() -> result<output-stream>;
/// 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.
finish: static func(this: outgoing-value) -> result<_, error>;
}
/// 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:
/// 1. `incoming-value-consume-sync` consumes the value synchronously and returns the
/// value as a list of bytes.
/// 2. `incoming-value-consume-async` consumes the value asynchronously and returns the
/// value as an input-stream.
/// Soon: switch to `resource incoming-value { ... }`
resource incoming-value {
incoming-value-consume-sync: static func(this: incoming-value) -> result<incoming-value-sync-body, error>;
incoming-value-consume-async: static func(this: incoming-value) -> result<incoming-value-async-body, error>;
size: func() -> u64;
}
type incoming-value-async-body = input-stream;
type incoming-value-sync-body = list<u8>;
}