Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions .gitattributes

This file was deleted.

1 change: 1 addition & 0 deletions .github/workflows/checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,4 +23,5 @@ jobs:
version: v2.13.2
install-only: true
github-token: ${{ secrets.GITHUB_TOKEN }}
- run: just ensure_no_componentize_go_toml
- run: just lint
8 changes: 0 additions & 8 deletions .golangci.yml

This file was deleted.

4 changes: 4 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,7 @@
echo "Lint..."
command -v golangci-lint >/dev/null 2>&1 || { echo "golangci-lint is not installed or in PATH"; exit 1; }
GOARCH=wasm GOOS=wasip1 golangci-lint run

[doc('Validates that a componentize-go.toml file is NOT present in the root of the repo, as it causes issues with some of the defaults in componentize-go')]
@ensure_no_componentize_go_toml:
test ! -e componentize-go.toml || { echo "componentize-go.toml must not exist"; exit 1; }
99 changes: 1 addition & 98 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,110 +15,13 @@

# Overview

Module `go.bytecodealliance.org/pkg` is the Go library for Wasm components. It adapts standard-library interfaces (`net/http`, `log/slog`) to standard `wasi:*` interfaces and ships the committed bindings and WIT worlds needed to build HTTP components with [componentize-go](https://github.com/bytecodealliance/componentize-go). The use of this package significantly reduces the number of files generated and committed for a typical go application.

The library targets two worlds defined in [`wit/world.wit`](./wit/world.wit):

- **`bytecodealliance:pkg/wasip2`** (default): a sync WASI P2 component exporting `wasi:http/incoming-handler@0.2.8`, buildable with stock Go.
- **`bytecodealliance:pkg/wasip3`** (opt-in): an async WASI P3 component exporting `wasi:http/handler@0.3.0` with streaming bodies and native concurrency.
Module `go.bytecodealliance.org/pkg` contains packages required for building components with [componentize-go](https://github.com/bytecodealliance/componentize-go).

## Packages

| Package | Description |
| --- | --- |
| `wasihttp` | `net/http` adapter for `wasi:http`: serve incoming requests with a standard `http.Handler` and send outbound requests through an `http.RoundTripper`. One API, two implementations selected by build tag (see below). |
| `wasilog` | `slog.Handler` implementation over `wasi:logging`. |
| `wasiconfig` | Helpers over `wasi:config/store`. |
| `wit/types`, `wit/runtime`, `wit/async` | Core WIT value types (option, result, tuple, stream, future) and the canonical-ABI runtime support used by generated bindings. |
| `imports/...` | Committed generated bindings for the `wasi:*` interfaces imported by the two worlds (both the 0.2.8 and 0.3.0 families). |
| `exports/...` | Per-world generated `//go:wasmexport` glue and export trampolines. |

Bindings under `imports/` and `exports/` are generated by
[`regenerate_bindings.sh`](./regenerate_bindings.sh) — do not edit them.

## Updating WIT dependencies

The `wasi:*` WIT packages under `wit/deps/` are vendored verbatim from the WebAssembly package registry using [wkg](https://github.com/bytecodealliance/wasm-pkg-tools). To update a dependency:

1. Bump its version in [`fetch_wit_deps.sh`](./fetch_wit_deps.sh) and in
[`wit/world.wit`](./wit/world.wit).
2. Re-fetch the vendored WIT:

```console
$ ./fetch_wit_deps.sh
```

3. Regenerate the committed bindings and commit everything together:

```console
$ ./regenerate_bindings.sh
```

> **Note**: the script uses `wkg get` with exact versions rather than
> `wkg wit fetch` because the library intentionally depends on two versions
> of several packages (e.g. `wasi:http@0.2.8` and `wasi:http@0.3.0`), and
> `wkg wit fetch` resolves at most one version per package name.

## The `componentizego_async` build tag

`wasihttp` compiles to one of two implementations; the exported API is identical under both:

- **Default (no tag)**: sync WASI P2 (`wasi:http@0.2.8`). Matches the `bytecodealliance:pkg/wasip2` world.
- **`-tags componentizego_async`**: async WASI P3 (`wasi:http@0.3.0`) with streaming bodies and native concurrency. Matches the `bytecodealliance:pkg/wasip3` world.

componentize-go sets the tag automatically when building an async world.

## Quickstart

```go
package main

import (
"net/http"

"go.bytecodealliance.org/pkg/wasihttp"
)

func init() {
wasihttp.HandleFunc(func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Hello, component!"))
})
}

func main() {}
```

Add componentize-go as a Go tool and build:

```console
$ go get -tool github.com/bytecodealliance/componentize-go
$ go tool componentize-go build
```

The default world (`bytecodealliance:pkg/wasip2@0.1.0`) is declared in [`componentize-go.toml`](./componentize-go.toml) and discovered automatically. To build the async WASI P3 world instead:

```console
$ go tool componentize-go -w bytecodealliance:pkg/wasip3 build
```

## Benchmarks

Pure-Go conversion logic (header conversion and friends) has microbenchmarks that run on the host:

```console
$ go test -bench=. -benchmem ./...
```

Packages that call `wasi:*` imports only link on wasm targets, so the benchmarks live in host-compilable packages (e.g. `internal/httpconv`).

For A/B comparisons use [benchstat](https://pkg.go.dev/golang.org/x/perf/cmd/benchstat): collect ≥10 samples per side with the test filter disabled, then compare:

```console
$ go test -bench=. -benchmem -count=10 -run='^$' ./... > old.txt
$ # ... apply your change ...
$ go test -bench=. -benchmem -count=10 -run='^$' ./... > new.txt
$ benchstat old.txt new.txt
```

## Questions?

Expand Down
9 changes: 0 additions & 9 deletions componentize-go.toml

This file was deleted.

10 changes: 10 additions & 0 deletions docs/wasi.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<html>
<head>
<title>go.bytecodealliance.org/wasi</title>
<meta name="go-import" content="go.bytecodealliance.org/wasi git https://github.com/bytecodealliance/go-wasi" />
<meta http-equiv="refresh" content="0; url=https://pkg.go.dev/go.bytecodealliance.org/wasi">
</head>
<body>
<a href="https://pkg.go.dev/go.bytecodealliance.org/wasi">Redirecting to documentation…</a>
</body>
</html>

This file was deleted.

3 changes: 0 additions & 3 deletions exports/bytecodealliance_pkg_wasip2_0_1_0/wit_exports/empty.s

This file was deleted.

This file was deleted.

This file was deleted.

3 changes: 0 additions & 3 deletions exports/bytecodealliance_pkg_wasip3_0_1_0/wit_exports/empty.s

This file was deleted.

Loading
Loading