// # wasi-cloud blobstore service definition
//
// A blobstore is service that can mange containers and objects.
//
// ## Object
// An object is a named sequence of bytes. Objects can be read or written with a stream interface.
// Once an object is written its contents cannot be modified.
// Objects can be any size from 1 byte up to the limits imposed by the underlying store.
// Object names are unique within their container.
//
// ## Container
// A container is a named collection of objects. Container names can be any utf-8 string.
// Within any instance of the blobstore interface, all containers share the same "flat" namespace.
// wasi-cloud Blobstore service definition
interface "wasi:blob/blobstore" {
use wasi:blob/types::{ Error, container-metadata, 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>
}
// a Container is a collection of objects
resource "wasi:blob/container" {
// returns container name
name: func() -> result<string, Error>
// returns container metadata
info: func() -> result<container-metadata, Error>
// begins reading an object
read-object: func(name: object-name) -> result<read-stream, Error>
// creates or replaces an object.
write-object: func(name: object-name) -> result<write-stream, 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<data-blob, Error>
// creates or replaces an object with the data blob.
write-data: func(name: object-name, data: data-blob) -> result<_, Error>
// returns list of objects in the container. Order is undefined.
list-objects: func(name: object-name) -> result<stream<object-name>, 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>
}
// A write stream for saving an object to a blobstore.
resource "wasi:blob/write-stream" {
// writes (appends) bytes to the object.
write: func(data: list<u8>) -> result<_, Error>
// closes the write stream
close: func() -> result<_,Error>
}
// A read stream for retrieving an object (or object region) from blob store
resource "wasi:blob/read-stream" {
// reads bytes from the object into an existing array,
// until the buffer is full or the end of the stream.
// Returns number of bytes written, or none if the stream has ended.
read-into: func(ref mut list<u8>) -> result<option<u64>, Error>
// returns the number of bytes remaining that could be read until the end of the stream.
available: func() -> result<u64, Error>
// closes the read stream. May be used by reader to signal that it is not interested in reading more bytes.
close: func() -> result<_, Error>
}
// A data-blob resource references a byte array. It is intended to be lightweight
// and can be passed to other components, without the overhead of copying the underlying bytes.
// A data-blob can be created with object::get-data(), or with the create() function below.
resource "wasi:blob/data-blob" {
// creates a new data blob
create: func() -> data-blob-writer
// begins reading this data-blob
read: func() -> result<read-stream, Error>
// returns the total size of this data-blob
size: func() -> result<u64, Error>
}
// A data-blob-writer is a writable stream that creates a transient data-blob.
// The data-blob can later be saved to an object with container::write-data()
resource "wasi:blob/data-blob-writer" {
// append bytes to a data-blob
write: func(data: list<u8>) -> result<_, Error>
// finish writing blob
finalize: func() -> result<data-blob, Error>
}
// Types used by blobstore
interface "wasi:blob/types" {
// 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
// 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: u64,
}
// identifier for an object that includes its container name
record object-id {
container: container-name,
object: object-name
}
}