mleku/wazero
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Simplifies API per feedback (#427)

Browse Source 
During #425, @neilalexander gave constructive feedback that the API is
both moving fast, and not good enough yet. This attempts to reduce the
incidental complexity at the cost of a little conflation.

### odd presence of `wasm` and `wasi` packages -> `api` package

We had public API packages in wasm and wasi, which helped us avoid
leaking too many internals as public. That these had names that look
like there should be implementations in them cause unnecessary
confusion. This squashes both into one package "api" which has no
package collission with anything.

We've long struggled with the poorly specified and non-uniformly
implemented WASI specification. Trying to bring visibility to its
constraints knowing they are routinely invalid taints our API for no
good reason. This removes all `WASI` commands for a default to invoke
the function `_start` if it exists. In doing so, there's only one path
to start a module.

Moreover, this puts all wasi code in a top-level package "wasi" as it
isn't re-imported by any internal types.

### Reuse of Module for pre and post instantiation to `Binary` -> `Module`

Module is defined by WebAssembly in many phases, from decoded to
instantiated. However, using the same noun in multiple packages is very
confusing. We at one point tried a name "DecodedModule" or
"InstantiatedModule", but this is a fools errand. By deviating slightly
from the spec we can make it unambiguous what a module is.

This make a result of compilation a `Binary`, retaining `Module` for an
instantiated one. In doing so, there's no longer any name conflicts
whatsoever.

### Confusion about config -> `ModuleConfig`

Also caused by splitting wasm into wasm+wasi is configuration. This
conflates both into the same type `ModuleConfig` as it is simpler than
trying to explain a "will never be finished" api of wasi snapshot-01 in
routine use of WebAssembly. In other words, this further moves WASI out
of the foreground as it has been nothing but burden.

```diff
--- a/README.md
+++ b/README.md
@@ -49,8 +49,8 @@ For example, here's how you can allow WebAssembly modules to read
-wm, err := r.InstantiateModule(wazero.WASISnapshotPreview1())
-defer wm.Close()
+wm, err := wasi.InstantiateSnapshotPreview1(r)
+defer wm.Close()

-sysConfig := wazero.NewSysConfig().WithFS(os.DirFS("/work/home"))
-module, err := wazero.StartWASICommandWithConfig(r, compiled, sysConfig)
+config := wazero.ModuleConfig().WithFS(os.DirFS("/work/home"))
+module, err := r.InstantiateModule(binary, config)
 defer module.Close()
 ...
```
This commit is contained in:
Crypt Keeper
2022-04-02 06:42:36 +08:00
committed by GitHub
parent 3c3df6b836
commit 2664b1eb62
127 changed files with 3153 additions and 3230 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
config_test.go
View File

@@ -9,7 +9,7 @@ import (
"github.com/stretchr/testify/require"
internalwasm "github.com/tetratelabs/wazero/internal/wasm"
"github.com/tetratelabs/wazero/internal/wasm"
)
func TestRuntimeConfig(t *testing.T) {
@@ -51,7 +51,7 @@ func TestRuntimeConfig(t *testing.T) {
return c.WithFeatureMutableGlobal(true)
},
expected: &RuntimeConfig{
enabledFeatures: internalwasm.FeatureMutableGlobal,
enabledFeatures: wasm.FeatureMutableGlobal,
},
},
{
@@ -60,7 +60,7 @@ func TestRuntimeConfig(t *testing.T) {
return c.WithFeatureSignExtensionOps(true)
},
expected: &RuntimeConfig{
enabledFeatures: internalwasm.FeatureSignExtensionOps,
enabledFeatures: wasm.FeatureSignExtensionOps,
},
},
}
@@ -80,13 +80,13 @@ func TestRuntimeConfig(t *testing.T) {
func TestRuntimeConfig_FeatureToggle(t *testing.T) {
tests := []struct {
name string
feature internalwasm.Features
feature wasm.Features
expectDefault bool
setFeature func(*RuntimeConfig, bool) *RuntimeConfig
}{
{
name: "mutable-global",
feature: internalwasm.FeatureMutableGlobal,
feature: wasm.FeatureMutableGlobal,
expectDefault: true,
setFeature: func(c *RuntimeConfig, v bool) *RuntimeConfig {
return c.WithFeatureMutableGlobal(v)
@@ -94,7 +94,7 @@ func TestRuntimeConfig_FeatureToggle(t *testing.T) {
},
{
name: "sign-extension-ops",
feature: internalwasm.FeatureSignExtensionOps,
feature: wasm.FeatureSignExtensionOps,
expectDefault: false,
setFeature: func(c *RuntimeConfig, v bool) *RuntimeConfig {
return c.WithFeatureSignExtensionOps(v)
@@ -124,18 +124,18 @@ func TestRuntimeConfig_FeatureToggle(t *testing.T) {
}
}
func TestSysConfig_toSysContext(t *testing.T) {
func TestModuleConfig_toSysContext(t *testing.T) {
testFS := fstest.MapFS{}
testFS2 := fstest.MapFS{}
tests := []struct {
name string
input *SysConfig
expected *internalwasm.SysContext
input *ModuleConfig
expected *wasm.SysContext
}{
{
name: "empty",
input: NewSysConfig(),
input: NewModuleConfig(),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -148,7 +148,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithArgs",
input: NewSysConfig().WithArgs("a", "bc"),
input: NewModuleConfig().WithArgs("a", "bc"),
expected: requireSysContext(t,
math.MaxUint32, // max
[]string{"a", "bc"}, // args
@@ -161,7 +161,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithArgs - empty ok", // Particularly argv[0] can be empty, and we have no rules about others.
input: NewSysConfig().WithArgs("", "bc"),
input: NewModuleConfig().WithArgs("", "bc"),
expected: requireSysContext(t,
math.MaxUint32, // max
[]string{"", "bc"}, // args
@@ -174,7 +174,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithArgs - second call overwrites",
input: NewSysConfig().WithArgs("a", "bc").WithArgs("bc", "a"),
input: NewModuleConfig().WithArgs("a", "bc").WithArgs("bc", "a"),
expected: requireSysContext(t,
math.MaxUint32, // max
[]string{"bc", "a"}, // args
@@ -187,7 +187,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithEnv",
input: NewSysConfig().WithEnv("a", "b"),
input: NewModuleConfig().WithEnv("a", "b"),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -200,7 +200,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithEnv - empty value",
input: NewSysConfig().WithEnv("a", ""),
input: NewModuleConfig().WithEnv("a", ""),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -213,7 +213,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithEnv twice",
input: NewSysConfig().WithEnv("a", "b").WithEnv("c", "de"),
input: NewModuleConfig().WithEnv("a", "b").WithEnv("c", "de"),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -226,7 +226,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithEnv overwrites",
input: NewSysConfig().WithEnv("a", "bc").WithEnv("c", "de").WithEnv("a", "de"),
input: NewModuleConfig().WithEnv("a", "bc").WithEnv("c", "de").WithEnv("a", "de"),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -240,7 +240,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
{
name: "WithEnv twice",
input: NewSysConfig().WithEnv("a", "b").WithEnv("c", "de"),
input: NewModuleConfig().WithEnv("a", "b").WithEnv("c", "de"),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -253,7 +253,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithFS",
input: NewSysConfig().WithFS(testFS),
input: NewModuleConfig().WithFS(testFS),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -261,7 +261,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
nil, // stdin
nil, // stdout
nil, // stderr
map[uint32]*internalwasm.FileEntry{ // openedFiles
map[uint32]*wasm.FileEntry{ // openedFiles
3: {Path: "/", FS: testFS},
4: {Path: ".", FS: testFS},
},
@@ -269,7 +269,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithFS - overwrites",
input: NewSysConfig().WithFS(testFS).WithFS(testFS2),
input: NewModuleConfig().WithFS(testFS).WithFS(testFS2),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -277,7 +277,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
nil, // stdin
nil, // stdout
nil, // stderr
map[uint32]*internalwasm.FileEntry{ // openedFiles
map[uint32]*wasm.FileEntry{ // openedFiles
3: {Path: "/", FS: testFS2},
4: {Path: ".", FS: testFS2},
},
@@ -285,7 +285,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithWorkDirFS",
input: NewSysConfig().WithWorkDirFS(testFS),
input: NewModuleConfig().WithWorkDirFS(testFS),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -293,14 +293,14 @@ func TestSysConfig_toSysContext(t *testing.T) {
nil, // stdin
nil, // stdout
nil, // stderr
map[uint32]*internalwasm.FileEntry{ // openedFiles
map[uint32]*wasm.FileEntry{ // openedFiles
3: {Path: ".", FS: testFS},
},
),
},
{
name: "WithFS and WithWorkDirFS",
input: NewSysConfig().WithFS(testFS).WithWorkDirFS(testFS2),
input: NewModuleConfig().WithFS(testFS).WithWorkDirFS(testFS2),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -308,7 +308,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
nil, // stdin
nil, // stdout
nil, // stderr
map[uint32]*internalwasm.FileEntry{ // openedFiles
map[uint32]*wasm.FileEntry{ // openedFiles
3: {Path: "/", FS: testFS},
4: {Path: ".", FS: testFS2},
},
@@ -316,7 +316,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
},
{
name: "WithWorkDirFS and WithFS",
input: NewSysConfig().WithWorkDirFS(testFS).WithFS(testFS2),
input: NewModuleConfig().WithWorkDirFS(testFS).WithFS(testFS2),
expected: requireSysContext(t,
math.MaxUint32, // max
nil, // args
@@ -324,7 +324,7 @@ func TestSysConfig_toSysContext(t *testing.T) {
nil, // stdin
nil, // stdout
nil, // stderr
map[uint32]*internalwasm.FileEntry{ // openedFiles
map[uint32]*wasm.FileEntry{ // openedFiles
3: {Path: ".", FS: testFS},
4: {Path: "/", FS: testFS2},
},
@@ -342,45 +342,45 @@ func TestSysConfig_toSysContext(t *testing.T) {
}
}
func TestSysConfig_toSysContext_Errors(t *testing.T) {
func TestModuleConfig_toSysContext_Errors(t *testing.T) {
tests := []struct {
name string
input *SysConfig
input *ModuleConfig
expectedErr string
}{
{
name: "WithArgs - arg contains NUL",
input: NewSysConfig().WithArgs("", string([]byte{'a', 0})),
input: NewModuleConfig().WithArgs("", string([]byte{'a', 0})),
expectedErr: "args invalid: contains NUL character",
},
{
name: "WithEnv - key contains NUL",
input: NewSysConfig().WithEnv(string([]byte{'a', 0}), "a"),
input: NewModuleConfig().WithEnv(string([]byte{'a', 0}), "a"),
expectedErr: "environ invalid: contains NUL character",
},
{
name: "WithEnv - value contains NUL",
input: NewSysConfig().WithEnv("a", string([]byte{'a', 0})),
input: NewModuleConfig().WithEnv("a", string([]byte{'a', 0})),
expectedErr: "environ invalid: contains NUL character",
},
{
name: "WithEnv - key contains equals",
input: NewSysConfig().WithEnv("a=", "a"),
input: NewModuleConfig().WithEnv("a=", "a"),
expectedErr: "environ invalid: key contains '=' character",
},
{
name: "WithEnv - empty key",
input: NewSysConfig().WithEnv("", "a"),
input: NewModuleConfig().WithEnv("", "a"),
expectedErr: "environ invalid: empty key",
},
{
name: "WithFS - nil",
input: NewSysConfig().WithFS(nil),
input: NewModuleConfig().WithFS(nil),
expectedErr: "FS for / is nil",
},
{
name: "WithWorkDirFS - nil",
input: NewSysConfig().WithWorkDirFS(nil),
input: NewModuleConfig().WithWorkDirFS(nil),
expectedErr: "FS for . is nil",
},
}
@@ -394,9 +394,9 @@ func TestSysConfig_toSysContext_Errors(t *testing.T) {
}
}
// requireSysContext ensures internalwasm.NewSysContext doesn't return an error, which makes it usable in test matrices.
func requireSysContext(t *testing.T, max uint32, args, environ []string, stdin io.Reader, stdout, stderr io.Writer, openedFiles map[uint32]*internalwasm.FileEntry) *internalwasm.SysContext {
sys, err := internalwasm.NewSysContext(max, args, environ, stdin, stdout, stderr, openedFiles)
// requireSysContext ensures wasm.NewSysContext doesn't return an error, which makes it usable in test matrices.
func requireSysContext(t *testing.T, max uint32, args, environ []string, stdin io.Reader, stdout, stderr io.Writer, openedFiles map[uint32]*wasm.FileEntry) *wasm.SysContext {
sys, err := wasm.NewSysContext(max, args, environ, stdin, stdout, stderr, openedFiles)
require.NoError(t, err)
return sys
}