blob-store.wit

// wasi-blob-store based on https://github.com/WebAssembly/wasi-blob-store

use { container-metadata, object-name, object-metadata, object-id } from blob-types

// a Container is a collection of objects
resource container {
	static open: func(name: string) -> expected<container, error>

	// returns container name
	name: func() -> expected<string, error>
  
	// returns container metadata
	info: func() -> expected<container-metadata, error>
  
	// begins reading an object
	read-object: func(name: object-name) -> expected<read-stream, error>
  
	// creates or replaces an object.
	write-object: func(name: object-name) -> expected<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) -> expected<data-blob, error>
  
	// creates or replaces an object with the data blob.
	// write-data: func(name: object-name, data: data-blob) -> expected<unit, error>

	// returns list of objects in the container. Order is undefined.
	list-objects: func() -> expected<list<object-name>, error>
  
	// deletes object.
	// does not return error if object did not exist.
	delete-object: func(name: object-name) -> expected<unit, error>
  
	// deletes multiple objects in the container
	delete-objects: func(names: list<object-name>) -> expected<unit, error>
  
	// returns true if the object exists in this container
	has-object: func(name: object-name) -> expected<bool, error>
  
	// returns metadata for the object
	object-info: func(name: object-name) -> expected<object-metadata, error>
  
	// removes all objects within the container, leaving the container empty.
	clear: func() -> expected<unit, error>
  }

// A write stream for saving an object to a blobstore.
resource write-stream {

	// writes (appends) bytes to the object.
	write: func(data: list<u8>) -> expected<unit, error>
  
	// closes the write stream
	close: func() -> expected<unit,error>
  }

  
// A read stream for retrieving an object (or object region) from blob store
resource 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: list<u8>) -> expected<option<u64>, error>

	read: func(size: u64) -> expected<option<list<u8>>, error>
  
	// returns the number of bytes remaining that could be read until the end of the stream.
	available: func() -> expected<u64, 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() 
resource data-blob {
	// creates a new data blob
	create: func() -> data-blob-writer
	// begins reading this data-blob
	read: func() -> expected<read-stream, error>
	// returns the total size of this data-blob
	size: func() -> expected<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 data-blob-writer {
	// append bytes to a data-blob
	write: func(data: list<u8>) -> expected<unit, error>
	// finish writing blob
	finalize: func() -> expected<data-blob, error>
}

*/

/// common keyvalue errors
variant error {
	unexpected-error(string)
}