Skip to content

Commit

Permalink
chore: pin examples to 0.82
Browse files Browse the repository at this point in the history 
Signed-off-by: Brooks Townsend <brooksmtownsend@gmail.com>
  • Loading branch information
@brooksmtownsend
brooksmtownsend committed Mar 17, 2024
1 parent ee3c540 commit 116c941
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 77 deletions.
58 changes: 28 additions & 30 deletions docs/developer/actors/generate.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: "Create"
title: 'Create'
date: 2018-12-29T11:00:00+00:00
sidebar_position: 0
draft: false
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import HubspotForm from 'react-hubspot-form';

We provide example templates for creating [actors](/docs/concepts/actors) in Rust and TinyGo. You can use these templates to create a new actor project, or you can use them as a reference for creating your own actor from scratch. As other languages are updated to use the same component APIs that wasmtime uses, we will add templates for those languages as well.
Expand All @@ -16,7 +16,7 @@ We provide example templates for creating [actors](/docs/concepts/actors) in Rus
Creating the scaffold for a new actor in Rust is easy. We will create an actor that accepts an HTTP request and responds with "Hello from Rust!". To create your new actor project, change to the directory where you want the project to be created, and enter the command below. The first term on the command (`hello`) is the project name. If you choose a different project name, the name of the subdirectory and some symbols in the generated code will be different from the example code in this guide.

```bash
wash new actor hello --template-name hello-world-rust
wash new actor hello --subfolder examples/rust/actors/http-hello-world --git wasmcloud/wasmcloud --branch 0.82-examples
```

Let's change into the newly-created folder `hello` and take a look at the generated project. The file `src/lib.rs` includes a `wit-bindgen` generate macro, an imports section, a struct `HttpServer`, and an `impl` block that implements the `Guest` trait for the actor struct. Let's walk through these sections in detail.
Expand All @@ -32,7 +32,6 @@ wit_bindgen::generate!({

This shows us that we're using a core wasmCloud package called `wit-bindgen` to generate the types and bindings for our actor. The `world` term is the name of the wit world we're generating from under `./wit`, and the `exports` term declares the functions the component will export. In this case, we're declaring that the actor will implement the `wasi:http/incoming-handler` capability interface, and that the implementation struct is named `HttpServer`.


Note the two lines near the top of the source code file:

```rust
Expand Down Expand Up @@ -68,7 +67,7 @@ Within the `handle` method, the actor receives the HTTP request, creates an `Out
Creating the scaffold for a new actor in TinyGo is easy. We will create an actor that accepts an HTTP request and responds with "Hello from Go!". To create your new actor project, change to the directory where you want the project to be created, and enter the command below. The first term on the command (`hello`) is the project name. If you choose a different project name, the name of the subdirectory and some symbols in the generated code will be different from the example code in this guide.

```bash
wash new actor hello --template-name hello-world-tinygo
wash new actor hello --subfolder examples/golang/actors/http-hello-world --git wasmcloud/wasmcloud --branch 0.82-examples
```

Let's change into the newly-created folder `hello` and take a look at the generated project. The file `hello.go` will include imports, a `main` function, a `Hello` struct, and an HTTP handler. Let's walk through these pieces in depth.
Expand Down Expand Up @@ -122,25 +121,20 @@ The business logic of our actor is contained within the `Handle` method. Within
func main() {}
```

Lastly, this Go directive will ensure that when we build our project with `tinygo build`, the `wit-bindgen` tool will be run to generate the types and bindings for our actor.
Lastly, this Go directive will ensure that when we build our project with `tinygo build`, the `wit-bindgen` tool will be run to generate the types and bindings for our actor.

</TabItem>
<TabItem value="typescript" label="TypeScript">
Creating the scaffold for a new actor in TypeScript is easy. We will create an actor that accepts an HTTP request and responds with "Hello from TypeScript!". To create your new actor project, change to the directory where you want the project to be created, and enter the command below. The first term on the command (`hello`) is the project name. If you choose a different project name, the name of the subdirectory and some symbols in the generated code will be different from the example code in this guide.

```bash
wash new actor hello --template-name hello-world-typescript
wash new actor hello --subfolder examples/typescript/actors/http-hello-world --git wasmcloud/wasmcloud --branch 0.82-examples
```

Let's change into the newly-created folder `hello` and take a look at the generated project. The file `http-hello-world.ts` will include imports and a `handle` function exported under `incomingHandler`. Let's walk through these pieces in depth.

```typescript
import {
IncomingRequest,
ResponseOutparam,
OutgoingResponse,
Fields,
} from "wasi:http/types@0.2.0";
import { IncomingRequest, ResponseOutparam, OutgoingResponse, Fields } from 'wasi:http/types@0.2.0';
```

The import section of this file is simple, we just import our generated types (from `jco`) for the WASI HTTP interface.
Expand All @@ -159,14 +153,14 @@ function handle(req: IncomingRequest, resp: ResponseOutparam) {
let outputStream = outgoingBody.write();
// // Write hello world to the response stream
outputStream.blockingWriteAndFlush(
new Uint8Array(new TextEncoder().encode("Hello from Typescript!\n"))
new Uint8Array(new TextEncoder().encode('Hello from Typescript!\n')),
);

// Set the status code for the response
outgoingResponse.setStatusCode(200);

// Set the created response
ResponseOutparam.set(resp, { tag: "ok", val: outgoingResponse });
ResponseOutparam.set(resp, { tag: 'ok', val: outgoingResponse });
}
```

Expand All @@ -185,7 +179,7 @@ Lastly, this export statement includes the `handle` function under the `incoming
Creating the scaffold for a new actor in Python is easy. We will create an actor that accepts an HTTP request and responds with "Hello from Python!". To create your new actor project, change to the directory where you want the project to be created, and enter the command below. The first term on the command (`hello`) is the project name. If you choose a different project name, the name of the subdirectory and some symbols in the generated code will be different from the example code in this guide.

```bash
wash new actor hello --template-name hello-world-python
wash new actor hello --subfolder examples/python/actors/http-hello-world --git wasmcloud/wasmcloud --branch 0.82-examples
```

Let's change into the newly-created folder `hello` and take a look at the generated project. The file `app.py` will include imports and a `handle` function on a `IncomingHandler` class. Let's walk through these pieces in depth.
Expand All @@ -204,7 +198,7 @@ The import section of this file is simple, we just import our generated types (f
```python
class IncomingHandler(exports.IncomingHandler):
def handle(self, _: IncomingRequest, response_out: ResponseOutparam):
# Construct the HTTP response to send back
# Construct the HTTP response to send back
outgoingResponse = OutgoingResponse(Fields.from_list([]))
# Set the status code to OK
outgoingResponse.set_status_code(200)
Expand All @@ -219,22 +213,26 @@ class IncomingHandler(exports.IncomingHandler):
The business logic of our actor is contained within the `handle` method. Within the `handle` method, the actor receives the HTTP request, creates an `OutgoingResponse` and writes that response back out to the requesting HTTP client (such as a `curl` command or a web browser).

This method is defined on the `IncomingHandler` class, which matches the `wasi:http/incoming-handler` interface declared in the application's [wit file](https://github.com/wasmCloud/wasmCloud/blob/main/examples/python/actors/http-hello-world/wit/world.wit).

</TabItem>
<TabItem value="unlisted" label="My Language Isn't Listed">

We're looking to add more examples in languages that support Wasm components. If you prefer working in a language that isn't listed here, let us know!
<div style={{ display: "flex", flexDirection: "row" }}>
<div style={{ width: "100%" }}>
<HubspotForm
portalId='20760433'
formId='71e74f55-cc30-41de-9d41-e3d9dc159c71'
onSubmit={() => console.log('Submitted form')}
onReady={(form) => console.log('Form ready for submit')}
region="na1"
loading={<div>Loading...</div>}
/>
</div>
We're looking to add more examples in languages that support Wasm components. If you prefer working in a language that isn't listed here, let us know!

{' '}

<div style={{ display: 'flex', flexDirection: 'row' }}>
<div style={{ width: '100%' }}>
<HubspotForm
portalId="20760433"
formId="71e74f55-cc30-41de-9d41-e3d9dc159c71"
onSubmit={() => console.log('Submitted form')}
onReady={(form) => console.log('Form ready for submit')}
region="na1"
loading={<div>Loading...</div>}
/>
</div>
</div>

</TabItem>
</Tabs>
Expand Down
99 changes: 52 additions & 47 deletions docs/tour/hello-world.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@
sidebar_position: 1
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import HubspotForm from 'react-hubspot-form'
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import HubspotForm from 'react-hubspot-form';

import washboard_hello from "../images/washboard_hello.png";
import washboard_hello from '../images/washboard_hello.png';

# Quickstart

Expand Down Expand Up @@ -39,9 +39,9 @@ To start a host, simply run `wash up`. The default settings should work well for
</TabItem>
<TabItem value="docker" label="Docker">

You can use the linked [docker-compose.yml](https://github.com/wasmCloud/wasmCloud/blob/main/examples/docker/docker-compose-full.yml) file to start the necessary host infrastructure in Docker:
You can use the linked [docker-compose.yml](https://github.com/wasmCloud/wasmCloud/blob/main/examples/docker/docker-compose-full.yml) file to start the necessary host infrastructure in Docker:

If you save the above file as `wasmcloud.yml`, you can start the host infrastructure with `docker compose --file wasmcloud.yaml up`.
If you save the above file as `wasmcloud.yml`, you can start the host infrastructure with `docker compose --file wasmcloud.yaml up`.

</TabItem>
</Tabs>
Expand All @@ -61,8 +61,7 @@ If you'd rather run the host in the background, run `wash up --detached` (or `wa

Now that our wasmCloud host infrastructure is running, let's generate a new actor component project. This is where our "Hello World" example begins. If you're running your host in the foreground, just switch to another terminal window to run these commands.

Pick your language of choice below to follow

Pick your language of choice below to follow

<Tabs groupId="lang" queryString>
<TabItem value="rust" label="Rust" default>
Expand All @@ -71,8 +70,9 @@ Pick your language of choice below to follow
:::

This command generates a new actor project in the `./hello` directory:

```bash
wash new actor hello --template-name hello-world-rust
wash new actor hello --subfolder examples/rust/actors/http-hello-world --git wasmcloud/wasmcloud --branch 0.82-examples
```

This actor is a simple Rust project with a few extra goodies included for wasmCloud. At a high level, the important pieces are:
Expand All @@ -87,18 +87,20 @@ You don't need any Rust dependencies installed to run this example, but if you w
```bash
rustup target add wasm32-wasi
```

:::

</TabItem>
<TabItem value="tinygo" label="TinyGo">

:::caution
Component examples are experimental and likely to require recompilation with each new release of wasmCloud.
:::
:::caution
Component examples are experimental and likely to require recompilation with each new release of wasmCloud.
:::

This command generates a new actor project in the `./hello` directory:

```bash
wash new actor hello --template-name hello-world-tinygo
wash new actor hello --subfolder examples/golang/actors/http-hello-world --git wasmcloud/wasmcloud --branch 0.82-examples
```

This actor is a simple Go project with a few extra goodies included for wasmCloud. At a high level, the important pieces are:
Expand All @@ -119,8 +121,9 @@ Component examples are experimental and likely to require recompilation with eac
:::

This command generates a new actor project in the `./hello` directory:

```bash
wash new actor hello --template-name hello-world-typescript
wash new actor hello --subfolder examples/typescript/actors/http-hello-world --git wasmcloud/wasmcloud --branch 0.82-examples
```

This actor is a simple TypeScript project with a few extra goodies included for wasmCloud. At a high level, the important pieces are:
Expand All @@ -141,8 +144,9 @@ Component examples are experimental and likely to require recompilation with eac
:::

This command generates a new actor project in the `./hello` directory:

```bash
wash new actor hello --template-name hello-world-python
wash new actor hello --subfolder examples/python/actors/http-hello-world --git wasmcloud/wasmcloud --branch 0.82-examples
```

This actor is a simple Python project with a few extra goodies included for wasmCloud. At a high level, the important pieces are:
Expand All @@ -153,34 +157,40 @@ This actor is a simple Python project with a few extra goodies included for wasm

:::info[Dependencies]
You don't need any Python dependencies installed to run this example, but if you want to build it yourself you'll need to install [Python 3.10 or later](https://www.python.org/) and [pip](https://pypi.org/project/pip/). After you have those, you'll need to install [componentize-py](https://github.com/bytecodealliance/componentize-py/tree/main?tab=readme-ov-file#getting-started) v0.11 or later:

```
pip install componentize-py
```

:::

</TabItem>
<TabItem value="unlisted" label="My Language Isn't Listed">

If you prefer working in a language that isn't listed here, let us know!
<div style={{ display: "flex", flexDirection: "row" }}>
<div style={{ width: "100%" }}>
<HubspotForm
portalId='20760433'
formId='71e74f55-cc30-41de-9d41-e3d9dc159c71'
onSubmit={() => console.log('Submitted form')}
onReady={(form) => console.log('Form ready for submit')}
region="na1"
loading={<div>Loading...</div>}
/>
</div>
If you prefer working in a language that isn't listed here, let us know!

{' '}

<div style={{ display: 'flex', flexDirection: 'row' }}>
<div style={{ width: '100%' }}>
<HubspotForm
portalId="20760433"
formId="71e74f55-cc30-41de-9d41-e3d9dc159c71"
onSubmit={() => console.log('Submitted form')}
onReady={(form) => console.log('Form ready for submit')}
region="na1"
loading={<div>Loading...</div>}
/>
</div>
</div>

</TabItem>
</Tabs>

Feel free to take a look at the code and the project structure. We'll take a look at each of these in depth later, so for now let's build and run the example.

## Building the Application

:::info
If you prefer not to build anything yet, you can use `wasmcloud.azurecr.io/hello:0.1.7` as the image inside of `wadm.yaml` instead to pull our prebuilt example actor.
:::
Expand All @@ -191,6 +201,7 @@ We can use the open source HTTP Server capability provider to serve our applicat
cd hello # enter the new project directory (if you haven't already)
wash build
```

```bash
Actor built and signed and can be found at "/Users/wasmcloud/hello/build/http_hello_world_s.wasm"
```
Expand All @@ -207,6 +218,7 @@ wash app deploy wadm.yaml
![wash app deploy diagram](../images/washappdeploy.png)

`wadm` will take care of taking this manifest and scheduling the resources on the host that you launched earlier. You should see output in the host logs when your actor and capability start up, which should happen after just a few seconds. After you see that the HTTP server set up the listener in the host logs, or once the application is **Deployed** when you check `wash app list`, you can query it yourself:

```bash
➜ wash app list

Expand Down Expand Up @@ -355,18 +367,15 @@ from hello.imports.types import (
)

class IncomingHandler(exports.IncomingHandler):
def handle(self, _: IncomingRequest, response_out: ResponseOutparam):
# Construct the HTTP response to send back
outgoingResponse = OutgoingResponse(Fields.from_list([]))
# Set the status code to OK
outgoingResponse.set_status_code(200)
outgoingBody = outgoingResponse.body()
# Write our Hello World message to the response body
outgoingBody.write().blocking_write_and_flush(bytes("Hello from Python!\n", "utf-8"))
OutgoingBody.finish(outgoingBody, None)
# Set and send the HTTP response
ResponseOutparam.set(response_out, Ok(outgoingResponse))
```
def handle(self, \_: IncomingRequest, response_out: ResponseOutparam): # Construct the HTTP response to send back
outgoingResponse = OutgoingResponse(Fields.from_list([])) # Set the status code to OK
outgoingResponse.set_status_code(200)
outgoingBody = outgoingResponse.body() # Write our Hello World message to the response body
outgoingBody.write().blocking_write_and_flush(bytes("Hello from Python!\n", "utf-8"))
OutgoingBody.finish(outgoingBody, None) # Set and send the HTTP response
ResponseOutparam.set(response_out, Ok(outgoingResponse))

````

This actor has a single class, `IncomingHandler`, that implements the `handle` function. This function is called by the HTTP Server capability provider when it receives an incoming HTTP request. The `handle` function constructs an HttpResponse and sends it back to the HTTP Server capability provider, which then sends it back to the client. There's no mention of ports, certificates, HTTP libraries, and if those things change this actor will work all the same.

Expand All @@ -389,7 +398,7 @@ metadata:
name: hello
annotations:
version: v0.0.1
description: "wasmCloud Hello World Example"
description: 'wasmCloud Hello World Example'
spec:
components:
# Your actor component, started from the wasmCloud example OCI artifact
Expand All @@ -415,7 +424,7 @@ spec:
properties:
image: wasmcloud.azurecr.io/httpserver:0.19.1
contract: wasmcloud:httpserver
```
````

## Scaling up 📈

Expand All @@ -429,7 +438,7 @@ metadata:
annotations:
# Make sure to bump the version so wadm knows to update the application
version: v0.0.2
description: "wasmCloud Hello World Example"
description: 'wasmCloud Hello World Example'
spec:
components:
- name: hello
Expand Down Expand Up @@ -460,11 +469,7 @@ Treat wasmCloud hosts as cattle, not pets. Stopping your host will stop all of t
Then, you can launch the wasmCloud dashboard using `wash ui`, which will launch the dashboard on [http://localhost:3030](http://localhost:3030).
This is a great way to visualize what is running on your host, even multiple hosts that are connected to the same NATS server.

<img
src={washboard_hello}
width="800"
alt="wasmCloud dashboard with hello world application"
/>
<img src={washboard_hello} width="800" alt="wasmCloud dashboard with hello world application" />

## Log files

Expand Down

0 comments on commit 116c941

Please sign in to comment.