WIT
package wasi:blobstore@0.2.0-draft;
/// 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>;
}
/// 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>;
}
}
/// wasi-cloud Blobstore service definition
interface blobstore {
use container.{container};
use types.{error, container-name, object-id};
/// creates a new empty container
create-container: func(name: container-name) -> result<container, error>;
/// retrieves a container by name
get-container: func(name: container-name) -> result<container, error>;
/// deletes a container and all objects within it
delete-container: func(name: container-name) -> result<_, error>;
/// returns true if the container exists
container-exists: func(name: container-name) -> result<bool, error>;
/// copies (duplicates) an object, to the same or a different container.
/// returns an error if the target container does not exist.
/// overwrites destination object if it already existed.
copy-object: func(src: object-id, dest: object-id) -> result<_, error>;
/// moves or renames an object, to the same or a different container
/// returns an error if the destination container does not exist.
/// overwrites destination object if it already existed.
move-object: func(src: object-id, dest: object-id) -> result<_, error>;
}
world imports {
import wasi:io/error@0.2.1;
import wasi:io/poll@0.2.1;
import wasi:io/streams@0.2.1;
import types;
import container;
import blobstore;
}