componentized

Interfaces

  • types โ€” Types used by blobstore
  • container โ€” a Container is a collection of objects
  • blobstore โ€” wasi-cloud Blobstore service definition

Worlds

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;
}