docs: add the HTTP request documentation. Improve features' docs (#180)

* docs: add the HTTP request documentation. Improve features' docs * docs: apply feedback on wording and code block types Co-authored-by: Rafael Fernández López <[email protected]> * docs: fix a rust code example for making HTTP requests * docs: fix indentation and improve Go HTTP request example * fix: typo error in a different example --------- Co-authored-by: Rafael Fernández López <[email protected]>
vmware-labs · Jul 14, 2023 · 0b5840e · 0b5840e
1 parent 5f2d167
commit 0b5840e
Show file tree

Hide file tree

Showing 13 changed files with 527 additions and 8 deletions.
diff --git a/docs/docs/features/_category_.json b/docs/docs/features/_category_.json
@@ -2,6 +2,7 @@
   "label": "Features",
   "position": 2,
   "link": {
-    "type": "generated-index"
+    "type": "doc",
+    "id": "all"
   }
-}
+}
diff --git a/docs/docs/features/all.md b/docs/docs/features/all.md
@@ -0,0 +1,38 @@
+# Features
+
+Wasm Workers Server provides different features to develop serverless applications. Some of these features are related to the server like the static asset management, while others relate to workers like sending HTTP requests.
+
+For that reason, we usually distinguish between server and worker features:
+
+* **Server features**: customizes or expands Wasm Worker Server capabilities. For example, you can expose static assets by saving these files in a `public` folder.
+
+* **Worker features**: expose new features to the individual workers so they can perform more complex tasks. For example, workers can access to a K/V store or use environment variables.
+
+## Available features
+
+### Server
+
+* [Static assets management](./static-assets.md)
+* [Multiple language runtimes](./multiple-language-runtimes.md)
+
+### Workers
+
+* [Key / Value store](./key-value.md)
+* [HTTP Requests (fetch)](./http-requests.md)
+* [Dynamic routes](./dynamic-routes.md)
+* [Environment variables](./environment-variables.md)
+* [Mount folders](./mount-folders.md)
+
+## Language compatibility
+
+You can develop workers in different languages. However, not all of them support all features. **The goal is to support all of them**, although there are some constraints that make some features more complex to implement in certain languages.
+
+The following table shows the language compatibility for the different worker functions:
+
+| Language | K/V Store | Environment Variables | Dynamic Routes | Folders | HTTP Requests |
+| --- | --- | --- | --- | --- | --- |
+| JavaScript | ✅ | ✅ | ✅ | ❌ | ✅ |
+| Rust | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Go | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Ruby | ✅ | ✅ | ✅ | ✅ | ❌ |
+| Python | ✅ | ✅ | ✅ | ✅ | ❌ |
diff --git a/docs/docs/features/dynamic-routes.md b/docs/docs/features/dynamic-routes.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # Dynamic routes
@@ -48,4 +48,14 @@ $ tree .
         └── show.js
 ```
 
-In this case, the `./[resource]/[id]/show.js` worker replies to URLs like `/articles/2/show`.
+In this case, the `./[resource]/[id]/show.js` worker replies to URLs like `/articles/2/show`.
+
+## Language compatibility
+
+| Language | Dynamic routes |
+| --- | --- |
+| JavaScript | ✅ |
+| Rust | ✅ |
+| Go | ✅ |
+| Ruby | ✅ |
+| Python | ✅ |
diff --git a/docs/docs/features/environment-variables.md b/docs/docs/features/environment-variables.md
@@ -39,4 +39,14 @@ JSON_MESSAGE = "Hello 👋! This message comes from an environment variable"
 TOKEN = "$TOKEN"
 ```
 
-This feature allows you to configure environment variables dynamically.
+This feature allows you to configure environment variables dynamically.
+
+## Language compatibility
+
+| Language | Environment variables |
+| --- | --- |
+| JavaScript | ✅ |
+| Rust | ✅ |
+| Go | ✅ |
+| Ruby | ✅ |
+| Python | ✅ |
diff --git a/docs/docs/features/http-requests.md b/docs/docs/features/http-requests.md
@@ -0,0 +1,41 @@
+---
+sidebar_position: 3
+---
+
+# HTTP Requests (fetch)
+
+Often times, workers require to access data from an external resource like a website or an API. This feature allows workers to perform HTTP requests to external resources. It follows the capability-based model, so workers cannot perform any HTTP request until you configure the allowed hosts and HTTP methods.
+
+In this configuration, you are allowing a worker to perform `GET` and `POST` HTTP requests to the [{JSON} Placeholder API](https://jsonplaceholder.typicode.com/):
+
+```toml
+name = "fetch"
+version = "1"
+
+[features]
+[features.http_requests]
+allowed_methods = ["GET", "POST"]
+allowed_hosts = ["jsonplaceholder.typicode.com"]
+```
+
+Now, your worker can perform HTTP requests following those rules.
+
+## Send HTTP requests in different languages
+
+Depending on the language, the different kits expose this feature in a different way. The goal is to use a common API to perform HTTP requests in that language. For example, to perform HTTP requests in JavaScript you can use the [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API.
+
+Check these guides to perform HTTP requests in the different supported languages:
+
+* [HTTP requests on JavaScript workers](../languages/javascript.md#send-an-http-request-fetch)
+* [HTTP requests on Rust workers](../languages/rust.md#send-an-http-request)
+* [HTTP requests on Go workers](../languages/go.md#send-an-http-request)
+
+## Language compatibility
+
+| Language | HTTP Requests |
+| --- | --- |
+| JavaScript | ✅ |
+| Rust | ✅ |
+| Go | ✅ |
+| Ruby | ❌ |
+| Python | ❌ |
diff --git a/docs/docs/features/key-value.md b/docs/docs/features/key-value.md
@@ -24,4 +24,14 @@ The worker may access all the data and perform changes over it. Then, a new K/V
 
 ## Limitations
 
-A known limitation of the snapshot approach is the data override when concurrent requests are writing to the same namespace. In the future, we will implement a consolidation mechanism or a different store type for applications that require to write intensively.
+A known limitation of the snapshot approach is the data override when concurrent requests are writing to the same namespace. In the future, we will implement a consolidation mechanism or a different store type for applications that require to write intensively.
+
+## Language compatibility
+
+| Language | K/V store |
+| --- | --- |
+| JavaScript | ✅ |
+| Rust | ✅ |
+| Go | ✅ |
+| Ruby | ✅ |
+| Python | ✅ |
diff --git a/docs/docs/features/mount-folders.md b/docs/docs/features/mount-folders.md
@@ -31,3 +31,13 @@ to = "/mnt/assets"
 In the previous example, all folders starts with an underscore character (`_`). This folder name convention tells `wws` to ignore any file inside it when detecting available workers.
 
 Note that those folders may include files that `wws` recognizes as workers (like `.js` or `.py`). By prefixing those folders with an `_`, you ensure `wws` won't process those files as workers.
+
+## Language compatibility
+
+| Language | Mount folders |
+| --- | --- |
+| JavaScript | ❌ |
+| Rust | ✅ |
+| Go | ✅ |
+| Ruby | ✅ |
+| Python | ✅ |
diff --git a/docs/docs/features/static-assets.md b/docs/docs/features/static-assets.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Static assets
@@ -44,4 +44,4 @@ The `about.html` file will be served as `/about`.
 
 ## Index file in public
 
-An `index.html` can be added to the `public` folder and it will be mounted in `/`. Note that static files have a lower priority, so if there's an `/index.js` and `/public/index.html` files, the `/` route will be served by the former.
+An `index.html` can be added to the `public` folder and it will be mounted in `/`. Note that static files have a lower priority, so if there's an `/index.js` and `/public/index.html` files, the `/` route will be served by the former.
diff --git a/docs/docs/languages/go.md b/docs/docs/languages/go.md
@@ -234,6 +234,140 @@ To add a KV store to your worker, follow these steps:
 
 1. Finally, open <http://127.0.0.1:8080/worker-kv> in your browser.
 
+## Send an HTTP request
+
+Wasm Workers allows you to send HTTP requests from your workers. Read more information about this feature in the [HTTP Requests](../features/http-requests.md) section.
+
+To perform HTTP requests from your worker, follow these steps:
+
+1. Create a new Go project:
+
+    ```shell-session
+    go mod init fetch
+    ```
+
+1. Add the project dependencies:
+
+    ```
+    go get -u github.com/vmware-labs/wasm-workers-server/kits/go/[email protected] \
+        github.com/tidwall/gjson
+    ```
+
+1. Create a `fetch.go` file with the following contents:
+
+    ```go title="fetch.go"
+    package main
+
+    import (
+        "io"
+        "fmt"
+        "net/http"
+
+        "github.com/vmware-labs/wasm-workers-server/kits/go/worker"
+
+        "github.com/tidwall/gjson"
+    )
+
+    func main() {
+        worker.ServeFunc(func(w http.ResponseWriter, r *http.Request) {
+            w.Header().Set("x-generated-by", "wasm-workers-server")
+            w.Write([]byte("Hello wasm!"))
+        })
+    }
+    ```
+
+1. Then, let's create the `http.Request` instance and pass it to the `worker.SendHttpRequest` method. In this example, we will call the [{JSON} Placeholder API](https://jsonplaceholder.typicode.com/) to retrieve a `Post`. You will read the content of the response using the `gjson` API:
+
+    ```go title="fetch.go"
+    package main
+
+    import (
+        "io"
+        "fmt"
+        "net/http"
+
+        "github.com/vmware-labs/wasm-workers-server/kits/go/worker"
+
+        "github.com/tidwall/gjson"
+    )
+
+    func main() {
+        worker.ServeFunc(func(w http.ResponseWriter, r *http.Request) {
+            url := "https://jsonplaceholder.typicode.com/posts/1"
+
+            // Create the request
+            req, err := http.NewRequest(http.MethodGet, url, nil)
+            if err != nil {
+                panic(err)
+            }
+
+            // Send the request
+            res, err := worker.SendHttpRequest(req)
+            if err != nil {
+                msg := fmt.Sprintf("Error when calling the API: %s", err);
+
+                // Send the reponse
+                w.Write([]byte(msg))
+
+                return
+            }
+
+            // Read the response and parse the title
+            resBody, err := io.ReadAll(res.Body)
+            if err != nil {
+                msg := fmt.Sprintf("Error when reading the response body: %s", err);
+
+                // Send the reponse
+                w.Write([]byte(msg))
+
+                return
+            }
+            res.Body.Close()
+
+            title := gjson.Get(string(resBody), "title")
+
+            w.Header().Set("x-generated-by", "wasm-workers-server")
+            w.Write([]byte(fmt.Sprintf("Title: %s", title.String())))
+        })
+    }
+    ```
+
+1. Compile the project to Wasm ([WASI](https://wasi.dev/)):
+
+    ```shell-session
+    tinygo build -o fetch.wasm -target wasi fetch.go
+    ```
+
+1. Create a `fetch.toml` file with the following content. It enables the worker to perform HTTP requests to that host given that, by default, HTTP requests are forbidden.
+
+  Note the name of the TOML file must match the name of the worker. In this case we have `fetch.wasm` and `fetch.toml` in the same folder:
+
+    ```toml title="fetch.toml"
+    name = "fetch"
+    version = "1"
+
+    [features]
+    [features.http_requests]
+    allowed_methods = ["GET"]
+    allowed_hosts = ["jsonplaceholder.typicode.com"]
+    ```
+
+1. Run your worker with `wws`. If you didn't download the `wws` server yet, check our [Getting Started](../get-started/quickstart.md) guide.
+
+    ```shell-session
+    wws .
+
+    ⚙️  Preparing the project from: .
+    ⚙️  Loading routes from: .
+    ⏳ Loading workers from 1 routes...
+    ✅ Workers loaded in 135.717667ms.
+        - http://127.0.0.1:8080/fetch
+          => ./fetch.wasm
+    🚀 Start serving requests at http://127.0.0.1:8080
+    ```
+
+1. Finally, open <http://127.0.0.1:8080/fetch> in your browser.
+
 ## Dynamic routes
 
 You can define [dynamic routes by adding route parameters to your worker files](../features/dynamic-routes.md) (like `[id].wasm`). To read them in Go, follow these steps:
@@ -328,4 +462,14 @@ If you prefer, you can configure the environment variable value dynamically by f
 * [Basic](https://github.com/vmware-labs/wasm-workers-server/tree/main/examples/go-basic)
 * [Counter](https://github.com/vmware-labs/wasm-workers-server/tree/main/examples/go-kv)
 
+## Contributors
+
 The Go kit was originally authored by Mohammed Nafees ([@mnafees](https://github.com/mnafees))
+
+## Feature compatibility
+
+[Workers' features](../features/all.md) that are available in Go:
+
+| [K/V Store](../features/key-value.md) | [Environment Variables](../features/environment-variables.md) | [Dynamic Routes](../features/dynamic-routes.md) | [Folders](../features/mount-folders.md) | [HTTP Requests](../features/http-requests.md) |
+| --- | --- | --- | --- | --- |
+|  ✅ | ✅ | ✅ | ✅ | ✅ |