Using OCI for WIT specs

[ricochet]

We should create release packages from this repository for WIT definitions. This will aid in discovery and many different tools will soon be compliant with the OCI artifact layout for Wasm components.

Example of how the mechanics may work:

cargo install wit

cd preview2/io
wit init
wit build

# view built wasm and observe doc comments are preserved
# and it defines an `imports` world
wasm-tools component wit io.wasm

# push the .wasm artifact as an OCI artifact
# TODO wasm-pkg-tools crate to push
# I used wash to demonstrate:
wash push ghcr.io/ricochet/io:0.2.0 io.wasm --world imports

# on @thomastaylor312 branch of [wasm-pkg-loader](https://github.com/bytecodealliance/wasm-pkg-tools/pull/28)
wasm-pkg-loader ricochet:io fetch 0.2.0
Fetching release details for ricochet:[email protected]...
Downloading content to "ricochet-io-0.2.0.wasm"...

# inspect again
wasm-tools component wit ricochet-io-0.2.0.wasm
# confirm identical and correct wit definition

The WIT-only component that I pushed: https://github.com/users/ricochet/packages/container/package/io

Note that the maintainers of wasm-pkg-tools and cargo-component are planning a refactor in this space soon for the tooling, but the OCI definition will not change.

[pchickey]

I'm in favor of publishing release packages as OCI now that it is finally possible!

Have you checked that the tooling works for more packages beyond io - how does it work for the packages which have a dependency on io?

[ricochet]

I verified that this also works for WIT definitions that have dependencies. The way the wit tool works is by enumerating dependencies in a wit.toml.

Expanding to something more interesting with wasi-clocks that depends on wasi:io/[email protected].{pollable}:

cd preview2/clocks
wit init --registry https://ghcr.io
wit add wasi:[email protected] --path ../io

bat wit.toml
───────┬────────────────────────────────────────────────────────────────────────────────────────
       │ File: wit.toml
───────┼────────────────────────────────────────────────────────────────────────────────────────
   1   │ version = "0.1.0"
   2   │
   3   │ [dependencies]
   4   │ "wasi:io" = { path = "../io" }
   5   │
   6   │ [registries]
   7   │ default = "https://ghcr.io/"


wit build

Output from wasm-tools component wit clocks.wasm:

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

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

world imports {
  import wasi:io/poll@0.2.0;
  import monotonic-clock;
  import wall-clock;
}

# push the .wasm artifact as an OCI artifact
# TODO wasm-pkg-tools crate to push
# I used wash to demonstrate:
wash push ghcr.io/ricochet/clocks:0.2.0 clocks.wasm --world imports

# on @thomastaylor312 branch of [wasm-pkg-loader](https://github.com/bytecodealliance/wasm-pkg-tools/pull/28)
wasm-pkg-loader ricochet:clocks fetch 0.2.0

# inspect again
wasm-tools component wit ricochet-clocks-0.2.0.wasm
# confirm identical and correct wit definition
# this definition does not include wasi-io

[squillace]

I love it

[lukewagner]

\o/

[LiamRandall]

Building better together! This is incredible! Liam

…

On Sat, Jun 8, 2024 at 5:56 PM Luke Wagner ***@***.***> wrote: \o/ — Reply to this email directly, view it on GitHub <#606 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALVWIELOQ4TVNJHRIZ23Y3ZGN4XNAVCNFSM6AAAAABITRZEBCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNJWGIYDAOBZGM> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[ricochet]

WASI WIT packages have been pushed and are associated with this (WASI) repo.

Example usage flow:

[lann]

Note for future readers:

The wasm-pkg-loader tool has been merged into a new general-purpose wkg tool and the examples above may stop working. You can do this instead:

$ cargo install wkg
...
$ wkg get wasi:http
No version specified; fetching version list...
Getting wasi:[email protected]...
Wrote './[email protected]'