Improve the wasmtime crate's README (bytecodealliance#4174)

* Improve the `wasmtime` crate's README

This commit is me finally getting back to bytecodealliance#2688 and improving the README
of the `wasmtime` crate. Currently we have a [pretty drab README][drab]
that doesn't really convey what we want about Wasmtime.

While I was doing this I opted to update the feature list of Wasmtime as
well in the main README (which is mirrored into the crate readme),
namely adding a bullet point for "secure" which I felt was missing
relative to how we think about Wasmtime.

Naturally there's a lot of ways to paint this shed, so feedback is of
course welcome on this! (I'm not the best writer myself)

[drab]: https://crates.io/crates/wasmtime/0.37.0

* Expand the "Fast" bullet a bit more

* Reference the book from the wasmtime crate

* Update more security docs

Also merge the sandboxing security page with the main security page to
avoid the empty security page.

README.md

@@ -62,29 +62,48 @@ Hello, world!
 
 ## Features
 
-* **Lightweight**. Wasmtime is a standalone runtime for WebAssembly that scales
-  with your needs. It fits on tiny chips as well as makes use of huge servers.
-  Wasmtime can be [embedded] into almost any application too.
-
 * **Fast**. Wasmtime is built on the optimizing [Cranelift] code generator to
-  quickly generate high-quality machine code at runtime.
-
-* **Configurable**. Whether you need to precompile your wasm ahead of time,
-  or interpret it at runtime, Wasmtime has you covered for all your
-  wasm-executing needs.
-
-* **WASI**. Wasmtime supports a rich set of APIs for interacting with the host
+  quickly generate high-quality machine code either at runtime or
+  ahead-of-time. Wasmtime's runtime is also optimized for cases such as
+  efficient instantiation, low-overhead transitions between the embedder and
+  wasm, and scalability of concurrent instances.
+
+* **[Secure]**. Wasmtime's development is strongly focused on the correctness of
+  its implementation with 24/7 fuzzing donated by [Google's OSS Fuzz],
+  leveraging Rust's API and runtime safety guarantees, careful design of
+  features and APIs through an [RFC process], a [security policy] in place
+  for when things go wrong, and a [release policy] for patching older versions
+  as well. We follow best practices for defense-in-depth and known
+  protections and mitigations for issues like Spectre. Finally, we're working
+  to push the state-of-the-art by collaborating with academic
+  researchers to formally verify critical parts of Wasmtime and Cranelift.
+
+* **[Configurable]**. Wastime supports a rich set of APIs and build time
+  configuration to provide many options such as further means of restricting
+  WebAssembly beyond its basic guarantees such as its CPU and Memory
+  consumption. Wasmtime also runs in tiny environments all the way up to massive
+  servers with many concurrent instances.
+
+* **[WASI]**. Wasmtime supports a rich set of APIs for interacting with the host
   environment through the [WASI standard](https://wasi.dev).
 
-* **Standards Compliant**. Wasmtime passes the [official WebAssembly test
+* **[Standards Compliant]**. Wasmtime passes the [official WebAssembly test
   suite](https://github.com/WebAssembly/testsuite), implements the [official C
   API of wasm](https://github.com/WebAssembly/wasm-c-api), and implements
   [future proposals to WebAssembly](https://github.com/WebAssembly/proposals) as
   well. Wasmtime developers are intimately engaged with the WebAssembly
   standards process all along the way too.
 
+[Wasmtime]: https://github.com/bytecodealliance/wasmtime
 [Cranelift]: https://github.com/bytecodealliance/wasmtime/blob/main/cranelift/README.md
-[embedded]: https://bytecodealliance.github.io/wasmtime/lang.html
+[Google's OSS Fuzz]: https://google.github.io/oss-fuzz/
+[security policy]: https://bytecodealliance.org/security
+[RFC process]: https://github.com/bytecodealliance/rfcs
+[release policy]: https://docs.wasmtime.dev/stability-release.html
+[Secure]: https://docs.wasmtime.dev/security.html
+[Configurable]: https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html
+[WASI]: https://docs.rs/wasmtime-wasi/latest/wasmtime_wasi/
+[Standards Compliant]: https://docs.wasmtime.dev/stability-wasm-proposals-support.html
 
 ## Language Support
 

crates/wasmtime/README.md

@@ -1,8 +1,119 @@
-## Wasmtime Embedding API
+<div align="center">
+  <h1><code>wasmtime</code></h1>
 
-The `wasmtime` crate is an embedding API of the `wasmtime` WebAssembly runtime.
-This is intended to be used in Rust projects and provides a high-level API of
-working with WebAssembly modules.
+  <p>
+    <strong>A standalone runtime for
+    <a href="https://webassembly.org/">WebAssembly</a></strong>
+  </p>
 
-If you're interested in embedding `wasmtime` in other languages, you may wish to
-take a look a the [C embedding API](../c-api) instead!
+  <strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> project</strong>
+</div>
+
+## About
+
+This crate is the Rust embedding API for the [Wasmtime] project: a
+cross-platform engine for running WebAssembly programs. Notable features of
+Wasmtime are:
+
+* **Fast**. Wasmtime is built on the optimizing [Cranelift] code generator to
+  quickly generate high-quality machine code either at runtime or
+  ahead-of-time. Wasmtime's runtime is also optimized for cases such as
+  efficient instantiation, low-overhead transitions between the embedder and
+  wasm, and scalability of concurrent instances.
+
+* **[Secure]**. Wasmtime's development is strongly focused on the correctness of
+  its implementation with 24/7 fuzzing donated by [Google's OSS Fuzz],
+  leveraging Rust's API and runtime safety guarantees, careful design of
+  features and APIs through an [RFC process], a [security policy] in place
+  for when things go wrong, and a [release policy] for patching older versions
+  as well. We follow best practices for defense-in-depth and known
+  protections and mitigations for issues like Spectre. Finally, we're working
+  to push the state-of-the-art by collaborating with academic
+  researchers to formally verify critical parts of Wasmtime and Cranelift.
+
+* **[Configurable]**. Wastime supports a rich set of APIs and build time
+  configuration to provide many options such as further means of restricting
+  WebAssembly beyond its basic guarantees such as its CPU and Memory
+  consumption. Wasmtime also runs in tiny environments all the way up to massive
+  servers with many concurrent instances.
+
+* **[WASI]**. Wasmtime supports a rich set of APIs for interacting with the host
+  environment through the [WASI standard](https://wasi.dev).
+
+* **[Standards Compliant]**. Wasmtime passes the [official WebAssembly test
+  suite](https://github.com/WebAssembly/testsuite), implements the [official C
+  API of wasm](https://github.com/WebAssembly/wasm-c-api), and implements
+  [future proposals to WebAssembly](https://github.com/WebAssembly/proposals) as
+  well. Wasmtime developers are intimately engaged with the WebAssembly
+  standards process all along the way too.
+
+[Wasmtime]: https://github.com/bytecodealliance/wasmtime
+[Cranelift]: https://github.com/bytecodealliance/wasmtime/blob/main/cranelift/README.md
+[Google's OSS Fuzz]: https://google.github.io/oss-fuzz/
+[security policy]: https://bytecodealliance.org/security
+[RFC process]: https://github.com/bytecodealliance/rfcs
+[release policy]: https://docs.wasmtime.dev/stability-release.html
+[Secure]: https://docs.wasmtime.dev/security.html
+[Configurable]: https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html
+[WASI]: https://docs.rs/wasmtime-wasi/latest/wasmtime_wasi/
+[Standards Compliant]: https://docs.wasmtime.dev/stability-wasm-proposals-support.html
+
+## Example
+
+An example of using the Wasmtime embedding API for running a small WebAssembly
+module might look like:
+
+```rust
+use anyhow::Result;
+use wasmtime::*;
+
+fn main() -> Result<()> {
+    // Modules can be compiled through either the text or binary format
+    let engine = Engine::default();
+    let wat = r#"
+        (module
+            (import "host" "hello" (func $host_hello (param i32)))
+
+            (func (export "hello")
+                i32.const 3
+                call $host_hello)
+        )
+    "#;
+    let module = Module::new(&engine, wat)?;
+
+    // Create a `Linker` which will be later used to instantiate this module.
+    // Host functionality is defined by name within the `Linker`.
+    let mut linker = Linker::new(&engine);
+    linker.func_wrap("host", "hello", |caller: Caller<'_, u32>, param: i32| {
+        println!("Got {} from WebAssembly", param);
+        println!("my host state is: {}", caller.data());
+    })?;
+
+    // All wasm objects operate within the context of a "store". Each
+    // `Store` has a type parameter to store host-specific data, which in
+    // this case we're using `4` for.
+    let mut store = Store::new(&engine, 4);
+    let instance = linker.instantiate(&mut store, &module)?;
+    let hello = instance.get_typed_func::<(), (), _>(&mut store, "hello")?;
+
+    // And finally we can call the wasm!
+    hello.call(&mut store, ())?;
+
+    Ok(())
+}
+```
+
+More examples and information can be found in the `wasmtime` crate's [online
+documentation](https://docs.rs/wasmtime) as well.
+
+## Documentation
+
+[📚 Read the Wasmtime guide here! 📚][guide]
+
+The [wasmtime guide][guide] is the best starting point to learn about what
+Wasmtime can do for you or help answer your questions about Wasmtime. If you're
+curious in contributing to Wasmtime, [it can also help you do
+that][contributing]!
+
+[contributing]: https://bytecodealliance.github.io/wasmtime/contributing.html
+[guide]: https://bytecodealliance.github.io/wasmtime

crates/wasmtime/src/lib.rs

@@ -1,5 +1,11 @@
 //! Wasmtime's embedding API
 //!
+//! Wasmtime is a WebAssembly engine for JIT-complied or ahead-of-time compiled
+//! WebAssembly modules. More information about the Wasmtime project as a whole
+//! can be found [in the documentation book](https://docs.wasmtime.dev) whereas
+//! this documentation mostly focuses on the API reference of the `wasmtime`
+//! crate itself.
+//!
 //! This crate contains an API used to interact with WebAssembly modules. For
 //! example you can compile modules, instantiate them, call them, etc. As an
 //! embedder of WebAssembly you can also provide WebAssembly modules

docs/SUMMARY.md

@@ -48,7 +48,6 @@
   - [Wasm Proposals Support](./stability-wasm-proposals-support.md)
 - [Security](security.md)
   - [Disclosure Policy](./security-disclosure.md)
-  - [Sandboxing](./security-sandboxing.md)
 - [Contributing](contributing.md)
   - [Architecture](./contributing-architecture.md)
   - [Building](./contributing-building.md)