diff --git a/docs/examples.mdx b/docs/examples.mdx index 31975ea7..790a5926 100644 --- a/docs/examples.mdx +++ b/docs/examples.mdx @@ -128,7 +128,7 @@ wash new https://github.com/wasmCloud/wasmCloud.git --name my-project --subfolde #### HTTP API with Distributed Workloads (Rust) -A two-component Rust workspace demonstrating distributed workloads over messaging. An `http-api` component receives `POST /task` requests and dispatches work via `wasmcloud:messaging/consumer`; a `task-leet` component exports `wasmcloud:messaging/handler` and transforms the payload (e.g., text → "leet speak"). During `wash dev`, the runtime routes calls between components in-process — no NATS server required. +A two-component Rust workspace demonstrating distributed workloads over messaging. An `http-api` component receives `POST /task` requests and dispatches work via `wasmcloud:messaging/consumer`; a `task-leet` component exports `wasmcloud:messaging/handler` and transforms the payload (e.g., text → "leet speak"). During `wash dev`, the runtime routes calls between components in-process — no NATS server required. When deployed with multiple replicas (as of wasmCloud 2.6.0), replicas join a per-component consumer group by default so that one replica handles each message; set `consumer_group` to `broadcast` in the component's configuration to deliver every message to every replica. - **Source**: [`wasmCloud/wasmCloud — templates/http-api-with-distributed-workloads`](https://github.com/wasmCloud/wasmCloud/tree/main/templates/http-api-with-distributed-workloads) - **`http-api` interfaces**: Imports `wasmcloud:messaging/consumer@0.2.0`; exports `wasi:http/incoming-handler` (via the `wstd` `#[http_server]` proc macro) @@ -252,7 +252,7 @@ wash new https://github.com/wasmCloud/typescript.git --name my-project --subfold #### HTTP API with Distributed Workloads -A two-component TypeScript project demonstrating component-to-component coordination over `wasmcloud:messaging`. An `http-api` component accepts `POST /task` requests and dispatches work via `wasmcloud:messaging/consumer`; a `task-worker` component exports `wasmcloud:messaging/handler`, processes the payload, and returns a reply. During `wash dev`, the runtime routes calls between components in-process — no NATS server required. +A two-component TypeScript project demonstrating component-to-component coordination over `wasmcloud:messaging`. An `http-api` component accepts `POST /task` requests and dispatches work via `wasmcloud:messaging/consumer`; a `task-worker` component exports `wasmcloud:messaging/handler`, processes the payload, and returns a reply. During `wash dev`, the runtime routes calls between components in-process — no NATS server required. When deployed with multiple replicas (as of wasmCloud 2.6.0), replicas join a per-component consumer group by default so that one replica handles each message; set `consumer_group` to `broadcast` in the component's configuration to deliver every message to every replica. - **Source**: [`wasmCloud/typescript — templates/http-api-with-distributed-workloads`](https://github.com/wasmCloud/typescript/tree/main/templates/http-api-with-distributed-workloads) - **`http-api` interfaces**: Imports `wasmcloud:messaging/consumer@0.2.0`; exports `wasi:http/incoming-handler@0.2.6` @@ -280,12 +280,13 @@ wash new https://github.com/wasmCloud/typescript.git --name my-project --subfold ## Examples -Complete example applications are available in the [`examples/` directory of `wasmCloud/wasmCloud`](https://github.com/wasmCloud/wasmCloud/tree/main/examples) (Rust) and the [`examples/components/` directory of `wasmCloud/typescript`](https://github.com/wasmCloud/typescript/tree/main/examples/components) (TypeScript). Run `wash dev` from any example directory to build and start a local development environment. +Complete example applications are available in the [`examples/` directory of `wasmCloud/wasmCloud`](https://github.com/wasmCloud/wasmCloud/tree/main/examples) (Rust) and the [`examples/components/` directory of `wasmCloud/typescript`](https://github.com/wasmCloud/typescript/tree/main/examples/components) (TypeScript). Run `wash dev` from any example directory to build and start a local development environment (check individual entries for any additional build requirements). | Example | Language | OCI Artifact | |---|---|---| | [Blobby](#blobby) | Rust | [`ghcr.io/wasmcloud/components/blobby`](https://github.com/orgs/wasmCloud/packages/container/package/components%2Fblobby) | | [gRPC Hello World](#grpc-hello-world) | Rust | [`components/grpc-hello-world-client`](https://github.com/orgs/wasmCloud/packages/container/package/components%2Fgrpc-hello-world-client), [`components/grpc-hello-world-server`](https://github.com/orgs/wasmCloud/packages/container/package/components%2Fgrpc-hello-world-server) | +| [OCI Registry](#oci-registry) | Rust | — | | [OpenTelemetry Config](#opentelemetry-config) | Rust | [`ghcr.io/wasmcloud/components/otel-config`](https://github.com/orgs/wasmCloud/packages/container/package/components%2Fotel-config) | | [QR Code Generator](#qr-code-generator) | Rust | [`ghcr.io/wasmcloud/components/qrcode`](https://github.com/orgs/wasmCloud/packages/container/package/components%2Fqrcode) | | [HTTP Axios](#http-axios) | TypeScript | — | @@ -315,6 +316,17 @@ Two components demonstrating how to make and serve gRPC calls from a wasmCloud c - **`component-client` interfaces**: Imports `wasi:http/outgoing-handler`; exports `wasi:http/incoming-handler` (via `wstd`) - **`component-server` interfaces**: Exports `wasi:http/incoming-handler` (via `wstd`) +#### OCI Registry + +A minimal [OCI Distribution Spec (v2)](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) registry implemented as a single WASI P3 component. The registry API is served over the async `wasi:http/handler@0.3.0` export, and every blob, manifest, and tag is stored through the async, natively-streaming `wasmcloud:blobstore` interface — so the same component runs against any blobstore backend (in-memory, filesystem, NATS) without code changes. Spec-compliant as a drop-in target for clients like [`oras`](https://oras.land) and `docker`/`podman`: blob and manifest CRUD, resumable uploads, tag listing, and the referrers API. HTTP Basic auth is required on every request — including the `/v2/` version probe — with credentials read through `wasmcloud:secrets`, served by a [host component plugin](/docs/overview/hosts/plugins/); without a configured secrets backend, the registry denies all requests rather than serving unauthenticated. + +- **Source**: [`wasmCloud/wasmCloud — examples/oci-registry`](https://github.com/wasmCloud/wasmCloud/tree/main/examples/oci-registry) +- **Interfaces**: Imports `wasmcloud:blobstore/{blobstore,container,types}@0.1.0`, `wasmcloud:secrets/{store,reveal}@2.1.0`, and `wasi:random/random@0.3.0`; exports `wasi:http/handler@0.3.0` + +:::note[Build requirements] +This example depends on the async `wasmcloud:blobstore` host plugin (behind the `wasm_component_model_implements` feature) and WASI P3 component builds from the in-progress async-backends line of `wash` — a released `wash` (≤ 2.x) can't run it yet. See the [example README](https://github.com/wasmCloud/wasmCloud/tree/main/examples/oci-registry) for current build prerequisites. (At the time of writing, the README's feature notes lag the code — auth landed after it was written.) +::: + #### OpenTelemetry Config A component instrumented with OpenTelemetry through the `wasi:otel` interfaces, with its OTel `Resource` (service name, environment, etc.) sourced from `wasi:config/store`. Each operation emits tracing, log, and metric data; the same component identifies itself differently per environment because `workload.config` and the OTel `Resource` are wired together at deploy time rather than at compile time. @@ -387,3 +399,11 @@ An HTTP component that reads runtime configuration via the `wasi:config/store` i - **Source**: [`wasmCloud/typescript — examples/components/wasi-config-from-k8s-env`](https://github.com/wasmCloud/typescript/tree/main/examples/components/wasi-config-from-k8s-env) - **Interfaces**: Imports `wasi:config/store@0.2.0-rc.1`; exports `wasi:http/incoming-handler@0.2.6` + +## Community projects: awesome-wasmcloud + +Beyond the first-party templates and examples above, the community maintains [awesome-wasmcloud](https://github.com/wasmCloud/awesome-wasmcloud) — a collection of community-built **components**, **host plugins** (native and host component plugins), **workload examples**, and **tools**. Projects can be hosted directly in the repository or linked from their own repositories; each entry is tagged `(hosted)` or `(linked)`. + +The first entry is [wasi-ai-app](https://github.com/bharattech/wasi-ai-app), a local AI meeting-notes pipeline built from three Rust components — a transcriber, a summarizer, and a web UI — that runs inference entirely on-device. + +Have something to share? See the repository's [contributing guide](https://github.com/wasmCloud/awesome-wasmcloud/blob/main/CONTRIBUTING.md) to add your project. Note that community projects are maintained by their authors: inclusion is not an endorsement or security review, so read the code before running it.