container.wit

package wasi:blobstore

// a Container is a collection of objects
interface container {
  use types.{ object-name, object-metadata, container-metadata, error }
  use data-blob.{ data-blob }

  use wasi:io/streams.{input-stream, output-stream}
  use wasi:poll/poll.{ pollable }

  type read-stream = input-stream
  type write-stream = output-stream


  // this defines the `container` resource
  type container = u32
  drop-container: func(container: container)


  // returns container name
  name: func(container: container) -> result<string, error>

  // returns container metadata
  info: func(container: container) -> result<container-metadata, error>


  // begins reading an object
  read-object: func(container: container, name: object-name) -> result<read-stream, error>

  // creates or replaces an object.
  write-object: func(container: container, 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(container: container, name: object-name, start: u64, end: u64) -> result<data-blob, error>

  // creates or replaces an object with the data blob.
  write-data: func(container: container, name: object-name, data: data-blob) -> result<_, error>

  // this defines the `stream-object-names` resource which is a representation of stream<object-name>
  type stream-object-names = u32
  
  drop-stream-object-names: func(names: 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(this: stream-object-names, 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(this: stream-object-names, num: u64) -> result<tuple<u64, bool>, error>


  // returns list of objects in the container. Order is undefined.
  list-objects: func(container: container) -> result<stream-object-names, error>

  // deletes object.
  // does not return error if object did not exist.
  delete-object: func(container: container, name: object-name) -> result<_, error>

  // deletes multiple objects in the container
  delete-objects: func(container: container, names: list<object-name>) -> result<_, error>

  // returns true if the object exists in this container
  has-object: func(container: container, name: object-name) -> result<bool, error>

  // returns metadata for the object
  object-info: func(container: container, name: object-name) -> result<object-metadata, error>

  // removes all objects within the container, leaving the container empty.
  clear: func(container: container) -> result<_, error>
}