[water-api] new API design draft

config.go

@@ -1,21 +1,21 @@
 package water
 
 type Config struct {
-	// WASI contains the compiled WASI binary in bytes.
-	WASI []byte
-
-	// Dialer is used to dial a network connection.
-	Dialer Dialer
+	Dialer   Dialer  // A dialer supporting multiple network types.
+	Feature  Feature // Bit-masked experimental features
+	WABin    []byte  // WebAssembly module binary.
+	WAConfig []byte  // WebAssembly module config file, if any.
 }
 
-// init() checks if the Config is valid and initializes
-// the Config with default values if optional fields are not provided.
+// complete the config by filling in the missing optional fields
+// with fault values and panic if any of the required fields are not
+// provided.
 func (c *Config) init() {
-	if len(c.WASI) == 0 {
-		panic("water: WASI binary is not provided")
-	}
-
 	if c.Dialer == nil {
 		c.Dialer = DefaultDialer()
 	}
+
+	if len(c.WABin) == 0 {
+		panic("water: WASI binary is not provided")
+	}
 }

core.go

@@ -0,0 +1,114 @@
+package water
+
+import (
+	"fmt"
+	"net"
+
+	"github.com/bytecodealliance/wasmtime-go/v12"
+)
+
+// RuntimeConn defines an interface that all implementations of RuntimeConn
+// must implement no matter of which version it is.
+type RuntimeConn interface {
+	net.Conn
+}
+
+// runtimeCore provides the WASM runtime base and is an internal struct
+// that every RuntimeXxx implementation will embed.
+type runtimeCore struct {
+	// wasmtime
+	engine   *wasmtime.Engine
+	module   *wasmtime.Module
+	store    *wasmtime.Store
+	linker   *wasmtime.Linker
+	instance *wasmtime.Instance
+
+	// wasi imports
+	deferFuncs []func() // defer functions to be called by WASM module on exit
+
+	// wasi exports
+	_init    *wasmtime.Func
+	_version *wasmtime.Func
+
+	// other wasi related stuff
+	wd *WasiDialer
+}
+
+func NewCore() *runtimeCore {
+	return &runtimeCore{}
+}
+
+func (c *runtimeCore) Defer(f func()) {
+	c.deferFuncs = append(c.deferFuncs, f)
+}
+
+func (c *runtimeCore) linkDefer() error {
+	if c.linker == nil {
+		return fmt.Errorf("linker not set")
+	}
+
+	if err := c.linker.DefineFunc(c.store, "env", "defer", c._defer); err != nil {
+		return fmt.Errorf("(*wasmtime.Linker).DefineFunc: %w", err)
+	}
+
+	return nil
+}
+
+func (c *runtimeCore) linkDialer(dialer Dialer, address string) error {
+	if c.linker == nil {
+		return fmt.Errorf("linker not set")
+	}
+
+	if dialer == nil {
+		return fmt.Errorf("dialer not set")
+	}
+
+	if c.wd == nil {
+		c.wd = NewWasiDialer(address, dialer, c.store)
+	} else {
+		return fmt.Errorf("wasi dialer already set, double-linking?")
+	}
+
+	if err := c.linker.DefineFunc(c.store, "env", "dial", c.wd.WasiDialerFunc); err != nil {
+		return fmt.Errorf("(*wasmtime.Linker).DefineFunc: %w", err)
+	}
+
+	return nil
+}
+
+func (c *runtimeCore) initializeConn() (RuntimeConn, error) {
+	// get _init and _version functions
+	c._init = c.instance.GetFunc(c.store, "_init")
+	if c._init == nil {
+		return nil, fmt.Errorf("instantiated WASM module does not export _init function")
+	}
+	c._version = c.instance.GetFunc(c.store, "_version")
+	if c._version == nil {
+		return nil, fmt.Errorf("instantiated WASM module does not export _version function")
+	}
+
+	// initialize WASM instance.
+	// In a _init() call, the WASM module will setup all its internal states
+	_, err := c._init.Call(c.store)
+	if err != nil {
+		return nil, fmt.Errorf("errored upon calling _init function: %w", err)
+	}
+
+	// get version
+	// In a _version() call, the WASM module will return its version
+	ret, err := c._version.Call(c.store)
+	if err != nil {
+		return nil, fmt.Errorf("errored upon calling _version function: %w", err)
+	}
+	if ver, ok := ret.(int32); !ok {
+		return nil, fmt.Errorf("_version function returned non-int32 value")
+	} else {
+		return RuntimeConnWithVersion(c, ver)
+	}
+}
+
+func (c *runtimeCore) _defer() {
+	for _, f := range c.deferFuncs {
+		f()
+	}
+}

example/main.go

@@ -0,0 +1,66 @@
+package main
+
+import (
+	"crypto/rand"
+	"fmt"
+	"net"
+	"os"
+	"sync"
+)
+
+func main() {
+	// get temp dir
+	tempDir := os.TempDir()
+	// append OS-specific path separator
+	tempDir += string(os.PathSeparator)
+	// randomize a socket name
+	randBytes := make([]byte, 16)
+	if _, err := rand.Read(randBytes); err != nil {
+		panic(fmt.Errorf("water: rand.Read returned error: %w", err))
+	}
+	tempDir += fmt.Sprintf("%x", randBytes)
+
+	// create a one-time use UnixListener
+	ul, err := net.Listen("unix", tempDir)
+	if err != nil {
+		panic(fmt.Errorf("water: net.Listen returned error: %w", err))
+	}
+	defer ul.Close()
+
+	var waConn net.Conn
+	var wg *sync.WaitGroup = new(sync.WaitGroup)
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		var err error
+		waConn, err = ul.Accept()
+		if err != nil {
+			panic(fmt.Errorf("water: ul.Accept returned error: %w", err))
+		}
+	}()
+
+	// dial the one-time use UnixListener
+	uc, err := net.Dial("unix", ul.Addr().String())
+	if err != nil {
+		panic(fmt.Errorf("water: net.Dial returned error: %w", err))
+	}
+	defer uc.Close()
+	wg.Wait()
+
+	// write to uc, read from waConn
+	uc.Write([]byte("hello"))
+	buf := make([]byte, 128)
+	n, err := waConn.Read(buf)
+	if err != nil {
+		panic(fmt.Errorf("water: waConn.Read returned error: %w", err))
+	}
+	fmt.Printf("read %d bytes from waConn: %s\n", n, string(buf[:n]))
+
+	// write to waConn, read from uc
+	waConn.Write([]byte("world"))
+	n, err = uc.Read(buf)
+	if err != nil {
+		panic(fmt.Errorf("water: uc.Read returned error: %w", err))
+	}
+	fmt.Printf("read %d bytes from uc: %s\n", n, string(buf[:n]))
+}

feature.go

@@ -0,0 +1,12 @@
+package water
+
+type Feature uint64
+
+// Feature is a bit mask of experimental features of WATER.
+const (
+	FEATURE_DUMMY    Feature = 1 << iota // a dummy feature that does nothing.
+	FEATURE_RESERVED                     // reserved for future use
+	// ...
+	FEATURE_CWAL Feature = 0xFFFFFFFFFFFFFFFF // CWAL = Can't Wait Any Longer
+	FEATURE_NONE Feature = 0                  // NONE = No Experimental Features
+)

go.mod

@@ -1,5 +1,7 @@
 module github.com/gaukas/water
 
-go 1.21.0
+go 1.18
 
-require github.com/bytecodealliance/wasmtime-go/v11 v11.0.0
+replace github.com/bytecodealliance/wasmtime-go/v12 v12.0.0 => github.com/refraction-networking/wasmtime-go/v12 v12.0.0
+
+require github.com/bytecodealliance/wasmtime-go/v12 v12.0.0

go.sum

@@ -1,10 +1,10 @@
-github.com/bytecodealliance/wasmtime-go/v11 v11.0.0 h1:SwLgbjbFpQ1tf5vIbWexaZABezBSL8WmzP+foLyi0lE=
-github.com/bytecodealliance/wasmtime-go/v11 v11.0.0/go.mod h1:9btfEuCkOP7EDR9a7LqDXrfQ7dtWeGlDHt3buV5UyjY=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/testify v1.8.0 h1:pSgiaMZlXftHpm5L7V1+rVB+AZJydKsMxsQBIJw4PKk=
-github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/refraction-networking/wasmtime-go/v12 v12.0.0 h1:crB/5HgsjL5OvfXwCT6YthaoL19tDYdK3R6NOKw42n8=
+github.com/refraction-networking/wasmtime-go/v12 v12.0.0/go.mod h1:xLry3QSj/6qi3uMlhbeCoJhf2gWtuXfNTS6TKhz9M+s=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=