diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f69e7de..951946a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -13,4 +13,4 @@ jobs: - uses: actions/checkout@v2 - uses: WebAssembly/wit-abi-up-to-date@v17 with: - wit-bindgen: '0.18.0' + wit-bindgen: '0.22.0' diff --git a/README.md b/README.md index ebaf490..23b0f7b 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Phase 1 - Jiaxiao Zhou - Kevin Hoffman - David Justice -- Dan Chiarlon +- Dan Chiarlone - Taylor Thomas ### Phase 4 Advancement Criteria @@ -23,28 +23,45 @@ Phase 1 ## Table of Contents -- [Introduction](#introduction) -- [Goals](#goals) -- [Non-goals](#non-goals) -- [API walk-through](#api-walk-through) - - [Process Blob Contents](#process-blob-contents) - - [Write to a Blob Stream](#write-to-a-blob-stream) - - [List Objects within a Container](#list-objects-within-a-container) -- [Detailed Design Discussion](#detailed-design-discussion) - - [Handling Large Files](#handling-large-files) -- [Stakeholder Interest & Feedback](#stakeholder-interest--feedback) +- [WASI Blob Store](#wasi-blob-store) + - [Current Phase](#current-phase) + - [Champions](#champions) + - [Phase 4 Advancement Criteria](#phase-4-advancement-criteria) + - [Table of Contents](#table-of-contents) + - [Introduction](#introduction) + - [Goals](#goals) + - [Non-goals](#non-goals) + - [API walk-through](#api-walk-through) + - [Process Blob Contents](#process-blob-contents) + - [Write to a Blob Stream](#write-to-a-blob-stream) + - [List Objects within a Container](#list-objects-within-a-container) + - [Detailed Design Discussion](#detailed-design-discussion) + - [Handling Large Files](#handling-large-files) + - [Stakeholder Interest \& Feedback](#stakeholder-interest--feedback) ### Introduction -**Blob storage** is a type of data storage used for unstructured data such as images, videos, documents, backups, etc. Blob storage is also commonly referred to as _object storage_. The term **blob** is actually an acronym for **B**inary **L**arge **OB**ject but can be used to refer to all types of unstructured data. +**Blob storage** is a type of data storage used for unstructured data such as images, videos, +documents, backups, etc. Blob storage is also commonly referred to as _object storage_. The term +**blob** is actually an acronym for **B**inary **L**arge **OB**ject but can be used to refer to all +types of unstructured data. -Within the context of this proposal, blob storage refers to granting WebAssembly components access to a common abstraction of a blob store. Examples of blob storage services include [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/), [AWS S3](https://aws.amazon.com/s3/), or [Google Cloud Storage](https://cloud.google.com/storage), but can be anything that can be represented as unstructured binary data that conforms to the interface, including file systems. +Within the context of this proposal, blob storage refers to granting WebAssembly components access +to a common abstraction of a blob store. Examples of blob storage services include [Azure Blob +Storage](https://azure.microsoft.com/en-us/services/storage/blobs/), [AWS +S3](https://aws.amazon.com/s3/), or [Google Cloud Storage](https://cloud.google.com/storage), but +can be anything that can be represented as unstructured binary data that conforms to the interface, +including file systems. ### Goals -The primary goal of this API is to provide a common abstraction for blob storage services, so that WebAssembly components can be written to work with any implementation, without needing to know the details of the underlying service. +The primary goal of this API is to provide a common abstraction for blob storage services, so that +WebAssembly components can be written to work with any implementation, without needing to know the +details of the underlying service. -Additionally, components using this API will be unable to tell the difference between a blob storage service and a file system, allowing them to be written to work with either and will not need to configure the store within the component code. +Additionally, components using this API will be unable to tell the difference between a blob storage +service and a file system, allowing them to be written to work with either and will not need to +configure the store within the component code. ### Non-goals The following is a list of goals explicitly out of scope for this API specification: @@ -57,15 +74,17 @@ The following is a list of goals explicitly out of scope for this API specificat ### API walk-through -The following sections provide an overview of how this API might be used. Note that while the samples are in Rust, any language targetable by wasm components via code generation should work. +The following sections provide an overview of how this API might be used. Note that while the +samples are in Rust, any language targetable by wasm components via code generation should work. #### Process Blob Contents -This example shows obtaining a reference to the container and the desired object within that container, and then using `read_into` in a loop to access the blob contents. +This example shows obtaining a reference to the container and the desired object within that +container, and then using `read_into` in a loop to access the blob contents. ```rust // Count the number of lines in an object // For simplicity, assume the object contains ascii text and lines end in '\n' -fn count_lines(store: &impl BlobStore, id: &ObjectId) -> Result { +fn count_lines(store: &impl Blobstore, id: &ObjectId) -> Result { let mut stream = store.get_container(&id.container_name)?.read_object(&id.object_name)?; let mut buf = [0u8; 4096]; let mut num_lines = 0; @@ -77,12 +96,13 @@ fn count_lines(store: &impl BlobStore, id: &ObjectId) -> Result { ``` #### Write to a Blob Stream -The following code sample shows how to obtain a reference to a container and a writable reference to a stream that will be stored in a blob. +The following code sample shows how to obtain a reference to a container and a writable reference to +a stream that will be stored in a blob. ```rust // Download a file from an http url and save it to the blob store. // When completed, returns metadata for the new object -fn download(url: &str, store: &impl BlobStore, id: &ObjectId) -> Result { +fn download(url: &str, store: &impl Blobstore, id: &ObjectId) -> Result { let container = store.get_container(&id.container_name)?; // retrieve a url via wasi-http fetch() method // the http service hasn't been defined yet, but assume its fetch() method returns a readable stream. @@ -106,7 +126,7 @@ The following code shows how to enumerate the objects within a container. // suppose the "logs" container has objects with names that start with a timestamp, like "2022-01-01-12-00-00.log" // for every day that activity occurred. To count the number of logs from january 2022, call: // `count_objects_with_prefix(store, "logs", "2022-01")` -fn count_objects_with_prefix(store: &impl BlobStore, container_name: &str, prefix: &str) -> Result { +fn count_objects_with_prefix(store: &impl Blobstore, container_name: &str, prefix: &str) -> Result { let container = store.get_container(container_name)?; let names = container.list_objects()?; let count = names.filter(|n| n.starts_with(prefix)).count(); @@ -120,11 +140,16 @@ See the [wit files](./wit) #### Handling Large Files -Handling large files may require changes to the API that are not accounted for in this current proposal. If a component attempts to allocate more memory than the host is willing to give it, then the component could be terminated by the host runtime and the processing will fail. +Handling large files may require changes to the API that are not accounted for in this current +proposal. If a component attempts to allocate more memory than the host is willing to give it, then +the component could be terminated by the host runtime and the processing will fail. -Additionally, if a component spends too long processing a file, either processing one large blob or by processing many small blobs in a tight loop, then the component could again be shut off because it consumed too many resources or too much time. +Additionally, if a component spends too long processing a file, either processing one large blob or +by processing many small blobs in a tight loop, then the component could again be shut off because +it consumed too many resources or too much time. -How to handle this and whether the `callback` approach belongs in the blob store API or in a lower level [wasm-io API](https://github.com/WebAssembly/wasi-io/issues/31) is still under discussion. +How to handle this and whether the `callback` approach belongs in the blob store API or in a lower +level [wasm-io API](https://github.com/WebAssembly/wasi-io/issues/31) is still under discussion. ### Stakeholder Interest & Feedback diff --git a/blobstore.abi.md b/blobstore.abi.md deleted file mode 100644 index e69de29..0000000 diff --git a/blobstore.wit.md b/blobstore.wit.md deleted file mode 100644 index b6e491b..0000000 --- a/blobstore.wit.md +++ /dev/null @@ -1,178 +0,0 @@ -``` - -// # 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 - - // retrieves a container by name - get-container: func(name: container-name) -> result - - // 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 - - // 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 - - // returns container metadata - info: func() -> result - - // begins reading an object - read-object: func(name: object-name) -> result - - // creates or replaces an object. - write-object: func(name: object-name) -> result - - // 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 - - // 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, 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) -> result<_, Error> - - // returns true if the object exists in this container - has-object: func(name: object-name) -> result - - // returns metadata for the object - object-info: func(name: object-name) -> result - - // 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) -> 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) -> result, Error> - - // returns the number of bytes remaining that could be read until the end of the stream. - available: func() -> result - - // 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 - - // returns the total size of this data-blob - size: func() -> result -} - -// 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) -> result<_, Error> - - // finish writing blob - finalize: func() -> result -} - -// 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 - } -} -``` diff --git a/imports.md b/imports.md index 03f0a7b..b2836c9 100644 --- a/imports.md +++ b/imports.md @@ -5,8 +5,8 @@
  • interface wasi:io/error@0.2.0
  • interface wasi:io/poll@0.2.0
  • interface wasi:io/streams@0.2.0
    • +
  • interface wasi:clocks/wall-clock@0.2.0
  • interface wasi:blobstore/types@0.2.0-draft
    • -
  • interface wasi:blobstore/container@0.2.0-draft
  • interface wasi:blobstore/blobstore@0.2.0-draft
    • @@ -421,6 +421,47 @@ is ready for reading, before performing the splice.

    +

    Import interface wasi:clocks/wall-clock@0.2.0

    +

    WASI Wall Clock is a clock API intended to let users query the current +time. The name "wall" makes an analogy to a "clock on the wall", which +is not necessarily monotonic as it may be reset.

    +

    It is intended to be portable at least between Unix-family platforms and +Windows.

    +

    A wall clock is a clock which measures the date and time according to +some external reference.

    +

    External references may be reset, so this clock is not necessarily +monotonic, making it unsuitable for measuring elapsed time.

    +

    It is intended for reporting the current date and time for humans.

    +
    +

    Types

    +

    record datetime

    +

    A time and date in seconds plus nanoseconds.

    +
    Record Fields
    +
      +
    • seconds: u64
      • +
    • nanoseconds: u32
      • +
    +
    +

    Functions

    +

    now: func

    +

    Read the current value of the clock.

    +

    This clock is not monotonic, therefore calling this function repeatedly +will not necessarily produce a sequence of non-decreasing values.

    +

    The returned timestamps represent the number of seconds since +1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, +also known as Unix Time.

    +

    The nanoseconds field of the output is always less than 1000000000.

    +
    Return values
    + +

    resolution: func

    +

    Query the resolution of the clock.

    +

    The nanoseconds field of the output is always less than 1000000000.

    +
    Return values
    +

    Import interface wasi:blobstore/types@0.2.0-draft

    Types used by blobstore

    @@ -431,35 +472,19 @@ is ready for reading, before performing the splice.

    #### `type output-stream` [`output-stream`](#output_stream)

    -#### `type container-name` -`string` -

    name of a container, a collection of objects. -The container name may be any valid UTF-8 string. -

    type object-name

    -

    string

    -

    name of an object within a container -The object name may be any valid UTF-8 string. -

    type timestamp

    -

    u64

    -

    TODO: define timestamp to include seconds since -Unix epoch and nanoseconds -https://github.com/WebAssembly/wasi-blob-store/issues/7 -

    type object-size

    -

    u64

    -

    size of an object, in bytes -

    type error

    -

    string

    +#### `type datetime` +[`datetime`](#datetime)

    #### `record container-metadata`

    information about a container

    Record Fields
    @@ -468,19 +493,19 @@ https://github.com/WebAssembly/wasi-blob-store/issues/7
    Record Fields
    @@ -488,8 +513,8 @@ https://github.com/WebAssembly/wasi-blob-store/issues/7

    identifier for an object that includes its container name

    Record Fields

    resource outgoing-value

    A data is the data stored in a data blob. The value can be of any type @@ -556,7 +581,7 @@ should treat the value as corrupted.

    Return values

    [static]incoming-value.incoming-value-consume-async: func

    Params
    @@ -565,7 +590,7 @@ should treat the value as corrupted.

    Return values

    [method]incoming-value.size: func

    Params
    @@ -576,8 +601,8 @@ should treat the value as corrupted.

    • u64
    -

    Import interface wasi:blobstore/container@0.2.0-draft

    -

    a Container is a collection of objects

    +

    Import interface wasi:blobstore/blobstore@0.2.0-draft

    +

    wasi-cloud Blobstore service definition

    Types

    type input-stream

    @@ -589,26 +614,86 @@ should treat the value as corrupted.

    #### `type container-metadata` [`container-metadata`](#container_metadata)

    -#### `type error` -[`error`](#error) -

    #### `type incoming-value` [`incoming-value`](#incoming_value)

    #### `type object-metadata` [`object-metadata`](#object_metadata)

    -#### `type object-name` -[`object-name`](#object_name) -

    #### `type outgoing-value` [`outgoing-value`](#outgoing_value)

    #### `resource container`

    this defines the container resource

    resource stream-object-names

    -

    this defines the stream-object-names resource which is a representation of stream

    +

    this defines the stream-object-names resource which is a representation of stream

    Functions

    +

    create-container: func

    +

    creates a new empty container

    +
    Params
    +
      +
    • name: string
      • +
    +
    Return values
    + +

    get-container: func

    +

    retrieves a container by name

    +
    Params
    +
      +
    • name: string
      • +
    +
    Return values
    + +

    delete-container: func

    +

    deletes a container and all objects within it

    +
    Params
    +
      +
    • name: string
      • +
    +
    Return values
    +
      +
    • result<_, string>
      • +
    +

    container-exists: func

    +

    returns true if the container exists

    +
    Params
    +
      +
    • name: string
      • +
    +
    Return values
    +
      +
    • result<bool, string>
      • +
    +

    copy-object: func

    +

    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.

    +
    Params
    +
      +
    • src: string
      • +
    • dest: string
      • +
    +
    Return values
    +
      +
    • result<_, string>
      • +
    +

    move-object: func

    +

    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.

    +
    Params
    +
      +
    • src: string
      • +
    • dest: string
      • +
    +
    Return values
    +
      +
    • result<_, string>
      • +

    [method]container.name: func

    returns container name

    Params
    @@ -617,7 +702,7 @@ should treat the value as corrupted.

    Return values
      -
    • result<string, error>
      • +
    • result<string, string>

    [method]container.info: func

    returns container metadata

    @@ -627,7 +712,7 @@ should treat the value as corrupted.

    Return values

    [method]container.get-data: func

    retrieves an object or portion of an object, as a resource. @@ -637,25 +722,25 @@ of the data-blob resource, even if the object they came from is later deleted.Params

    Return values

    [method]container.write-data: func

    creates or replaces an object with the data blob.

    Params
    Return values
      -
    • result<_, error>
      • +
    • result<_, string>

    [method]container.list-objects: func

    returns list of objects in the container. Order is undefined.

    @@ -665,7 +750,7 @@ of the data-blob resource, even if the object they came from is later deleted.
    Return values

    [method]container.delete-object: func

    deletes object. @@ -673,44 +758,44 @@ does not return error if object did not exist.

    Params
    Return values
      -
    • result<_, error>
      • +
    • result<_, string>

    [method]container.delete-objects: func

    deletes multiple objects in the container

    Params
    Return values
      -
    • result<_, error>
      • +
    • result<_, string>

    [method]container.has-object: func

    returns true if the object exists in this container

    Params
    Return values
      -
    • result<bool, error>
      • +
    • result<bool, string>

    [method]container.object-info: func

    returns metadata for the object

    Params
    Return values

    [method]container.clear: func

    removes all objects within the container, leaving the container empty.

    @@ -720,7 +805,7 @@ does not return error if object did not exist.

    Return values
      -
    • result<_, error>
      • +
    • result<_, string>

    [method]stream-object-names.read-stream-object-names: func

    reads the next number of objects from the stream

    @@ -732,7 +817,7 @@ does not return error if object did not exist.

    Return values
      -
    • result<(list<object-name>, bool), error>
      • +
    • result<(list<string>, bool), string>

    [method]stream-object-names.skip-stream-object-names: func

    skip the next number of objects in the stream

    @@ -744,89 +829,5 @@ does not return error if object did not exist.

    Return values
      -
    • result<(u64, bool), error>
      • -
    -

    Import interface wasi:blobstore/blobstore@0.2.0-draft

    -

    wasi-cloud Blobstore service definition

    -
    -

    Types

    -

    type container

    -

    container

    -

    -#### `type error` -[`error`](#error) -

    -#### `type container-name` -[`container-name`](#container_name) -

    -#### `type object-id` -[`object-id`](#object_id) -

    ----- -

    Functions

    -

    create-container: func

    -

    creates a new empty container

    -
    Params
    - -
    Return values
    - -

    get-container: func

    -

    retrieves a container by name

    -
    Params
    - -
    Return values
    - -

    delete-container: func

    -

    deletes a container and all objects within it

    -
    Params
    - -
    Return values
    - -

    container-exists: func

    -

    returns true if the container exists

    -
    Params
    - -
    Return values
    - -

    copy-object: func

    -

    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.

    -
    Params
    - -
    Return values
    - -

    move-object: func

    -

    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.

    -
    Params
    - -
    Return values
    -
      -
    • result<_, error>
      • +
    • result<(u64, bool), string>
    diff --git a/proposal-template.abi.md b/proposal-template.abi.md deleted file mode 100644 index 7a1c372..0000000 --- a/proposal-template.abi.md +++ /dev/null @@ -1,31 +0,0 @@ -# Types - -## `api-type-one`: record - - Short description - - Explanation for developers using the API. - -Size: 16, Alignment: 8 - -### Record Fields - -- [`property1`](#api_type_one.property1): `u64` - - -- [`property2`](#api_type_one.property2): `string` - - -# Functions - ----- - -#### `api-function-one` - - Short description - - Explanation for developers using the API. -##### Results - -- [`api-type-one`](#api_type_one) - diff --git a/proposal-template.wit.md b/proposal-template.wit.md deleted file mode 100644 index 3c7e8ef..0000000 --- a/proposal-template.wit.md +++ /dev/null @@ -1,32 +0,0 @@ -# [Proposal Template] API - -[This document contains the actual specification. It should be written in the WIT interface definition format. You can find more documentation on the WIT syntax (coming soon!).] - -[Note that all comments inside of WIT code blocks will be included in the developer facing documentation for language bindings generated using this WIT file. If there is additional information that needs to be communicated to implementers of the API, then these should be captured in text directly below the code block.] - -[If you want to include examples of the API in use, these should be in the README and linked to from this file.] - -## api_type_one - -```wit -/// Short description -/// -/// Explanation for developers using the API. -record api-type-one { - property1: u64, - property2: string, -} -``` - -More rigorous specification details for the implementer go here, if needed. - -## api_function_one - -```wit -/// Short description -/// -/// Explanation for developers using the API. -api-function-one: func() -> api-type-one -``` - -If needed, this would explain what a compliant implementation MUST do, such as never returning an earlier result from a later call. diff --git a/wit/blobstore.wit b/wit/blobstore.wit index 5a50214..6194152 100644 --- a/wit/blobstore.wit +++ b/wit/blobstore.wit @@ -1,27 +1,86 @@ // wasi-cloud Blobstore service definition interface blobstore { - use container.{container}; - use types.{error, container-name, object-id}; + use wasi:io/streams@0.2.0.{ + input-stream, + output-stream, + }; + + use types.{ + container-metadata, + incoming-value, + object-metadata, + outgoing-value, + }; // creates a new empty container - create-container: func(name: container-name) -> result; + create-container: func(name: string) -> result; // retrieves a container by name - get-container: func(name: container-name) -> result; + get-container: func(name: string) -> result; // deletes a container and all objects within it - delete-container: func(name: container-name) -> result<_, error>; + delete-container: func(name: string) -> result<_, string>; // returns true if the container exists - container-exists: func(name: container-name) -> result; + container-exists: func(name: string) -> result; // 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>; + copy-object: func(src: string, dest: string) -> result<_, string>; // 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>; + move-object: func(src: string, dest: string) -> result<_, string>; + + // this defines the `container` resource + resource container { + // returns container name + name: func() -> result; + + // returns container metadata + info: func() -> result; + + // 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: string, start: u64, end: u64) -> result; + + // creates or replaces an object with the data blob. + write-data: func(name: string, data: borrow) -> result<_, string>; + + // returns list of objects in the container. Order is undefined. + list-objects: func() -> result; + + // deletes object. + // does not return error if object did not exist. + delete-object: func(name: string) -> result<_, string>; + + // deletes multiple objects in the container + delete-objects: func(names: list) -> result<_, string>; + + // returns true if the object exists in this container + has-object: func(name: string) -> result; + + // returns metadata for the object + object-info: func(name: string) -> result; + + // removes all objects within the container, leaving the container empty. + clear: func() -> result<_, string>; + } + + // this defines the `stream-object-names` resource which is a representation of stream + 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, bool>, string>; + + // 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, string>; + } } \ No newline at end of file diff --git a/wit/container.wit b/wit/container.wit deleted file mode 100644 index f4c577e..0000000 --- a/wit/container.wit +++ /dev/null @@ -1,66 +0,0 @@ -// a Container is a collection of objects -interface container { - use wasi:io/streams@0.2.0.{ - 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; - - // returns container metadata - info: func() -> result; - - // 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; - - // creates or replaces an object with the data blob. - write-data: func(name: object-name, data: borrow) -> result<_, error>; - - // returns list of objects in the container. Order is undefined. - list-objects: func() -> result; - - // 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) -> result<_, error>; - - // returns true if the object exists in this container - has-object: func(name: object-name) -> result; - - // returns metadata for the object - object-info: func(name: object-name) -> result; - - // 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 - 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, 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, error>; - } -} \ No newline at end of file diff --git a/wit/deps.lock b/wit/deps.lock index dcc8282..dc899da 100644 --- a/wit/deps.lock +++ b/wit/deps.lock @@ -1,3 +1,8 @@ +[clocks] +url = "https://github.com/WebAssembly/wasi-clocks/archive/v0.2.0.tar.gz" +sha256 = "468b4d12892fe926b8eb5d398dbf579d566c93231fa44f415440572c695b7613" +sha512 = "e6b53a07221f1413953c9797c68f08b815fdaebf66419bbc1ea3e8b7dece73731062693634731f311a03957b268cf9cc509c518bd15e513c318aa04a8459b93a" + [io] url = "https://github.com/WebAssembly/wasi-io/archive/v0.2.0.tar.gz" sha256 = "7210e5653539a15478f894d4da24cc69d61924cbcba21d2804d69314a88e5a4c" diff --git a/wit/deps.toml b/wit/deps.toml index bb31cd7..6dd20d3 100644 --- a/wit/deps.toml +++ b/wit/deps.toml @@ -1 +1,2 @@ io = "https://github.com/WebAssembly/wasi-io/archive/v0.2.0.tar.gz" +clocks = "https://github.com/WebAssembly/wasi-clocks/archive/v0.2.0.tar.gz" diff --git a/wit/deps/clocks/monotonic-clock.wit b/wit/deps/clocks/monotonic-clock.wit new file mode 100644 index 0000000..4e4dc3a --- /dev/null +++ b/wit/deps/clocks/monotonic-clock.wit @@ -0,0 +1,45 @@ +package wasi:clocks@0.2.0; +/// WASI Monotonic Clock is a clock API intended to let users measure elapsed +/// time. +/// +/// It is intended to be portable at least between Unix-family platforms and +/// Windows. +/// +/// A monotonic clock is a clock which has an unspecified initial value, and +/// successive reads of the clock will produce non-decreasing values. +/// +/// It is intended for measuring elapsed time. +interface monotonic-clock { + use wasi:io/poll@0.2.0.{pollable}; + + /// An instant in time, in nanoseconds. An instant is relative to an + /// unspecified initial value, and can only be compared to instances from + /// the same monotonic-clock. + type instant = u64; + + /// A duration of time, in nanoseconds. + type duration = u64; + + /// Read the current value of the clock. + /// + /// The clock is monotonic, therefore calling this function repeatedly will + /// produce a sequence of non-decreasing values. + now: func() -> instant; + + /// Query the resolution of the clock. Returns the duration of time + /// corresponding to a clock tick. + resolution: func() -> duration; + + /// Create a `pollable` which will resolve once the specified instant + /// occured. + subscribe-instant: func( + when: instant, + ) -> pollable; + + /// Create a `pollable` which will resolve once the given duration has + /// elapsed, starting at the time at which this function was called. + /// occured. + subscribe-duration: func( + when: duration, + ) -> pollable; +} diff --git a/wit/deps/clocks/wall-clock.wit b/wit/deps/clocks/wall-clock.wit new file mode 100644 index 0000000..440ca0f --- /dev/null +++ b/wit/deps/clocks/wall-clock.wit @@ -0,0 +1,42 @@ +package wasi:clocks@0.2.0; +/// WASI Wall Clock is a clock API intended to let users query the current +/// time. The name "wall" makes an analogy to a "clock on the wall", which +/// is not necessarily monotonic as it may be reset. +/// +/// It is intended to be portable at least between Unix-family platforms and +/// Windows. +/// +/// A wall clock is a clock which measures the date and time according to +/// some external reference. +/// +/// External references may be reset, so this clock is not necessarily +/// monotonic, making it unsuitable for measuring elapsed time. +/// +/// It is intended for reporting the current date and time for humans. +interface wall-clock { + /// A time and date in seconds plus nanoseconds. + record datetime { + seconds: u64, + nanoseconds: u32, + } + + /// Read the current value of the clock. + /// + /// This clock is not monotonic, therefore calling this function repeatedly + /// will not necessarily produce a sequence of non-decreasing values. + /// + /// The returned timestamps represent the number of seconds since + /// 1970-01-01T00:00:00Z, also known as [POSIX's Seconds Since the Epoch], + /// also known as [Unix Time]. + /// + /// The nanoseconds field of the output is always less than 1000000000. + /// + /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16 + /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time + now: func() -> datetime; + + /// Query the resolution of the clock. + /// + /// The nanoseconds field of the output is always less than 1000000000. + resolution: func() -> datetime; +} diff --git a/wit/deps/clocks/world.wit b/wit/deps/clocks/world.wit new file mode 100644 index 0000000..c022457 --- /dev/null +++ b/wit/deps/clocks/world.wit @@ -0,0 +1,6 @@ +package wasi:clocks@0.2.0; + +world imports { + import monotonic-clock; + import wall-clock; +} diff --git a/wit/types.wit b/wit/types.wit index ca59724..e897c48 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -1,49 +1,32 @@ // Types used by blobstore interface types { use wasi:io/streams@0.2.0.{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; + use wasi:clocks/wall-clock@0.2.0.{datetime}; // information about a container record container-metadata { // the container's name - name: container-name, + name: string, // date and time container was created - created-at: timestamp, + created-at: datetime, } // information about an object record object-metadata { // the object's name - name: object-name, + name: string, // the object's parent container - container: container-name, + container: string, // date and time the object was created - created-at: timestamp, + created-at: datetime, // size of the object, in bytes - size: object-size, + size: u64, } // identifier for an object that includes its container name record object-id { - container: container-name, - object: object-name + container: string, + object: string } /// A data is the data stored in a data blob. The value can be of any type @@ -81,8 +64,8 @@ interface types { /// 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-consume-async: static func(this: incoming-value) -> result; + incoming-value-consume-sync: static func(this: incoming-value) -> result; + incoming-value-consume-async: static func(this: incoming-value) -> result; size: func() -> u64; }