a Container is a collection of objects
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.
use record container-metadata
from wasi:blobstore/types@0.2.0-draft
information about a container
name:container-namethe container's name
created-at:timestampdate and time container was created
use resource incoming-value
from wasi:blobstore/types@0.2.0-draft
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
use record object-metadata
from wasi:blobstore/types@0.2.0-draft
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
use type object-name
from wasi:blobstore/types@0.2.0-draft
name of an object within a container The object name may be any valid UTF-8 string.
string
use resource outgoing-value
from wasi:blobstore/types@0.2.0-draft
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 container
this defines the container resource
name: func() -> result<string, error>returns container name
info: func() -> result<container-metadata, error>returns container metadata
get-data: func( name: object-name, start: u64, end: u64, ) -> result<incoming-value, error>retrieves an object or portion of an object, as a resource. Start and end offsets are inclusive. Once a data-blob resource has been created, the underlying bytes are held by the blobstore service for the lifetime of the data-blob resource, even if the object they came from is later deleted.
write-data: func( name: object-name, data: borrow<outgoing-value>, ) -> result<_, error>creates or replaces an object with the data blob.
list-objects: func() -> result<stream-object-names, error>returns list of objects in the container. Order is undefined.
delete-object: func(name: object-name) -> result<_, error>deletes object. does not return error if object did not exist.
delete-objects: func(names: list<object-name>) -> result<_, error>deletes multiple objects in the container
has-object: func(name: object-name) -> result<bool, error>returns true if the object exists in this container
object-info: func(name: object-name) -> result<object-metadata, error>returns metadata for the object
clear: func() -> result<_, error>removes all objects within the container, leaving the container empty.
resource stream-object-names
this defines the stream-object-names resource which is a representation of stream
read-stream-object-names: func( len: u64, ) -> result<tuple<list<object-name>, bool>, error>reads the next number of objects from the stream
This function returns the list of objects read, and a boolean indicating if the end of the stream was reached.
skip-stream-object-names: func( num: u64, ) -> result<tuple<u64, bool>, error>skip the next number of objects in the stream
This function returns the number of objects skipped, and a boolean indicating if the end of the stream was reached.
WIT
/// a Container is a collection of objects
interface container {
use wasi:io/streams@0.2.1.{input-stream, output-stream};
use types.{container-metadata, error, incoming-value, object-metadata, object-name, outgoing-value};
/// this defines the `container` resource
resource container {
/// returns container name
name: func() -> result<string, error>;
/// returns container metadata
info: func() -> result<container-metadata, error>;
/// retrieves an object or portion of an object, as a resource.
/// Start and end offsets are inclusive.
/// Once a data-blob resource has been created, the underlying bytes are held by the blobstore service for the lifetime
/// of the data-blob resource, even if the object they came from is later deleted.
get-data: func(name: object-name, start: u64, end: u64) -> result<incoming-value, error>;
/// creates or replaces an object with the data blob.
write-data: func(name: object-name, data: borrow<outgoing-value>) -> result<_, error>;
/// returns list of objects in the container. Order is undefined.
list-objects: func() -> result<stream-object-names, error>;
/// deletes object.
/// does not return error if object did not exist.
delete-object: func(name: object-name) -> result<_, error>;
/// deletes multiple objects in the container
delete-objects: func(names: list<object-name>) -> result<_, error>;
/// returns true if the object exists in this container
has-object: func(name: object-name) -> result<bool, error>;
/// returns metadata for the object
object-info: func(name: object-name) -> result<object-metadata, error>;
/// removes all objects within the container, leaving the container empty.
clear: func() -> result<_, error>;
}
/// this defines the `stream-object-names` resource which is a representation of stream<object-name>
resource stream-object-names {
/// reads the next number of objects from the stream
///
/// This function returns the list of objects read, and a boolean indicating if the end of the stream was reached.
read-stream-object-names: func(len: u64) -> result<tuple<list<object-name>, bool>, error>;
/// skip the next number of objects in the stream
///
/// This function returns the number of objects skipped, and a boolean indicating if the end of the stream was reached.
skip-stream-object-names: func(num: u64) -> result<tuple<u64, bool>, error>;
}
}