Migrated the Wasmer Pack docs to docs.wasmer.io

pages/_meta.json

@@ -10,6 +10,8 @@
   "registry": "Registry",
   "javascript-sdk": "JavaScript SDK",
   "edge": "Edge",
+  "wai": "WAI",
+  "wasmer-pack": "Wasmer Pack",
   "---": {
     "type": "separator"
   },

pages/index.mdx

@@ -14,7 +14,7 @@ Welcome to the Wasmer Documentation! 👋
 1. [Wasmer Runtime](/runtime): allows running Wasmer containers anywhere
 2. [Wasmer Registry](/registry): explore containers from the community and distribute your own ones
 3. [Wasmer Edge](/edge): run containers on Wasmer distributed Edge infrastructure
-3. [Wasmer SDK](/sdk): run containers on Wasmer distributed Edge infrastructure
+3. [Wasmer JavaScript SDK](/javascript-sdk): run containers on Wasmer distributed Edge infrastructure
 
 ## Social
 

pages/wai.md

@@ -0,0 +1,110 @@
+# WebAssembly Interfaces (WAI)
+
+The WebAssembly spec that was first released in 2017 was only a minimum viable
+product and deliberately left several features incomplete to be iterated on by
+the ecosystem.
+
+Arguably the most important functionality gap is the fact that only WebAssembly
+primitives can be passed between the host and guest. That means imports and
+exports can only use the following data types,
+
+- `i32` - signed 32-bit integers
+- `i64` - signed 64-bit integers
+- `f32` - a 32-bit float
+- `f64` - a 64-bit float (often called a `double`)
+- `funcref` - a reference to a WebAssembly function
+- `externref` - a reference to some opaque object owned by the WebAssembly
+  virtual machine
+
+You'll notice this list doesn't even include strings or boolean values!
+
+The WebAssembly Interfaces project (WAI for short) provides a polyfill for
+passing around higher-level objects. It lets developers define their imports and
+exports in a `*.wai` file, then uses `wai-bindgen` to generate glue which
+automagically passes things around within the constraints of WebAssembly.
+
+There are four main parts to WAI:
+
+- The `*.wai` file
+- The WAI Bindgen code generator
+- The guest
+- The host
+
+The [Wasmer Pack](../../) project provides a convenient way to consume
+WebAssembly packages which implement a WAI interface.
+
+Some useful links:
+
+- [The `wasmerio/wai` repository](https://github.com/wasmerio/wai)
+- [The `*.wai` format](https://github.com/wasmerio/wai/blob/main/WAI.md)
+- [The `wai-bindgen` CLI on crates.io](https://crates.io/crates/wai-bindgen-cli)
+
+## The `*.wai` File
+
+WAI uses a file (or files) with the `*.wai` extension to define the host-guest
+interface for an application that uses WebAssembly.
+
+The items in a `*.wai` file map closely to concepts shared by most programming
+languages. It has [types](./types.md), interfaces
+(["Resources"](./resources.md)), structs (["Records"](./records.md)),
+[functions](./functions.md), [enums](./variants.md), and so on.
+
+The precise syntax [is defined in the WAI repository][wai-format] and a parser,
+[`wai-parser`][wai-parser], is available as a Rust crate.
+
+## The Guest
+
+In an application using WebAssembly, the "guest" is the code that has been
+compiled to WebAssembly and is being loaded into a WebAssembly virtual machine.
+
+## The Host
+
+In an application using WebAssembly, the "host" is the code that uses a
+WebAssembly virtual machine (like [`wasmer`][wasmer]) to load a guest and use
+functionality it provides.
+
+The WebAssembly spec refers to the host in some places as
+[*the embedder*][embedder].
+
+## WAI Bindgen
+
+The WAI Bindgen code generator consumes `*.wai` files and generates glue code
+that [the host](#the-host) can use for using functionality from a WebAssembly
+module or [the guest](#the-guest) can use for implementing that functionality.
+
+There are two primary ways users will interact with WAI Bindgen, the
+`wai-bindgen` CLI, and the `wai-bindgen-*` family of crates.
+
+The `wai-bindgen` CLI provides a command-line interface to the `wai-bindgen-*`
+crates, and is often used for once-off investigation or integration with a
+non-Rust build system.
+
+On the other hand, the `wai-bindgen-*` crates allow users to generate bindings
+programmatically and give them much more control over the generation process.
+
+| Language   | Direction       | Code Generator                                   | Procedural Macro                        |
+| ---------- | --------------- | ------------------------------------------------ | --------------------------------------- |
+| Rust       | Guest           | [`wai-bindgen-gen-rust-wasm`][gen-rust-wasm]     | [`wai-bindgen-rust`][proc-rust]         |
+| Rust       | Host (Wasmer)   | [`wai-bindgen-gen-wasmer`][gen-rust-wasmer]      | [`wai-bindgen-wasmer`][proc-wasmer]     |
+| Rust       | Host (Wasmtime) | [`wai-bindgen-gen-wasmtime`][gen-rust-wasmtime]  | [`wai-bindgen-wasmtime`][proc-wasmtime] |
+| C          | Guest           | [`wai-bindgen-gen-c`][gen-c-wasm]                |                                         |
+| JavaScript | Host            | [`wai-bindgen-gen-js`][gen-js-host]              |                                         |
+| Python     | Host (Wasmer)   | [`wai-bindgen-gen-wasmer-py`][gen-py-host]       |                                         |
+| Python     | Host (Wasmtime) | [`wai-bindgen-gen-wasmtime-py`][gen-py-wasmtime] |                                         |
+
+[gen-c-wasm]: https://docs.rs/wai-bindgen-gen-c/
+[gen-js-host]: https://docs.rs/wai-bindgen-gen-js/
+[gen-py-host]: https://docs.rs/wai-bindgen-gen-wasmer-py/
+[gen-py-wasmtime]: https://docs.rs/wai-bindgen-gen-wasmtime-py/
+[gen-rust-wasm]: https://docs.rs/wai-bindgen-gen-rust-wasm/
+[gen-rust-wasmer]: https://docs.rs/wai-bindgen-gen-wasmer/
+[gen-rust-wasmtime]: https://docs.rs/wai-bindgen-gen-wasmtime/
+[proc-rust]: https://docs.rs/wai-bindgen-rust/
+[proc-wasmer]: https://docs.rs/wai-bindgen-wasmer/
+[proc-wasmtime]: https://docs.rs/wai-bindgen-wasmtime/
+
+[embedder]: https://webassembly.github.io/spec/core/intro/overview.html#embedder
+[idl]: https://en.wikipedia.org/wiki/Interface_description_language
+[wai-format]: https://github.com/wasmerio/wai/blob/main/WAI.md
+[wai-parser]: https://docs.rs/wai-parser
+[wasmer]: https://docs.rs/wasmer

pages/wai/functions.md

@@ -0,0 +1,22 @@
+# Functions
+
+Functions are one of the most important concepts in WAI. They are what guests
+and hosts use to expose functionality to each other, and have a name,
+parameters, and results.
+
+Here are some examples:
+
+```
+thunk: func()
+fibonacci: func(n: u32) -> u32
+sleep: async func(ms: u64)
+```
+
+Most guests will map functions to top-level functions, while most hosts will
+expose functions as some sort of callable object which eventually calls into
+the relevant part of the WebAssembly virtual machine.
+
+For a more details, consult [the *Item: `func`* section][func] in the `*.wai`
+format.
+
+[func]: https://github.com/wasmerio/wai/blob/main/WAI.md#item-func

pages/wai/records.md

@@ -0,0 +1,34 @@
+# Records
+
+A record is an abstract data type containing a series of named fields. It has no
+associated behaviour and acts as a way to group data together. In C++, this
+would be referred to as a [plain old data][pod] type.
+
+Depending on the language, records may be expressed in in different ways.
+
+| Language   | Equivalent Construct     |
+| ---------- | ------------------------ |
+| Rust       | Struct                   |
+| C          | Struct                   |
+| Python     | [Data Class][dataclass]  |
+| TypeScript | [Type alias][type-alias] |
+
+## Syntax
+
+A record contains a list of fields, where each field must be given a type.
+
+```
+record person {
+    name: string,
+    age: u32,
+    has-lego-action-figure: bool,
+}
+```
+
+For a more details, consult [the *Item: `record`* section][record] in the
+`*.wai` format.
+
+[dataclass]: https://peps.python.org/pep-0557/
+[pod]: https://en.wikipedia.org/wiki/Passive_data_structure
+[record]: https://github.com/wasmerio/wai/blob/main/WAI.md#item-record-bag-of-named-fields
+[type-alias]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-aliases

pages/wai/resources.md

@@ -0,0 +1,56 @@
+# Resources
+
+A resource represents an opaque object where the representation and underlying
+implementation is completely hidden from the outside world. Resources may have
+associated methods, static methods, or no methods at all.
+
+Depending on the language, records may be expressed in in different ways.
+
+| Language   | Equivalent Construct         |
+| ---------- | ---------------------------- |
+| Rust       | [Trait object][trait-object] |
+| Python     | class                        |
+| JavaScript | class                        |
+
+Resources can only be used through a "handle" and can be owned by either the
+host or the guest. Resource lifetimes are managed manually, although most
+languages provide some sort of reference counting or garbage collection
+mechanism.
+
+## Syntax
+
+The simplest resource is an opaque "token". Users can pass this value around,
+but have no other way to interact with it.
+
+```
+resource file-descriptor
+```
+
+Resources can also have methods. These are functions which are associated with
+the resource and are implicitly given a reference to the resource when they
+are invoked.
+
+```
+resource writer {
+  write: func(data: list<u8>) -> expected<unit, error>
+  flush: func() -> expected<unit, error>
+}
+```
+
+Additionally, resources can have `static` methods. These are often used to
+implement constructors.
+
+```
+resource request {
+    static new: func() -> request
+
+    body: async func() -> list<u8>
+    headers: func() -> list<string>
+}
+```
+
+For a more details, consult [the *Item: `resource`* section][resource] in the
+`*.wai` format.
+
+[resource]: https://github.com/wasmerio/wai/blob/main/WAI.md#item-resource
+[trait-object]: https://doc.rust-lang.org/reference/types/trait-object.html

pages/wai/types.md

@@ -0,0 +1,78 @@
+# Builtin Types
+
+All types that can be used in a `*.wai` file are intended to mappable to native
+types in a general purpose programming language.
+
+The core basic types are
+
+- Unsigned integers (`u8`, `u16`, `u32`, `u64`)
+- Signed integers (`s8`, `s16`, `s32`, `s64`)
+- Floating point numbers (`float32`, `float64`)
+- UTF-8 Strings (`string`)
+- UTF-8 code points (`char`)
+- [Void][void] or nothing (`unit`)
+
+For a more precise definition, consult [the *Types* section][types] in the
+`*.wai` format.
+
+## Other Builtin Types
+
+Besides the basic builtin types, there are several "generic" types built into
+WAI which let users express common concepts.
+
+### Tuples
+
+The tuple is equivalent to a [record](./records.md) that has numeric fields.
+
+Code generators may be able to express tuples as a first-class concept. For
+example, `tuple<string, float32, float32>` would be expressed as
+`(String, f32, f32)` in Rust.
+
+### Lists
+
+Lists are dynamically-sized sequences of the same element type. Often called
+a "list", "vector", or "array", a `list<string>` would be expressed as
+`Vec<String>` in Rust.
+
+### Option
+
+The option type is used to express a value that may or may not be present.
+
+In Rust, an `option<T>` is expressed as [`std::option::Option<T>`][rust-option],
+while other languages may choose to use `null` to represent the missing value.
+
+It is semantically equivalent to the following variant:
+
+```
+variant option {
+    none,
+    some(T),
+}
+```
+
+### Expected
+
+The expected type is used to express the result of a fallible operation.
+
+In Rust, an `expected<T, E>` is expressed as
+[`std::result::Result<T, E>`][rust-result], although other languages may choose
+to convert errors into exceptions.
+
+It is semantically equivalent to the following variant:
+
+```
+variant expected {
+    ok(T),
+    err(E),
+}
+```
+
+### Futures & Streams
+
+The `future<T>` and `stream<T, E>` types are used to represent the result of
+asynchronous operations.
+
+[rust-option]: https://doc.rust-lang.org/std/option/enum.Option.html
+[rust-result]: https://doc.rust-lang.org/std/result/enum.Result.html
+[void]: https://en.wikipedia.org/wiki/Void_type
+[types]: https://github.com/wasmerio/wai/blob/main/WAI.md#types