Skip to content

Commit 9befd75

Browse files
thomastaylor312thomastaylor312
committed
docs(examples): Adds additional docs for remaining examples
Signed-off-by: Taylor Thomas <[email protected]>
1 parent 541ea59 commit 9befd75

File tree

7 files changed

+327
-9
lines changed

7 files changed

+327
-9
lines changed

‎examples/component/http-client/README.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Go HTTP Client
2+
3+
This repository contains a WebAssembly Component compiled using [TinyGo][tinygo], which:
4+
5+
- Implements a [`wasi:http`][wasi-http]-compliant HTTP handler
6+
- Uses the [`httpserver` provider][httpserver-provider] to serve requests
7+
- Calls a random number generator service to get random numbers using [`wasi:http`][wasi-http]
8+
- Can be declaratively provisioned with [`wadm`][wadm]
9+
10+
[wasi-http]: https://github.com/WebAssembly/wasi-http
11+
[httpserver-provider]: https://github.com/wasmCloud/wasmCloud/tree/main/crates/provider-http-server
12+
[httpclient-provider]: https://github.com/wasmCloud/wasmCloud/tree/main/crates/provider-http-client
13+
[wadm]: https://github.com/wasmCloud/wadm
14+
[tinygo]: https://tinygo.org/getting-started/install/
15+
[wash]: https://wasmcloud.com/docs/ecosystem/wash/
16+
[wasm-tools]: https://github.com/bytecodealliance/wasm-tools#installation
17+
18+
# Dependencies
19+
20+
Before starting, ensure that you have the following installed in addition to the Go toolchain:
21+
22+
- The [TinyGo toolchain][tinygo]
23+
- [`wash`, the WAsmcloud SHell][wash] installed.
24+
- [`wasm-tools`][wasm-tools] for Go bindings
25+
26+
# Quickstart
27+
28+
To get started developing this repository quickly, clone the repo and run `wash dev`:
29+
30+
```console
31+
wash dev
32+
```
33+
34+
`wash dev` does many things for you:
35+
36+
- Starts the [wasmCloud host][wasmcloud-host] that can run your WebAssembly component
37+
- Builds this project
38+
- Builds a declarative WADM manifest consisting of:
39+
- Your locally built component
40+
- A [HTTP server provider][httpserver-provider] which will receive requests from the outside world
41+
(on port 8000 by default)
42+
- A [HTTP client provider][httpclient-provider] which will call a random number generator service
43+
- Necessary links between providers and your component so your component can handle web traffic
44+
- Deploys the built manifest (i.e all dependencies to run this application) locally
45+
- Watches your code for changes and re-deploys when necessary.
46+
47+
[wasmcloud-host]: https://wasmcloud.com/docs/concepts/hosts
48+
49+
## Send a request to the running component
50+
51+
Once `wash dev` is serving your component, to send a request to the running component (via the HTTP
52+
server provider). It will call an upstream API and return a list of random numbers:
53+
54+
```console
55+
curl localhost:8000
56+
[438,424,166,260,681]
57+
```
58+
59+
# Issues/ FAQ
60+
61+
<summary>
62+
<description>
63+
64+
## `curl` produces a "failed to invoke" error
65+
66+
</description>
67+
68+
If `curl`ing produces
69+
70+
```
71+
curl localhost:8000
72+
failed to invoke `wrpc:http/incoming-handler.handle`: failed to invoke `wrpc:http/[email protected]`: failed to shutdown synchronous parameter channel: not connected%
73+
```
74+
75+
You *may* need to just wait a little bit -- the HTTP server takes a second or two to start up.
76+
77+
If the issue *persists*, you *may* have a lingering HTTP server provider running on your system. You
78+
can use `pgrep` to find it:
79+
80+
```console
81+
❯ pgrep -la ghcr_io
82+
4007604 /tmp/wasmcloudcache/NBCBQOZPJXTJEZDV2VNY32KGEMTLFVP2XJRZJ5FWEJJOXESJXXR2RO46/ghcr_io_wasmcloud_http_server_0_23_1
83+
```
84+
85+
</summary>

‎examples/component/http-client/wadm.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ spec:
4040
source_config:
4141
- name: default-http
4242
properties:
43-
address: 0.0.0.0:30001
43+
address: 0.0.0.0:8000
4444
- name: httpclient
4545
type: capability
4646
properties:

‎examples/component/http-password-checker/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,15 @@ This repository contains a WebAssembly Component written in [TinyGo][tinygo], wh
1111
[wadm]: https://github.com/wasmCloud/wadm
1212
[tinygo]: https://tinygo.org/getting-started/install/
1313
[wash]: https://wasmcloud.com/docs/ecosystem/wash/
14+
[wasm-tools]: https://github.com/bytecodealliance/wasm-tools#installation
1415

1516
# Dependencies
1617

17-
Before starting, ensure that you have the following installed:
18+
Before starting, ensure that you have the following installed in addition to the Go toolchain:
1819

1920
- The [TinyGo toolchain][tinygo]
2021
- [`wash`, the WAsmcloud SHell][wash] installed.
22+
- [`wasm-tools`][wasm-tools] for Go bindings
2123

2224
# Quickstart
2325

‎examples/component/http-server/README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Go HTTP Password Checker
2+
3+
This repository contains a WebAssembly Component compiled using [TinyGo][tinygo], which:
4+
5+
- Implements a [`wasi:http`][wasi-http]-compliant HTTP handler
6+
- Uses the [`httpserver` provider][httpserver-provider] to serve requests
7+
- Can be declaratively provisioned with [`wadm`][wadm]
8+
9+
[wasi-http]: https://github.com/WebAssembly/wasi-http
10+
[httpserver-provider]: https://github.com/wasmCloud/wasmCloud/tree/main/crates/provider-http-server
11+
[wadm]: https://github.com/wasmCloud/wadm
12+
[tinygo]: https://tinygo.org/getting-started/install/
13+
[wash]: https://wasmcloud.com/docs/ecosystem/wash/
14+
[wasm-tools]: https://github.com/bytecodealliance/wasm-tools#installation
15+
16+
# Dependencies
17+
18+
Before starting, ensure that you have the following installed in addition to the Go toolchain:
19+
20+
- The [TinyGo toolchain][tinygo]
21+
- [`wash`, the WAsmcloud SHell][wash] installed.
22+
- [`wasm-tools`][wasm-tools] for Go bindings
23+
24+
## Quickstart
25+
26+
To get started developing this repository quickly, clone the repo and run `wash dev`:
27+
28+
```console
29+
wash dev
30+
```
31+
32+
`wash dev` does many things for you:
33+
34+
- Starts the [wasmCloud host][wasmcloud-host] that can run your WebAssembly component
35+
- Builds this project
36+
- Builds a declarative WADM manifest consisting of:
37+
- Your locally built component
38+
- A [HTTP server provider][httpserver-provider] which will receive requests from the outside world
39+
(on port 8000 by default)
40+
- Necessary links between providers and your component so your component can handle web traffic
41+
- Deploys the built manifest (i.e all dependencies to run this application) locally
42+
- Watches your code for changes and re-deploys when necessary.
43+
44+
[wasmcloud-host]: https://wasmcloud.com/docs/concepts/hosts
45+
46+
## Send a request to the running component
47+
48+
Once `wash dev` is serving your component, to send a request to the running component (via the HTTP
49+
server provider)
50+
51+
### Available Endpoints
52+
53+
#### GET /
54+
55+
Returns a list of available endpoints and their descriptions.
56+
57+
```console
58+
curl http://localhost:8000/
59+
/error - return a 500 error
60+
/form - echo the fields of a POST request
61+
/headers - echo your user agent back as a server side header
62+
/post - echo the body of a POST request
63+
```
64+
65+
#### GET /error
66+
67+
Returns a 500 Internal Server Error.
68+
69+
```console
70+
curl -v http://localhost:8000/error
71+
* Host localhost:8000 was resolved.
72+
* IPv6: ::1
73+
* IPv4: 127.0.0.1
74+
* Trying [::1]:8000...
75+
* connect to ::1 port 8000 from ::1 port 51390 failed: Connection refused
76+
* Trying 127.0.0.1:8000...
77+
* Connected to localhost (127.0.0.1) port 8000
78+
> GET /error HTTP/1.1
79+
> Host: localhost:8000
80+
> User-Agent: curl/8.7.1
81+
> Accept: */*
82+
>
83+
* Request completely sent off
84+
< HTTP/1.1 500 Internal Server Error
85+
< content-type: text/plain; charset=utf-8
86+
< x-content-type-options: nosniff
87+
< vary: origin, access-control-request-method, access-control-request-headers
88+
< access-control-allow-origin: *
89+
< access-control-expose-headers: *
90+
< connection: close
91+
< transfer-encoding: chunked
92+
< date: Thu, 19 Dec 2024 23:52:34 GMT
93+
<
94+
Something went wrong
95+
* Closing connection
96+
```
97+
98+
#### GET /headers
99+
100+
Returns your User-Agent in the response headers.
101+
102+
```console
103+
curl -v http://localhost:8000/headers
104+
* Host localhost:8000 was resolved.
105+
* IPv6: ::1
106+
* IPv4: 127.0.0.1
107+
* Trying [::1]:8000...
108+
* connect to ::1 port 8000 from ::1 port 51499 failed: Connection refused
109+
* Trying 127.0.0.1:8000...
110+
* Connected to localhost (127.0.0.1) port 8000
111+
> GET /headers HTTP/1.1
112+
> Host: localhost:8000
113+
> User-Agent: curl/8.7.1
114+
> Accept: */*
115+
>
116+
* Request completely sent off
117+
< HTTP/1.1 200 OK
118+
< x-your-user-agent: curl/8.7.1
119+
< vary: origin, access-control-request-method, access-control-request-headers
120+
< access-control-allow-origin: *
121+
< access-control-expose-headers: *
122+
< connection: close
123+
< transfer-encoding: chunked
124+
< date: Thu, 19 Dec 2024 23:53:49 GMT
125+
<
126+
* Closing connection
127+
Check headers!
128+
```
129+
130+
#### POST /form
131+
132+
Echoes back form data from a POST request.
133+
134+
```console
135+
curl -X POST -d "field1=value1&field2=value2" http://localhost:8000/form
136+
field2: value2
137+
field1: value1
138+
```
139+
140+
#### POST /post
141+
142+
Echoes back the entire body of a POST request.
143+
144+
```console
145+
curl -X POST -d "Hello World" http://localhost:8000/post
146+
Hello World
147+
```
148+
149+
## Adding Capabilities
150+
151+
To learn how to extend this example with additional capabilities, see the [Adding
152+
Capabilities](https://wasmcloud.com/docs/tour/adding-capabilities?lang=rust) section of the
153+
wasmCloud documentation.
154+
155+
# Issues/ FAQ
156+
157+
<summary>
158+
<description>
159+
160+
## `curl` produces a "failed to invoke" error
161+
162+
</description>
163+
164+
If `curl`ing produces
165+
166+
```
167+
➜ curl localhost:8000
168+
failed to invoke `wrpc:http/incoming-handler.handle`: failed to invoke `wrpc:http/[email protected]`: failed to shutdown synchronous parameter channel: not connected%
169+
```
170+
171+
You *may* need to just wait a little bit -- the HTTP server takes a second or two to start up.
172+
173+
If the issue *persists*, you *may* have a lingering HTTP server provider running on your system. You
174+
can use `pgrep` to find it:
175+
176+
```console
177+
❯ pgrep -la ghcr_io
178+
4007604 /tmp/wasmcloudcache/NBCBQOZPJXTJEZDV2VNY32KGEMTLFVP2XJRZJ5FWEJJOXESJXXR2RO46/ghcr_io_wasmcloud_http_server_0_23_1
179+
```
180+
181+
</summary>

‎examples/component/http-server/wadm.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,4 +34,4 @@ spec:
3434
source_config:
3535
- name: default-http
3636
properties:
37-
address: 0.0.0.0:30000
37+
address: 0.0.0.0:8000

‎examples/component/invoke/README.md‎

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,68 @@
11
# Custom WIT example
22

3-
This example shows how to combine the component-sdk with your custom interfaces.
3+
This example shows how to combine the wasmCloud Component SDK with your custom interfaces. You can
4+
find the custom interface in `wit/world.wit`. It should look something like this:
45

5-
Build the example:
6+
```wit
7+
interface invoker {
8+
call: func() -> string;
9+
}
10+
```
11+
12+
# Dependencies
13+
14+
Before starting, ensure that you have the following installed in addition to the Go toolchain:
15+
16+
- The [TinyGo toolchain][tinygo]
17+
- [`wash`, the WAsmcloud SHell][wash] installed.
18+
- [`wasm-tools`][wasm-tools] for Go bindings
19+
20+
[wasm-tools]: https://github.com/bytecodealliance/wasm-tools#installation
21+
22+
## Running the example
23+
24+
For this example, we will be building and deploying manually rather than using `wash dev` since we
25+
will be demonstrating `wash call` which requires a stable identity to call. As you gain experience
26+
with wasmCloud, you will likely want to use `wash dev` to automate your development process.
27+
28+
First, build the component:
629

730
```bash
831
wash build
932
```
1033

11-
Deploy
34+
Then you can start the host:
1235

1336
```bash
14-
wash app deploy ./wadm.yaml
37+
wash up -d
1538
```
1639

17-
Call the custom interface:
40+
Next, deploy the component:
41+
42+
```bash
43+
wash app deploy wadm.yaml
44+
```
45+
46+
You should then be able to call the component:
1847

1948
```bash
2049
wash call invoke_example-invoker example:invoker/invoker.call
50+
Hello from the invoker!
51+
```
52+
53+
To clean up, run:
54+
55+
```bash
56+
wash app delete wadm.yaml
57+
wash down
58+
```
59+
60+
### Bonus: Calling when running with `wash dev`
61+
62+
When running with `wash dev`, it uses a generated ID for the component. If you have `jq` installed,
63+
you can run the following command to call the component:
64+
65+
```bash
66+
wash call "$(wash get inventory -o json | jq -r '.inventories[0].components[0].id')" example:invoker/invoker.call
67+
Hello from the invoker!
2168
```

‎examples/component/sqldb-postgres-query/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,17 @@ This folder contains a WebAssembly component that makes use of:
99

1010
## 📦 Dependencies
1111

12-
- `go` 1.23+
12+
Before starting, ensure that you have the following installed in addition to the Go toolchain:
13+
1314
- `tinygo` 0.33+
1415
- [`docker`][docker] for easily running instances of [`postgres`]
1516
- [`wash`][wash] for building and running the components and [wasmCloud][wasmcloud] hosts
17+
- [`wasm-tools`][wasm-tools] for Go bindings
1618

1719
[docker]: https://docs.docker.com
1820
[wash]: https://wasmcloud.com/docs/installation
1921
[wadm]: https://github.com/wasmCloud/wadm
22+
[wasm-tools]: https://github.com/bytecodealliance/wasm-tools#installation
2023

2124
## 👟 Quickstart
2225

0 commit comments

Comments
 (0)