docs: address first round of feedback

docs: update the timer example
docs: add page with a general overview of language support

ref #136

Signed-off-by: Radu Matei <[email protected]>

Author: radu-matei

Cargo.lock

@@ -47,7 +47,7 @@ members = [
     "crates/outbound-http",
     "crates/redis",
     "crates/templates",
-    "examples/spin-timer-echo",
+    "examples/spin-timer",
     "sdk/rust", 
     "sdk/rust/macro"
 ]

Cargo.toml

@@ -23,7 +23,7 @@ fn main() {
         "crates/http/benches/spin-http-benchmark",
     );
     build_wasm_test_program("wagi-benchmark.wasm", "crates/http/benches/wagi-benchmark");
-    build_wasm_test_program("echo.wasm", "examples/spin-timer-echo/example");
+    build_wasm_test_program("echo.wasm", "examples/spin-timer/example");
 
     cargo_build(RUST_HTTP_INTEGRATION_TEST);
     cargo_build(RUST_HTTP_INTEGRATION_ENV_TEST);

build.rs

@@ -64,8 +64,8 @@ Each `component` object has the following fields:
   - a string with the path to a local file containing the WebAssembly module for
     the component OR
   - a pair of `reference` (REQUIRED) and `parcel` (REQUIRED) fields pointing to
-    a remote bindle package (Note that this is currently not implemented, see
-    [#135](https://github.com/fermyon/spin/issues/135)).
+    a remote bindle package
+    ([Planned in #135](https://github.com/fermyon/spin/issues/135)).
 - `environment` (OPTIONAL): Environment variables to be made available inside
   the WebAssembly module at runtime.
 - `files` (OPTIONAL): Files to be made available inside the WebAssembly module
@@ -75,7 +75,7 @@ Each `component` object has the following fields:
   - a mapping of a `source` (REQUIRED), a directory relative to `spin.toml` and
     `destination` (REQUIRED), the absolute mount path to be mapped inside the
     WebAssembly module. For example
-    `{ source = "/content/", destination = "/"}`.
+    `{ source = "content/", destination = "/"}`.
 - `allowed_http_hosts` (OPTIONAL): List of HTTP hosts the component is allowed
   to make HTTP requests to (using the
   [WASI experimental HTTP library](https://github.com/deislabs/wasi-experimental-http))
@@ -104,7 +104,7 @@ Each `component` object has the following fields:
           parameters of the request, formatted as arguments. The default is to
           follow the CGI specification, and pass `${SCRIPT_NAME} ${ARGS}`
         - `entrypoint` (OPTIONAL): The name of the function that should be called
-          as the entrypoint to this handler. By default, it is `_start` (which in
+          as the entry point to this handler. By default, it is `_start` (which in
           most languages translates to calling `main` in the guest module).
   - `redis`: The configuration for a Redis component. This has the following fields:
     - `channel` (REQUIRED): The Redis channel for which, whenever a new message
@@ -124,7 +124,7 @@ route = "/static/..."
 ```
 
 - a Wagi HTTP component that contains file mounts and sets the module `argv` and
-  invokes a custom export function as the entrypoint:
+  invokes a custom export function as the entry point:
 
 ```toml
 [[component]]

docs/content/configuration.md

@@ -5,7 +5,7 @@ date = "2022-03-14T00:22:56Z"
 url = "https://github.com/fermyon/spin/blob/main/docs/content/extending-and-embedding.md"
 ---
 
-> The complete example for extending and embedding Spin [can be found on GitHub](https://github.com/fermyon/spin/tree/main/examples/spin-timer-echo).
+> The complete example for extending and embedding Spin [can be found on GitHub](https://github.com/fermyon/spin/tree/main/examples/spin-timer).
 
 Spin currently implements triggers and application models for:
 
@@ -20,36 +20,41 @@ In this document we will explore how to extend Spin with custom event sources
 (triggers) and application models built on top of the WebAssembly component
 model, as well as how to embed Spin in your application.
 
-The current application types that can be implemented with Spin have entrypoints
+In this article we will build a Spin trigger to run the applications based on a
+timer, executing Spin components at configured time interval.
+
+The current application types that can be implemented with Spin have entry points
 defined using
 [WebAssembly Interface (WIT)]((https://github.com/bytecodealliance/wit-bindgen/blob/main/WIT.md)):
 
 ```fsharp
-// The entrypoint for an HTTP handler.
+// The entry point for an HTTP handler.
 handle-http-request: function(req: request) -> response
 
-// The entrypoint for a Redis handler.
+// The entry point for a Redis handler.
 handle-redis-message: function(msg: payload) -> expected<_, error>
 ```
 
-Let's see how define a new application entrypoint for Spin:
+The entry point we want to execute for our timer trigger takes a string as its
+only argument (and the trigger will populate that with the current date and time),
+and it expects a string as the only return value. This is purposefully chosen
+to be a simple function signature:
 
 ```fsharp
-// examples/spin-timer-echo/echo.wit
-echo: function(msg: string) -> string
+// examples/spin-timer/spin-timer.wit
+handle-timer-request: function(msg: string) -> string
 ```
 
-This is the function signature that all "echo" components must implement, and
-which is used by the "echo" executor when instantiating and invoking the
-component.
+This is the function that all components executed by the timer trigger must
+implement, and which is used by the timer executor when instantiating and
+invoking the component.
 
-Let's define a new trigger for our new application type — a timer-based trigger:
+Let's have a look at building the timer trigger:
 
 ```rust
-// examples/spin-timer-echo/src/lib.rs
-wit_bindgen_wasmtime::import!("examples/spin-timer-echo/echo.wit");
-
-type ExecutionContext = spin_engine::ExecutionContext<echo::EchoData>;
+// examples/spin-timer/src/main.rs
+wit_bindgen_wasmtime::import!("spin-timer.wit");
+type ExecutionContext = spin_engine::ExecutionContext<spin_timer::SpinTimerData>;
 
 /// A custom timer trigger that executes the
 /// first component of an application on every interval.
@@ -66,10 +71,10 @@ pub struct TimerTrigger {
 
 A few important things to note from the start:
 
-- we use the WIT defined entrypoint with the
+- we use the WIT defined entry point with the
 [Bytecode Alliance `wit-bindgen` project](https://github.com/bytecodealliance/wit-bindgen)
-to generate "import" bindings based on the entrypoint — this generates code that
-allows us to easily invoke the entrypoint from application components that
+to generate "import" bindings based on the entry point — this generates code that
+allows us to easily invoke the entry point from application components that
 implement our new application model.
 - the new trigger has a field that contains a `Configuration<CoreComponent>` —
 in most cases, either `CoreComponent` will have to be updated with new trigger
@@ -81,7 +86,7 @@ creating the trigger (in the `new` function, you get access to the underlying
 Wasmtime store, instance, and linker, which can be configured as necessary).
 
 Finally, whenever there is a new event (in the case of our timer-based trigger
-every `n` seconds), we execute the entrypoint of a selected component:
+every `n` seconds), we execute the entry point of a selected component:
 
 ```rust
 /// Execute the first component in the application configuration.
@@ -91,12 +96,15 @@ async fn handle(&self, msg: String) -> Result<()> {
         self.engine
             .prepare_component(&self.app.components[0].id, None, None, None, None)?;
 
-    // spawn a new thread and call the `echo` function from the WebAssembly module 
+    // spawn a new thread and call the entry point function from the WebAssembly module 
     let res = spawn_blocking(move || -> Result<String> {
-        // use the auto-generated WIT bindings to get the Wasm exports and call the `echo` export.
-        let e = echo::Echo::new(&mut store, &instance, |host| host.data.as_mut().unwrap())?;
-        Ok(e.echo(&mut store, &msg)?)
-    }).await??;
+            // use the auto-generated WIT bindings to get the Wasm exports and call the `handle-timer-request` function.
+        let t = spin_timer::SpinTimer::new(&mut store, &instance, |host| {
+            host.data.as_mut().unwrap()
+        })?;
+        Ok(t.handle_timer_request(&mut store, &msg)?)
+    })
+    .await??;
     // do something with the result.
     log::info!("{}\n", res);
     Ok(())
@@ -109,7 +117,7 @@ A few notes:
 and it handles taking the Wasmtime pre-instantiated module, mapping all the
 component files, environment variables, and allowed HTTP domains, populating
 the Wasmtime store with the appropriate data, and returning the store and instance.
-- invoking the entrypoint `echo` is done in this example in a new Tokio thread —
+- invoking the entry point `handle-timer-request` is done in this example in a new Tokio thread —
 this is an implementation choice based on the needs of the trigger.
 - the return value from the component (a string in this example) can then be
 used — in the case of the HTTP trigger, this is an HTTP response, which is then
@@ -119,13 +127,55 @@ This is very similar to how the [HTTP](/http-trigger) and [Redis](/redis-trigger
 triggers are implemented, and it is the recommended way to extend Spin with your
 own trigger and application model.
 
+Writing components for the new trigger can be done by using the
+[`wit-bindgen` tooling](https://github.com/bytecodealliance/wit-bindgen) from
+Rust and other supported languages (see [the example in Rust](https://github.com/fermyon/spin/tree/main/examples/spin-timer/example)):
+
+```rust
+// automatically generate Rust bindings that help us implement the 
+// `handle-timer-request` function that the trigger will execute.
+wit_bindgen_rust::export!("../spin-timer.wit");
+...
+fn handle_timer_request(msg: String) -> String {
+    format!("ECHO: {}", msg)
+}
+```
+
+Components can be compiled to WebAssembly, then used from a `spin.toml`
+application configuration.
+
 Embedding the new trigger in a Rust application is done by creating a new trigger
 instance, then calling its `run` function:
 
 ```rust
+// app() is a utility function that generates a complete application configuration.
 let trigger = TimerTrigger::new(Duration::from_secs(1), app()).await?;
+// run the trigger indefinitely
 trigger.run().await
 ```
 
 > We are exploring [APIs for embedding Spin from other programming languages](https://github.com/fermyon/spin/issues/197)
 > such as Go or C#.
+
+In this example, we built a simple timer trigger — building more complex triggers
+would also involve updating the Spin application configuration, and extending
+the application-level trigger configuration, as well as component-level
+trigger configuration (an example of component-level trigger configuration
+for this scenario would be each component being able to define its own
+independent time interval for scheduling the execution).
+
+## Other ways to extend and use Spin
+
+Besides building custom triggers, the internals of Spin could also be used
+independently:
+
+- the Spin execution context can be used entirely without a `spin.toml`
+application configuration — for embedding scenarios, the configuration for the
+execution can be constructed without a `spin.toml` (see [issue #229](https://github.com/fermyon/spin/issues/229)
+for context)
+- the standard way of distributing a Spin application can be changed by
+re-implementing the [`loader`](https://github.com/fermyon/spin/tree/main/crates/loader)
+and [`publish`](https://github.com/fermyon/spin/tree/main/crates/publish) crates —
+all is required is that loading the application returns a valid
+`Configuration<CoreComponent>` that the Spin execution context can use to
+instantiate and execute components.

docs/content/extending-and-embedding.md

@@ -14,6 +14,8 @@ to build programs written in Go as Spin components.
 > This guide assumes you are familiar with the Go programming language, and that
 > you have
 > [configured the TinyGo toolchain locally](https://tinygo.org/getting-started/install/).
+Using TinyGo to compile components for Spin is currently required, as the
+[Go compiler doesn't currently have support for compiling to WASI](https://github.com/golang/go/issues/31105).
 
 > All examples from this page can be found in [the Spin repository on GitHub](https://github.com/fermyon/spin/tree/main/examples).
 
@@ -47,7 +49,7 @@ func main() {
 
 The important things to note in the implementation above:
 
-- the entrypoint to the component is the standard `func main()` for Go programs
+- the entry point to the component is the standard `func main()` for Go programs
 - handling the request is done by calling the `spin.HandleRequest` function,
 which takes a `func(w http.ResponseWriter, r *http.Request)` as parameter — these
 contain the HTTP request and response writer you can use to handle the request

docs/content/go-components.md

@@ -14,7 +14,7 @@ is used in Spin.
 The HTTP trigger in Spin is a web server. It listens for incoming requests and
 based on the [application configuration](/configuration), it routes them to an
 _executor_ which instantiates the appropriate component, executes its
-entrypoint function, then returns an HTTP response.
+entry point function, then returns an HTTP response.
 
 Creating an HTTP application is done when [configuring the application](/configuration)
 by defining the top-level application trigger:
@@ -33,7 +33,7 @@ and the _HTTP executor_ (see details below about executors). For example:
 ```toml
 [component.trigger]
 route = "/hello"
-executor = "spin"
+executor = { type = "spin" }
 ```
 
 - an HTTP component configured on the `/goodbye` route that uses the Wagi executor:
@@ -53,7 +53,7 @@ to all component routes defined for that application.
 
 For example, if the application `base` path is `base = /base`, and a component
 has defined `route = /foo`, that component will be executed for requests on
-`http/s::<spin-up-defined-address-and-port>/base/bar`.
+`http/s://<spin-up-defined-address-and-port>/base/foo`.
 
 Components can either define exact routes, for example `route = /bar/baz`, where
 the component will be invoked only for requests on `/base/bar/baz`, or they
@@ -103,7 +103,7 @@ community on building exciting new features and tools for it. As a result, the
 Spin HTTP _executor_ is defined using WebAssembly interfaces.
 
 > The WebAssembly component model is in its early stages, and during the `0.x`
-> releases of Spin, the triggers and application entrypoints will suffer
+> releases of Spin, the triggers and application entry points will suffer
 > breaking changes, particularly around the primitive types used to defined
 > the HTTP objects and function signatures — i.e. bodies will become streams,
 > handler functions will become asynchronous.
@@ -149,13 +149,13 @@ record response {
 > HTTP requests, and you can see its implementation in
 > [the WASI toolkit repository](https://github.com/fermyon/wasi-experimental-toolkit).
 
-Then, we define the entrypoint for a Spin HTTP component:
+Then, we define the entry point for a Spin HTTP component:
 
 ```fsharp
 // wit/ephemeral/spin-http.wit
 
 use * from http-types
-// The entrypoint for an HTTP handler.
+// The entry point for an HTTP handler.
 handle-http-request: function(req: request) -> response
 ```
 

docs/content/http-trigger.md

@@ -30,8 +30,8 @@ fn hello_world(req: Request) -> Result<Response> {​
 Spin applications are comprised of one or more function-based _components_, and
 follow the event-driven model — they are executed as the result of events being
 generated by _triggers_ (for example an HTTP server receiving requests, or a queue
-subscription receiving messages). On each new event, _the entrypoint_ of a
-component is executed by Spin. The entrypoints to components are _functions_.
+subscription receiving messages). On each new event, _the entry point_ of a
+component is executed by Spin. The entry points to components are _functions_.
 This, together with the fact that they are invoked in response to events, brings
 the Spin application model closer to the Function-as-a-Service model.
 

docs/content/index.md

@@ -0,0 +1,33 @@
+title = "Building Spin components in other languages"
+template = "main"
+date = "2022-03-14T00:22:56Z"
+[extra]
+url = "https://github.com/fermyon/spin/blob/main/docs/content/other-languages.md"
+---
+
+> This document is continuously evolving as we improve language SDKs and add
+> more examples on how to build Spin components in various programming languages.
+
+> See the document on writing [Rust](/rust-components) and [Go](/go-components)
+> components for Spin for detailed guides.
+
+WebAssembly is becoming [a popular compilation target for programming languages](https://www.fermyon.com/wasm-languages/webassembly-language-support), and as language toolchains add support for the
+[WebAssembly component model](https://github.com/WebAssembly/component-model),
+building Spin components will also become supported.
+
+As a general rule:
+
+- if your language supports the
+[WebAssembly component model](https://github.com/WebAssembly/component-model),
+building Spin components is supported either through an official Spin SDK
+(such as [the Spin SDK for Rust](/rust-components)), or through using
+bindings generators like [`wit-bindgen`](https://github.com/bytecodealliance/wit-bindgen)
+(for languages such as C and C++)
+- if your language compiles to WASI, but doesn't have support for the component
+model, you can build [Spin HTTP components](/http-trigger) that use the
+Wagi executor — for example in languages such as
+[Grain](https://github.com/deislabs/hello-wagi-grain),
+[AssemblyScript](https://github.com/deislabs/hello-wagi-as), or
+[Python](https://github.com/fermyon/wagi-python).
+- if your language doesn't currently compile to WebAssembly, there is no way to
+build and run Spin components in that programming language